# Changelog
## 0.4.0.0 — 2026-08-17
### Breaking Changes
- `0012-relocate-projections-to-kioku-schema.sql` moves the seven Kioku-owned projections out of
the `kiroku` schema and into a dedicated `kioku` one, dropping the now-redundant name prefix:
`kiroku.kioku_memories` becomes `kioku.memories`, and likewise for `sessions`, `turns`,
`l1_watermarks`, `consolidation_decisions`, `scenes`, and `personas`. The shared Kiroku event
store does not move. `ALTER TABLE ... SET SCHEMA` plus `... RENAME TO` preserve each table's
OID, rows, indexes, constraints, owner, and grants; index and constraint names are deliberately
unchanged. The `vector` extension is not touched.
- The migration accepts exactly two catalog states — seven ordinary source tables with no occupied
target, or no source with seven ordinary targets — and raises before moving anything otherwise.
It is transactional, so a refusal leaves the catalog exactly as it was found. There are no
compatibility views: run it with writers stopped, before the new binary starts, and see
`docs/user/upgrading-to-the-kioku-schema.md`.
- The composed fresh-install plan is now 53 migrations: kiroku 11, keiro 30, kioku 12.
- Moved to `keiro-migrations ^>=0.13.0.0` and `kiroku-store-migrations ^>=0.4.0.0`. Those bring
eleven new framework migrations that Kioku composes but does not own: kiroku `0009` (the frozen
`kiroku.subscription_checkpoints_v1` view), `0010` (replay-history retention leases) and `0011`,
and keiro `0021`–`0030` (exact workflow discovery, then the schema-versioned projection rebuild,
promotion, and external-read-guard machinery). Keiro `0024` renames a rebuild-group column, so
complete or abandon any active catalog rebuild **before** upgrading.
- `kiroku-store-migrations` 0.4.0.0 corrects the payload of kiroku `0010`, which changes its
checksum. A database that already applied `0010` from the withdrawn 0.3.2.0 or 0.3.2.1 fails
every `up` and `verify` with `MigrationChecksumMismatch` until its ledger row is re-baselined
with that package's `ledger-fixups/2026-08-16-rebaseline-0010-checksum.sql`; kiroku `0011` then
converges its schema. A database that never reached `0010` — which is every database blocked by
the PostgreSQL 17 defect this release fixes — needs neither, and applies the corrected `0010`
as an ordinary pending migration.
### Added
- `0011-kioku-memory-space-partition.sql` adds a non-null `memory_space_id` to `kioku_memories`,
`kioku_sessions`, `kioku_turns`, `kioku_l1_watermarks`, `kioku_consolidation_decisions`,
`kioku_scenes`, and `kioku_personas`. Existing rows are backfilled into the explicit
`kioku_legacy` space; turns and watermarks derive theirs from their parent session, and the
migration aborts if any derived row disagrees with a session that exists.
### Breaking Changes
- `kioku_scenes` and `kioku_personas` now have composite primary keys,
`(memory_space_id, scene_id)` and `(memory_space_id, persona_id)`, and their scope-uniqueness
constraints gained the space. Their ids are derived from the namespace and scope alone, which
two spaces are allowed to share, so a single-column key let one space's upsert overwrite the
other's row. Stored id strings are unchanged.
- Indexes led by a namespace or a scope were rebuilt partition-first and renamed:
`kioku_memories_scope_idx` → `kioku_memories_space_scope_idx`, `kioku_memories_type_idx` →
`kioku_memories_space_type_idx` (now covering namespace as well), `kioku_sessions_scope_idx`,
`kioku_sessions_namespace_started_idx`, `kioku_sessions_namespace_focus_idx`,
`kioku_sessions_awaiting_corr_idx`, and `kioku_consolidation_scope_idx` likewise.
`kioku_memories_space_namespace_idx` is new. `kioku_scenes_scope_idx` is dropped as a strict
prefix of the per-space unique index.
- The migration is forward-only and has no down step. Re-running it is a no-op. Rolling the
application back is safe only while nothing has been written outside `kioku_legacy`.
## 0.3.0.0 — 2026-08-05
### Breaking Changes
- Raised `keiro-migrations` to `^>=0.11.0.0`. The bound is breaking because no single
`kioku-migrations` spans the Keiro 0.4 and 0.11 components, but the composed plan is not:
`keiro-migrations` ships the same 20 SQL files at 0.4.0.1 and 0.11.0.0, byte-for-byte, so
`kiokuMigrationPlan` still carries 38 forward migrations. Unlike 0.2.0.0, this release adds no
migration.
### Changed
- This is a code-only upgrade. A database already at kioku 0.2.0.0 has nothing to apply.
## 0.2.0.0 — 2026-07-30
### Breaking Changes
- Raised `keiro-migrations` to `^>=0.4.0.1`. Keiro's component gains two migrations, which the
composed `kiokuMigrationPlan` now carries:
`0019-keiro-snapshots-state-shape-hash.sql`, which adds a `state_shape_hash` column to
`keiro.keiro_snapshots`, and `0020-keiro-workflow-children-failure-reason.sql`, which adds a
nullable `failure_reason` column to Keiro's workflow-children table. Both are additive
`ALTER TABLE ... ADD COLUMN` statements on Keiro-owned tables that Kioku neither reads nor
writes. The plan's forward-migration total moves from 36 to 38.
### Deprecated
- `Kioku.Migrations.History.Codd` and the `codd-upgrade/` SQL fixups are deprecated. They are a
one-time bridge for databases whose schema evolution predates the pg-migrate cutover; a database
created by `kioku-migrate up` has never needed them. Removal is gated on the last codd-era
downstream database crossing over — as of this release that is Shikigami, tracked by its
`docs/plans/38-migrate-shikigami-database-evolution-from-codd-to-pg-migrate.md`. If you still
have a `codd.sql_migrations` table, cross over now: the bridge will be deleted, together with
everything listed in `codd-upgrade/README.md`, in a future release.
## 0.1.0.0 — 2026-07-14
### Added
- Added the initial ten-migration Kioku schema for memory and session event streams, read models,
embeddings, distillation artifacts, timers, delegation, and durable awaiting state.
- Added schema hardening and repair migrations for supersession chains, session indexes, scope
constraints, embedding columns, and collision-safe distillation identities.
- Added a checked migration manifest and a test that fails when compiled migration order falls out
of sync with the files on disk.
- Added `Kioku.Migrations.History.Codd`, which lets downstream databases import the pinned
30-migration Kiroku/Keiro/Kioku history into pg-migrate without replaying historical DDL.
- Shipped the reviewed Kiroku/Keiro ledger realignment and Keiro schema-relocation SQL used by the
downstream cutover runbook under `codd-upgrade/`.
- Added pg-migrate-backed ephemeral database test support while preserving the existing
`withKiokuMigratedDatabase` and `withBareDatabase` signatures.
### Fixed
- Made read-model registry migration logic locate `keiro_read_models` across supported cohort
layouts.
### Changed
- Upgraded the framework dependency baseline to Keiki 0.2, Keiro 0.3, Kiroku Store 0.3,
PGMQ 0.4, and pg-migrate 1.1. The project now resolves the released packages from Hackage and
no longer carries Git source overrides or migration-era `allow-newer` exceptions.
- Adapted Kioku's inline read models to Keiro 0.3's explicit `StrongScope` contract. They retain
`Eventual` consistency and declare `EntireLog` as the otherwise-unused strong-read scope.
- Added Kiroku 0.3's `KirokuStoreResource` to the application effect stack and write API
constraints so Keiro's transactional command runners preserve configured event-enrichment
hooks. `AppEnv.store` was replaced by `AppEnv.connectionSettings`; `runAppIO` now acquires the
resource and interprets `Store` through `runStoreResource`.
- Registered every Kioku read model during application startup, as required by Keiro 0.3's
explicit read-model lifecycle.
- Replaced the Codd-backed migration runner functions with the native pg-migrate
`kiokuMigrations` component and composed `kiokuMigrationPlan`. This is a breaking API change for
consumers of the removed `runKiokuMigrations`, `runKiokuMigrationsNoCheck`, and
`kiokuOwnMigrations` functions.
- Renamed Kioku's ten migration files to stable `NNNN-slug.sql` identities and made their explicit
manifest the source of apply order.
- Updated the composed migration plan to Keiro migrations 0.3, including Keiro migration 0018;
the current plan contains 36 migrations (Kiroku 8, Keiro 18, Kioku 10).