generated from coulomb/repo-seed
95 lines
4.4 KiB
Markdown
95 lines
4.4 KiB
Markdown
# 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.
|
|
- `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
|
|
```
|
|
|
|
Browser Binding API verification with optional service extras:
|
|
|
|
```text
|
|
.venv/bin/python -m pytest tests/cmis/test_cmis_browser_binding_api.py -q
|
|
|
|
Result: 16 passed in 39.09s
|
|
```
|
|
|
|
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.
|