diff --git a/docs/cmis-compliance-assessment.md b/docs/cmis-compliance-assessment.md new file mode 100644 index 0000000..001ab31 --- /dev/null +++ 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. diff --git a/docs/cmis-compliance-test-foundation.md b/docs/cmis-compliance-test-foundation.md new file mode 100644 index 0000000..a96aebe --- /dev/null +++ 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. diff --git a/workplans/KONT-WP-0011-cmis-compliance-assessment-test-foundation.md b/workplans/KONT-WP-0011-cmis-compliance-assessment-test-foundation.md new file mode 100644 index 0000000..1c6d423 --- /dev/null +++ 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`. diff --git a/workplans/KONT-WP-0012-cmis-profiled-access-points.md b/workplans/KONT-WP-0012-cmis-profiled-access-points.md new file mode 100644 index 0000000..13d2222 --- /dev/null +++ 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.