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. | Complete; see `docs/cmis-read-side-contract.md`. |
| Tests | Full suite passes in the project venv. | `.venv/bin/python -m pytest -q` passed: `166 passed`, `15 skipped` in `42.23s`; advisory performance drift warnings recorded. |
| CMIS evidence | OpenCMIS selected baseline completes with no unexpected findings. | `run-20260514T003705Z` completed; object/content passed; 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. | Complete; scorecard updated for WP-0016 and `run-20260514T003705Z`. |
| Packaging | Version, dependencies, optional extras, and install smoke are checked. | Complete; sdist/wheel build and clean `[service]` install smoke passed. |
| Configuration | Storage backend, S3 settings, local blob path, and environment defaults are documented. | Complete; see `docs/release-security-configuration-storage-review.md`. |
| Data safety | Blob cleanup, backups, restore path, and migration posture are documented. | Complete for preview; backup/restore expectations documented in the release review and runbook. |
| Security | Actor headers, access-point profiles, secrets, and dependency/license review are done. | Complete for controlled preview; HTTPS/authenticated edge remains deployment requirement. |
| Operations | Health checks, logs, performance history, and known warnings are documented. | Complete; see `docs/release-runbook-0.1.0.md`. |
| State | State Hub consistency check passes after release docs/workplan updates. | Complete; State Hub consistency check passed with `0 fail`, `0 warn`, `0 info`. |

## 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.
- Optional `markdown` and `llm` extras point at sibling repositories in this
  workspace and are not part of the default/service install path.

## 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 packaging smoke: build wheel/sdist and import `kontextual_engine` from a
   clean install with the `[service]` extra.
4. Review security/configuration: HTTPS termination, profile exposure, secrets,
   local/S3 blob backend settings, and dependency licenses.
5. Update `CHANGELOG.md` or release notes with capabilities, known limitations,
   and accepted warnings.
6. Run State Hub consistency check and ensure workplans are registered.
7. Tag the release only after the gates above are green or explicitly waived.

## Release Decision

The current foundation is ready for a controlled `0.1.0` preview. No release
tag has been created by this workplan; tag creation remains a deliberate
operator action after reviewing the release notes and deployment target.

## Packaging Evidence

```text
python3 -m build --sdist --wheel --outdir /tmp/kontextual-release-smoke-20260514T010625Z/dist
```

Built artifacts:

- `kontextual_engine-0.1.0.tar.gz`
- `kontextual_engine-0.1.0-py3-none-any.whl`

Clean install smoke:

```text
/tmp/kontextual-release-smoke-20260514T010625Z/venv/bin/python \
  -m pip install /tmp/kontextual-release-smoke-20260514T010625Z/dist/kontextual_engine-0.1.0-py3-none-any.whl[service]

/tmp/kontextual-release-smoke-20260514T010625Z/venv/bin/python \
  -c "import kontextual_engine; from kontextual_engine import ServiceRuntime, create_app; app=create_app(ServiceRuntime()); print(kontextual_engine.__version__); print(app.title); print(hasattr(app.state, 'kontextual_runtime'))"
```

Smoke output:

```text
0.1.0
Kontextual Engine Service API
True
```