From efb6152487874bdbf235cd62c7413d2a975ad609 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 8 May 2026 12:52:56 +0200 Subject: [PATCH] CMIS maturity improvement workplan --- ...NT-WP-0014-cmis-object-content-maturity.md | 264 ++++++++++++++++++ 1 file changed, 264 insertions(+) create mode 100644 workplans/KONT-WP-0014-cmis-object-content-maturity.md diff --git a/workplans/KONT-WP-0014-cmis-object-content-maturity.md b/workplans/KONT-WP-0014-cmis-object-content-maturity.md new file mode 100644 index 0000000..8972f13 --- /dev/null +++ b/workplans/KONT-WP-0014-cmis-object-content-maturity.md @@ -0,0 +1,264 @@ +--- +id: KONT-WP-0014 +type: workplan +title: "CMIS Object/Content Maturity Expansion" +domain: markitect +repo: kontextual-engine +status: planned +owner: codex +topic_slug: markitect +planning_priority: high +planning_order: 14 +created: "2026-05-08" +updated: "2026-05-08" +state_hub_workstream_id: "ccfa90ee-be23-499b-a727-451a0d289df7" +--- + +# KONT-WP-0014: CMIS Object/Content Maturity Expansion + +## Purpose + +Raise the evidence-backed CMIS 1.1 Browser Binding maturity score in ways that +fit `kontextual-engine` naturally. The work should deepen object/content, +navigation, query, ACL, relationship, and change-log compatibility without +turning the engine into a generic ECM clone or duplicating native domain +services. + +## Trigger + +The fresh OpenCMIS assessment on 2026-05-08 completed successfully: + +- Run ID: `run-20260508T103313Z` +- Maturity score: `23.81` +- Coverage: `2/9` groups +- `repository-type`: `38 pass`, `2 info`, `2 skipped`, `1 warning`, `0 fail` +- `object-content`: `22 skipped`, `0 fail` + +The remaining useful maturity blocker is not Browser Binding session creation +anymore. It is capability depth: OpenCMIS skips object/content checks because +`cmis:folder` is not creatable in the compatibility profile. + +## References + +- `docs/cmis-opencmis-tck-implementation-evidence-2026-05-08T092113Z.md` +- `docs/cmis-1-1-capability-scorecard.md` +- `docs/cmis-profiled-access-points-implementation.md` +- `docs/blob-storage-content-streaming-workplan.md` +- `workplans/KONT-WP-0012-cmis-profiled-access-points.md` +- `workplans/KONT-WP-0013-cmis-browser-binding-tck-compatibility.md` +- `src/kontextual_engine/core/cmis.py` +- `src/kontextual_engine/api/app.py` +- `tests/cmis/` +- `/home/worsch/open-cmis-tck/profiles/assessments/cmis-browser-baseline.json` + +## Architecture Boundary + +CMIS remains an adapter over the native engine. Native asset identity, +classification, source grounding, representation/blob storage, policy, audit, +and workflow services remain authoritative. + +Allowed architectural moves: + +- Add a profile-scoped CMIS workspace/folder registry if needed for CMIS client + compatibility. +- Treat CMIS-created folders as adapter-managed workspace objects, not as the + engine's canonical knowledge organization model. +- Delegate CMIS document, metadata, and content mutations to existing engine + services. +- Improve Browser Binding request/response shape around capabilities the engine + already owns. +- Use conservative unsupported flags and diagnostics for advanced CMIS areas. + +Disallowed architectural moves: + +- Do not add AtomPub or Web Services bindings. +- Do not build a full ECM filing model, repository permission model, mutable + type system, PWC/checkin/checkout stack, or broad CMIS SQL engine unless a + later workplan justifies it. +- Do not bypass profile gates, policy decisions, audit events, blob + deduplication, or source-grounded asset semantics for TCK convenience. + +## Desired Outcome + +- OpenCMIS `object-content` checks execute beyond the current + `cmis:folder is not creatable` skip boundary. +- CMIS Browser Binding object/content actions use standard selector/action + shapes while still delegating to native services. +- Content stream read/write behavior is more compatible and better documented. +- Natural navigation/query/read-side services improve without claiming full CMIS + optional capability support. +- The maturity scorecard is updated from fresh TCK evidence, with remaining + unsupported features explicitly classified. + +## D14.1 - Define CMIS maturity boundary and TCK profile semantics + +```task +id: KONT-WP-0014-T001 +status: todo +priority: high +state_hub_task_id: "333f8ea0-0582-467d-a52d-7ef5cf6f34c0" +``` + +Acceptance: + +- Document which maturity improvements are natural for `kontextual-engine` and + which remain out of scope. +- Define the `compat-tck` profile's special responsibilities, including whether + it may expose adapter-managed folders solely for compatibility. +- Update capability flags and unsupported-feature diagnostics so they match the + intended profile boundary before implementation starts. + +## D14.2 - Design scoped virtual folder registry for compat profile + +```task +id: KONT-WP-0014-T002 +status: todo +priority: high +state_hub_task_id: "30d02544-0325-490e-84d7-ebaa3825ee78" +``` + +Acceptance: + +- A virtual folder registry design exists for CMIS-created workspace folders. +- Folder identity, parentage, lifecycle, visibility, path lookup, and audit + behavior are specified. +- The design keeps projection folders and CMIS-created workspace folders + distinguishable. +- Persistence expectations are explicit: in-memory first is acceptable for TCK + compatibility only if the follow-up durable boundary is documented. + +## D14.3 - Implement createFolder and folder lifecycle in the CMIS adapter + +```task +id: KONT-WP-0014-T003 +status: todo +priority: high +state_hub_task_id: "b5324bcb-67fe-4f28-9591-83e6361bfd01" +``` + +Acceptance: + +- Browser Binding `createFolder` works for profiles that explicitly allow it. +- Read-only profiles still reject folder creation. +- Created folders can be retrieved, listed under parents, resolved by path, and + deleted or lifecycle-marked according to the profile. +- Folder operations emit audit/progress evidence and preserve actor context. +- OpenCMIS object/content tests no longer skip solely because `cmis:folder` is + not creatable. + +## D14.4 - Complete Browser Binding object/content action parity + +```task +id: KONT-WP-0014-T004 +status: todo +priority: high +state_hub_task_id: "f9323c25-4d81-42cd-b7e6-e40d7e0487cd" +``` + +Acceptance: + +- Browser Binding action/form routes cover the supported subset of + `createDocument`, `setContentStream`, `updateProperties`, `deleteObject`, and + `getContentStream`. +- The implementation delegates to existing asset, metadata, content, policy, and + audit services. +- Unsupported standard `cmis:*` property mutations return CMIS-shaped + diagnostics rather than native validation leakage. +- Internal route tests exercise OpenCMIS-style action requests in addition to + existing convenience routes. + +## D14.5 - Improve content stream fidelity + +```task +id: KONT-WP-0014-T005 +status: todo +priority: medium +state_hub_task_id: "5feb6db8-24eb-4c20-8c3e-d530f396ef6a" +``` + +Acceptance: + +- Content stream reads support headers expected by common CMIS clients, + including content length, content type, ETag, and content disposition. +- Range reads are supported or explicitly rejected with a clear standard-shaped + response. +- `appendContentStream` and `deleteContentStream` are either implemented + naturally through blob services or explicitly advertised as unsupported. +- Blob deduplication and digest verification remain intact. + +## D14.6 - Add natural navigation and query depth + +```task +id: KONT-WP-0014-T006 +status: todo +priority: medium +state_hub_task_id: "b1562023-807b-4fed-b794-6930fcc2274e" +``` + +Acceptance: + +- `getObjectByPath` and `getFolderParent` are added where they naturally map to + projection or workspace folder state. +- Shallow `getDescendants` support is added only if it can be implemented over + existing projection/workspace folder traversal without expensive graph scans. +- The query subset supports basic `WHERE` predicates and safe ordering for + indexed/available metadata fields, or returns precise unsupported diagnostics. +- Capability flags are updated only for behavior that is actually supported. + +## D14.7 - Polish read-side relationships, ACL discovery, and change tokens + +```task +id: KONT-WP-0014-T007 +status: todo +priority: medium +state_hub_task_id: "60f7b222-6eea-4add-822d-3439d568d4f6" +``` + +Acceptance: + +- Relationship read services expose source/target filters and object envelopes + in Browser Binding-compatible shapes. +- ACL discovery exposes clearer principal, direct/inherited, and permission + mapping while policy gateway decisions remain authoritative. +- Durable-enough change tokens are defined for the current persistence layer. +- ACL mutation, policy mutation, PWC/versioning, and type mutability remain + unsupported unless a later task explicitly changes scope. + +## D14.8 - Expand OpenCMIS assessment and update maturity scorecard + +```task +id: KONT-WP-0014-T008 +status: todo +priority: high +state_hub_task_id: "c9514345-793c-489e-9dcc-86776db47cf4" +``` + +Acceptance: + +- Rerun `repository-type` and `object-content` after folder/action changes. +- Persist a timestamped assessment result with normalized case counts and + capability interpretation. +- Expand selected OpenCMIS groups only after the baseline remains stable. +- Update `docs/cmis-1-1-capability-scorecard.md` from evidence, separating + preparation score, controlled-client usefulness, and market benchmark depth. +- Register final task/workstream status with State Hub. + +## Suggested Implementation Order + +1. Confirm profile boundary and capability flags. +2. Design and implement virtual folder registry plus `createFolder`. +3. Align Browser Binding object/content actions with OpenCMIS request shapes. +4. Rerun `object-content` and classify concrete failures. +5. Improve content stream fidelity if failures or common-client expectations + point there. +6. Add navigation/query/read-side polish in small measured increments. +7. Expand TCK coverage and update the scorecard. + +## Definition Of Done + +- Internal CMIS tests pass. +- OpenCMIS baseline completes with object/content cases executing beyond the + previous folder-creatable skip. +- New failures are classified by capability area and either fixed or documented + as unsupported by design. +- Documentation and State Hub reflect the evidence-backed maturity delta.