query parsing and diagnostics

docs/cmis-read-side-contract.md

@@ -0,0 +1,94 @@
+# 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.