coulomb/kontextual-engine
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Workplan reorg for queries, acl, rel envelopes

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-14 01:32:35 +02:00
parent b3501b1ef1
commit b8ec86bcf7
4 changed files with 289 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
workplans/KONT-WP-0014-cmis-object-content-maturity.md
View File

@@ -4,7 +4,7 @@ type: workplan
title: "CMIS Object/Content Maturity Expansion"
domain: markitect
repo: kontextual-engine
status: active
status: completed
owner: codex
topic_slug: markitect
planning_priority: high
@@ -18,11 +18,11 @@ state_hub_workstream_id: "ccfa90ee-be23-499b-a727-451a0d289df7"
## Purpose
Raise the evidence-backed CMIS 1.1 Browser Binding maturity score in ways that
fit `kontextual-engine` naturally. The work should deepen object/content,
navigation, query, ACL, relationship, and change-log compatibility without
turning the engine into a generic ECM clone or duplicating native domain
services.
Raise the evidence-backed CMIS 1.1 Browser Binding object/content maturity
score in ways that fit `kontextual-engine` naturally. This workplan is now
closed around repository/type and object/content compatibility. Broader
read-side maturity for navigation, query, relationships, ACL discovery, and
change-token contracts has been split into `KONT-WP-0016`.
## Trigger
@@ -85,8 +85,6 @@ Disallowed architectural moves:
- CMIS Browser Binding object/content actions use standard selector/action
shapes while still delegating to native services.
- Content stream read/write behavior is more compatible and better documented.
- Natural navigation/query/read-side services improve without claiming full CMIS
optional capability support.
- The maturity scorecard is updated from fresh TCK evidence, with remaining
unsupported features explicitly classified.
@@ -240,9 +238,8 @@ Current external frontier:
- The selected OpenCMIS Browser Binding repository/type and object/content
baseline is completed with warnings only.
- The only remaining warning is local HTTP instead of HTTPS.
- Further maturity work should move to deliberately selected optional CMIS
areas: query depth, descendants/folder-tree read navigation, version-history
reads, relationship service depth, ACL detail, and rendition projection.
- Further maturity work has been split into `KONT-WP-0016` so read-side
contracts can be designed deliberately before first release.
## D14.1 - Define CMIS maturity boundary and TCK profile semantics
@@ -350,57 +347,37 @@ Progress:
whole-object append through the deduplicating representation service, with a
composed-size guard.
## D14.6 - Add natural navigation and query depth
## D14.6 - Transferred: natural navigation and query depth
```task
id: KONT-WP-0014-T006
status: in_progress
status: cancelled
priority: medium
state_hub_task_id: "b1562023-807b-4fed-b794-6930fcc2274e"
```
Acceptance:
Disposition:
- `getObjectByPath` and `getFolderParent` are added where they naturally map to
projection or workspace folder state.
- Shallow `getDescendants` support is added only if it can be implemented over
existing projection/workspace folder traversal without expensive graph scans.
- The query subset supports basic `WHERE` predicates and safe ordering for
indexed/available metadata fields, or returns precise unsupported diagnostics.
- Capability flags are updated only for behavior that is actually supported.
- Removed from WP-0014 active scope and transferred to `KONT-WP-0016`.
- Historical partial progress remains useful input for the new workplan:
`getObjectByPath`, `getFolderParent`, parent path segments, and folder rename
path stability are already implemented.
Progress:
- Done for `getObjectByPath`, `getFolderParent`, parent path segments, and
folder rename path stability.
- Remaining: query predicate/order depth and any deliberate descendants/tree
expansion.
## D14.7 - Polish read-side relationships, ACL discovery, and change tokens
## D14.7 - Transferred: relationships, ACL discovery, and change tokens
```task
id: KONT-WP-0014-T007
status: in_progress
status: cancelled
priority: medium
state_hub_task_id: "60f7b222-6eea-4add-822d-3439d568d4f6"
```
Acceptance:
Disposition:
- Relationship read services expose source/target filters and object envelopes
in Browser Binding-compatible shapes.
- ACL discovery exposes clearer principal, direct/inherited, and permission
mapping while policy gateway decisions remain authoritative.
- Durable-enough change tokens are defined for the current persistence layer.
- ACL mutation, policy mutation, PWC/versioning, and type mutability remain
unsupported unless a later task explicitly changes scope.
Progress:
- Started by isolating OpenCMIS change-token failures as the main T007 maturity
gap.
- Done for CMIS property/content mutation change-token conflict handling.
- Relationship and ACL discovery were not expanded in this pass.
- Removed from WP-0014 active scope and transferred to `KONT-WP-0016`.
- Historical partial progress remains useful input for the new workplan:
CMIS property/content mutation change-token conflict handling is already
implemented.
## D14.9 - Resolve OpenCMIS object/content blocker set
@@ -452,7 +429,7 @@ Acceptance:
4. Rerun `object-content` and classify concrete failures.
5. Improve content stream fidelity if failures or common-client expectations
point there.
6. Add navigation/query/read-side polish in small measured increments.
6. Transfer broader read-side maturity to `KONT-WP-0016`.
7. Expand TCK coverage and update the scorecard.
## Definition Of Done
@@ -460,6 +437,8 @@ Acceptance:
- Internal CMIS tests pass.
- OpenCMIS baseline completes with object/content cases executing beyond the
previous folder-creatable skip.
- New failures are classified by capability area and either fixed or documented
as unsupported by design.
- New object/content failures are classified by capability area and either
fixed or documented as unsupported by design.
- Documentation and State Hub reflect the evidence-backed maturity delta.
- Broader read-side maturity is tracked in `KONT-WP-0016` rather than remaining
open inside this object/content workplan.

8
workplans/KONT-WP-0015-first-release-readiness.md
View File

@@ -8,10 +8,12 @@ status: active
owner: codex
topic_slug: markitect
planning_priority: high
planning_order: 15
planning_order: 16
created: "2026-05-14"
updated: "2026-05-14"
state_hub_workstream_id: "cb525023-1139-4d6c-9226-d6fdd1f5fd8f"
depends_on_workplans:
- KONT-WP-0016
---
# KONT-WP-0015: First Release Readiness
@@ -28,6 +30,7 @@ reproducible, honest, operable, and easy to validate.
- `docs/cmis-1-1-capability-scorecard.md`
- `docs/cmis-opencmis-tck-release-readiness-evidence-2026-05-13T223537Z.md`
- `docs/blob-storage-content-streaming-workplan.md`
- `workplans/KONT-WP-0016-cmis-read-side-contract-maturity.md`
- `pyproject.toml`
- `tests/`
- `/home/worsch/guide-board`
@@ -38,7 +41,8 @@ reproducible, honest, operable, and easy to validate.
This workplan should harden the release envelope without changing the engine's
scope. CMIS remains a profiled Browser Binding adapter above native services.
Blob storage, policy, audit, and State Hub integration remain authoritative
release concerns.
release concerns. `KONT-WP-0016` is a pre-release dependency unless explicitly
waived for an internal-only release.
## D15.1 - Final Verification Pass

242
workplans/KONT-WP-0016-cmis-read-side-contract-maturity.md Normal file
View 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.