# 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.