@zq-silk/yui 0.14.1 → 0.15.0

package/dist/storage/sqliteSchema.js

@@ -8,26 +8,20 @@
  *
  *   - `global_sequences` (§5.3): global record ID high-water marks.
  *   - `outbox` (§5.4): durable outbox with `UNIQUE(request_id)` for exactly-once.
- *   - `config`: the `YuiConfig` singleton (the design keeps `home_meta` for
- *     identity/revision/versions; config is a separate singleton).
+ *   - `config`: the `YuiConfig` singleton (`home_meta` keeps identity/revision).
  *
  * Record payloads are stored two ways, per §4: typed columns for fields that are
  * queried/filtered/used-for-CAS, and a `payload` JSON column holding the full
- * versioned record (including its family `schemaVersion`). The record axis of
- * the three-axis versioning is therefore unchanged.
+ * current record. Record-local `schemaVersion` tags remain validation guards;
+ * they are not independent Home compatibility axes. Any historical payload
+ * rewrite belongs to the ordered Home migration that introduced the new shape.
  *
- * The migration runner is idempotent: it records applied versions in
- * `schema_migrations` and uses `CREATE TABLE IF NOT EXISTS`, so re-running on an
- * already-current database is a no-op and a crash mid-migration is rolled back
- * by SQLite (DDL is transactional) and re-applied on the next open.
+ * The migration runner is append-only and idempotent: it records one ordered
+ * Home version in `schema_migrations`. Re-running an already-current database
+ * is a no-op; a crash mid-upgrade rolls the whole migration transaction back.
  */
 import { createHash } from "node:crypto";
-/** The current SQLite layout version. */
-export const SQLITE_LAYOUT_VERSION = 8;
-/** The aggregate version of the normalized SQLite schema. */
-export const SQLITE_AGGREGATE_VERSION = 2;
-/** The current schema migration version. */
-export const SQLITE_SCHEMA_VERSION = 1;
+import { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION } from "./storageVersions.js";
 /** Telemetry retention bounds (§4.4). Open question 3 in §11; defaults from the design. */
 export const TELEMETRY_KEEP_PER_GENERATION = 200;
 export const TELEMETRY_TURN_CAP = 50_000;
@@ -38,20 +32,19 @@ export const TELEMETRY_TURN_CAP = 50_000;
  * the store; `journal_mode=WAL` is a persistent database property set on open.
  * The migration itself only contains schema objects.
  *
- * This is the direct current baseline for a new Home. Its checksum rejects any
- * database initialized from a different physical contract.
+ * This is the Yui 0.15.0 / storage-version-1 baseline. Future releases append
+ * migrations after it so fresh and upgraded databases converge on the same
+ * current contract.
  */
 const BASELINE_CORE_SQL = `
 -- Global catalog and coordination (§4.1) -------------------------------------
 
 CREATE TABLE IF NOT EXISTS home_meta (
-  id                INTEGER PRIMARY KEY CHECK (id = 1),
-  home_identity     TEXT NOT NULL,
-  revision          INTEGER NOT NULL,
-  layout_version    INTEGER NOT NULL,
-  aggregate_version INTEGER NOT NULL,
-  created_at        TEXT NOT NULL,
-  updated_at        TEXT NOT NULL
+  id            INTEGER PRIMARY KEY CHECK (id = 1),
+  home_identity TEXT NOT NULL,
+  revision      INTEGER NOT NULL,
+  created_at    TEXT NOT NULL,
+  updated_at    TEXT NOT NULL
 );
 
 CREATE TABLE IF NOT EXISTS config (
@@ -460,29 +453,11 @@ BEGIN
     AND turn_id = NEW.turn_id AND generation = NEW.generation;
 END;
 `;
