diff --git a/docs/first-release-readiness.md b/docs/first-release-readiness.md index 2aa6373..6b0d39d 100644 --- a/docs/first-release-readiness.md +++ b/docs/first-release-readiness.md @@ -29,6 +29,7 @@ Out of scope for `0.1.0`: | Area | Gate | Current state | | --- | --- | --- | +| CMIS read-side contract | Query, navigation, relationship, ACL, and change-token contracts are release-stable or explicitly waived. | `KONT-WP-0016` created as a pre-release dependency. | | 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. | @@ -53,20 +54,23 @@ Out of scope for `0.1.0`: ## Release Procedure -1. Run `.venv/bin/python -m pytest -q`. -2. Run the OpenCMIS selected baseline through `guide-board` and persist the +1. Complete or explicitly waive `KONT-WP-0016`. +2. Run `.venv/bin/python -m pytest -q`. +3. 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 +4. Run State Hub consistency check and ensure workplans are registered. +5. Run packaging smoke: build wheel/sdist and import `kontextual_engine` from a clean install. -5. Review security/configuration: HTTPS termination, profile exposure, secrets, +6. 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, +7. 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. +8. 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. +The current foundation is close to a controlled `0.1.0` preview, but CMIS +read-side contracts should be settled before release if external projects will +build on the engine. After `KONT-WP-0016`, the remaining release work is mainly +discipline around repeatable verification, packaging, deployment posture, and +clearly documented limits. diff --git a/workplans/KONT-WP-0014-cmis-object-content-maturity.md b/workplans/KONT-WP-0014-cmis-object-content-maturity.md index 3f5fe22..2086c6f 100644 --- a/workplans/KONT-WP-0014-cmis-object-content-maturity.md +++ b/workplans/KONT-WP-0014-cmis-object-content-maturity.md @@ -4,7 +4,7 @@ type: workplan title: "CMIS Object/Content Maturity Expansion" domain: markitect repo: kontextual-engine -status: active +status: completed owner: codex topic_slug: markitect planning_priority: high @@ -18,11 +18,11 @@ state_hub_workstream_id: "ccfa90ee-be23-499b-a727-451a0d289df7" ## 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. +Raise the evidence-backed CMIS 1.1 Browser Binding object/content maturity +score in ways that fit `kontextual-engine` naturally. This workplan is now +closed around repository/type and object/content compatibility. Broader +read-side maturity for navigation, query, relationships, ACL discovery, and +change-token contracts has been split into `KONT-WP-0016`. ## Trigger @@ -85,8 +85,6 @@ Disallowed architectural moves: - 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. @@ -240,9 +238,8 @@ Current external frontier: - The selected OpenCMIS Browser Binding repository/type and object/content baseline is completed with warnings only. - The only remaining warning is local HTTP instead of HTTPS. -- Further maturity work should move to deliberately selected optional CMIS - areas: query depth, descendants/folder-tree read navigation, version-history - reads, relationship service depth, ACL detail, and rendition projection. +- Further maturity work has been split into `KONT-WP-0016` so read-side + contracts can be designed deliberately before first release. ## D14.1 - Define CMIS maturity boundary and TCK profile semantics @@ -350,57 +347,37 @@ Progress: whole-object append through the deduplicating representation service, with a composed-size guard. -## D14.6 - Add natural navigation and query depth +## D14.6 - Transferred: natural navigation and query depth ```task id: KONT-WP-0014-T006 -status: in_progress +status: cancelled priority: medium state_hub_task_id: "b1562023-807b-4fed-b794-6930fcc2274e" ``` -Acceptance: +Disposition: -- `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. +- Removed from WP-0014 active scope and transferred to `KONT-WP-0016`. +- Historical partial progress remains useful input for the new workplan: + `getObjectByPath`, `getFolderParent`, parent path segments, and folder rename + path stability are already implemented. -Progress: - -- Done for `getObjectByPath`, `getFolderParent`, parent path segments, and - folder rename path stability. -- Remaining: query predicate/order depth and any deliberate descendants/tree - expansion. - -## D14.7 - Polish read-side relationships, ACL discovery, and change tokens +## D14.7 - Transferred: relationships, ACL discovery, and change tokens ```task id: KONT-WP-0014-T007 -status: in_progress +status: cancelled priority: medium state_hub_task_id: "60f7b222-6eea-4add-822d-3439d568d4f6" ``` -Acceptance: +Disposition: -- 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. - -Progress: - -- Started by isolating OpenCMIS change-token failures as the main T007 maturity - gap. -- Done for CMIS property/content mutation change-token conflict handling. -- Relationship and ACL discovery were not expanded in this pass. +- Removed from WP-0014 active scope and transferred to `KONT-WP-0016`. +- Historical partial progress remains useful input for the new workplan: + CMIS property/content mutation change-token conflict handling is already + implemented. ## D14.9 - Resolve OpenCMIS object/content blocker set @@ -452,7 +429,7 @@ Acceptance: 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. +6. Transfer broader read-side maturity to `KONT-WP-0016`. 7. Expand TCK coverage and update the scorecard. ## Definition Of Done @@ -460,6 +437,8 @@ Acceptance: - 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. +- New object/content 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. +- Broader read-side maturity is tracked in `KONT-WP-0016` rather than remaining + open inside this object/content workplan. diff --git a/workplans/KONT-WP-0015-first-release-readiness.md b/workplans/KONT-WP-0015-first-release-readiness.md index 44476db..ef85889 100644 --- a/workplans/KONT-WP-0015-first-release-readiness.md +++ b/workplans/KONT-WP-0015-first-release-readiness.md @@ -8,10 +8,12 @@ status: active owner: codex topic_slug: markitect planning_priority: high -planning_order: 15 +planning_order: 16 created: "2026-05-14" updated: "2026-05-14" state_hub_workstream_id: "cb525023-1139-4d6c-9226-d6fdd1f5fd8f" +depends_on_workplans: + - KONT-WP-0016 --- # KONT-WP-0015: First Release Readiness @@ -28,6 +30,7 @@ reproducible, honest, operable, and easy to validate. - `docs/cmis-1-1-capability-scorecard.md` - `docs/cmis-opencmis-tck-release-readiness-evidence-2026-05-13T223537Z.md` - `docs/blob-storage-content-streaming-workplan.md` +- `workplans/KONT-WP-0016-cmis-read-side-contract-maturity.md` - `pyproject.toml` - `tests/` - `/home/worsch/guide-board` @@ -38,7 +41,8 @@ reproducible, honest, operable, and easy to validate. This workplan should harden the release envelope without changing the engine's scope. CMIS remains a profiled Browser Binding adapter above native services. Blob storage, policy, audit, and State Hub integration remain authoritative -release concerns. +release concerns. `KONT-WP-0016` is a pre-release dependency unless explicitly +waived for an internal-only release. ## D15.1 - Final Verification Pass diff --git a/workplans/KONT-WP-0016-cmis-read-side-contract-maturity.md b/workplans/KONT-WP-0016-cmis-read-side-contract-maturity.md new file mode 100644 index 0000000..cd31352 --- /dev/null +++ b/workplans/KONT-WP-0016-cmis-read-side-contract-maturity.md @@ -0,0 +1,242 @@ +--- +id: KONT-WP-0016 +type: workplan +title: "CMIS Read-Side Contract Maturity" +domain: markitect +repo: kontextual-engine +status: active +owner: codex +topic_slug: markitect +planning_priority: high +planning_order: 15 +created: "2026-05-14" +updated: "2026-05-14" +depends_on_workplans: + - KONT-WP-0014 +state_hub_workstream_id: "8783b411-3ad4-4f32-90eb-035b538c8156" +--- + +# KONT-WP-0016: CMIS Read-Side Contract Maturity + +## Purpose + +Stabilize the CMIS read-side contracts that are likely to become hard to +change after external projects start building on `kontextual-engine`. The goal +is not to implement a full ECM clone. The goal is to make navigation, query, +relationship, ACL discovery, and change-token behavior deliberate, bounded, +testable, and honest before first release. + +## Trigger + +`KONT-WP-0014` closed the object/content OpenCMIS frontier: the selected +`repository-type` and `object-content` baseline now completes with no +object/content warnings. Its remaining broader maturity topics were split out +because they shape public contracts and may drive later migration work if left +ambiguous. + +## References + +- `workplans/KONT-WP-0014-cmis-object-content-maturity.md` +- `workplans/KONT-WP-0015-first-release-readiness.md` +- `docs/cmis-1-1-capability-scorecard.md` +- `docs/cmis-compliance-assessment.md` +- `docs/cmis-compliance-test-foundation.md` +- `examples/cmis/capability-fixtures.json` +- `src/kontextual_engine/core/cmis.py` +- `src/kontextual_engine/api/app.py` +- `tests/cmis/` +- `/home/worsch/open-cmis-tck` +- `/home/worsch/guide-board` + +## Architecture Boundary + +CMIS remains an adapter and read-side projection over native engine concepts. +The engine's asset registry, policy gateway, relationship model, metadata +records, audit log, blob storage, and source-grounded identity remain +authoritative. + +Allowed architectural moves: + +- Introduce a small CMIS read-model boundary if it prevents CMIS-specific + parsing, filtering, or envelope logic from leaking into native services. +- Add bounded query parsing for a declared subset of CMIS SQL, mapped to native + indexed fields and metadata records. +- Add efficient read-only tree/navigation projections only where they can be + built from existing folder, path, relationship, or asset indexes. +- Enrich relationship and ACL projections without inventing an independent + CMIS permission model. +- Define stable change-token semantics for supported mutation and read-side + caching workflows. + +Disallowed architectural moves: + +- Do not implement AtomPub, Web Services, PWC/checkin/checkout, mutable CMIS + type systems, CMIS policy mutation, or a broad ECM filing model. +- Do not advertise `capabilityGetDescendants`, `capabilityGetFolderTree`, + `capabilityQuery`, ACL, or relationship behavior beyond what is implemented + and tested. +- Do not duplicate native retrieval, relationship, ACL, or policy logic inside + the CMIS adapter. +- Do not add unbounded graph scans or query paths that become capacity traps. + +## Sufficient Maturity Target + +This workplan is complete when controlled CMIS Browser Binding clients can rely +on stable, documented behavior for: + +- path and folder-parent reads, +- declared query subset grammar, predicates, sorting, paging, and unsupported + diagnostics, +- relationship object projection and source/target filtering, +- ACL discovery shape and principal/permission vocabulary, +- change-token generation and conflict expectations across supported + persistence backends, +- conservative capability flags that match the implemented behavior. + +The result should reduce future migration risk even if advanced CMIS services +remain intentionally unsupported. + +## D16.1 - Define the pre-release CMIS read-side contract + +```task +id: KONT-WP-0016-T001 +status: todo +priority: high +state_hub_task_id: "961bb720-0825-44d9-bb30-b6aed0f3f2cc" +``` + +Acceptance: + +- Document the release-stable Browser Binding read-side contract. +- Classify each read-side capability as supported, bounded subset, + projection-only, or unsupported. +- Define which behavior is release-stable and which remains experimental. +- Identify compatibility risks if projects build on the current shape. + +## D16.2 - Implement a bounded CMIS query subset + +```task +id: KONT-WP-0016-T002 +status: todo +priority: high +state_hub_task_id: "f393271e-4e0a-4a60-8570-2f2bc1d84c0f" +``` + +Acceptance: + +- Replace the current allowlist-style query handling with a small parser for a + declared CMIS SQL subset. +- Support only safe indexed or readily available fields, such as object type, + object id, name/title, asset type, lifecycle, sensitivity, owner, topics, and + selected metadata keys. +- Implement deterministic paging and, only if efficient, bounded ordering. +- Unsupported joins, full text, broad predicates, and unindexed sorts return + CMIS-shaped diagnostics without overclaiming capability flags. +- Tests cover accepted queries, rejected queries, paging, and ordering limits. + +## D16.3 - Decide and implement bounded navigation tree semantics + +```task +id: KONT-WP-0016-T003 +status: todo +priority: high +state_hub_task_id: "468221a0-111c-4a68-b0b2-392f83e5a70b" +``` + +Acceptance: + +- Decide whether `getDescendants` or `getFolderTree` should be supported for + release or remain explicitly unsupported. +- If supported, implement only bounded read-only projections over existing + workspace/projection folder state with depth, item-count, and profile gates. +- If unsupported, tighten capability flags and diagnostics so clients get clear + behavior. +- Capacity tests cover larger folder/path examples and avoid unbounded graph + traversal. + +## D16.4 - Stabilize relationship read-side projection + +```task +id: KONT-WP-0016-T004 +status: todo +priority: medium +state_hub_task_id: "86d117a8-f569-4708-8687-5a53e6210813" +``` + +Acceptance: + +- Relationship Browser Binding responses expose stable source/target ids, + relationship type, confidence, provenance, and visibility behavior. +- Source and target filters are supported where they map naturally to native + relationship indexes. +- Relationship creation remains unsupported unless a later workplan changes + scope. +- Tests cover protected relationship leakage, source filters, target filters, + and object envelope compatibility. + +## D16.5 - Stabilize ACL discovery projection + +```task +id: KONT-WP-0016-T005 +status: todo +priority: high +state_hub_task_id: "6214aac1-4b3a-41f8-9e61-ab6844171dd1" +``` + +Acceptance: + +- ACL discovery exposes a stable principal and permission vocabulary while the + native policy gateway remains authoritative. +- Direct versus inherited or synthetic permissions are explicit. +- `applyACL` remains unsupported unless a later workplan deliberately changes + the security model. +- Tests cover public, internal, confidential, denied actor, and service-account + examples. + +## D16.6 - Harden change-token and persistence compatibility + +```task +id: KONT-WP-0016-T006 +status: todo +priority: high +state_hub_task_id: "1f492036-0ba0-4a85-addb-b73397e9e966" +``` + +Acceptance: + +- Define change-token semantics across in-memory and durable repositories. +- Ensure supported property, content, folder, and relationship-affecting reads + have predictable cache/conflict behavior. +- Document migration implications if token generation changes later. +- Tests cover stale tokens, current tokens, copied objects, content tombstones, + and folder moves/renames. + +## D16.7 - Expand examples, capacity tests, and external assessment evidence + +```task +id: KONT-WP-0016-T007 +status: todo +priority: high +state_hub_task_id: "73d9b377-1f03-4e12-8028-af43496457b6" +``` + +Acceptance: + +- Update CMIS example data to exercise query, navigation, relationship, ACL, + and change-token scenarios. +- Add bottleneck-risk capacity tests for query and navigation over larger + examples. +- Expand Guide Board/OpenCMIS evidence where available and persist a timestamped + assessment. +- Update the CMIS scorecard and first-release readiness notes from the final + evidence. + +## Release Advice + +This workplan should run before `KONT-WP-0015` unless the first release is +strictly internal and no external project will depend on CMIS read-side +contracts. The reason is not the current OpenCMIS object/content score, which +is already strong enough for a controlled preview. The reason is contract +stability: query grammar, ACL vocabulary, relationship envelopes, and navigation +capability flags are the kinds of surfaces that become expensive to migrate +once projects have built integrations around them.