Release readiness polish

docs/release-runbook-0.1.0.md

@@ -0,0 +1,115 @@
+# Release Runbook 0.1.0
+
+Date: 2026-05-14
+Release posture: controlled preview
+
+## Purpose
+
+This runbook defines the repeatable checks and operator expectations for the
+`kontextual-engine` `0.1.0` controlled preview. It is a release envelope, not a
+new product scope.
+
+## Preflight
+
+Run from `/home/worsch/kontextual-engine`:
+
+```sh
+.venv/bin/python -m pytest -q
+python3 -m build --sdist --wheel --outdir /tmp/kontextual-release-smoke-20260514T010625Z/dist
+```
+
+Expected evidence for this pass:
+
+- full suite: `166 passed`, `15 skipped`,
+- package build: `kontextual_engine-0.1.0.tar.gz` and
+  `kontextual_engine-0.1.0-py3-none-any.whl`,
+- clean install smoke: wheel plus `[service]` extra imports
+  `kontextual_engine`, creates `create_app(ServiceRuntime())`, and attaches
+  `app.state.kontextual_runtime`.
+
+## CMIS Evidence
+
+Run the selected OpenCMIS Browser Binding baseline through `guide-board` and
+`open-cmis-tck`. On this workstation, use port `8010` for the temporary engine
+endpoint because port `8000` is already occupied by another local service.
+
+Current accepted evidence:
+
+- run: `run-20260514T003705Z`,
+- assessment: `cmis-browser-baseline`,
+- result: completed,
+- policy: `0` unexpected findings and `0` waivers,
+- object/content: pass,
+- only warning: local HTTP loopback transport.
+
+The local HTTP warning is accepted only for harness runs. Preview deployments
+must serve production-facing CMIS access points behind HTTPS termination.
+
+## Runtime Start
+
+The app is currently exposed as a FastAPI factory:
+
+```sh
+PYTHONPATH=src .venv/bin/uvicorn 'kontextual_engine.api.app:create_app' \
+  --factory \
+  --host 127.0.0.1 \
+  --port 8010
+```
+
+For deployment, instantiate `ServiceRuntime` with explicit durable repository,
+blob storage, and policy gateway adapters instead of relying on the default
+in-memory runtime.
+
+## Health And Observability
+
+Required operator checks:
+
+- `/health` returns process health.
+- `/ready` returns readiness for the configured runtime.
+- `/version` returns the service version.
+- `/openapi.json` is available when the service extra is installed.
+- Pytest performance history is retained under
+  `.pytest_cache/kontextual/performance-history.json` during development runs.
+
+Performance drift warnings are advisory unless reproduced under a quiet system
+baseline. Keep the compact history file for trend awareness; use dedicated
+profiling experiments for detailed performance investigations.
+
+## Data Safety
+
+Preview deployments must define:
+
+- registry persistence location and backup schedule,
+- blob backend and backup or bucket-versioning strategy,
+- restore rehearsal for registry plus blob content,
+- retention policy for raw assessment artifacts and logs,
+- rollback point before migrations or adapter changes.
+
+For SQLite-backed previews, stop writes before copying the database or use a
+SQLite backup method. For local blob storage, back up the whole content-addressed
+root. For S3, enable bucket versioning or equivalent object protection and back
+up IAM/policy configuration alongside data.
+
+## Rollback
+
+Rollback for `0.1.0` preview means:
+
+1. Stop the service or remove it from routing.
+2. Preserve current logs, State Hub references, registry database, and blob
+   root/bucket state for analysis.
+3. Restore the previous package artifact and previous registry/blob snapshot.
+4. Re-run `/health`, `/ready`, smoke import, and a small read/write scenario.
+5. Record the rollback reason in State Hub before resuming external traffic.
+
+## Tag Gate
+
+Do not create the release tag until:
+
+- full venv tests pass,
+- OpenCMIS selected baseline is persisted,
+- package build and clean install smoke pass,
+- security/config/storage review is current,
+- State Hub consistency is clean,
+- release notes are updated.
+
+No tag is created by this runbook automatically.