coulomb/kontextual-engine
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Warnings cleanup

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-14 01:02:25 +02:00
parent 484a978795
commit 41bd662641
12 changed files with 331 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/blob-storage-content-streaming-workplan.md
View File

@@ -78,6 +78,8 @@ CMIS integration:
- `getContentStream` returns actual bytes/stream with content headers,
- `setContentStream` stores through deduplicating representation service,
- `appendContentStream` composes the current stream plus appended bytes and
stores the resulting representation through the same deduplicating service,
- content stream changes produce versions and audit events,
- descriptors remain available for clients that only need metadata.

44
docs/cmis-1-1-capability-scorecard.md
View File

@@ -1,14 +1,13 @@
# CMIS 1.1 Capability Scorecard
Date: 2026-05-13
Date: 2026-05-14
Evidence update: the 2026-05-13 WP-0014 OpenCMIS pass completed the selected
Evidence update: the 2026-05-14 release-warning pass completed the selected
Browser Binding `repository-type` and `object-content` baseline. The latest
run, `run-20260513T210255Z`, reports `0` unexpected findings:
`repository-type` is warning-only because the local harness uses HTTP, and
`object-content` is warning-only because `appendContentStream()` is not
supported. See
`docs/cmis-opencmis-tck-wp0014-evidence-2026-05-13T210255Z.md`.
run, `run-20260513T223537Z`, reports `0` unexpected findings. The
`object-content` group now passes without warnings; the only remaining
OpenCMIS warning is the local harness using HTTP rather than HTTPS. See
`docs/cmis-opencmis-tck-release-readiness-evidence-2026-05-13T223537Z.md`.
The score below remains a product-depth estimate against mature CMIS products.
The selected OpenCMIS baseline is now stable preparation evidence for
@@ -72,10 +71,10 @@ CMIS interoperability importance rather than engine-internal importance.
| Metric | Score |
| --- | ---: |
| OpenCMIS selected-baseline infrastructure score | 98.3% |
| Weighted CMIS 1.1 depth vs Hyland Alfresco benchmark | 59% |
| Controlled-client Browser Binding usefulness | 80% |
| Broad commodity CMIS client compatibility | 54% |
| OpenCMIS selected-baseline infrastructure score | 99.1% |
| Weighted CMIS 1.1 depth vs Hyland Alfresco benchmark | 60% |
| Controlled-client Browser Binding usefulness | 82% |
| Broad commodity CMIS client compatibility | 55% |
Interpretation: the OpenCMIS infrastructure score measures the selected
`repository-type` and `object-content` harness baseline only. The current CMIS
@@ -92,8 +91,8 @@ broad ECM/CMIS replacement surface.
| Type definitions | 6 | 55% | Hyland Alfresco ACS | - Base types, Browser Binding type definitions, secondary type projection, and nullable content stream properties exist.<br>- No mutable types or custom schema/type management.<br>- Property definition depth remains intentionally narrow. |
| Navigation service | 8 | 62% | Hyland Alfresco ACS | - Root and folder-scoped children, path lookup, folder parent lookup, parent path segments, move, and delete-tree work in the selected baseline.<br>- Projection-only parents exist.<br>- Missing `getDescendants`, `getFolderTree`, and real filing mutations. |
| Object read service | 10 | 84% | Hyland Alfresco ACS | - Object envelopes, properties, content descriptors, ACL projection, relationships, allowable actions, property filters, and path-addressed Browser Binding reads exist.<br>- Deleted/hidden objects are correctly not exposed.<br>- OpenCMIS object/content read-side baseline now completes with warnings only. |
| Object write service | 8 | 70% | Hyland Alfresco ACS | - `createDocument`, `createFolder`, scoped `moveObject`, folder rename, selected standard property updates, custom metadata updates, content stream set/delete, `bulkUpdateProperties`, and `createDocumentFromSource` exist.<br>- No broad filing mutation, raw physical delete, checkout/checkin, or policy/item creation.<br>- Delete remains intentionally governed, not raw repository removal. |
| Content stream read/write | 8 | 82% | Hyland Alfresco ACS | - Byte streaming, explicit content headers, multipart Browser Binding create, deduplicating `setContentStream`, no-content compatibility streams, content tombstones, partial body slicing, and offset-zero full-stream classification exist.<br>- Digest verification and governed access exist.<br>- Remaining warning is unsupported append semantics. |
| Object write service | 8 | 72% | Hyland Alfresco ACS | - `createDocument`, `createFolder`, scoped `moveObject`, folder rename, selected standard property updates, custom metadata updates, content stream set/append/delete, `bulkUpdateProperties`, and `createDocumentFromSource` exist.<br>- No broad filing mutation, raw physical delete, checkout/checkin, or policy/item creation.<br>- Delete remains intentionally governed, not raw repository removal. |
| Content stream read/write | 8 | 86% | Hyland Alfresco ACS | - Byte streaming, explicit content headers, multipart Browser Binding create, deduplicating `setContentStream`, whole-object `appendContentStream`, no-content compatibility streams, content tombstones, partial body slicing, and offset-zero full-stream classification exist.<br>- Digest verification and governed access exist.<br>- Chunk-level blob composition remains a later optimization for very large append workloads. |
| Versioning service | 8 | 25% | Hyland Alfresco ACS | - Version properties can be projected from engine versions.<br>- No checkout/checkin/cancelCheckout/PWC services.<br>- No version history route or all-versions query behavior. |
| Discovery/query | 8 | 25% | Hyland Alfresco ACS | - Narrow document select subset exists.<br>- Unsupported joins/order-by return diagnostics.<br>- Missing CMIS SQL predicates, type joins, full-text, ordering, and rich projection rules. |
| Relationships | 5 | 60% | Hyland Alfresco ACS | - Relationship object projection and source filtering exist.<br>- Visibility gates prevent protected relationship leakage.<br>- Missing full relationship service filters, relationship creation through CMIS, and type hierarchy maturity. |
@@ -104,19 +103,19 @@ broad ECM/CMIS replacement surface.
| Renditions | 3 | 15% | Hyland Alfresco ACS | - Native representations could become rendition candidates later.<br>- CMIS rendition capability is currently `none`.<br>- No rendition taxonomy or rendition stream routes. |
| Retention and hold | 2 | 5% | OpenText / Hyland governance stacks | - Native governance metadata can represent intent later.<br>- No CMIS retention/hold model or mutation services.<br>- Explicitly unsupported. |
| Bulk update | 2 | 65% | Hyland Alfresco ACS | - `bulkUpdateProperties` works for the `compat-tck` profile by batching existing property updates with change-token handling.<br>- It is intentionally narrow and not enabled on the normal governed-authoring profile yet.<br>- No advanced partial-success envelope beyond the Browser Binding response list. |
| Browser Binding protocol fidelity | 7 | 78% | Hyland Alfresco ACS | - Browser-style routes, JSON envelopes, CMIS exception names, action aliases, multipart forms, path-addressed root routes, property filters, path segments, and range responses exist.<br>- Selected OpenCMIS Browser Binding repository/type and object/content baseline completes with warnings only.<br>- Optional services and broader CMIS SQL/versioning protocol surfaces remain incomplete. |
| Browser Binding protocol fidelity | 7 | 80% | Hyland Alfresco ACS | - Browser-style routes, JSON envelopes, CMIS exception names, action aliases, multipart forms, path-addressed root routes, property filters, path segments, and range responses exist.<br>- Selected OpenCMIS Browser Binding repository/type and object/content baseline completes with only the local HTTP warning.<br>- Optional services and broader CMIS SQL/versioning protocol surfaces remain incomplete. |
| AtomPub binding | 2 | 0% | Hyland Alfresco ACS | - No AtomPub/XML service document or feeds.<br>- Intentionally deferred until monetized need. |
| Web Services binding | 2 | 0% | Hyland Alfresco ACS | - No SOAP/WSDL stack.<br>- Intentionally deferred until monetized need. |
| External conformance evidence | 3 | 82% | OpenCMIS TCK against Alfresco-like server behavior | - OpenCMIS Browser Binding session creation succeeds against `compat-tck`.<br>- Selected `repository-type` and `object-content` baselines complete with warnings only.<br>- Evidence still covers a selected baseline, not the full OpenCMIS TCK surface. |
| External conformance evidence | 3 | 86% | OpenCMIS TCK against Alfresco-like server behavior | - OpenCMIS Browser Binding session creation succeeds against `compat-tck`.<br>- Selected `repository-type` and `object-content` baselines complete with one local transport warning and no object/content warnings.<br>- Evidence still covers a selected baseline, not the full OpenCMIS TCK surface. |
Weighted result from this table: **59%**.
Weighted result from this table: **60%**.
## Most Important Gaps
1. **External conformance expansion**
- Keep the selected OpenCMIS TCK baseline running against `compat-tck`.
- Treat the current repository/type and object/content warnings as known:
local HTTP and unsupported append.
- Treat the remaining local HTTP warning as a harness/deployment topology
issue, not an adapter behavior failure.
- Expand selected groups after the supported baseline remains stable.
2. **Browser Binding fidelity**
@@ -145,10 +144,11 @@ Weighted result from this table: **59%**.
- Map selected derived representations to CMIS renditions only after we have
stable representation taxonomy and real preview/thumbnail use cases.
7. **Append streams**
- Keep `appendContentStream()` unsupported unless a real client requires it.
- If implemented later, design it through blob composition/deduplication
rather than byte concatenation in the CMIS adapter.
7. **Release transport and operational posture**
- Terminate CMIS access over HTTPS in deployable environments.
- Keep the local HTTP warning accepted only for loopback TCK runs.
- Revisit blob composition if large append workloads become a real usage
pattern.
## Product Positioning Takeaway

