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

24
docs/first-release-readiness.md
View File

@@ -29,6 +29,7 @@ Out of scope for `0.1.0`:
| Area | Gate | Current state |
| --- | --- | --- |
| CMIS read-side contract | Query, navigation, relationship, ACL, and change-token contracts are release-stable or explicitly waived. | `KONT-WP-0016` created as a pre-release dependency. |
| Tests | Full suite passes in the project venv. | `.venv/bin/python -m pytest -q` passed: `166 passed`, `14 skipped`; advisory performance drift warnings recorded. |
| CMIS evidence | OpenCMIS selected baseline completes with no unexpected findings. | `run-20260513T223537Z` completed; only local HTTP warning remains. |
| Transport | Released CMIS access points are served behind HTTPS. | Required deployment gate; local loopback warning is accepted only for harness runs. |
@@ -53,20 +54,23 @@ Out of scope for `0.1.0`:
## Release Procedure
1. Run `.venv/bin/python -m pytest -q`.
2. Run the OpenCMIS selected baseline through `guide-board` and persist the
1. Complete or explicitly waive `KONT-WP-0016`.
2. Run `.venv/bin/python -m pytest -q`.
3. Run the OpenCMIS selected baseline through `guide-board` and persist the
evidence document.
3. Run State Hub consistency check and ensure workplans are registered.
4. Run packaging smoke: build wheel/sdist and import `kontextual_engine` from a
4. Run State Hub consistency check and ensure workplans are registered.
5. Run packaging smoke: build wheel/sdist and import `kontextual_engine` from a
clean install.
5. Review security/configuration: HTTPS termination, profile exposure, secrets,
6. Review security/configuration: HTTPS termination, profile exposure, secrets,
local/S3 blob backend settings, and dependency licenses.
6. Update `CHANGELOG.md` or release notes with capabilities, known limitations,
7. Update `CHANGELOG.md` or release notes with capabilities, known limitations,
and accepted warnings.
7. Tag the release only after the gates above are green or explicitly waived.
8. Tag the release only after the gates above are green or explicitly waived.
## Release Decision
The current foundation is close to a controlled `0.1.0` preview. The main
remaining release work is not feature depth; it is discipline around repeatable
verification, packaging, deployment posture, and clearly documented limits.
The current foundation is close to a controlled `0.1.0` preview, but CMIS
read-side contracts should be settled before release if external projects will
build on the engine. After `KONT-WP-0016`, the remaining release work is mainly
discipline around repeatable verification, packaging, deployment posture, and
clearly documented limits.

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.