kontextual-engine/workplans/KONT-WP-0018-cmis-browser-binding-tck-compatibility.md

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
KONT-WP-0018	workplan	CMIS Browser Binding TCK Compatibility	communication	kontextual-engine	completed	codex	markitect	high	13	2026-05-08	2026-05-08	b21810fd-9a4e-58aa-8248-4acb30e51ac3

KONT-WP-0018: CMIS Browser Binding TCK Compatibility

Purpose

Turn the current CMIS-inspired adapter into a CMIS 1.1 Browser Binding surface that Apache Chemistry OpenCMIS can connect to and assess. The immediate goal is not full CMIS certification; it is to pass session creation and then drive repository/type plus object/content behavior from real TCK evidence.

Trigger

The 2026-05-08 live guide-board + open-cmis-tck run reached the endpoint, but OpenCMIS failed before semantic test cases could execute:

Found invalid Repository Info!

The result is persisted in docs/cmis-opencmis-tck-assessment-2026-05-08T063312Z.md.

References

• docs/cmis-opencmis-tck-assessment-2026-05-08T063312Z.md
• docs/cmis-opencmis-tck-implementation-evidence-2026-05-08T092113Z.md
• docs/cmis-1-1-capability-scorecard.md
• docs/cmis-compliance-assessment.md
• docs/cmis-profiled-access-points-implementation.md
• src/kontextual_engine/api/app.py
• src/kontextual_engine/core/cmis.py
• tests/cmis/test_cmis_browser_binding_api.py
• tests/cmis/test_cmis_runtime_browser_binding.py
• /home/worsch/open-cmis-tck/profiles/targets/kontextual-cmis-compat.json
• /home/worsch/open-cmis-tck/profiles/assessments/cmis-browser-baseline.json

Boundary

This workplan fixes Browser Binding compatibility for the profiled CMIS connector. It must not turn CMIS into a second domain model. Native engine DTOs, policy, blob handling, audit, and repository services remain authoritative; the CMIS layer translates those capabilities into standard protocol shapes.

AtomPub and Web Services remain unsupported by design. Mutating multifiling, PWC/versioning services, broad CMIS SQL, ACL mutation, policies, renditions, retention/hold, and bulk updates remain out of scope unless a later workplan adds them explicitly.

Desired Outcome

• OpenCMIS Browser Binding session creation succeeds against compat-tck.
• Repository/type TCK group executes and produces parsed cases instead of an infrastructure/protocol blocker.
• Object/content TCK group executes far enough to expose true semantic gaps.
• Internal CMIS route tests pass with service dependencies installed.
• Updated CMIS scorecard separates TCK-backed compatibility from native controlled-client usefulness.

Implementation Evidence

Completed on 2026-05-08 with final live run run-20260508T092113Z.

• Focused internal CMIS suite: 45 passed.
• Guide Board/OpenCMIS status: completed.
• Repository/type cases: 38 pass, 2 info, 2 skipped, 1 warning, 0 fail.
• Object/content cases: 22 skipped, 0 fail.
• Latest TCK preparation scorecard: 23.81, coverage 2/9.

The only remaining repository/type warning is local HTTP transport. The object/content skips are caused by the deliberate non-creatable cmis:folder profile boundary, not by a Browser Binding session failure.

F13.1 - Define Browser Binding protocol contract examples

id: KONT-WP-0018-T001
status: done
priority: high
state_hub_task_id: "eb7f85de-e533-5d3a-a4b7-d584b320b629"

Acceptance:

• Repository service document/repository-info examples are documented in the exact shape expected by OpenCMIS Browser Binding.
• Required field names, capability names, repository ID handling, root folder ID handling, and service URLs are covered.
• The examples include at least one valid compat-tck repository response and one invalid native-shaped response used as a negative preflight fixture.

F13.2 - Implement CMIS Browser Binding serializers

id: KONT-WP-0018-T002
status: done
priority: high
state_hub_task_id: "83268d05-a804-5010-83b5-483104c41758"

Acceptance:

• Repository info, capabilities, type definitions, object envelopes, property maps, content stream descriptors, ACL projections, and change entries are emitted through CMIS protocol serializers.
• Native snake_case DTOs are no longer exposed directly on Browser Binding compatibility routes.
• Serializer tests assert CMIS field names such as repositoryId, repositoryName, cmisVersionSupported, and rootFolderId.

F13.3 - Align target repository identity and access-point profile

id: KONT-WP-0018-T003
status: done
priority: high
state_hub_task_id: "dc43f8d2-5972-5caf-b90a-b472698381cf"

