From 801d2f48517b44ad22fb9b1e64121ee6c8a90e53 Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 7 May 2026 02:04:59 +0200 Subject: [PATCH] deployment and compatibility --- docs/cmis-deployment-compatibility.md | 143 ++++++++++++++++++ ...s-profiled-access-points-implementation.md | 5 +- ...ONT-WP-0012-cmis-profiled-access-points.md | 5 +- 3 files changed, 150 insertions(+), 3 deletions(-) create mode 100644 docs/cmis-deployment-compatibility.md diff --git a/docs/cmis-deployment-compatibility.md b/docs/cmis-deployment-compatibility.md new file mode 100644 index 0000000..806e5c1 --- /dev/null +++ b/docs/cmis-deployment-compatibility.md @@ -0,0 +1,143 @@ +# CMIS Deployment And Compatibility + +Date: 2026-05-07 + +Status: Browser Binding MVP implemented with profiled access points. + +## Endpoint Setup + +Install the service dependencies and run the FastAPI application: + +```sh +python3 -m pip install -e '.[service]' +uvicorn kontextual_engine.api.app:create_app --factory --host 127.0.0.1 --port 8000 +``` + +The CMIS access-point catalog is available at: + +```text +GET /cmis +``` + +Each configured profile is exposed as a Browser Binding MVP access point: + +```text +GET /cmis/{access_point_id}/browser +GET /cmis/{access_point_id}/browser/types +GET /cmis/{access_point_id}/browser/children +GET /cmis/{access_point_id}/browser/object/{object_id} +GET /cmis/{access_point_id}/browser/content/{object_id} +GET /cmis/{access_point_id}/browser/acl/{object_id} +GET /cmis/{access_point_id}/browser/query +GET /cmis/{access_point_id}/browser/relationships +GET /cmis/{access_point_id}/browser/changes +POST /cmis/{access_point_id}/browser/document +POST /cmis/{access_point_id}/browser/object/{object_id}/properties +POST /cmis/{access_point_id}/browser/object/{object_id}/content +POST /cmis/{access_point_id}/browser/object/{object_id}/delete +``` + +Supported `access_point_id` values: + +- `readonly-browser` +- `governed-authoring` +- `admin-export` +- `compat-tck` + +Actor context is passed through the existing service headers, especially: + +- `X-Actor-Id` +- `X-Actor-Type` +- `X-Correlation-Id` +- `X-Request-Scope` +- `X-Policy-Scope` + +`admin-export` requires `X-Actor-Type: service_account`. + +## Profile Capability Matrix + +| Capability | readonly-browser | governed-authoring | admin-export | compat-tck | +| --- | --- | --- | --- | --- | +| Browser Binding repository info | yes | yes | yes | yes | +| Type definitions | yes | yes | yes | yes | +| Synthetic navigation | yes | yes | yes | yes | +| Object reads | yes | yes | yes | yes | +| Content stream descriptors | yes | yes | yes | yes | +| ACL projection | discover | discover | discover | discover | +| Relationship projection | yes | yes | yes | yes | +| Change log projection | yes | yes | yes | yes | +| Query subset | document select only | document select only | document select only | document select only | +| Create document | no | yes | no | yes | +| Update properties | no | yes | no | yes | +| Set content stream | no | yes | no | yes | +| Delete object | no | delete-request lifecycle transition | no | delete-request lifecycle transition | +| Confidential/restricted visibility | hidden | hidden | service-account visible | hidden | +| AtomPub binding | deferred | deferred | deferred | deferred | +| Web Services binding | deferred | deferred | deferred | deferred | + +## Supported Query Subset + +The MVP supports: + +```sql +SELECT * FROM cmis:document +SELECT * FROM kontextual:document +``` + +Unsupported query grammar returns structured validation diagnostics. Full CMIS +SQL joins and broader predicate parsing are intentionally deferred. + +## Compatibility Posture + +This implementation is a CMIS 1.1 Browser Binding MVP, not a broad CMIS +certification claim. It is suitable for: + +- clients that can consume JSON Browser Binding-style repository, type, object, + query, relationship, ACL, and change-log envelopes, +- controlled integrations that can target a specific profile, +- internal validation against deterministic fixtures, +- optional selected OpenCMIS TCK checks through `compat-tck`. + +It is not yet suitable for clients that require: + +- AtomPub, +- SOAP/Web Services, +- full CMIS SQL, +- multifiling/unfiling, +- private-working-copy semantics, +- retention/hold mutation, +- rendition streams, +- bulk update properties, +- apply/remove policy, +- strict byte-stream download semantics instead of content stream descriptors. + +## Optional OpenCMIS TCK + +The optional harness boundary lives in: + +- `tests/cmis/opencmis-tck/README.md` +- `tests/cmis/opencmis-tck/tck-subset-map.json` +- `tests/cmis/opencmis-tck/tck-result-template.json` + +Default Python tests validate the fixture/TCK mapping but do not execute +Java/Maven. Optional TCK runs should target: + +```text +http://127.0.0.1:8000/cmis/compat-tck/browser +``` + +Record results using the compact result template and map failures back to +capability groups before treating them as implementation bugs. + +## Operational Notes + +- Hidden objects should be treated as not found by CMIS clients. +- Relationship and change-log responses are filtered through the same visibility + gates as object reads. +- Mutations always pass through engine services and produce normal engine audit + events. +- Delete is currently a governed lifecycle transition to `delete_requested`, + not physical removal. +- Compatibility should be discussed per profile and per client rather than as a + repo-wide binary property. + diff --git a/docs/cmis-profiled-access-points-implementation.md b/docs/cmis-profiled-access-points-implementation.md index 4a21fd9..a1e4f08 100644 --- a/docs/cmis-profiled-access-points-implementation.md +++ b/docs/cmis-profiled-access-points-implementation.md @@ -2,7 +2,7 @@ Date: 2026-05-06 -Status: profile and mapper slices implemented. +Status: Browser Binding MVP implemented. ## Implemented Slice @@ -139,3 +139,6 @@ Java or Maven. Actual OpenCMIS TCK execution remains opt-in. Route-level tests are present but skip when the optional FastAPI/httpx service dependencies are not installed. Runtime-level Browser Binding tests cover the same behavior in the default Python test suite. + +Deployment and compatibility posture are documented in +`docs/cmis-deployment-compatibility.md`. diff --git a/workplans/KONT-WP-0012-cmis-profiled-access-points.md b/workplans/KONT-WP-0012-cmis-profiled-access-points.md index 0f65189..4d24bed 100644 --- a/workplans/KONT-WP-0012-cmis-profiled-access-points.md +++ b/workplans/KONT-WP-0012-cmis-profiled-access-points.md @@ -4,7 +4,7 @@ type: workplan title: "CMIS Profiled Access Points Implementation" domain: markitect repo: kontextual-engine -status: active +status: completed owner: codex topic_slug: markitect planning_priority: high @@ -41,6 +41,7 @@ suite. ## Implementation Notes - `docs/cmis-profiled-access-points-implementation.md` +- `docs/cmis-deployment-compatibility.md` - `src/kontextual_engine/core/cmis.py` - `tests/cmis/test_cmis_access_profiles.py` - `tests/cmis/test_cmis_domain_mapper.py` @@ -158,7 +159,7 @@ Acceptance: ```task id: KONT-WP-0012-T007 -status: todo +status: done priority: medium state_hub_task_id: "a1d28453-2ab7-4d18-8757-6f9ece1674b3" ```