Workplan reorg for queries, acl, rel envelopes

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`.
+1. Complete or explicitly waive `KONT-WP-0016`.
-2. Run the OpenCMIS selected baseline through `guide-board` and persist the
+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 State Hub consistency check and ensure workplans are registered.
-4. Run packaging smoke: build wheel/sdist and import `kontextual_engine` from a
+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
+The current foundation is close to a controlled `0.1.0` preview, but CMIS
-remaining release work is not feature depth; it is discipline around repeatable
+read-side contracts should be settled before release if external projects will
-verification, packaging, deployment posture, and clearly documented limits.
+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.

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
+Raise the evidence-backed CMIS 1.1 Browser Binding object/content maturity
-fit `kontextual-engine` naturally. The work should deepen object/content,
+score in ways that fit `kontextual-engine` naturally. This workplan is now
-navigation, query, ACL, relationship, and change-log compatibility without
+closed around repository/type and object/content compatibility. Broader
-turning the engine into a generic ECM clone or duplicating native domain
+read-side maturity for navigation, query, relationships, ACL discovery, and
-services.
+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
+- Further maturity work has been split into `KONT-WP-0016` so read-side
-  areas: query depth, descendants/folder-tree read navigation, version-history
+  contracts can be designed deliberately before first release.
-  reads, relationship service depth, ACL detail, and rendition projection.
 
 ## 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
+- Removed from WP-0014 active scope and transferred to `KONT-WP-0016`.
-  projection or workspace folder state.
+- Historical partial progress remains useful input for the new workplan:
-- Shallow `getDescendants` support is added only if it can be implemented over
+  `getObjectByPath`, `getFolderParent`, parent path segments, and folder rename
-  existing projection/workspace folder traversal without expensive graph scans.
+  path stability are already implemented.
-- 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.
 
-Progress:
+## D14.7 - Transferred: relationships, ACL discovery, and change tokens
-
-- 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
 
 ```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
+- Removed from WP-0014 active scope and transferred to `KONT-WP-0016`.
-  in Browser Binding-compatible shapes.
+- Historical partial progress remains useful input for the new workplan:
-- ACL discovery exposes clearer principal, direct/inherited, and permission
+  CMIS property/content mutation change-token conflict handling is already
-  mapping while policy gateway decisions remain authoritative.
+  implemented.
-- 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.
 
 ## 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
+- New object/content failures are classified by capability area and either
-  as unsupported by design.
+  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.

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
 

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.