2
docs/cmis-compliance-assessment.md
View File

@@ -48,7 +48,7 @@ Practical strategy:
| Navigation service | Implemented subset. | `getChildren` and projected parents are supported. `getDescendants`, `getFolderTree`, mutating multifiling, and unfiling are explicitly flagged unsupported. | Low unless full folder tree is required |
| Object service read | Implemented subset. | Object envelopes, allowable actions, content stream descriptors, content stream properties, visibility redaction, and relationship IDs are covered. | Low |
| Object service write | Governed subset. | `createDocument`, custom metadata updates, `setContentStream`, and delete-request lifecycle transition are supported by authoring profiles. Unsupported standard property updates now fail with diagnostics. | Medium |
| Content streams | Implemented subset. | Descriptor and byte-stream routes exist; `setContentStream` writes through deduplicating blob storage. Append/delete content stream are unsupported. | Low |
| Content streams | Implemented subset. | Descriptor and byte-stream routes exist; `setContentStream` and whole-object `appendContentStream` write through deduplicating blob storage, while `deleteContentStream` tombstones the CMIS projection. Chunk-level append composition remains deferred. | Low |
| Versioning | Projection only. | Latest-version properties can be projected from engine versions, but CMIS checkout/PWC/all-versions services are not advertised. | Low if unsupported remains acceptable |
| Discovery/query | Implemented narrow subset. | `SELECT * FROM cmis:document` and `SELECT * FROM kontextual:document` are supported. Joins, order-by, full CMIS SQL predicates, and full-text are flagged unsupported. | Medium |
| Relationships | Implemented subset. | Relationship object projections and source filters are covered and profile-gated. | Low |

