generated from coulomb/repo-seed
Workplan reorg for queries, acl, rel envelopes
This commit is contained in:
242
workplans/KONT-WP-0016-cmis-read-side-contract-maturity.md
Normal file
242
workplans/KONT-WP-0016-cmis-read-side-contract-maturity.md
Normal file
@@ -0,0 +1,242 @@
|
||||
---
|
||||
id: KONT-WP-0016
|
||||
type: workplan
|
||||
title: "CMIS Read-Side Contract Maturity"
|
||||
domain: markitect
|
||||
repo: kontextual-engine
|
||||
status: active
|
||||
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: todo
|
||||
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: todo
|
||||
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: todo
|
||||
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: todo
|
||||
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: todo
|
||||
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: todo
|
||||
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: todo
|
||||
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.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user