kontextual-engine/docs/cmis-read-side-contract.md

CMIS Read-Side Contract

Date: 2026-05-14 Workplan: KONT-WP-0016 Status: release-stable Browser Binding subset

Boundary

The CMIS layer is a connector projection over native kontextual-engine services. Native assets, classifications, metadata records, relationships, audit events, policy decisions, and blob representations remain authoritative. CMIS does not own a second object store, a separate ACL model, or an independent filing graph.

Release-Stable Capabilities

Capability	Release posture	Contract
Repository and type discovery	Supported	Browser Binding service document, repository info, base type definitions, and property definitions are stable. Optional unsupported features are declared in unsupported_features.
Navigation	Bounded supported subset	children, parent, parents, object, properties, allowableActions, policies, and content are supported through profile-gated folder/path projections.
Descendants and folder tree	Unsupported	descendants and folderTree return CMIS notSupported; repository flags remain false. This avoids creating a broad ECM tree contract before there is a native need.
Query	Bounded supported subset	SELECT * FROM cmis:document and SELECT * FROM kontextual:document support simple WHERE predicates joined by AND, deterministic paging, and common-property ordering.
Relationships	Supported read projection	Source, target, and either-direction filters map to the native relationship repository. Relationship objects expose source/target ids, predicate, confidence, direction, provenance, actor, and a stable relationship change token.
ACL discovery	Supported projection	getACL exposes direct actor permissions plus synthetic/public inheritance markers. The native policy gateway remains the authority; applyACL stays unsupported.
Change tokens	Supported for governed mutations	Asset cmis:changeToken is the current version id. Folder workspace tokens and relationship tokens are projection tokens. Stale asset mutation tokens map to CMIS updateConflict.

Query Subset

Accepted grammar:

SELECT * FROM cmis:document
SELECT * FROM kontextual:document
SELECT * FROM cmis:document WHERE <field> = '<value>' [AND ...]
SELECT * FROM cmis:document WHERE <text-field> LIKE '<pattern>' [AND ...]
SELECT * FROM cmis:document WHERE <multi-field> IN ('<value>', ...) [AND ...]
SELECT * FROM cmis:document ... ORDER BY <common-cmis-field> [ASC|DESC]

Filterable fields:

cmis:objectId, cmis:name, cmis:objectTypeId, cmis:baseTypeId, cmis:description, kontextual:assetId, kontextual:assetType, kontextual:sensitivity, kontextual:lifecycle, kontextual:owner, kontextual:topics, and kontextual:reviewState.

Orderable fields:

cmis:objectId, cmis:name, cmis:creationDate, and cmis:lastModificationDate.

Unsupported joins, OR, nested expressions, full text, arbitrary projection lists, and custom-property ordering return CMIS notSupported diagnostics with the supported grammar and field sets included.

Compatibility Notes

• capabilityQuery remains metadataonly.
• capabilityOrderBy is now common, not none, because common CMIS property ordering is implemented and covered by tests.
• Folder and document children are returned in deterministic cmis:name order to match the common-ordering claim.
• capabilityGetDescendants and capabilityGetFolderTree remain false.
• Multifiling remains projection-only. Mutation semantics are deliberately out of scope for this read-side contract.
• The ACL vocabulary is intentionally small: cmis:read, cmis:write, and cmis:delete, with direct, inherited, principal_kind, and source markers.

Evidence

Focused tests run on 2026-05-14:

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

Focused CMIS verification with optional 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

The default system-Python run skips Browser Binding API tests when FastAPI/HTTPX are unavailable and skips capacity probes unless KONTEXTUAL_RUN_CAPACITY=1 is set. The capacity probe exercises 400 documents and 250 relationships over query and target-filter paths, while relying on the shared performance history monitor for drift tracking.

OpenCMIS selected-baseline verification:

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

The only remaining OpenCMIS warning is local HTTP transport on the loopback harness. object-content passes after child projections were made deterministically ordered by cmis:name.