kontextual-engine/workplans/KONT-WP-0016-cmis-read-side-contract-maturity.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, depends_on_workplans, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	depends_on_workplans	state_hub_workstream_id
KONT-WP-0016	workplan	CMIS Read-Side Contract Maturity	markitect	kontextual-engine	completed	codex	markitect	high	15	2026-05-14	2026-05-14	KONT-WP-0014	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

id: KONT-WP-0016-T001
status: done
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

id: KONT-WP-0016-T002
status: done
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

id: KONT-WP-0016-T003
status: done
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

id: KONT-WP-0016-T004
status: done
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

id: KONT-WP-0016-T005
status: done
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

id: KONT-WP-0016-T006
status: done
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

id: KONT-WP-0016-T007
status: done
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.

Implementation Evidence

Implemented on 2026-05-14:

• Added docs/cmis-read-side-contract.md as the release-stable read-side contract.
• Replaced the query allowlist with a bounded parser for SELECT * document queries, AND predicates, equality, LIKE, IN, deterministic paging, and common CMIS ORDER BY.
• Kept descendants and folderTree explicitly unsupported with CMIS notSupported diagnostics and false capability flags.
• Added relationship target and either-direction filters, relationship change tokens, provenance, direction, actor, and creation metadata.
• Enriched ACL discovery with principal kind, direct/inherited markers, source, permission mapping, and policy authority metadata.
• Updated examples, the OpenCMIS subset map, scorecard, compliance assessment, and release readiness notes.
• Added opt-in capacity coverage in tests/cmis/test_cmis_read_side_capacity.py.

Focused verification:

python3 -m pytest \
  tests/cmis/test_cmis_runtime_browser_binding.py \
  tests/cmis/test_cmis_browser_binding_api.py \
  tests/cmis/test_cmis_compliance_flags.py \
  tests/cmis/test_cmis_contract_examples.py

Result: 21 passed, 16 skipped in 5.19s

The skipped tests require optional FastAPI/HTTPX test extras in this local environment. They remain part of the release verification gate when the service extras are installed.

Focused CMIS verification with service extras:

.venv/bin/python -m pytest \
  tests/cmis/test_cmis_browser_binding_api.py \
  tests/cmis/test_cmis_runtime_browser_binding.py \
  tests/cmis/test_cmis_compliance_flags.py \
  tests/cmis/test_cmis_contract_examples.py \
  -q

Result: 37 passed in 44.72s

Full suite verification with service extras:

.venv/bin/python -m pytest -q

Result: 166 passed, 15 skipped in 42.23s

The run emitted advisory performance-drift warnings for several API tests. They do not indicate functional failures and should be watched through the existing compact performance-history monitor.

OpenCMIS release-readiness assessment:

run-20260514T003705Z
Assessment: cmis-browser-baseline
Result: completed
Guide Board summary: 2 pass, 1 warning
Policy: 0 unexpected findings, 0 applied waivers

The first post-WP-0016 assessment run exposed an avoidable cmis:name child ordering warning after capabilityOrderBy=common was advertised. CMIS children are now sorted deterministically by cmis:name; the final persisted run has object-content passing and only the known local HTTP transport warning remaining. Evidence is persisted in docs/cmis-opencmis-tck-release-readiness-evidence-2026-05-14T003705Z.md.

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.