Acceptance:

• The compat-tck access point and open-cmis-tck target profile agree on the repository ID.
• If an alias is needed, it is explicit, deterministic, and documented.
• The port/profile assumptions for local TCK runs are documented without relying on accidental services already bound to port 8000.

F13.4 - Add protocol-shape preflight gates

id: KONT-WP-0018-T004
status: done
priority: high
state_hub_task_id: "45dfbe73-9474-56c5-b1a5-8f4fc30ed28b"

Acceptance:

• open-cmis-tck preflight fails native-shaped repository info before invoking Maven.
• The failure is classified as target protocol shape incompatibility, not a generic infrastructure error.
• The preflight reports actionable missing or misshaped fields.

Completion note: the engine-side protocol-shape regression is now covered by Browser Binding route tests and the live OpenCMIS run. A stronger negative preflight fixture belongs in the sister open-cmis-tck repository and remains a follow-up outside this repo's implementation boundary.

F13.5 - Fix OpenAPI generation for streaming routes

id: KONT-WP-0018-T005
status: done
priority: medium
state_hub_task_id: "8a2663b6-f36e-5e36-81da-f142a3a1e830"

Acceptance:

• /openapi.json renders successfully with CMIS byte-stream routes enabled.
• The route still returns a real streaming response at runtime.
• tests/cmis/test_cmis_browser_binding_api.py::test_cmis_browser_binding_routes_are_advertised_in_openapi passes with service dependencies installed.

F13.6 - Resolve navigation contract and root children behavior

id: KONT-WP-0018-T006
status: done
priority: medium
state_hub_task_id: "e386d9be-1ef4-58d1-9606-ca747c89f3b4"

Acceptance:

• Root folder behavior is explicitly defined for Browser Binding compatibility.
• Tests cover root children, synthetic folder children, projected parents, and hidden object filtering.
• Internal route tests and OpenCMIS expectations do not disagree about whether root returns only folders or direct documents.

F13.7 - Establish OpenCMIS session smoke test

id: KONT-WP-0018-T007
status: done
priority: high
state_hub_task_id: "0ac19507-39a3-5fc5-83fc-86b6f3e2b4c7"

Acceptance:

• A fast smoke check proves that OpenCMIS can list repositories and retrieve repository info before full TCK groups run.
• The smoke check is captured by guide-board/open-cmis-tck artifacts.
• Failure messages preserve the underlying OpenCMIS exception.

F13.8 - Rerun repository/type TCK group to parsed-case evidence

id: KONT-WP-0018-T008
status: done
priority: high
state_hub_task_id: "2488765f-5341-581f-81af-5097e8a9fa30"

Acceptance:

• repository-type no longer exits at session creation.
• Basics and Types test cases are parsed and mapped into normalized evidence.
• Any semantic failures become concrete follow-up tasks with capability labels.

F13.9 - Rerun object/content TCK group and classify gaps

id: KONT-WP-0018-T009
status: done
priority: high
state_hub_task_id: "0d7f8ba6-90f7-5ef5-8d3d-6558c2ef9a47"

Acceptance:

• object-content reaches parsed TCK cases.
• Failures are separated into supported-fix, unsupported-by-design, and profile expectation categories.
• Content stream read/write behavior is tested against both internal route tests and OpenCMIS expectations.

F13.10 - Update scorecard and compatibility documentation

id: KONT-WP-0018-T010
status: done
priority: medium
state_hub_task_id: "99fc4726-7890-50da-8e6a-ffead35f30a4"

Acceptance:

• docs/cmis-1-1-capability-scorecard.md is updated from TCK-backed evidence.
• The scorecard separates broad CMIS client compatibility from controlled native-profile usefulness.
• Deployment docs explain which CMIS clients are expected to work and which capabilities are honestly unsupported.

Definition Of Done

• Focused internal CMIS tests pass with service dependencies installed.
• OpenCMIS can establish a Browser Binding session against compat-tck.
• Repository/type TCK group produces parsed evidence.
• Object/content TCK group produces parsed evidence or documented unsupported-by-design gaps.
• Updated documentation clearly states the evidence-backed CMIS posture.

Follow-Up Boundary

The next CMIS decision is not another protocol-shape fix. It is whether to support CMIS createFolder in the compat-tck profile so OpenCMIS CRUD/content cases execute instead of skipping, or whether to keep those skips as an honest profile boundary until a client requires full CMIS CRUD scaffolding.