@yielded/agent-storage-cloudflare 0.1.0-beta.169 → 0.1.0-beta.171

package/src/DoSubscriptionStore.ts

@@ -1,4 +1,8 @@
-import { makeSqlSubscriptionStore } from "@yielded/agent-storage-sql/sql-subscription-store";
+import {
+  backfillSubscriptionSettlementObservation,
+  makeSqlSubscriptionStore,
+} from "@yielded/agent-storage-sql/sql-subscription-store";
+import { sameSqliteLayoutStatement } from "@yielded/agent-storage-sql/sqlite-layout-inspection";
 import {
   SourcePartition,
   SubscriptionError,
@@ -10,7 +14,7 @@ import { Context, Effect, Layer, Schema } from "effect";
 import * as SqlClientService from "effect/sql/SqlClient";
 import type { SqlError } from "effect/sql/SqlError";
 
-const CURRENT_SUBSCRIPTION_STORE_VERSION = 3;
+const CURRENT_SUBSCRIPTION_STORE_VERSION = 4;
 
 const ScanRow = Schema.Struct({
   event_scan_cursor: Schema.String,
@@ -64,99 +68,133 @@ const validate = <A, I>(schema: Schema.Codec<A, I>, value: unknown, code: string
 const decodeRows = <A, I>(schema: Schema.Codec<A, I>, rows: unknown, code: string) =>
   Schema.decodeUnknownEffect(Schema.Array(schema))(rows).pipe(Effect.mapError(() => corrupt(code)));
 
-const initializeDoSubscriptionStore = Effect.fnUntraced(function* () {
-  const sql = yield* SqlClientService.SqlClient;
-
-  const names = yield* sql<Record<string, unknown>>`
-    SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'effect_agent_subscription_%'
-  `.pipe(Effect.mapError(() => unavailable("inspect subscription storage")));
+const layoutStatements = [
+  "CREATE TABLE effect_agent_subscription_store_state ( singleton INTEGER PRIMARY KEY NOT NULL CHECK(singleton=1), storage_version INTEGER NOT NULL, alarm_generation INTEGER NOT NULL )",
+  "CREATE TABLE effect_agent_subscription_sequences ( tenant_id TEXT NOT NULL, source_address TEXT NOT NULL, sequence INTEGER NOT NULL, event_scan_cursor TEXT NOT NULL, delivery_scan_cursor TEXT NOT NULL, recovery_scan_cursor INTEGER NOT NULL, PRIMARY KEY (tenant_id, source_address) )",
+  "CREATE TABLE effect_agent_subscriptions ( tenant_id TEXT NOT NULL, source_address TEXT NOT NULL, owner_id TEXT NOT NULL, subscription_id TEXT NOT NULL, ordinal INTEGER NOT NULL, source_name TEXT NOT NULL, source_version TEXT NOT NULL, matching_key TEXT NOT NULL, state TEXT NOT NULL, expires_at_millis INTEGER, recovery_at_millis INTEGER, recovery_present INTEGER NOT NULL DEFAULT 0, record_json TEXT NOT NULL, PRIMARY KEY (tenant_id, source_address, owner_id, subscription_id), UNIQUE (tenant_id, source_address, ordinal) )",
+  "CREATE INDEX effect_agent_subscriptions_owner ON effect_agent_subscriptions (tenant_id, source_address, owner_id, ordinal)",
+  "CREATE INDEX effect_agent_subscriptions_capacity ON effect_agent_subscriptions (tenant_id, source_address, expires_at_millis) WHERE state IN ('active', 'paused')",
+  "CREATE INDEX effect_agent_subscriptions_owner_capacity ON effect_agent_subscriptions (tenant_id, source_address, owner_id, expires_at_millis) WHERE state IN ('active', 'paused')",
+  "CREATE INDEX effect_agent_subscriptions_candidates ON effect_agent_subscriptions (tenant_id, source_address, source_name, source_version, matching_key, ordinal)",
+  "CREATE INDEX effect_agent_subscriptions_recovery ON effect_agent_subscriptions (tenant_id, source_address, recovery_at_millis, ordinal) WHERE recovery_at_millis IS NOT NULL",
+  "CREATE TABLE effect_agent_subscription_events ( tenant_id TEXT NOT NULL, source_address TEXT NOT NULL, event_id TEXT NOT NULL, source_name TEXT NOT NULL, source_version TEXT NOT NULL, matching_key TEXT NOT NULL, payload_digest TEXT NOT NULL, cutoff INTEGER NOT NULL, cursor INTEGER NOT NULL, routing_complete INTEGER NOT NULL, tombstone INTEGER NOT NULL DEFAULT 0, next_attempt_at_millis INTEGER NOT NULL, record_json TEXT NOT NULL, PRIMARY KEY (tenant_id, source_address, event_id) )",
+  "CREATE INDEX effect_agent_subscription_events_pending ON effect_agent_subscription_events (tenant_id, source_address, routing_complete, next_attempt_at_millis, event_id)",
+  "CREATE TABLE effect_agent_subscription_deliveries ( tenant_id TEXT NOT NULL, source_address TEXT NOT NULL, owner_id TEXT NOT NULL, subscription_id TEXT NOT NULL, event_id TEXT NOT NULL, delivery_key TEXT NOT NULL, state TEXT NOT NULL, next_attempt_at_millis INTEGER NOT NULL, record_json TEXT NOT NULL, observe_settlement INTEGER NOT NULL DEFAULT 0 CHECK (observe_settlement IN (0, 1)), PRIMARY KEY (tenant_id, source_address, owner_id, subscription_id, event_id), UNIQUE (tenant_id, source_address, delivery_key) )",
+  "CREATE INDEX effect_agent_subscription_deliveries_pending ON effect_agent_subscription_deliveries (tenant_id, source_address, state, next_attempt_at_millis, delivery_key)",
+  "CREATE INDEX effect_agent_subscription_deliveries_registration ON effect_agent_subscription_deliveries (tenant_id, source_address, owner_id, subscription_id, delivery_key)",
+  "CREATE INDEX effect_agent_subscription_deliveries_capacity ON effect_agent_subscription_deliveries (tenant_id, source_address, owner_id) WHERE state IN ('selected', 'prepared')",
+  "CREATE INDEX effect_agent_subscription_deliveries_observing ON effect_agent_subscription_deliveries (tenant_id, source_address, owner_id) WHERE state='delivered' AND observe_settlement=1",
+] as const;
+
+const layoutObjects = layoutStatements.map((statement, index) => {
+  const name = /^CREATE (TABLE|INDEX) ([a-z_][a-z_0-9]*)/.exec(statement);
+
+  if (name === null) throw new Error("Invalid subscription layout statement");
+
+  return [name[1].toLowerCase(), name[2], index] as const;
+});
 
-  const decodedNames = yield* decodeRows(
-    Schema.Struct({ name: Schema.String }),
-    names,
-    "inspect subscription storage",
-  );
+const addedIndexes = new Set([
+  "effect_agent_subscriptions_capacity",
+  "effect_agent_subscriptions_owner_capacity",
+  "effect_agent_subscription_deliveries_capacity",
+  "effect_agent_subscription_deliveries_observing",
+]);
+
+const LayoutObject = Schema.Struct({
+  name: Schema.String,
+  type: Schema.String,
+  sql: Schema.NullOr(Schema.String),
+});
 
-  const expected = new Set([
-    "effect_agent_subscription_store_state",
-    "effect_agent_subscription_sequences",
-    "effect_agent_subscriptions",
-    "effect_agent_subscription_events",
-    "effect_agent_subscription_deliveries",
-  ]);
+/** Only the released v3 layout may upgrade; schema, backfill and version publish commit together. */
+const initializeDoSubscriptionStore = Effect.fnUntraced(function* () {
+  const sql = (yield* SqlClientService.SqlClient).withoutTransforms();
+  const tables = layoutObjects.filter(([type]) => type === "table").map(([, name]) => name);
 
-  const hasState = decodedNames.some(
-    ({ name }) => name === "effect_agent_subscription_store_state",
+  const readObjects = sql`SELECT name, type, sql FROM sqlite_master
+    WHERE name GLOB 'effect_agent_subscription*' OR (type='trigger' AND tbl_name IN ${sql.in(tables)})`.pipe(
+    Effect.flatMap((rows) => decodeRows(LayoutObject, rows, "subscription storage layout")),
   );
 
-  if (!hasState && decodedNames.length > 0) return yield* corrupt("partial subscription storage");
-  if (!hasState) {
-    yield* sql
-      .withTransaction(
-        Effect.gen(function* () {
-          yield* sql`CREATE TABLE effect_agent_subscription_store_state (
-        singleton INTEGER PRIMARY KEY NOT NULL CHECK(singleton=1), storage_version INTEGER NOT NULL, alarm_generation INTEGER NOT NULL
-      )`.withoutTransform;
-          yield* sql`CREATE TABLE effect_agent_subscription_sequences (
-        tenant_id TEXT NOT NULL, source_address TEXT NOT NULL, sequence INTEGER NOT NULL,
-        event_scan_cursor TEXT NOT NULL, delivery_scan_cursor TEXT NOT NULL, recovery_scan_cursor INTEGER NOT NULL,
-        PRIMARY KEY (tenant_id, source_address)
-      )`.withoutTransform;
-          yield* sql`CREATE TABLE effect_agent_subscriptions (
-        tenant_id TEXT NOT NULL, source_address TEXT NOT NULL, owner_id TEXT NOT NULL, subscription_id TEXT NOT NULL,
-        ordinal INTEGER NOT NULL, source_name TEXT NOT NULL, source_version TEXT NOT NULL, matching_key TEXT NOT NULL,
-        state TEXT NOT NULL, expires_at_millis INTEGER, recovery_at_millis INTEGER, recovery_present INTEGER NOT NULL DEFAULT 0, record_json TEXT NOT NULL,
-        PRIMARY KEY (tenant_id, source_address, owner_id, subscription_id), UNIQUE (tenant_id, source_address, ordinal)
-      )`.withoutTransform;
-          yield* sql`CREATE INDEX effect_agent_subscriptions_owner ON effect_agent_subscriptions (tenant_id, source_address, owner_id, ordinal)`
-            .withoutTransform;
-          yield* sql`CREATE INDEX effect_agent_subscriptions_candidates ON effect_agent_subscriptions (tenant_id, source_address, source_name, source_version, matching_key, ordinal)`
-            .withoutTransform;
-          yield* sql`CREATE INDEX effect_agent_subscriptions_recovery ON effect_agent_subscriptions (tenant_id, source_address, recovery_at_millis, ordinal) WHERE recovery_at_millis IS NOT NULL`
-            .withoutTransform;
-          yield* sql`CREATE TABLE effect_agent_subscription_events (
-        tenant_id TEXT NOT NULL, source_address TEXT NOT NULL, event_id TEXT NOT NULL, source_name TEXT NOT NULL,
-        source_version TEXT NOT NULL, matching_key TEXT NOT NULL, payload_digest TEXT NOT NULL, cutoff INTEGER NOT NULL,
-        cursor INTEGER NOT NULL, routing_complete INTEGER NOT NULL, tombstone INTEGER NOT NULL DEFAULT 0, next_attempt_at_millis INTEGER NOT NULL, record_json TEXT NOT NULL,
-        PRIMARY KEY (tenant_id, source_address, event_id)
-      )`.withoutTransform;
-          yield* sql`CREATE INDEX effect_agent_subscription_events_pending ON effect_agent_subscription_events (tenant_id, source_address, routing_complete, next_attempt_at_millis, event_id)`
-            .withoutTransform;
-          yield* sql`CREATE TABLE effect_agent_subscription_deliveries (
-        tenant_id TEXT NOT NULL, source_address TEXT NOT NULL, owner_id TEXT NOT NULL, subscription_id TEXT NOT NULL,
-        event_id TEXT NOT NULL, delivery_key TEXT NOT NULL, state TEXT NOT NULL, next_attempt_at_millis INTEGER NOT NULL,
-        record_json TEXT NOT NULL, PRIMARY KEY (tenant_id, source_address, owner_id, subscription_id, event_id),
-        UNIQUE (tenant_id, source_address, delivery_key)
-      )`.withoutTransform;
-          yield* sql`CREATE INDEX effect_agent_subscription_deliveries_pending ON effect_agent_subscription_deliveries (tenant_id, source_address, state, next_attempt_at_millis, delivery_key)`
-            .withoutTransform;
-          yield* sql`CREATE INDEX effect_agent_subscription_deliveries_registration ON effect_agent_subscription_deliveries (tenant_id, source_address, owner_id, subscription_id, delivery_key)`
-            .withoutTransform;
-          yield* sql`INSERT INTO effect_agent_subscription_store_state (singleton, storage_version, alarm_generation)
-        VALUES (1, ${CURRENT_SUBSCRIPTION_STORE_VERSION}, 0)`.withoutTransform;
-        }),
+  const checkLayout = Effect.fnUntraced(function* (
+    objects: ReadonlyArray<typeof LayoutObject.Type>,
+    version: number,
+  ) {
+    if (
+      objects.some(
+        ({ name, type }) =>
+          (type === "table" && !tables.includes(name)) ||
+          type === "trigger" ||
+          (version === 3 && addedIndexes.has(name)),
       )
-      .pipe(Effect.mapError(() => unavailable("initialize subscription storage")));
-
-    return;
-  }
-  if (decodedNames.length !== expected.size || decodedNames.some(({ name }) => !expected.has(name)))
-    return yield* corrupt("subscription storage tables");
+    )
+      return yield* corrupt("ambiguous subscription storage layout");
+    for (const [type, name, index] of layoutObjects) {
+      if (version === 3 && addedIndexes.has(name)) continue;
+
+      const expected =
+        version === 3
+          ? layoutStatements[index].replace(
+              ", observe_settlement INTEGER NOT NULL DEFAULT 0 CHECK (observe_settlement IN (0, 1))",
+              "",
+            )
+          : layoutStatements[index];
+
+      const actual = objects.find((row) => row.name === name);
+
+      if (
+        actual?.type !== type ||
+        actual.sql === null ||
+        !sameSqliteLayoutStatement(actual.sql, expected)
+      )
+        return yield* corrupt("incompatible subscription storage layout " + name);
+    }
+  });
 
-  const rows = yield* sql<
-    Record<string, unknown>
-  >`SELECT storage_version, alarm_generation FROM effect_agent_subscription_store_state WHERE singleton=1`.pipe(
-    Effect.mapError(() => unavailable("read subscription storage version")),
-  );
+  yield* sql
+    .withTransaction(
+      Effect.gen(function* () {
+        const objects = yield* readObjects;
 
-  const state = yield* decodeRows(StoreStateRow, rows, "read subscription storage version");
+        const hasState = objects.some(
+          ({ name }) => name === "effect_agent_subscription_store_state",
+        );
 
-  if (state.length !== 1 || state[0].storage_version !== CURRENT_SUBSCRIPTION_STORE_VERSION)
-    return yield* corrupt(
-      state.length === 1
-        ? `incompatible subscription storage version ${state[0].storage_version}; expected ${CURRENT_SUBSCRIPTION_STORE_VERSION}`
-        : "invalid subscription storage version row",
-    );
+        if (!hasState) {
+          if (objects.length > 0) return yield* corrupt("partial subscription storage");
+          for (const statement of layoutStatements) yield* sql.unsafe(statement).withoutTransform;
+          yield* sql`INSERT INTO effect_agent_subscription_store_state (singleton, storage_version, alarm_generation)
+        VALUES (1, ${CURRENT_SUBSCRIPTION_STORE_VERSION}, 0)`;
+
+          return;
+        }
+
+        const state = yield* decodeRows(
+          StoreStateRow,
+          yield* sql`SELECT storage_version, alarm_generation FROM effect_agent_subscription_store_state`,
+          "read subscription storage version",
+        );
+
+        if (state.length !== 1) return yield* corrupt("invalid subscription storage version row");
+        const version = state[0].storage_version;
+
+        if (version !== 3 && version !== CURRENT_SUBSCRIPTION_STORE_VERSION)
+          return yield* corrupt(
+            `incompatible subscription storage version ${version}; expected ${CURRENT_SUBSCRIPTION_STORE_VERSION}`,
+          );
+        yield* checkLayout(objects, version);
+        if (version === CURRENT_SUBSCRIPTION_STORE_VERSION) return;
+
+        yield* sql`ALTER TABLE effect_agent_subscription_deliveries ADD COLUMN observe_settlement INTEGER NOT NULL DEFAULT 0 CHECK (observe_settlement IN (0, 1))`;
+        yield* backfillSubscriptionSettlementObservation();
+        for (const [, name, index] of layoutObjects)
+          if (addedIndexes.has(name)) yield* sql.unsafe(layoutStatements[index]).withoutTransform;
+        yield* sql`UPDATE effect_agent_subscription_store_state SET storage_version=${CURRENT_SUBSCRIPTION_STORE_VERSION} WHERE singleton=1`;
+        yield* checkLayout(yield* readObjects, CURRENT_SUBSCRIPTION_STORE_VERSION);
+      }),
+    )
+    .pipe(Effect.catchTag("SqlError", () => unavailable("initialize subscription storage")));
 });
 
 const makeSubscriptionStore = Effect.fnUntraced(function* (owned: SourcePartition) {

package/src/internal/do-journal.ts

@@ -15,7 +15,6 @@ import {
   canonicalRecordJson,
   makeSqlThreadArchiveRange,
 } from "@yielded/agent-storage-sql/sql-thread-archive-range";
-import { makeProgressAppendValidation } from "@yielded/agent-storage-sql/sql-thread-native-reads";
 import { makeSqlThreadWork } from "@yielded/agent-storage-sql/sql-thread-work";
 import { ThreadId } from "@yielded/agent/identifiers";
 import {
@@ -395,10 +394,6 @@ const makeJournal = (
         cause,
       });
 
-    const validateProgress = yield* makeProgressAppendValidation().pipe(
-      Effect.provideService(SqlClient.SqlClient, sql),
-    );
-
     const executions = yield* makeSqlExecutions().pipe(
       Effect.provideService(SqlClient.SqlClient, sql),
     );
@@ -739,7 +734,6 @@ const makeJournal = (
       );
 
       yield* executionConflict(executions.validate(request));
-      yield* validateProgress(request);
 
       const result = RawAppendResult.make({
         firstSequence,

package/src/internal/migrations.ts

@@ -1,4 +1,8 @@
-import { SQL_PROMPT_PREDICATE } from "@yielded/agent-storage-sql/sql-thread-native-reads";
+import { backfillPeerMessageRetention } from "@yielded/agent-storage-sql/sql-message-delivery-store";
+import {
+  SQL_PROMPT_PREDICATE,
+  upgradeExecutionCheckpoints,
+} from "@yielded/agent-storage-sql/sql-thread-native-reads";
 import { createSqlThreadWorkTables } from "@yielded/agent-storage-sql/sql-thread-work";
 import { makeSqliteLayoutInspection } from "@yielded/agent-storage-sql/sqlite-layout-inspection";
 import { CURRENT_RECORD_FORMAT } from "@yielded/agent/records";
@@ -12,7 +16,7 @@ import {
   DoStorageError,
 } from "../DoStorageError.ts";
 
-export const CurrentDoStorageVersion = 25;
+export const CurrentDoStorageVersion = 27;
 
 /** Fresh layout only. Unsupported stores are rejected before these statements execute. */
 const layoutStatements = [
@@ -44,7 +48,7 @@ const layoutStatements = [
   'CREATE INDEX effect_agent_records_subtree ON "effect_agent_canonical_records"(thread_id, source_submission_id, sequence) WHERE record_tag = 22',
   'CREATE INDEX effect_agent_records_worker_input ON "effect_agent_canonical_records"(thread_id, message_id) WHERE record_tag = 34',
   "CREATE INDEX effect_agent_submissions_nonterminal ON effect_agent_submissions (thread_id, queue_sequence) WHERE state <> 'settled'",
-  "CREATE TABLE effect_agent_message_deliveries ( owner_thread_id TEXT NOT NULL, message_id TEXT NOT NULL, version INTEGER NOT NULL, state TEXT NOT NULL, deadline_at_millis INTEGER, record_json TEXT NOT NULL, PRIMARY KEY (owner_thread_id, message_id) )",
+  "CREATE TABLE effect_agent_message_deliveries ( owner_thread_id TEXT NOT NULL, message_id TEXT NOT NULL, version INTEGER NOT NULL, state TEXT NOT NULL, deadline_at_millis INTEGER, record_json TEXT NOT NULL, peer_retained_until_millis INTEGER, PRIMARY KEY (owner_thread_id, message_id) )",
   "CREATE INDEX effect_agent_message_deliveries_due ON effect_agent_message_deliveries (deadline_at_millis, owner_thread_id, message_id) WHERE deadline_at_millis IS NOT NULL",
   "CREATE INDEX effect_agent_message_deliveries_pending ON \"effect_agent_message_deliveries\"(owner_thread_id, message_id) WHERE state NOT IN ('processed', 'refused')",
   "CREATE TABLE effect_agent_worker_stops (thread_id TEXT PRIMARY KEY NOT NULL, terminal TEXT)",
@@ -60,7 +64,8 @@ const layoutStatements = [
   "CREATE INDEX effect_agent_records_worker_completed ON effect_agent_canonical_records(thread_id, message_id, sequence) WHERE record_tag = 32",
   "CREATE INDEX effect_agent_records_worker_stop ON effect_agent_canonical_records(thread_id, worker_thread_id, sequence) WHERE record_tag = 38",
   "CREATE INDEX effect_agent_message_deliveries_identity ON effect_agent_message_deliveries(owner_thread_id, json_quote(message_id))",
-  "CREATE INDEX effect_agent_message_deliveries_peer ON effect_agent_message_deliveries(owner_thread_id, message_id) WHERE state NOT IN ('processed', 'refused') AND json_extract(record_json, '$.envelope.messageAdmission.schemaVersion') = 1",
+  "CREATE INDEX effect_agent_message_deliveries_peer_retained ON effect_agent_message_deliveries(owner_thread_id, peer_retained_until_millis, message_id) WHERE peer_retained_until_millis IS NOT NULL",
+  "CREATE INDEX effect_agent_message_deliveries_peer ON effect_agent_message_deliveries(owner_thread_id, message_id) WHERE state NOT IN ('processed', 'refused') AND json_extract(record_json, '$.envelope.messageAdmission.peerName') IS NOT NULL",
   "CREATE TABLE effect_agent_journal_ranges (thread_id TEXT NOT NULL, first_sequence INTEGER NOT NULL, last_sequence INTEGER NOT NULL, record_count INTEGER NOT NULL, batch_count INTEGER NOT NULL, byte_count INTEGER NOT NULL, state TEXT NOT NULL, locator TEXT, PRIMARY KEY (thread_id, first_sequence), FOREIGN KEY (thread_id) REFERENCES effect_agent_threads(thread_id) ON DELETE RESTRICT)",
   "CREATE TABLE effect_agent_archive_batches (thread_id TEXT NOT NULL, batch_id TEXT NOT NULL, range_first_sequence INTEGER NOT NULL, batch_json TEXT NOT NULL, PRIMARY KEY (thread_id, batch_id), FOREIGN KEY (thread_id, batch_id) REFERENCES effect_agent_canonical_batches(thread_id, batch_id) ON DELETE RESTRICT, CONSTRAINT effect_agent_archive_batches_range_fkey FOREIGN KEY (thread_id, range_first_sequence) REFERENCES effect_agent_journal_ranges(thread_id, first_sequence) ON DELETE RESTRICT)",
   "CREATE TABLE effect_agent_archive_records (thread_id TEXT NOT NULL, sequence INTEGER NOT NULL, range_first_sequence INTEGER NOT NULL, record_json TEXT NOT NULL, PRIMARY KEY (thread_id, sequence), FOREIGN KEY (thread_id, sequence) REFERENCES effect_agent_canonical_records(thread_id, sequence) ON DELETE RESTRICT, CONSTRAINT effect_agent_archive_records_range_fkey FOREIGN KEY (thread_id, range_first_sequence) REFERENCES effect_agent_journal_ranges(thread_id, first_sequence) ON DELETE RESTRICT)",
@@ -82,13 +87,14 @@ const layoutStatements = [
 const headerStatement =
   "CREATE TABLE effect_agent_schema (singleton INTEGER PRIMARY KEY NOT NULL CHECK (singleton = 1), layout_version INTEGER NOT NULL CHECK (layout_version > 0), record_format TEXT NOT NULL CHECK (length(record_format) > 0))";
 
-const layoutObjects = layoutStatements.map((statement, index) => {
-  const name = /^CREATE (TABLE|(?:UNIQUE )?INDEX|TRIGGER) "?([a-z_][a-z_0-9]*)"?/.exec(statement);
+const layoutObjects = (statements: ReadonlyArray<string>) =>
+  statements.map((statement, index) => {
+    const name = /^CREATE (TABLE|(?:UNIQUE )?INDEX|TRIGGER) "?([a-z_][a-z_0-9]*)"?/.exec(statement);
 
-  if (name === null) throw new Error("Invalid fresh layout statement");
+    if (name === null) throw new Error("Invalid fresh layout statement");
 
-  return [name[1].replace("UNIQUE ", "").toLowerCase(), name[2], index] as const;
-});
+    return [name[1].replace("UNIQUE ", "").toLowerCase(), name[2], index] as const;
+  });
 
 const Legacy = Schema.Tuple([
   Schema.Struct({
@@ -115,22 +121,43 @@ const incompatible = (actualVersion: number, message: string) =>
 const storageError = (cause: SqlError) =>
   DoStorageError.make({ operation: "inspect storage layout", cause, message: cause.message });
 
-const { decode, readObjects, readHeader } = makeSqliteLayoutInspection({
-  version: CurrentDoStorageVersion,
-  statements: layoutStatements,
-  objects: layoutObjects,
-  headerStatement,
-  incompatible,
-  storageError,
-  corruption: (table) =>
-    DoStorageCorruptionError.make({
-      table,
-      rowKey: "schema",
-      message: "Malformed storage layout or version header.",
-    }),
-});
+const inspection = (version: number, statements: ReadonlyArray<string>) =>
+  makeSqliteLayoutInspection({
+    version,
+    statements,
+    objects: layoutObjects(statements),
+    headerStatement,
+    incompatible,
+    storageError,
+    corruption: (table) =>
+      DoStorageCorruptionError.make({
+        table,
+        rowKey: "schema",
+        message: "Malformed storage layout or version header.",
+      }),
+  });
 
-const inspectStorage = Effect.fnUntraced(function* (): Effect.fn.Return<
+// Released predecessors retain the same record format and canonical tables.
+const addedIndexes = new Set(["effect_agent_message_deliveries_peer_retained"]);
+
+const layout25Statements = layoutObjects(layoutStatements)
+  .filter(([, name]) => !addedIndexes.has(name))
+  .map(([, , index]) =>
+    layoutStatements[index]
+      .replace(", peer_retained_until_millis INTEGER", "")
+      .replace(
+        "'$.envelope.messageAdmission.peerName') IS NOT NULL",
+        "'$.envelope.messageAdmission.schemaVersion') = 1",
+      ),
+  );
+
+const { decode, readObjects, readHeader } = inspection(CurrentDoStorageVersion, layoutStatements);
+const layout25 = inspection(25, layout25Statements);
+const layout26 = inspection(26, layoutStatements);
+
+const inspectStorage = Effect.fnUntraced(function* (
+  allowUpgrade = false,
+): Effect.fn.Return<
   DoStorageHeader | undefined,
   DoStorageCompatibilityError | DoStorageCorruptionError | DoStorageError,
   SqlClient.SqlClient
@@ -157,6 +184,17 @@ const inspectStorage = Effect.fnUntraced(function* (): Effect.fn.Return<
 
   const version = legacy.value;
 
+  if (allowUpgrade && (version === 25 || version === 26)) {
+    if (version === 25 && objects.some(({ name }) => addedIndexes.has(name)))
+      return yield* incompatible(version, "Mixed layout 25 and 26 objects.");
+    const predecessor = version === 25 ? layout25 : layout26;
+    const header = yield* predecessor.readHeader(objects, version);
+
+    yield* predecessor.readManagedTriggers(true);
+
+    return header;
+  }
+
   return yield* readHeader(objects, version);
 });
 
@@ -170,15 +208,46 @@ export const readDoStorageHeader = Effect.fnUntraced(function* () {
   return header;
 });
 
-/** Validate under the writer transaction before any DDL; initialize only a fresh store. */
+/** Initialize fresh storage or atomically upgrade the exact released layouts 25 and 26. */
 export const ensureDoStorageLayout = Effect.fn("DoStorage.initializeLayout")(function* () {
   const sql = (yield* SqlClient.SqlClient).withoutTransforms();
 
   return yield* sql
     .withTransaction(
       Effect.gen(function* () {
-        const header = yield* inspectStorage();
+        const header = yield* inspectStorage(true);
+
+        if (header?.layoutVersion === 25) {
+          yield* sql`ALTER TABLE effect_agent_message_deliveries ADD COLUMN peer_retained_until_millis INTEGER`;
+          yield* backfillPeerMessageRetention().pipe(
+            Effect.catchTag("MessageDeliveryError", () =>
+              DoStorageCorruptionError.make({
+                table: "effect_agent_message_deliveries",
+                rowKey: "upgrade",
+                message: "Invalid layout-25 delivery evidence; upgrade rolled back.",
+              }),
+            ),
+          );
+          yield* sql`DROP INDEX effect_agent_message_deliveries_peer`;
+          for (const [, name, index] of layoutObjects(layoutStatements))
+            if (addedIndexes.has(name) || name === "effect_agent_message_deliveries_peer")
+              yield* sql.unsafe(layoutStatements[index]).withoutTransform;
+        }
+        if (header?.layoutVersion === 25 || header?.layoutVersion === 26) {
+          yield* upgradeExecutionCheckpoints(undefined).pipe(
+            Effect.catchTag("ThreadStoreError", (cause) =>
+              DoStorageCorruptionError.make({
+                table: "effect_agent_executions",
+                rowKey: "upgrade",
+                message: `Invalid retained execution; upgrade rolled back: ${cause.message}`,
+              }),
+            ),
+          );
+          yield* sql`UPDATE effect_agent_schema SET layout_version=${CurrentDoStorageVersion} WHERE singleton=1`;
+          yield* sql`UPDATE effect_agent_meta SET value=${String(CurrentDoStorageVersion)} WHERE key='storage_version'`;
 
+          return yield* readDoStorageHeader();
+        }
         if (header !== undefined) return header;
         for (const statement of layoutStatements) yield* sql.unsafe(statement).withoutTransform;
         yield* createSqlThreadWorkTables().pipe(