generated from coulomb/repo-seed
321 lines
11 KiB
Markdown
321 lines
11 KiB
Markdown
---
|
|
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.
|