-/**
- * Cross-Round semantic review
- * findings with stable keys and Leader dispositions. Failed execution attempts
- * never create rows; only completed Rounds feed the ledger.
- */
-const BASELINE_REVIEW_FINDING_SQL = `
-CREATE TABLE IF NOT EXISTS review_findings (
-  task_id     TEXT NOT NULL,
-  finding_id  TEXT NOT NULL,
-  stable_key  TEXT NOT NULL,
-  severity    TEXT NOT NULL,
-  payload     TEXT NOT NULL,
-  updated_at  TEXT NOT NULL,
-  PRIMARY KEY (task_id, finding_id)
-);
-CREATE INDEX IF NOT EXISTS idx_review_findings_task ON review_findings(task_id);
-CREATE INDEX IF NOT EXISTS idx_review_findings_stable_key ON review_findings(task_id, stable_key);
-`;
 /**
  * Session owner physical identity records.
  *
- * One row per runtime generation, keyed by launch id. The payload column
- * stores the full versioned JSON record; typed columns support the
+ * One row per runtime generation, keyed by runtime generation id. The payload column
+ * stores the full current JSON record; typed columns support the
  * reconciliation queries (task/role lookup, PID liveness).
  */
 const BASELINE_SESSION_OWNER_SQL = `
@@ -503,9 +478,8 @@ CREATE INDEX IF NOT EXISTS idx_session_owners_task
 /**
  * Resource GC registry.
  *
- * GC-owned table for resource lifecycle records.  The registry is GC's own
- * state — it is not part of the aggregate and never participates in aggregate
- * versioning.  Records are stored as full versioned JSON in `payload`, with
+ * GC-owned table for resource lifecycle records. The registry is GC's own
+ * state. Records are stored as full current JSON in `payload`, with
  * typed columns for the fields GC queries (disposition, kind, task_id).
  */
 const BASELINE_RESOURCE_REGISTRY_SQL = `
