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:

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

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:

Stop the service or remove it from routing.
Preserve current logs, State Hub references, registry database, and blob root/bucket state for analysis.
Restore the previous package artifact and previous registry/blob snapshot.
Re-run /health, /ready, smoke import, and a small read/write scenario.
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.

3.7 KiB Raw Blame History