Crossexamination of utility based on the content management interoperability standard

2026-05-06 23:36:22 +02:00
parent a44b439cc7
commit 28420c68d1
4 changed files with 596 additions and 0 deletions
--- a/docs/cmis-compliance-assessment.md
+++ b/docs/cmis-compliance-assessment.md
@@ -0,0 +1,99 @@
+# CMIS Compliance Assessment
+
+Date: 2026-05-06
+
+Status: planning baseline for CMIS compliance and access-point implementation.
+
+## Reference Standard
+
+Target CMIS version: OASIS Content Management Interoperability Services
+Version 1.1, OASIS Standard, approved 23 May 2013, including approved errata
+where applicable.
+
+CMIS defines a domain model plus Web Services, AtomPub, and Browser JSON
+bindings for one or more content repositories. The standard explicitly allows a
+CMIS endpoint to expose more than one repository and does not require every
+underlying content-management feature to be represented through CMIS.
+
+## Reusable Validation Foundation
+
+Primary reusable validation candidate: Apache Chemistry OpenCMIS TCK and CMIS
+Workbench.
+
+OpenCMIS provides client libraries, server frameworks, development tools,
+InMemory/FileShare reference repositories, and TCK artifacts. The project pages
+now indicate the project is retired, so we should treat OpenCMIS as a legacy
+compatibility validation tool rather than a moving dependency. The Maven
+artifact `org.apache.chemistry.opencmis:chemistry-opencmis-test-tck:1.1.0`
+remains available and should be used as the first external conformance harness.
+
+Practical strategy:
+
+- Build local, deterministic example fixtures grouped by CMIS service
+  capability.
+- Build internal contract tests that validate our mapper and profile behavior
+  without Java tooling.
+- Add an optional external TCK harness that can run OpenCMIS TCK against a
+  running CMIS access point when Java/Maven are available.
+- Keep TCK execution optional in the default Python suite to avoid turning the
+  engine into a Java project.
+
+## Capability Assessment
+
+| CMIS capability | Current engine availability | Gap | Demand |
+| --- | --- | --- | --- |
+| Repository service | Service health/version, runtime repository state, capability catalogs. | Need CMIS repository info, repository IDs, root folder IDs, capability flags, type summaries. | Low |
+| Type definitions | Asset classifications, metadata schemas, relationship target kinds. | Need CMIS base types, property definitions, type mutability flags, secondary type projection. | Medium |
+| Navigation service | Relationships and context graph exist, but no folder tree model. | Need root folder, folder children, descendants/tree, parent relationships, path semantics. | High |
+| Object service read | Assets, metadata, representations, content refs, audit, versions exist. | Need CMIS object envelopes, allowable actions, path/object-id lookup, property filters, rendition/content stream response shape. | Medium |
+| Object service write | Asset create, metadata add, lifecycle transition, relationship create, ingestion. | Need createDocument/createFolder/updateProperties/deleteObject/moveObject mapping and CMIS change tokens. | High |
+| Content streams | Source, normalized, derived representations store content hashes and storage refs. | Need getContentStream/setContentStream/deleteContentStream/appendContentStream semantics and streaming endpoints. | Medium-High |
+| Versioning | Asset versions and transformation/workflow lineage exist. | Need CMIS checkout, PWC, checkin, cancelCheckout, version series semantics, latest/major flags. | High |
+| Discovery/query | Governed retrieval, lexical search, filters, relationships. | Need CMIS SQL-like query grammar or supported subset, query result shape, joins/capability flags. | High |
+| Relationships | Core relationships exist. | Need CMIS relationship object mapping and relationship type capability exposure. | Medium |
+| ACL service | Policy gateway and authorization decisions exist. | Need CMIS ACL model, principals, direct/inherited ACEs, applyACL, exact capability flags. | High |
+| Policy service | Policy decisions and governance reports exist. | Need CMIS policy objects/applyPolicy/removePolicy/getAppliedPolicies mapping or explicit unsupported profile. | Medium |
+| Change log | Audit events and correlation IDs exist. | Need CMIS change events, change tokens, object change entries, paging. | Medium |
+| Multi-filing/unfiling | Not modeled directly. | Need folder membership model or profile-level unsupported flags. | High if full support, Low if unsupported |
+| Renditions | Representations exist, no rendition taxonomy. | Need rendition metadata and stream mapping for thumbnails/previews. | Medium |
+| Retention and hold | Metadata/governance hooks exist, no first-class legal hold model. | Need retention/hold capabilities, apply/remove hold, retention date semantics. | High for full support |
+| Bulk update | Metadata update pathways exist. | Need bulkUpdateProperties semantics, partial failure reporting, change tokens. | Medium |
+| Browser JSON binding | FastAPI JSON service already exists. | Need CMIS Browser Binding routes, selectors/actions, multipart/content stream behavior. | High |
+| AtomPub binding | No AtomPub/XML binding. | Need XML/Atom feed generation and protocol semantics. | Very High |
+| Web Services binding | No SOAP stack. | Need WSDL/SOAP implementation. | Very High |
+
+## Recommended Compliance Profile Strategy
+
+Start with a constrained CMIS 1.1 Browser Binding profile:
+
+- Repository, type, object read, content stream read, query subset,
+  relationships, change log, and navigation over a synthetic root/folder
+  projection.
+- Explicitly unsupported or read-only: AtomPub, Web Services, full ACL mutation,
+  retention/hold, multifiling/unfiling, and full CMIS SQL joins.
+
+Then expand by profile:
+
+- `readonly-browser`: safe read-only repository and content access.
+- `governed-authoring`: selected object creation/update/content stream changes
+  through engine policy and audit.
+- `admin-export`: broad export and governance inspection, restricted to
+  service accounts.
+- `compat-tck`: profile tuned to pass a selected OpenCMIS TCK capability subset.
+
+## Risk Summary
+
+The engine already has strong foundations for asset identity, metadata,
+representations, relationships, versions, audit, policy, retrieval, and
+service APIs. The hard parts are not storage; they are CMIS protocol semantics:
+folder/path behavior, versioning/PWC semantics, CMIS query grammar, ACL shape,
+content stream actions, and binding-specific compatibility.
+
+Best estimate:
+
+- Internal mapper and examples: moderate.
+- Browser Binding MVP profile: medium-high.
+- TCK subset harness: medium.
+- Broad CMIS 1.1 Browser compliance: high.
+- AtomPub and Web Services compliance: very high and probably not justified
+  until a real client demands those bindings.
--- a/docs/cmis-compliance-test-foundation.md
+++ b/docs/cmis-compliance-test-foundation.md
@@ -0,0 +1,190 @@
+# CMIS Compliance Test Foundation
+
+Date: 2026-05-06
+
+Status: planned test foundation for CMIS access-point work.
+
+## Purpose
+
+Set up CMIS examples and compliance tests before implementation so the engine
+can compare required CMIS behavior with current capabilities and planned
+profiles.
+
+## External Harness
+
+Use Apache Chemistry OpenCMIS TCK 1.1.0 as an optional external conformance
+harness.
+
+Planned harness shape:
+
+- `tests/cmis/examples/` contains deterministic fixture descriptions grouped by
+  CMIS service capability.
+- `tests/cmis/test_cmis_contract_examples.py` validates mapper and profile
+  behavior without external Java dependencies.
+- `tests/cmis/opencmis-tck/` contains optional harness config, Maven
+  invocation notes, and selected TCK group mapping.
+- Default `pytest` skips external OpenCMIS TCK unless explicitly enabled.
+
+## Example Groups
+
+### Repository And Type Service
+
+Fixtures:
+
+- one repository profile with CMIS 1.1 Browser Binding,
+- one read-only profile,
+- one authoring profile,
+- base types for document, folder, relationship, policy, item, and secondary.
+
+Validates:
+
+- repository info,
+- capability flags,
+- type definitions,
+- property definitions,
+- unsupported capability flags are explicit.
+
+### Navigation Service
+
+Fixtures:
+
+- synthetic root folder,
+- folder projection by collection/topic/source system,
+- documents filed under one folder,
+- unfiled asset projection when profile allows it.
+
+Validates:
+
+- root folder children,
+- folder path lookup,
+- getChildren/getDescendants/getFolderTree,
+- profile restrictions on folder visibility.
+
+### Object And Content Stream Service
+
+Fixtures:
+
+- source document with content stream,
+- normalized representation,
+- derived representation,
+- metadata-rich document,
+- document with no stream.
+
+Validates:
+
+- getObject/getObjectByPath,
+- getProperties,
+- getContentStream,
+- create/update/delete behavior by profile,
+- content stream hash and media type mapping.
+
+### Versioning Service
+
+Fixtures:
+
+- single-version document,
+- multi-version document,
+- derived output linked to source version,
+- attempted checkout in read-only profile.
+
+Validates:
+
+- version series projection,
+- latest version flags,
+- checkout/checkin unsupported or supported per profile,
+- version history listing.
+
+### Discovery Query Service
+
+Fixtures:
+
+- lexical query examples,
+- metadata filter examples,
+- relationship-scoped query examples,
+- unsupported CMIS SQL features.
+
+Validates:
+
+- query capability flags,
+- supported subset behavior,
+- paging,
+- error diagnostics for unsupported grammar.
+
+### Relationship Service
+
+Fixtures:
+
+- asset-to-asset relationship,
+- asset-to-context-entity projection,
+- derived lineage relation.
+
+Validates:
+
+- relationship object projection,
+- source/target filters,
+- profile-level relationship visibility.
+
+### ACL And Policy Services
+
+Fixtures:
+
+- public asset,
+- internal asset,
+- confidential asset,
+- denied actor,
+- service-account actor.
+
+Validates:
+
+- allowable actions,
+- ACL projection,
+- applyACL/applyPolicy supported or unsupported by profile,
+- no protected metadata leakage on denial.
+
+### Change Log Events
+
+Fixtures:
+
+- asset create,
+- metadata update,
+- content update,
+- transformation output,
+- workflow run,
+- policy denial.
+
+Validates:
+
+- change tokens,
+- change event ordering,
+- correlation with audit records,
+- paging.
+
+### Retention Hold Renditions And Bulk Operations
+
+Fixtures:
+
+- retention metadata,
+- legal hold metadata,
+- preview/thumbnail representation,
+- bulk metadata update request.
+
+Validates:
+
+- explicit capability flags,
+- supported subset behavior,
+- structured unsupported-operation diagnostics.
+
+## Capability Profile Test Matrix
+
+| Profile | Expected external TCK posture |
+| --- | --- |
+| `readonly-browser` | Pass repository/type/read/navigation/query/content-read groups where supported; skip mutation groups. |
+| `governed-authoring` | Add selected create/update/delete/content stream checks with engine policy and audit. |
+| `admin-export` | Not intended as general CMIS client profile; focus internal contract tests. |
+| `compat-tck` | Tuned profile for OpenCMIS TCK subset and compatibility client smoke tests. |
+
+## Certification Note
+
+No current OASIS certification service was identified during planning. The
+practical reusable foundation is OpenCMIS TCK/Workbench, plus our own
+capability-profile contract tests.
--- a/workplans/KONT-WP-0011-cmis-compliance-assessment-test-foundation.md
+++ b/workplans/KONT-WP-0011-cmis-compliance-assessment-test-foundation.md
@@ -0,0 +1,138 @@
+---
+id: KONT-WP-0011
+type: workplan
+title: "CMIS Compliance Assessment And Test Foundation"
+domain: markitect
+repo: kontextual-engine
+status: active
+owner: codex
+topic_slug: markitect
+planning_priority: high
+planning_order: 11
+created: "2026-05-06"
+updated: "2026-05-06"
+state_hub_workstream_id: "c14d232c-cf80-443b-b5e0-76b51baf6676"
+---
+
+# KONT-WP-0011: CMIS Compliance Assessment And Test Foundation
+
+## Purpose
+
+Establish the CMIS compliance baseline before implementation. This workplan
+maps OASIS CMIS 1.1 capabilities to current engine functionality, organizes
+example fixtures by capability, and prepares internal and optional external
+compliance tests.
+
+## References
+
+- `docs/cmis-compliance-assessment.md`
+- `docs/cmis-compliance-test-foundation.md`
+- OASIS CMIS 1.1 standard and errata.
+- Apache Chemistry OpenCMIS TCK 1.1.0 and CMIS Workbench as optional external
+  validation tools.
+
+## Boundary
+
+This workplan does not implement CMIS access points. It creates the assessment,
+fixtures, profile matrix, and test harness that will govern implementation in
+`KONT-WP-0012`.
+
+## C11.1 - Freeze CMIS target version and reusable validation strategy
+
+```task
+id: KONT-WP-0011-T001
+status: todo
+priority: high
+state_hub_task_id: "1f4ed133-74f7-46df-9266-277813b5399a"
+```
+
+Acceptance:
+
+- CMIS target version, bindings, and errata posture are documented.
+- OpenCMIS TCK/Workbench reuse strategy is documented.
+- External harness is optional and does not block default Python tests.
+
+## C11.2 - Build capability assessment and demand estimate
+
+```task
+id: KONT-WP-0011-T002
+status: todo
+priority: high
+state_hub_task_id: "02651630-16e6-4c5f-879d-988a55fb7227"
+```
+
+Acceptance:
+
+- Capability-by-capability availability is documented.
+- Each CMIS area has a gap statement and implementation demand estimate.
+- High-risk areas are called out before implementation begins.
+
+## C11.3 - Create CMIS example fixture catalog grouped by capability
+
+```task
+id: KONT-WP-0011-T003
+status: todo
+priority: high
+state_hub_task_id: "a895218c-61b1-4944-8774-fd21c5416580"
+```
+
+Acceptance:
+
+- Example fixture groups cover repository/type, navigation, object/content,
+  versioning, discovery, relationships, ACL/policy, change log, renditions,
+  retention/hold, and bulk operations.
+- Fixtures declare expected behavior per profile.
+- Fixtures can seed both internal tests and external TCK preparations.
+
+## C11.4 - Add internal CMIS contract test skeleton
+
+```task
+id: KONT-WP-0011-T004
+status: todo
+priority: high
+state_hub_task_id: "710da9b6-2034-4948-8bc7-16230cc839cf"
+```
+
+Acceptance:
+
+- Internal tests validate CMIS mapper outputs independent of OpenCMIS.
+- Tests are organized by capability.
+- Unsupported capabilities assert explicit CMIS capability flags and structured
+  diagnostics.
+
+## C11.5 - Add optional OpenCMIS TCK harness plan
+
+```task
+id: KONT-WP-0011-T005
+status: todo
+priority: medium
+state_hub_task_id: "85b321a1-b9b5-469e-bc45-b207dc39ad7a"
+```
+
+Acceptance:
+
+- Optional Java/Maven harness configuration is documented.
+- TCK group selection is mapped to access-point profiles.
+- CI/default test suite skips TCK unless explicitly enabled.
+
+## C11.6 - Produce readiness gate for implementation
+
+```task
+id: KONT-WP-0011-T006
+status: todo
+priority: medium
+state_hub_task_id: "604e2f06-fde5-4d88-a13e-f3b725177696"
+```
+
+Acceptance:
+
+- A readiness checklist determines when `KONT-WP-0012` can start.
+- The checklist includes capability profile scope, fixture coverage, TCK
+  strategy, and known unsupported features.
+
+## Definition Of Done
+
+- CMIS capability assessment exists and is reviewed.
+- Example fixtures and internal test skeleton are organized by capability.
+- Optional OpenCMIS TCK strategy is ready.
+- Implementation proceeds only through the profile plan in `KONT-WP-0012`.
--- a/workplans/KONT-WP-0012-cmis-profiled-access-points.md
+++ b/workplans/KONT-WP-0012-cmis-profiled-access-points.md
@@ -0,0 +1,169 @@
+---
+id: KONT-WP-0012
+type: workplan
+title: "CMIS Profiled Access Points Implementation"
+domain: markitect
+repo: kontextual-engine
+status: active
+owner: codex
+topic_slug: markitect
+planning_priority: high
+planning_order: 12
+created: "2026-05-06"
+updated: "2026-05-06"
+state_hub_workstream_id: "d538d68f-17a8-401f-9cdc-d526dd734ddc"
+---
+
+# KONT-WP-0012: CMIS Profiled Access Points Implementation
+
+## Purpose
+
+Implement a CMIS API extension for `kontextual-engine` that can expose multiple
+CMIS access points. Each access point has a profile that regulates which CMIS
+capabilities are available, which data is visible, which mutations are allowed,
+and which data must never be exposed.
+
+## Requirement
+
+It must be possible to allow and expose multiple CMIS access points with
+different profiles that regulate:
+
+- which subset of CMIS capabilities are provided on the access point,
+- which engine data is accessible using the access point,
+- which data must not be exposed through the access point.
+
+## Dependency
+
+Implementation must begin after the assessment, examples, and test foundation
+from `KONT-WP-0011` are sufficient to define the first profile and regression
+suite.
+
+## Architecture Constraint
+
+CMIS routes are adapters over engine services and policy gates. They must not
+become a second domain model. Every CMIS access point resolves an
+`OperationContext`, applies profile rules, authorizes exposure/mutation, and
+emits audit events.
+
+## D12.1 - Define CMIS profile and access-point model
+
+```task
+id: KONT-WP-0012-T001
+status: todo
+priority: high
+state_hub_task_id: "031c3ce5-bb56-41fb-a014-6a496c280d20"
+```
+
+Acceptance:
+
+- Access-point config includes ID, repository ID, profile name, binding,
+  capability flags, visibility scope, deny rules, mutation policy, and actor
+  context requirements.
+- Profiles support read-only, governed authoring, admin/export, and TCK
+  compatibility variants.
+- Profile matching is deterministic and auditable.
+
+## D12.2 - Implement CMIS domain mapper
+
+```task
+id: KONT-WP-0012-T002
+status: todo
+priority: high
+state_hub_task_id: "a4c44471-22a9-40d9-9821-4b78e5ba9360"
+```
+
+Acceptance:
+
+- Engine assets map to CMIS documents/items.
+- Synthetic folders, paths, object IDs, properties, content streams,
+  relationships, versions, allowable actions, and change tokens are mapped.
+- Unsupported CMIS features are represented by correct capability flags and
+  structured errors.
+
+## D12.3 - Implement Browser Binding MVP access point
+
+```task
+id: KONT-WP-0012-T003
+status: todo
+priority: high
+state_hub_task_id: "b9f5d790-f291-4613-89da-5d47e7887a9e"
+```
+
+Acceptance:
+
+- Browser Binding routes expose repository info, types, navigation, object read,
+  content stream read, query subset, relationships, and change log.
+- Route behavior is profile-scoped.
+- Responses match CMIS Browser Binding expectations for the supported subset.
+
+## D12.4 - Implement governed authoring operations
+
+```task
+id: KONT-WP-0012-T004
+status: todo
+priority: high
+state_hub_task_id: "49716ca7-6a10-43ac-8ac5-ffa1c15b048e"
+```
+
+Acceptance:
+
+- Supported create/update/delete/content stream operations delegate through
+  engine services.
+- Mutations enforce policy, profile rules, version expectations, and audit.
+- Read-only profiles reject mutations with CMIS-compatible diagnostics.
+
+## D12.5 - Implement profile-scoped ACL policy and redaction
+
+```task
+id: KONT-WP-0012-T005
+status: todo
+priority: high
+state_hub_task_id: "64289d84-d7a2-4c03-8fa6-5f439bc233fe"
+```
+
+Acceptance:
+
+- Access points can hide assets by classification, owner, topic, lifecycle,
+  source system, metadata, actor, or policy decision.
+- Denied data is omitted rather than partially leaked.
+- ACL/allowable action projections reflect engine policy and profile rules.
+
+## D12.6 - Integrate CMIS compliance fixtures and optional OpenCMIS TCK
+
+```task
+id: KONT-WP-0012-T006
+status: todo
+priority: medium
+state_hub_task_id: "2f1e9075-395e-4ed0-9abd-ed7c4ecd774d"
+```
+
+Acceptance:
+
+- Internal CMIS tests run for every profile.
+- Optional OpenCMIS TCK can target a running CMIS access point.
+- TCK subset results are captured and mapped back to capability gaps.
+
+## D12.7 - Document deployment and compatibility posture
+
+```task
+id: KONT-WP-0012-T007
+status: todo
+priority: medium
+state_hub_task_id: "a1d28453-2ab7-4d18-8757-6f9ece1674b3"
+```
+
+Acceptance:
+
+- CMIS endpoint setup is documented.
+- Supported/unsupported CMIS capabilities are documented per profile.
+- Browser Binding MVP, AtomPub/Web Services deferral, OpenCMIS TCK posture, and
+  known client compatibility notes are explicit.
+
+## Definition Of Done
+
+- Multiple CMIS access points can be configured and exposed.
+- Each access point enforces profile-specific capability and data-visibility
+  rules.
+- Supported CMIS Browser Binding subset passes internal compliance tests.
+- Optional OpenCMIS TCK harness can be run against a compatibility profile.
+- `python3 -m pytest` passes.