---
id: KONT-WP-0016
type: workplan
title: "CMIS Read-Side Contract Maturity"
domain: markitect
repo: kontextual-engine
status: completed
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: 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

```task
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

```task
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

```task
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

```task
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

```task
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

```task
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:

```text
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:

```text
.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:

```text
.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:

```text
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.