70
docs/cmis-opencmis-tck-release-readiness-evidence-2026-05-13T223537Z.md Normal file
View File

@@ -0,0 +1,70 @@
# CMIS OpenCMIS TCK Evidence - Release Readiness - 2026-05-13T22:35:37Z
## Run Summary
- Run ID: `run-20260513T223537Z`
- Local date: 2026-05-14 Europe/Berlin
- Harness: `guide-board` with `open-cmis-tck` extension
- Assessment: `cmis-browser-baseline`
- Target: `kontextual-cmis-compat`
- Endpoint: `http://127.0.0.1:8010/cmis/compat-tck/browser`
- OpenCMIS TCK: CMIS 1.1.0, revision `1789681`
- Result: `completed`
- Policy: `0` unexpected findings, `0` applied waivers
- Run directory: `/tmp/kontextual-cmis-release-20260514-toolchain`
- Internal verification: `.venv/bin/python -m pytest -q` -> `166 passed`,
`14 skipped`
This run was executed after adding Browser Binding `appendContent` /
`appendContentStream` support through the existing content representation
service.
## Normalized Results
| Group | Result | Counts | Remaining non-green findings |
| --- | --- | --- | --- |
| `repository-type` | `warning` | `38 pass`, `2 info`, `1 skipped`, `1 warning` | Local loopback endpoint uses HTTP rather than HTTPS. |
| `object-content` | `pass` | `10 info`, `5 skipped` | None. |
Guide Board summary:
- `pass`: 2
- `warning`: 1
## Score
This is a compatibility-infrastructure score for the selected Browser Binding
baseline, not a CMIS certification score.
| Metric | Score | Basis |
| --- | ---: | --- |
| Selected baseline completion | 100.0% | Guide Board result `completed`; both selected groups returned `0`. |
| Unexpected finding clearance | 100.0% | `0` unexpected findings, `0` fail, `0` infrastructure_error. |
| Warning-adjusted normalized case score | 99.1% | `(56 accepted + 0.5 * 1 warning) / 57 normalized cases`. |
| Strict no-warning normalized case score | 98.2% | `56 accepted / 57 normalized cases`. |
Digest versus `run-20260513T210255Z`:
- OpenCMIS selected-baseline infrastructure score improved from `98.3%` to
`99.1%`.
- `object-content` improved from warning to pass.
- The previous `appendContentStream()` warning is closed.
- The only remaining warning is local HTTP transport in the loopback harness.
## Interpretation
The selected Browser Binding repository/type and object/content baseline is now
release-ready for a controlled preview. The remaining HTTP warning should be
handled as a deployment gate: released access points need HTTPS termination,
while loopback TCK runs may keep the warning as an accepted local harness
condition.
Skipped object/content cases remain aligned with declared capability
boundaries:
- Relationship, policy, and item creation are not advertised as creatable.
- Folder-name change-token subcases are skipped by the TCK.
This evidence still does not cover full CMIS 1.1 certification, AtomPub, Web
Services, PWC/checkin/checkout, full CMIS SQL, renditions, retention, or policy
mutation depth.

