v1.0.0 — first stable public developer release

Statewave v1.0 is the first stable public developer release of the open-source memory runtime that gives AI agents reproducible, provenance-tagged context. The v1 API contract (/v1/*) and the v0.9 governance surfaces (HMAC-signed receipts, replay, sensitivity labels with declarative policy, opt-in detector-suggested labels, per-region residency pinning) are now considered stable for developer use under a self-hosted deployment model. Limitations are documented in why-statewave.md; see v1.0-readiness-checklist.md for the full sign-off artefact.

What is stable in v1.0

• The /v1 API contract — backward-compatible additions only from here.
• The v0.9 governance surfaces — HMAC-signed state-assembly receipts, receipt-driven replay (current code + original policy), per-memory sensitivity labels + declarative YAML policy, opt-in detector-suggested labels, per-region data residency.
• Both SDKs at v1.0.0 — statewave (PyPI) and @statewavedev/sdk (npm), typed surfaces matching the REST contract, semver-stable from 1.0.0.
• Multi-replica API deployment — supported and verified since v0.8 (single-Postgres only).

What landed for v1.0

• Public GET /v1/version (#178).
• Python SDK governance helpers — list_suggested_labels() / promote_suggested_labels() (#176).
• session_id on create_episode in both SDKs (#174).
• Webhook delivery stats + tenant scoping; a correctness lap across admin / receipts / conflicts / backup / embeddings / snapshots surfaces.

What v1.0 does NOT promise

Carried forward honestly from why-statewave.md: not load-tested at >10k subjects; single-Postgres only (no cross-region clustering); app-layer tenant isolation (no Postgres RLS yet); no second-region failover; no admin-action identity (promoted_by); LLM-vs-heuristic compiler eval not yet published. Not "GA", not "production-ready", not "battle-tested", not "enterprise-ready".

Full notes: release-notes/v1.0-launch.md.

Statewave v0.9.2 — version-consistency & SDK-readiness patch

Small stabilization patch on top of the canonical v0.9 governance release (v0.9.1). No new backend features, no API changes, no schema migrations. Operators upgrading v0.9.1 → v0.9.2 should expect zero functional difference.

What changes in this server release

• pyproject.toml bumped from 0.9.0 to 0.9.2 (#171) — closes the pyproject/tag drift introduced when 0.9.0 was bumped ahead of the actual v0.9 work. Both the v0.9.0 (stub, superseded) and v0.9.1 (canonical) tags reported 0.9.0 from pip show statewave; v0.9.2 closes that drift so pip show statewave reports a version matching the published tag.

That is the entire server-side change. Zero code, schema, or behaviour difference vs. v0.9.1.

Coordinated companion PRs in the same stabilization patch

These ship as additive patch releases on their own repos:

• statewave-py v0.10.1 (closes #169) — adds verify_receipt(receipt_id) and replay_receipt(receipt_id) to both StatewaveClient (sync) and AsyncStatewaveClient (async) with typed Pydantic return models (ReceiptVerifyResult, ReceiptReplayResult) and a dedicated StatewaveUnreplayableError(reason) for HTTP 422 refusal codes. README governance section refreshed; PyPI Development Status Alpha → Beta.
• statewave-ts v0.10.1 (closes #170) — adds verifyReceipt(receiptId) and replayReceipt(receiptId) to StatewaveClient. The Receipt interface gains the v0.9 governance fields (policySnapshot, receiptSignatureAlgorithm, plus region if missing) and a discriminated StatewaveUnreplayableError mirrors the Python error type. Version-aligned with statewave-py v0.10.1.
• statewave-examples — corrects try-it.sh install command: pip install statewave-py (the GitHub repo name) → pip install statewave (the published package name).
• statewave-web — refreshes three stale v0.9-era strings: ProductPage auto-labeling description ("planned" → "shipped"), llms-full.txt Governance version tag (v0.8 → v0.8+), proof-figure counts where re-counted locally against current main. No broader proof-figure sweep in this patch.

Out of scope (explicit)

No new backend features. No admin identity, bulk label promotion, visual policy editor, federated cross-region audit, second-region deployment, RLS, byte-for-byte replay, or proof-figure workspace-wide sweep — all deferred to later v0.9.x patches or post-1.0 per the v0.9.x → v1.0 roadmap.

Upgrade

pip install --upgrade statewave==0.9.2 or docker pull statewavedev/statewave:0.9.2. Zero migrations to run; database state is unchanged from v0.9.1.

For SDK upgrade, wait for statewave-py / statewave-ts v0.10.1 (landing alongside this server release).

Statewave v0.9.1 — v0.9 governance release correction

v0.9.0 was cut too early and does not contain the full v0.9 governance stack. v0.9.1 is the canonical v0.9 governance release.

What v0.9 delivers

Receipts, auto-labeling, replay, and residency — the v0.8 governance foundation extended into an end-to-end audit story:

• Scheduled retention-purge worker (#162, closes #156) — hourly worker reads tenant_configs.config.receipt_retention_days and tombstones expired receipts. Soft-delete only; partial index keeps it cheap. Migration 0020.
• HMAC-signed receipts (#163, closes #157) — hmac-sha256-canonical-v1 over the canonical receipt body. Operator-provided keys via STATEWAVE_RECEIPT_SIGNING_KEYS (never persisted to DB). GET /v1/receipts/{id}/verify returns {valid: true | false | null, key_id, algorithm, reason} with constant-time compare. Pre-v0.9 receipts verify cleanly as no_signature. Migration 0021.
• Heuristic auto-labeling pipeline (#164, closes #158) — opt-in STATEWAVE_AUTO_LABELING_ENABLED stamps advisory suggested_labels (strictly separate from authoritative sensitivity_labels). v0.9 first wave: pii.email, pii.phone, financial.card (Luhn), secret.token. Migration 0022 (GIN-indexed).
• Receipt replay (#165, closes #159) — every v0.9+ receipt embeds the active policy bundle's YAML in policy_snapshot. POST /v1/receipts/{id}/replay re-runs the original retrieval against current memories with the original policy, returning a structural diff envelope. Mode "as_of_replay", child receipts link to the parent. Semantic: current code + original policy. Migration 0023.
• Admin review/promote/replay UI (#166 + statewave-admin#89, closes #160) — POST /admin/memories/{id}/promote-labels is review-only with audit-trail entries on memory.metadata.label_promotions. Admin app gains a /suggested-labels page and a Replay button on receipt detail that renders the diff envelope inline.
• Per-tenant residency (#167, closes #161) — STATEWAVE_REGION + tenant_configs.config.region. Hard application-layer enforcement on /v1/ AND /admin/ (total isolation). HTTP 403 residency.mismatch on conflict. Receipts stamp region for end-to-end audit. Code + config + tests + ops runbook shipped.
• Handoff replay symmetry (#168) — /v1/handoff receipts now stamp the same policy_snapshot as retrieval receipts; both paths are replayable through the same endpoint. Pre-fix handoff receipts remain backwards-compatible and return unreplayable.missing_policy_snapshot.
• Release-hardening docs sweep — #168 (server README + receipt/replay docs) + statewave-docs#45 (changelog, roadmap, receipts, sensitivity-labels, api/v1-contract, ADR-001 Postgres positioning) + statewave-admin#90 (admin app README + sidebar v0.9 footer).

API surface added (no breaking changes)

Endpoint	Purpose
GET /v1/receipts/{id}/verify	HMAC signature verification
POST /v1/receipts/{id}/replay	As-of replay against current memories + original policy
POST /admin/receipts/{id}/replay	Admin-proxy shim mirroring the public endpoint
GET /admin/memories/with-suggested-labels	Review queue for auto-labeling suggestions
POST /admin/memories/{id}/promote-labels	Explicit operator commit of suggestions into sensitivity_labels

Migrations (additive, reversible)

0020_receipts_retention · 0021_receipts_signature_keyid · 0022_memories_suggested_labels · 0023_receipts_policy_snapshot

DB head moves from 0019_per_tenant_bundles (v0.8) to 0023_receipts_policy_snapshot (v0.9.1). No data backfill required; pre-v0.9 rows carry NULL on the new columns and remain fully functional.

Backwards compatibility

• Pre-v0.9 receipts verify as no_signature and refuse replay with unreplayable.missing_policy_snapshot — same contract as a fresh tenant that hasn't opted into signing.
• Pre-fix handoff receipts (emitted between v0.9 ship and #168) carry NULL policy_snapshot and remain backwards-compatible: /v1/receipts/{id}/replay returns unreplayable.missing_policy_snapshot for them.
• No breaking API changes beyond the new endpoints listed above.

Deferred to v0.10

Visual policy editor · Admin identity (so promoted_by populates) · Bulk label promotion · Federated cross-region audit · Memory snapshots for byte-for-byte replay. Listed explicitly in CHANGELOG.md, roadmap.md, and the server README's Current limitations.

Why v0.9.1 instead of moving v0.9.0

The published v0.9.0 tag (at e51a553) and its GitHub release predate the v0.9 governance work. Moving a published tag breaks anyone who already consumed it; cutting an additive v0.9.1 preserves immutability of published tags while making the canonical v0.9 release point at the actual v0.9 commit (4036f4f).

v0.9.0

⚠️ Superseded by v0.9.1. This tag was cut before the final v0.9 governance PRs landed; use v0.9.1 for the complete v0.9 release. The notes below reflect the original commit at e51a553, which predates the actual v0.9 governance stack (retention purge, HMAC-signed receipts, suggested labels, receipt replay, admin review/promote/replay UI, residency tenant pinning, and handoff replay symmetry — all of which land in v0.9.1).

---

What's Changed

• docs(readme): launch-week hardening — text-only changes by @smaramwbc in #98
• chore: align workspace version to v0.9.0 by @smaramwbc in #105
• ci: release gate verifies server/contract self-consistency only (#106) by @smaramwbc in #109
• docs(readme): make Run the server Docker-only by @smaramwbc in #110
• Fix schema check ignoring STATEWAVE_DATABASE_URL from .env by @cowboy823 in #108
• Adjust STATEWAVE_API_KEY placeholder in docker-compose.yml by @Wangbocheng75 in #113
• fix(compiler): anchor relative dates to the episode's real timestamp (#115) by @smaramwbc in #118
• fix(context): flag when no stored context is relevant to the task (#116) by @smaramwbc in #119
• feat(docker): add support for host port overrides in local development by @MiriamDiazH in #120
• fix(api): enforce one canonical subject_id contract at every ingress (#121) by @smaramwbc in #123
• fix(llm): warn on startup and clarify /readyz when LITELLM API key is… by @cowboy823 in #107
• fix(llm): don't flag missing API key for local Ollama models (#62 follow-up) by @smaramwbc in #125
• fix(api): apply the canonical id contract to session_id (#124) by @smaramwbc in #126
• feat(server): /readyz distinguishes DB not-set / unparseable / unreachable (#66) by @smaramwbc in #127
• docs(readme): add understated star CTA under the tagline by @smaramwbc in #128
• feat(bootstrap): auto-import demo-agent packs on fresh server start by @smaramwbc in #129
• docs(img): add mobile How Statewave works diagrams by @VLK-123 in #130
• docs(readme): serve mobile diagram variants at narrow viewports by @smaramwbc in #132
• docs(readme): add Skip to Quickstart heading-link after Try it by @smaramwbc in #133
• fix(compile): drain async jobs to completion; sync returns has_more (#134) by @smaramwbc in #135
• docs(readme): point top jump-link to Documentation section by @smaramwbc in #136
• docs: correct /readyz wording, mark LLM key optional in DOCKER.md by @smaramwbc in #151
• feat(webhooks): add event-type allowlist for webhook delivery by @smaramwbc in #150
• feat(templates): add memory templates for common patterns by @smaramwbc in #152
• chore(deps): update uvicorn requirement from <1,>=0.29 to >=0.47.0,<1 by @dependabot[bot] in #141
• chore(deps): update structlog requirement from <26,>=24.1 to >=25.5.0,<26 by @dependabot[bot] in #144
• chore(deps): update opentelemetry-exporter-otlp requirement from <2,>=1.41.1 to >=1.42.0,<2 by @dependabot[bot] in #142
• chore(deps): update ruff requirement from <1,>=0.4 to >=0.15.13,<1 by @dependabot[bot] in #143
• chore(deps): update litellm requirement from <2,>=1.84.0 to >=1.85.1,<2 by @dependabot[bot] in #148
• chore(deps): update alembic requirement from <2,>=1.13 to >=1.18.4,<2 by @dependabot[bot] in #146
• chore(deps): update pyyaml requirement from <7,>=6 to >=6.0.3,<7 by @dependabot[bot] in #140
• chore(deps): update tiktoken requirement from <1,>=0.12.0 to >=0.13.0,<1 by @dependabot[bot] in #149
• chore(deps): update opentelemetry-sdk requirement from <2,>=1.41.1 to >=1.42.1,<2 by @dependabot[bot] in #145
• chore(deps): update sqlalchemy requirement from <3,>=2.0 to >=2.0.49,<3 by @dependabot[bot] in #147
• docs: align v0.8 shipped state by @smaramwbc in #153

New Contributors

• @cowboy823 made their first contribution in #108
• @Wangbocheng75 made their first contribution in #113
• @MiriamDiazH made their first contribution in #120
• @VLK-123 made their first contribution in #130

Full Changelog: https://github.com/smaramwbc/statewave/commits/v0.9.0

v0.8.0

What's Changed

• perf(memory-packs): kill redundant LLM recompile on starter-pack import by @smaramwbc in #69
• feat: bi-temporal anchor + temporal-grounded compile + granular detail extraction + async-compile embedding backfill by @smaramwbc in #71
• chore: bump README status to v0.7.2 by @smaramwbc in #74
• ci: gate release on cross-repo version consistency by @smaramwbc in #75
• feat: state-assembly receipts (#49) by @smaramwbc in #72
• feat: sensitivity labels & per-memory policy bindings (#50) by @smaramwbc in #76
• fix(policy): drop in-process bundle cache — multi-replica staleness by @smaramwbc in #77
• fix(admin): /admin/policy/active returns 200 + null when no bundle active by @smaramwbc in #78
• feat(admin): tenant-config write endpoint — closes the #50 enforce-mode API gap by @smaramwbc in #80
• feat(policy): composite (tenant_id, bundle_hash) uniqueness — closes #79 by @smaramwbc in #81
• release: v0.8.0 — governance & audit layer by @smaramwbc in #82
• fix(docs): v0.8 README limitations — version + multi-node + retention by @smaramwbc in #83

Full Changelog: v0.7.2...v0.8.0

v0.7.2

What's Changed

• Dual licensing model + auto-bootstrap support docs pack by @smaramwbc in #10
• fix(quickstart): idempotent docs-pack bootstrap logs the skip outcome by @smaramwbc in #11
• feat(starter-packs): expand 5 demo packs into multi-session story arcs by @smaramwbc in #17
• feat(docs-pack): add subject-design.md to support-pack allowlist by @smaramwbc in #18
• fix(docs-pack): raise compile-step client timeout for full LLM rebuilds by @smaramwbc in #19
• feat(support-pack): build the bundled pack from the docs corpus by @smaramwbc in #20
• feat(support-pack): version-aware auto-update with selective purge by @smaramwbc in #21
• feat(docs-pack): add comparisons/* to support-pack allowlist by @smaramwbc in #22
• fix: backfill embeddings for imported memories by @smaramwbc in #23
• feat(support-pack): rebuild bundled pack with current LLM compiler by @smaramwbc in #25
• feat(admin): purge endpoints for terminal compile jobs + webhook events by @smaramwbc in #26
• feat(support-pack): split combined SDK install memory into focused pip + npm by @smaramwbc in #28
• feat(starter-packs): expand demo personas with denser narrative content by @smaramwbc in #29
• refactor(server): drop silent fallbacks in compile + embedding paths by @smaramwbc in #30
• fix: single-source the project version + bump-version script by @smaramwbc in #32
• chore(ci): bump actions/github-script from 7 to 9 by @dependabot[bot] in #31
• fix(health): detect recurring issues against per-resolved-session text by @smaramwbc in #35
• chore(eval): move eval_docs_support from statewave-examples by @smaramwbc in #34
• chore: update postgres eval README link by @smaramwbc in #36
• ci(docker): publish statewavedev/statewave to Docker Hub + GHCR by @smaramwbc in #41
• ci(docker): auto-sync DOCKER.md to Docker Hub repo description by @smaramwbc in #42
• ci(docker): tolerate Docker Hub description sync failure by @smaramwbc in #43
• feat(docs-pack): include connectors/*.md in support-pack manifest by @smaramwbc in #44
• feat(compose): add admin service to default compose stack by @smaramwbc in #45
• fix(compose): ship ADMIN_AUTH_DISABLED=true as a dev default by @smaramwbc in #46
• docs(readme): refresh connector status table + drop "coming soon" caveat by @smaramwbc in #47
• feat(episodes): add first-class occurred_at column for source-event time by @smaramwbc in #48
• fix(context): lexical-overlap bonus so semantic+keyword matches clear kind/recency floor by @smaramwbc in #51
• ci(fly): add auto-deploy workflow for statewave-api on push to main by @smaramwbc in #52
• fix(bootstrap-docs): retry purge/ingest/compile on transient API failures by @smaramwbc in #53
• fix(health): preserve non-ASCII tokens in keyword overlap detection by @smaramwbc in #54
• fix(security): sanitize starter-pack manifest errors before returning to API caller by @smaramwbc in #55
• ci(docker-publish): bump all actions to Node 24-compatible majors by @smaramwbc in #56
• feat(helm): add API-only Helm chart at helm/statewave (v0.7) by @smaramwbc in #58
• feat(memory): per-kind TTL with retrieval filter + cleanup tombstoning (v0.7) by @smaramwbc in #59
• docs: refresh connector status table — Tier 2 push-receiver wave shipped by @smaramwbc in #60

New Contributors

• @smaramwbc made their first contribution in #10

Full Changelog: v0.7.1...v0.7.2

v0.7.1

What's Changed

• chore(ci): bump github/codeql-action from 3 to 4 by @dependabot[bot] in #7
• chore(ci): bump actions/checkout from 4 to 6 by @dependabot[bot] in #5
• chore(ci): bump actions/setup-python from 5 to 6 by @dependabot[bot] in #2
• chore(ci): bump softprops/action-gh-release from 2 to 3 by @dependabot[bot] in #3
• chore(deps): update pytest requirement from <9,>=8 to >=8,<10 by @dependabot[bot] in #9
• chore(deps): update structlog requirement from <25,>=24.1 to >=24.1,<26 by @dependabot[bot] in #4

New Contributors

• @dependabot[bot] made their first contribution in #7

Full Changelog: v0.7.0...v0.7.1

v0.7.0: Admin Dashboard API

Features

• Complete Admin API for dashboard support — comprehensive endpoints for operational monitoring
• Subject health monitoring — health scoring with configurable thresholds
• Session timeline and resolution tracking — visualize conversation flow
• Compile job monitoring — stuck job detection and retry capabilities
• Webhook event listing and statistics — delivery tracking with dead letter queue
• Enhanced SLA calculations — null-safe metrics computation

Fixes

• Fixed ResolutionRow metadata column mapping
• Fixed session_count calculation from episodes.session_id

Breaking Changes

None — all changes are additive.

Upgrade Notes

Run migrations before deploying: alembic upgrade head

v0.5.0

Full Changelog: v0.4.3...v0.5.0

v0.4.3

Full Changelog: v0.4.0...v0.4.3