@@ -671,7 +645,6 @@ const MIGRATION_1_SQL = [
     BASELINE_JOB_AND_RELEASE_SQL,
     BASELINE_JOB_CALLER_SQL,
     BASELINE_TELEMETRY_AGGREGATE_SQL,
-    BASELINE_REVIEW_FINDING_SQL,
     BASELINE_SESSION_OWNER_SQL,
     BASELINE_RESOURCE_REGISTRY_SQL,
     BASELINE_GATE_ARTIFACT_SQL,
@@ -680,10 +653,26 @@ const MIGRATION_1_SQL = [
     BASELINE_TASK_WAKE_SQL,
     BASELINE_CONTEXT_SNAPSHOT_SQL
 ].join("\n");
-/** Future compatible releases append new migrations after this baseline. */
-const MIGRATIONS = [
-    { version: 1, axis: "layout", sql: MIGRATION_1_SQL }
-];
+/** Released migrations are append-only and must never be rewritten. */
+const MIGRATIONS = Object.freeze([
+    {
+        version: 1,
+        name: "v0.15.0-baseline",
+        introducedIn: "0.15.0",
+        sql: MIGRATION_1_SQL
+    }
+]);
+for (let index = 0; index < MIGRATIONS.length; index += 1) {
+    const expectedVersion = MIN_SUPPORTED_STORAGE_VERSION + index;
+    if (MIGRATIONS[index]?.version !== expectedVersion) {
+        throw new Error(`Storage migration registry must be contiguous from `
+            + `${MIN_SUPPORTED_STORAGE_VERSION}; missing version ${expectedVersion}.`);
+    }
+}
+if (MIGRATIONS.at(-1)?.version !== CURRENT_STORAGE_VERSION) {
+    throw new Error(`Storage migration registry head ${String(MIGRATIONS.at(-1)?.version)} does not match `
+        + `CURRENT_STORAGE_VERSION ${CURRENT_STORAGE_VERSION}.`);
+}
 /** Current hot-path indexes whose absence would invalidate a current Home. */
 const REQUIRED_SCHEMA_INDEXES = [
     "idx_mailboxes_ready",
@@ -707,11 +696,10 @@ export class SqliteSchemaMigrationError extends Error {
 }
 const SCHEMA_MIGRATIONS_SQL = `
     CREATE TABLE schema_migrations (
-      version     INTEGER PRIMARY KEY,
-      axis        TEXT NOT NULL CHECK (axis IN ('layout','aggregate','record')),
-      record_kind TEXT,
-      applied_at  TEXT NOT NULL,
-      checksum    TEXT NOT NULL
+      version    INTEGER PRIMARY KEY,
+      name       TEXT NOT NULL,
+      applied_at TEXT NOT NULL,
+      checksum   TEXT NOT NULL
     )
   `;
 /**
@@ -739,10 +727,20 @@ function ensureMigrationLedger(db, mode) {
     }
     return false;
 }
-/** Validate the applied prefix and return its versions for the migration loop. */
+function validateMigrationLedgerColumns(db) {
+    const columns = new Set(db.prepare("PRAGMA table_info(schema_migrations)").all()
+        .flatMap(({ name }) => typeof name === "string" ? [name] : []));
+    if (columns.size === 4
+        && ["version", "name", "applied_at", "checksum"].every((name) => columns.has(name))) {
+        return;
+    }
+    throw new SqliteSchemaMigrationError("schema_migrations columns do not match the storage-version-1 ledger");
+}
+/** Validate the applied linear prefix and return its current head. */
 function validateAppliedMigrations(db, ledgerWasCreated) {
+    validateMigrationLedgerColumns(db);
     const expected = new Map(MIGRATIONS.map((migration) => [migration.version, migration]));
-    const rows = db.prepare("SELECT version, axis, record_kind, checksum FROM schema_migrations ORDER BY version").all();
+    const rows = db.prepare("SELECT version, name, checksum FROM schema_migrations ORDER BY version").all();
     if (rows.length === 0 && !ledgerWasCreated) {
         throw new SqliteSchemaMigrationError("schema_migrations ledger is empty in an existing database");
     }
@@ -753,19 +751,22 @@ function validateAppliedMigrations(db, ledgerWasCreated) {
         }
         const version = row.version;
         const migration = expected.get(version);
-        if (migration === undefined) {
-            throw new SqliteSchemaMigrationError(`unknown migration version ${version}`);
-        }
         if (applied.has(version)) {
             throw new SqliteSchemaMigrationError(`duplicate migration version ${version}`);
         }
         applied.add(version);
-        const expectedRecordKind = migration.recordKind ?? null;
-        if (row.axis !== migration.axis) {
-            throw new SqliteSchemaMigrationError(`migration ${version} axis ${String(row.axis)} does not match ${migration.axis}`);
+        if (migration === undefined) {
+            if (version <= CURRENT_STORAGE_VERSION) {
+                throw new SqliteSchemaMigrationError(`unknown migration version ${version}`);
+            }
+            if (typeof row.name !== "string" || row.name.length === 0
+                || typeof row.checksum !== "string" || row.checksum.length === 0) {
+                throw new SqliteSchemaMigrationError(`future migration ${version} metadata is invalid`);
+            }
+            continue;
         }
-        if (row.record_kind !== expectedRecordKind) {
-            throw new SqliteSchemaMigrationError(`migration ${version} record_kind ${String(row.record_kind)} does not match ${String(expectedRecordKind)}`);
+        if (row.name !== migration.name) {
+            throw new SqliteSchemaMigrationError(`migration ${version} name ${String(row.name)} does not match ${migration.name}`);
         }
         const expectedChecksum = checksum(migration.sql);
         if (row.checksum !== expectedChecksum) {
@@ -774,12 +775,18 @@ function validateAppliedMigrations(db, ledgerWasCreated) {
     }
     const versions = [...applied].sort((left, right) => left - right);
     for (let index = 0; index < versions.length; index += 1) {
-        const expectedVersion = index + 1;
+        const expectedVersion = MIN_SUPPORTED_STORAGE_VERSION + index;
         if (versions[index] !== expectedVersion) {
             throw new SqliteSchemaMigrationError(`migration ledger has a gap before version ${versions[index]}`);
         }
     }
-    return applied;
+    const currentVersion = versions.at(-1) ?? 0;
+    const head = rows.at(-1);
+    return {
+        versions: applied,
+        currentVersion,
+        currentChecksum: typeof head?.checksum === "string" ? head.checksum : ""
+    };
 }
 /**
  * Validate the physical objects promised by the migration ledger.  Ledger
@@ -799,25 +806,63 @@ function validateSchemaObjects(db) {
             throw new SqliteSchemaMigrationError(`required index '${index}' is missing or has the wrong type`, "schema object");
         }
     }
+    const homeMetaColumns = db.prepare("PRAGMA table_info(home_meta)").all().map(({ name }) => name);
+    const expectedHomeMetaColumns = [
+        "id",
+        "home_identity",
+        "revision",
+        "created_at",
+        "updated_at"
+    ];
+    if (homeMetaColumns.length !== expectedHomeMetaColumns.length
+        || homeMetaColumns.some((name, index) => name !== expectedHomeMetaColumns[index])) {
+        throw new SqliteSchemaMigrationError("home_meta columns do not match the current storage contract", "schema object");
+    }
+}
+/** Return the one linear upgrade path from a supported source to this release. */
+export function storageMigrationPlan(currentVersion) {
+    if (!Number.isInteger(currentVersion)
+        || currentVersion < MIN_SUPPORTED_STORAGE_VERSION
+        || currentVersion > CURRENT_STORAGE_VERSION) {
+        return null;
+    }
+    return MIGRATIONS
+        .filter(({ version }) => version > currentVersion)
+        .map(({ version, name, introducedIn }) => ({
+        fromVersion: version - 1,
+        toVersion: version,
+        name,
+        introducedIn
+    }));
 }
 /** Inspect a recognized migration prefix without changing it. */
 export function inspectSqliteSchemaMigrations(db) {
     const ledgerWasCreated = ensureMigrationLedger(db, "validate");
     const applied = validateAppliedMigrations(db, ledgerWasCreated);
+    if (applied.currentVersion > CURRENT_STORAGE_VERSION) {
+        return {
+            currentVersion: applied.currentVersion,
+            currentChecksum: applied.currentChecksum,
+            targetVersion: CURRENT_STORAGE_VERSION,
+            minimumSupportedVersion: MIN_SUPPORTED_STORAGE_VERSION,
+            targetChecksum: checksum(MIGRATIONS.at(-1).sql),
+            pendingVersions: []
+        };
+    }
     const pendingVersions = MIGRATIONS
-        .filter((migration) => !applied.has(migration.version))
+        .filter((migration) => !applied.versions.has(migration.version))
         .map((migration) => migration.version);
     if (pendingVersions.length === 0)
         validateSchemaObjects(db);
-    const current = MIGRATIONS[applied.size - 1];
     const target = MIGRATIONS.at(-1);
-    if (current === undefined) {
+    if (applied.currentVersion === 0) {
         throw new SqliteSchemaMigrationError("schema_migrations ledger has no current head");
     }
     return {
-        currentVersion: applied.size,
-        currentChecksum: checksum(current.sql),
-        targetVersion: SQLITE_SCHEMA_VERSION,
+        currentVersion: applied.currentVersion,
+        currentChecksum: applied.currentChecksum,
+        targetVersion: CURRENT_STORAGE_VERSION,
+        minimumSupportedVersion: MIN_SUPPORTED_STORAGE_VERSION,
         targetChecksum: checksum(target.sql),
         pendingVersions
     };
@@ -838,15 +883,26 @@ export function migrateSqliteSchema(db, options) {
         // prevents a manually altered or partially recorded ledger from silently
         // skipping a later schema/data step.
         const applied = validateAppliedMigrations(db, ledgerWasCreated);
-        const pending = MIGRATIONS.filter((migration) => !applied.has(migration.version));
+        if (applied.currentVersion > CURRENT_STORAGE_VERSION) {
+            throw new SqliteSchemaMigrationError(`storage version ${applied.currentVersion} is newer than supported `
+                + `${CURRENT_STORAGE_VERSION}`, "admission");
+        }
+        if (applied.currentVersion !== 0
+            && applied.currentVersion < MIN_SUPPORTED_STORAGE_VERSION) {
+            throw new SqliteSchemaMigrationError(`storage version ${applied.currentVersion} is older than the minimum supported `
+                + `${MIN_SUPPORTED_STORAGE_VERSION}`, "admission");
+        }
+        const pending = MIGRATIONS.filter((migration) => !applied.versions.has(migration.version));
         if (!ledgerWasCreated && pending.length > 0 && options.mode === "validate") {
-            throw new SqliteSchemaMigrationError(`SQLite schema ${applied.size} requires an explicit upgrade to ${SQLITE_SCHEMA_VERSION}`, "admission");
+            throw new SqliteSchemaMigrationError(`Storage version ${applied.currentVersion} requires an explicit upgrade to `
+                + `${CURRENT_STORAGE_VERSION}`, "admission");
         }
         const newlyApplied = [];
         for (const migration of pending) {
             db.exec(migration.sql);
-            db.prepare(`INSERT INTO schema_migrations (version, axis, record_kind, applied_at, checksum)
-         VALUES (?, ?, ?, ?, ?)`).run(migration.version, migration.axis, migration.recordKind ?? null, new Date().toISOString(), checksum(migration.sql));
+            const appliedAt = new Date().toISOString();
+            db.prepare(`INSERT INTO schema_migrations (version, name, applied_at, checksum)
+         VALUES (?, ?, ?, ?)`).run(migration.version, migration.name, appliedAt, checksum(migration.sql));
             newlyApplied.push(migration.version);
         }
         validateSchemaObjects(db);
@@ -855,7 +911,7 @@ export function migrateSqliteSchema(db, options) {
     const newlyApplied = options.mode === "apply" && !db.inTransaction
         ? db.transaction(migrate)()
         : migrate();
-    return { applied: newlyApplied, version: SQLITE_SCHEMA_VERSION };
+    return { applied: newlyApplied, version: CURRENT_STORAGE_VERSION };
 }
 /** The names of every table the schema creates (for tests/introspection). */
 export const SQLITE_SCHEMA_TABLES = [
@@ -886,7 +942,6 @@ export const SQLITE_SCHEMA_TABLES = [
     "turns",
     "active_turns",
     "review_rounds",
-    "review_findings",
     "change_sets",
     "integration_attempts",
     "messages",

package/dist/storage/sqliteStore.js

@@ -17,11 +17,12 @@
  *                                    on the durable outbox.
  *   - Crash recovery .............. WAL rollback of uncommitted transactions;
  *                                    outbox replay of committed-but-unacked effects.
- *   - Record family versioning .... full record (incl. schemaVersion) in payload.
+ *   - Record validation ........... current record (incl. local schemaVersion)
+ *                                    in payload.
  *   - Evidence retention .......... events/review_rounds/change_sets/
  *                                    integration_attempts are never pruned.
  *
- * Records are stored as full versioned JSON in `payload` columns, with typed
+ * Records are stored as full current JSON in `payload` columns, with typed
  * columns for the fields that are queried/filtered/used-for-CAS (§4). A
  * high-frequency runtime telemetry observation is a single-row upsert into
  * `telemetry` scoped by its primary key — it never rewrites global
@@ -40,8 +41,7 @@ import Database from "better-sqlite3";
 import { consumePendingBatch, mailboxTargetKey, validateWorkMailbox } from "../coordination/workMailbox.js";
 import { validateContextSnapshot } from "../context/contextSnapshot.js";
 import { compareRuntimeSessionCandidates, projectRuntimeSessionCandidate } from "../runtime/runtimeSessionCandidate.js";
-import { validateReviewFinding } from "../review/reviewFinding.js";
-import { reviewFindingLedgerMode } from "../review/reviewFindingLedger.js";
+import { validateReviewRound } from "../review/reviewRound.js";
 import { generateHomeIdentity, validateHomeIdentity } from "../repository/homeIdentity.js";
 import { validateIntegrationQueueEntry } from "../integration/integrationQueueEntry.js";
 import { validDurableJobTransition, validateDurableJob } from "../job/durableJob.js";
@@ -52,7 +52,8 @@ import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
 import { CURRENT_CONFIG_SCHEMA_VERSION, CURRENT_WORK_MAILBOX_SCHEMA_VERSION, executionLaneActiveTurnKey, executionLaneActiveTurnKeyParts, StorageConflictError, StorageCancelledError, StorageRecordError, storedCapabilityGrant, storedPublicationReference, storedReleaseWorkflow, isValidCapabilityGrantTransition, isValidReleaseWorkflowTransition, pendingWakeupProjection, validateYuiConfig } from "./taskStore.js";
 import { publicationExternalKey } from "../task/publicationReference.js";
 import { gateArtifactKey, validateGateArtifact } from "../verification/gateArtifact.js";
-import { inspectSqliteSchemaMigrations, migrateSqliteSchema, SqliteSchemaMigrationError, SQLITE_AGGREGATE_VERSION, SQLITE_LAYOUT_VERSION, TELEMETRY_KEEP_PER_GENERATION, TELEMETRY_TURN_CAP } from "./sqliteSchema.js";
+import { inspectSqliteSchemaMigrations, migrateSqliteSchema, SqliteSchemaMigrationError, TELEMETRY_KEEP_PER_GENERATION, TELEMETRY_TURN_CAP } from "./sqliteSchema.js";
+import { StorageSchemaError } from "./storageSchema.js";
 /** Read the immutable Home identity without opening a writable Store connection. */
 export function readSqliteHomeIdentity(rootDir, databaseFilename = "yui.db") {
     const database = new Database(join(rootDir, databaseFilename), {
@@ -123,6 +124,10 @@ export class SqliteTaskStore {
         mkdirSync(rootDir, { recursive: true, mode: 0o700 });
         const filename = _options.databaseFilename ?? "yui.db";
         const databasePath = join(rootDir, filename);
+        // Remember whether the database file existed before this connection opened
+        // it. A store that creates the file is bootstrapping a fresh database and
+        // may seed its singleton rows; a store that opens an existing file missing
+        // those rows has found corruption, not a bootstrap opportunity.
         const databaseExisted = existsSync(databasePath);
         this.#db = new Database(databasePath);
         try {
@@ -140,8 +145,7 @@ export class SqliteTaskStore {
                 version: schema.currentVersion,
                 checksum: schema.currentChecksum
             };
-            this.#seedHomeMeta();
-            this.#seedConfig();
+            this.#ensureSeedRows(databaseExisted);
         }
         catch (error) {
             this.#db.close();
@@ -158,11 +162,40 @@ export class SqliteTaskStore {
      */
     databaseHandle() { return this.#db; }
     // -- transaction primitives -------------------------------------------------
+    /**
+     * Guarantee the `home_meta` and `config` singleton rows exist.
+     *
+     * A fresh database created by this connection is bootstrapped with defaults.
+     * An existing database that is missing either row is corrupt —
+     * truncated, partially migrated, or hand-edited — and must fail closed
+     * instead of silently masking the damage with fresh defaults (Issue 01
+     * cross-issue handoff: INSERT OR IGNORE could hide migration corruption).
+     */
+    #ensureSeedRows(databaseExisted) {
+        const hasHomeMeta = this.#db.prepare("SELECT 1 FROM home_meta WHERE id = 1").get() !== undefined;
+        const hasConfig = this.#db.prepare("SELECT 1 FROM config WHERE id = 1").get() !== undefined;
+        if (hasHomeMeta && hasConfig)
+            return;
+        if (databaseExisted) {
+            const missing = [
+                !hasHomeMeta ? "home_meta" : null,
+                !hasConfig ? "config" : null
+            ].filter((value) => value !== null).join(", ");
+            throw new StorageSchemaError("STORAGE_SCHEMA_INVALID", `SQLite database is corrupt: required singleton row(s) missing (${missing}). `
+                + "The database may be truncated or partially migrated. Restore yui.db from a "
+                + "backup, or preserve this Home for diagnosis and initialize a new Home.");
+        }
+        if (!hasHomeMeta)
+            this.#seedHomeMeta();
+        if (!hasConfig)
+            this.#seedConfig();
+    }
     #seedHomeMeta() {
         const now = new Date().toISOString();
         const identity = generateHomeIdentity(new Date());
-        this.#db.prepare(`INSERT OR IGNORE INTO home_meta (id, home_identity, revision, layout_version, aggregate_version, created_at, updated_at)
-       VALUES (1, ?, 0, ?, ?, ?, ?)`).run(JSON.stringify(identity), SQLITE_LAYOUT_VERSION, SQLITE_AGGREGATE_VERSION, now, now);
+        this.#db.prepare(`INSERT OR IGNORE INTO home_meta
+       (id, home_identity, revision, created_at, updated_at)
+       VALUES (1, ?, 0, ?, ?)`).run(JSON.stringify(identity), now, now);
     }
     #seedConfig() {
         this.#db.prepare(`INSERT OR IGNORE INTO config (id, payload, updated_at) VALUES (1, ?, ?)`).run(JSON.stringify(DEFAULT_CONFIG), new Date().toISOString());
@@ -731,9 +764,7 @@ export class SqliteTaskStore {
             activeTurns: runs.filter((run) => run.status === "active"),
             leaderTurns: runs.filter((run) => run.roleName === "leader"),
             reviewOutcomeEvidence: {
-                turns: this.#sortById(this.#listPayload("turns", "task_id = ?", [taskId]).filter((run) => run.purpose === "review"), (run) => run.id),
-                reviewFindings: this.listReviewFindings(taskId),
-                events: events.filter((event) => event.type === "review.completed")
+                turns: this.#sortById(this.#listPayload("turns", "task_id = ?", [taskId]).filter((run) => run.purpose === "review"), (run) => run.id)
             }
         };
     }
@@ -743,13 +774,9 @@ export class SqliteTaskStore {
             return null;
         return {
             ...base,
-            turns: operationalTaskRecords(this.listTurns(taskId), this.listEvents(taskId), "turn"),
             managedWorkspaces: this.#sortById(this.#listPayload("managed_workspaces", "task_id = ?", [taskId]), (workspace) => managedWorkspaceKey(workspace.owner)),
             durableJobs: this.#sortById(this.#listPayload("durable_jobs", "task_id = ?", [taskId]), (job) => job.id),
             integrationQueueEntries: this.#sortById(this.#listPayload("integration_queue", "task_id = ?", [taskId]), (entry) => entry.id),
-            reviewFindings: this.#sortById(this.#listPayload("review_findings", "task_id = ?", [taskId]), (finding) => finding.id),
-            reviewFindingLedgerMode: reviewFindingLedgerMode(this.getConfig()),
-            events: this.#sortById(this.#listPayload("events", "task_id = ?", [taskId]), (event) => event.id)
         };
     }
     /** Task ids flagged active in the catalog projection (the global active index). */
@@ -926,11 +953,11 @@ export class SqliteTaskStore {
            role_name = excluded.role_name, agent_id = excluded.agent_id,
            native_session_id = excluded.native_session_id,
            provider_root_pid = excluded.provider_root_pid,
-           payload = excluded.payload, recorded_at = excluded.recorded_at`).run(identity.launchId, owner.scope, owner.scope === "task" ? owner.taskId : null, owner.roleName, identity.agentId, identity.nativeSessionId ?? null, identity.providerRoot.pid, this.#json(identity), identity.recordedAt);
+           payload = excluded.payload, recorded_at = excluded.recorded_at`).run(identity.runtimeGenerationId, owner.scope, owner.scope === "task" ? owner.taskId : null, owner.roleName, identity.agentId, identity.nativeSessionId ?? null, identity.providerRoot.pid, this.#json(identity), identity.recordedAt);
         });
     }
-    getSessionOwner(launchId) {
-        const row = this.#db.prepare("SELECT payload FROM session_owners WHERE launch_id = ?").get(launchId);
+    getSessionOwner(runtimeGenerationId) {
+        const row = this.#db.prepare("SELECT payload FROM session_owners WHERE launch_id = ?").get(runtimeGenerationId);
         return row === undefined ? null : this.#parse(row.payload);
     }
     listSessionOwners() {
@@ -942,9 +969,9 @@ export class SqliteTaskStore {
         }
         return this.#listPayload("session_owners", "scope = 'task' AND task_id = ? AND role_name = ?", [owner.taskId, owner.roleName]);
     }
-    removeSessionOwner(launchId) {
+    removeSessionOwner(runtimeGenerationId) {
         this.#mutate(() => {
-            this.#db.prepare("DELETE FROM session_owners WHERE launch_id = ?").run(launchId);
+            this.#db.prepare("DELETE FROM session_owners WHERE launch_id = ?").run(runtimeGenerationId);
         });
     }
     // -- task roles -------------------------------------------------------------
@@ -1058,7 +1085,7 @@ export class SqliteTaskStore {
             ? ""
             : ` WHERE ${predicates.join(" AND ")}`;
         const rows = this.#db.prepare(`SELECT scope, task_id, role_name, agent_id, adapter_id,
-              native_session_id, launch_id, session_updated_at,
+              native_session_id, launch_id AS runtime_generation_id, session_updated_at,
               cleanup_required
        FROM runtime_session_candidates${where}`).all(...parameters);
         const candidates = rows.map((row) => ({
@@ -1068,7 +1095,7 @@ export class SqliteTaskStore {
             agentId: row.agent_id,
             adapterId: row.adapter_id,
             nativeSessionId: row.native_session_id,
-            ...(row.launch_id === null ? {} : { launchId: row.launch_id }),
+            ...(row.runtime_generation_id === null ? {} : { runtimeGenerationId: row.runtime_generation_id }),
             sessionUpdatedAt: row.session_updated_at,
             cleanupRequired: row.cleanup_required === 1
         })).sort(compareRuntimeSessionCandidates);
@@ -1123,7 +1150,7 @@ export class SqliteTaskStore {
            json_extract(active_session, '$.agentId') AS agent_id,
            json_extract(active_session, '$.adapterId') AS adapter_id,
            json_extract(active_session, '$.nativeSessionId') AS native_session_id,
-           json_extract(active_session, '$.launchId') AS launch_id,
+           json_extract(active_session, '$.runtimeGenerationId') AS runtime_generation_id,
            CASE
              WHEN json_extract(active_session, '$.status') = 'active'
              THEN 1 ELSE 0
@@ -1131,7 +1158,7 @@ export class SqliteTaskStore {
            json_extract(active_session, '$.updatedAt') AS session_updated_at,
            CASE
              WHEN json_extract(active_session, '$.status') = 'active'
-               AND json_type(active_session, '$.launchId') = 'text'
+               AND json_type(active_session, '$.runtimeGenerationId') = 'text'
              THEN 1 ELSE 0
            END AS cleanup_required
          FROM active`).get(...source.parameters);
@@ -1151,7 +1178,7 @@ export class SqliteTaskStore {
             && row.agent_id === candidate.agentId
             && row.adapter_id === candidate.adapterId
             && row.native_session_id === candidate.nativeSessionId
-            && (row.launch_id ?? undefined) === candidate.launchId
+            && (row.runtime_generation_id ?? undefined) === candidate.runtimeGenerationId
             && row.is_active === 1
             && row.session_updated_at === candidate.sessionUpdatedAt
             && row.cleanup_required === (candidate.cleanupRequired ? 1 : 0);
@@ -1192,7 +1219,7 @@ export class SqliteTaskStore {
          native_session_id = excluded.native_session_id,
          launch_id = excluded.launch_id,
          session_updated_at = excluded.session_updated_at,
-         cleanup_required = excluded.cleanup_required`).run(candidate.owner.scope, taskId, candidate.owner.roleName, candidate.agentId, candidate.adapterId, candidate.nativeSessionId, candidate.launchId ?? null, candidate.sessionUpdatedAt, candidate.cleanupRequired ? 1 : 0);
+         cleanup_required = excluded.cleanup_required`).run(candidate.owner.scope, taskId, candidate.owner.roleName, candidate.agentId, candidate.adapterId, candidate.nativeSessionId, candidate.runtimeGenerationId ?? null, candidate.sessionUpdatedAt, candidate.cleanupRequired ? 1 : 0);
     }
     #deleteRuntimeSessionCandidate(owner) {
         this.#db.prepare(`DELETE FROM runtime_session_candidates
@@ -1295,8 +1322,7 @@ export class SqliteTaskStore {
                 if (sameExternal.length > 0) {
                     const latest = latestSqlitePublicationReference(sameExternal);
                     if (stored.supersedes !== latest.id) {
-                        throw new StorageRecordError(`Publication external identity conflicts with ${latest.id}; `
-                            + `explicitly supersede that record: ${key}.`);
+                        throw new StorageRecordError(`Publication external identity conflicts with current record ${latest.id}: ${key}.`);
                     }
                 }
                 else if (stored.supersedes !== undefined) {
@@ -1500,6 +1526,7 @@ export class SqliteTaskStore {
         return this.#sortById(this.#listPayload("review_rounds", "task_id = ?", [taskId]), (round) => round.id);
     }
     saveReviewRound(taskId, round) {
+        validateReviewRound(round);
         if (round.taskId !== taskId)
             throw new StorageRecordError(`Review round belongs to another Task: ${round.taskId}`);
         this.#requireTask(taskId);
@@ -1509,27 +1536,6 @@ export class SqliteTaskStore {
            payload = excluded.payload, updated_at = excluded.updated_at`).run(taskId, round.id, round.status, this.#json(round), this.#now());
         });
     }
-    // -- review findings --------------------------------------------------------
-    nextReviewFindingId(taskId) { return this.#nextTaskRecordId(taskId, "reviewFinding"); }
-    getReviewFinding(taskId, findingId) {
-        return this.#getPayload("review_findings", "task_id = ? AND finding_id = ?", [taskId, findingId]);
-    }
-    listReviewFindings(taskId) {
-        return this.#sortById(this.#listPayload("review_findings", "task_id = ?", [taskId]), (finding) => finding.id);
-    }
-    saveReviewFinding(taskId, finding) {
-        validateReviewFinding(finding);
-        if (finding.taskId !== taskId) {
-            throw new StorageRecordError(`Review finding belongs to another Task: ${finding.taskId}`);
-        }
-        this.#requireTask(taskId);
-        this.#mutate(() => {
-            this.#db.prepare(`INSERT INTO review_findings (task_id, finding_id, stable_key, severity, payload, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?)
-         ON CONFLICT(task_id, finding_id) DO UPDATE SET stable_key = excluded.stable_key,
-           severity = excluded.severity, payload = excluded.payload, updated_at = excluded.updated_at`).run(taskId, finding.id, finding.stableKey, finding.severity, this.#json(finding), this.#now());
-        });
-    }
     // -- active turns ----------------------------------------------------------
     #saveActiveTurn(taskId, pointer, turnId) {
         this.#mutate(() => {
@@ -1721,6 +1727,18 @@ export class SqliteTaskStore {
             this.#observeHighWater(taskId, "message", seq);
         });
     }
+    updateMessage(taskId, message) {
+        if (message.taskId !== taskId) {
+            throw new StorageRecordError(`Message belongs to another Task: ${message.taskId}`);
+        }
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            const result = this.#db.prepare(`UPDATE messages SET payload = ? WHERE task_id = ? AND message_id = ?`).run(this.#json(message), taskId, message.id);
+            if (result.changes !== 1) {
+                throw new StorageRecordError(`Message does not exist: ${taskId}/${message.id}`);
+            }
+        });
+    }
     listMessages(taskId) {
         return this.#sortById(this.#listPayload("messages", "task_id = ?", [taskId]), (message) => message.id);
     }
@@ -2109,10 +2127,9 @@ function validIntegrationQueueTransition(before, after) {
         || before.createdAt !== after.createdAt)
         return false;
     const allowed = {
-        queued: ["queued", "running", "validated", "superseded"],
+        queued: ["queued", "running", "superseded"],
         running: ["running", "conflicted", "committed"],
         conflicted: ["conflicted", "running", "committed", "queued", "superseded"],
-        validated: ["validated", "running", "queued", "superseded"],
         committed: ["committed"],
         superseded: ["superseded"]
     };