kontextual-engine/docs/first-release-readiness.md

First Release Readiness

Date: 2026-05-14

Target posture: 0.1.0 controlled preview. This release can be good to go when it is honest, reproducible, observable, and recoverable. It does not need to pretend to be a full ECM or certified CMIS repository.

Release Scope

In scope:

• native asset registry, metadata, relationship, retrieval, transformation, workflow, service API, blob, S3-backend, and observability foundations,
• profiled CMIS Browser Binding subset for controlled integrations,
• OpenCMIS selected baseline for repository-type and object-content,
• explicit unsupported flags for out-of-scope CMIS capabilities,
• State Hub registered workplans and evidence documents.

Out of scope for 0.1.0:

• AtomPub and Web Services bindings,
• full CMIS SQL, checkout/checkin/PWC, policy mutation, retention/hold, renditions, and broad filing mutation,
• full ECM/records-management semantics,
• formal CMIS certification claim.

Go / No-Go Gates

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 implemented locally; full release verification still required.
Tests	Full suite passes in the project venv.	.venv/bin/python -m pytest -q passed: 166 passed, 15 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.
Capability honesty	Scorecard, unsupported catalog, and examples match behavior.	Updated for appendContentStream and WP-0016 read-side contract; final doc review required.
Packaging	Version, dependencies, optional extras, and install smoke are checked.	pyproject.toml is already 0.1.0; build/install smoke still required.
Configuration	Storage backend, S3 settings, local blob path, and environment defaults are documented.	Existing docs cover backends; release runbook should point to them.
Data safety	Blob cleanup, backups, restore path, and migration posture are documented.	Cleanup exists; backup/restore release notes still needed.
Security	Actor headers, access-point profiles, secrets, and dependency/license review are done.	Profile model exists; release security review still required.
Operations	Health checks, logs, performance history, and known warnings are documented.	Health and performance monitor exist; release runbook still needed.
State	State Hub consistency check passes after release docs/workplan updates.	Passed after WP-0015 registration.

Known Accepted Limitations

• CMIS Browser Binding is the supported external CMIS protocol surface.
• CMIS multifiling remains projection-only.
• CMIS append is implemented as whole-object append through deduplicating representation storage; chunk-level blob composition is deferred.
• Local OpenCMIS loopback runs warn about HTTP. This must not be carried into production-facing access points.
• Performance drift warnings from pytest are advisory unless repeated under a quiet system baseline; the current run flagged several CMIS API tests.

Release Procedure

1. Run .venv/bin/python -m pytest -q.
2. 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 clean install.
5. 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, and accepted warnings.
7. 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. With the KONT-WP-0016 read-side contract settled locally, the remaining release work is mainly discipline around repeatable verification, packaging, deployment posture, and clearly documented limits.