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:

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

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

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

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:

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