72
docs/first-release-readiness.md Normal file
View File

@@ -0,0 +1,72 @@
# First Release Readiness
Date: 2026-05-14
Target posture: `0.1.0` controlled preview. This release can be good to go
when it is honest, reproducible, observable, and recoverable. It does not need
to pretend to be a full ECM or certified CMIS repository.
## Release Scope
In scope:
- native asset registry, metadata, relationship, retrieval, transformation,
workflow, service API, blob, S3-backend, and observability foundations,
- profiled CMIS Browser Binding subset for controlled integrations,
- OpenCMIS selected baseline for `repository-type` and `object-content`,
- explicit unsupported flags for out-of-scope CMIS capabilities,
- State Hub registered workplans and evidence documents.
Out of scope for `0.1.0`:
- AtomPub and Web Services bindings,
- full CMIS SQL, checkout/checkin/PWC, policy mutation, retention/hold,
renditions, and broad filing mutation,
- full ECM/records-management semantics,
- formal CMIS certification claim.
## Go / No-Go Gates
| Area | Gate | Current state |
| --- | --- | --- |
| Tests | Full suite passes in the project venv. | `.venv/bin/python -m pytest -q` passed: `166 passed`, `14 skipped`; advisory performance drift warnings recorded. |
| CMIS evidence | OpenCMIS selected baseline completes with no unexpected findings. | `run-20260513T223537Z` completed; only local HTTP warning remains. |
| Transport | Released CMIS access points are served behind HTTPS. | Required deployment gate; local loopback warning is accepted only for harness runs. |
| Capability honesty | Scorecard, unsupported catalog, and examples match behavior. | Updated for `appendContentStream`; final doc review required. |
| Packaging | Version, dependencies, optional extras, and install smoke are checked. | `pyproject.toml` is already `0.1.0`; build/install smoke still required. |
| Configuration | Storage backend, S3 settings, local blob path, and environment defaults are documented. | Existing docs cover backends; release runbook should point to them. |
| Data safety | Blob cleanup, backups, restore path, and migration posture are documented. | Cleanup exists; backup/restore release notes still needed. |
| Security | Actor headers, access-point profiles, secrets, and dependency/license review are done. | Profile model exists; release security review still required. |
| Operations | Health checks, logs, performance history, and known warnings are documented. | Health and performance monitor exist; release runbook still needed. |
| State | State Hub consistency check passes after release docs/workplan updates. | Passed after WP-0015 registration. |
## Known Accepted Limitations
- CMIS Browser Binding is the supported external CMIS protocol surface.
- CMIS multifiling remains projection-only.
- CMIS append is implemented as whole-object append through deduplicating
representation storage; chunk-level blob composition is deferred.
- Local OpenCMIS loopback runs warn about HTTP. This must not be carried into
production-facing access points.
- Performance drift warnings from pytest are advisory unless repeated under a
quiet system baseline; the current run flagged several CMIS API tests.
## Release Procedure
1. Run `.venv/bin/python -m pytest -q`.
2. Run the OpenCMIS selected baseline through `guide-board` and persist the
evidence document.
3. Run State Hub consistency check and ensure workplans are registered.
4. Run packaging smoke: build wheel/sdist and import `kontextual_engine` from a
clean install.
5. Review security/configuration: HTTPS termination, profile exposure, secrets,
local/S3 blob backend settings, and dependency licenses.
6. Update `CHANGELOG.md` or release notes with capabilities, known limitations,
and accepted warnings.
7. Tag the release only after the gates above are green or explicitly waived.
## Release Decision
The current foundation is close to a controlled `0.1.0` preview. The main
remaining release work is not feature depth; it is discipline around repeatable
verification, packaging, deployment posture, and clearly documented limits.