@defrex/autobuild-postgres-store 0.8.0 → 0.10.0

package/src/schema.ts

@@ -8,7 +8,7 @@ import {
   assertAuthSchema,
 } from './auth-schema'
 
-export const SCHEMA_VERSION = 6
+export const SCHEMA_VERSION = 9
 export const MIGRATE_COMMAND = 'bun run postgres:migrate (from a pinned Autobuild release checkout)'
 
 /** The frozen v3 DDL, kept verbatim so a deployed v3 marker's checksum can be
@@ -376,6 +376,296 @@ CREATE TABLE IF NOT EXISTS stream_chunks (
 );`.trim()
 export const SCHEMA_V5_CHECKSUM = new Bun.CryptoHasher('sha256').update(SCHEMA_V5_DDL).digest('hex')
 
+/** The frozen v6 DDL, kept verbatim so a deployed v6 marker's checksum can be
+ * recognized and upgraded in place (see migratePostgres). v6 is the shape the
+ * hosted service ran immediately before the build-digest scan index (v7). */
+export const SCHEMA_V6_DDL = `
+CREATE TABLE IF NOT EXISTS ab_schema_migrations (
+  singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
+  version integer NOT NULL,
+  checksum text NOT NULL,
+  applied_at timestamptz NOT NULL
+);
+CREATE TABLE IF NOT EXISTS builds (
+  slug text PRIMARY KEY, repo text NOT NULL, ticket jsonb, branch text,
+  created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL,
+  lease_holder text, lease_expires_at timestamptz, lease_ttl_ms bigint,
+  heartbeat_at timestamptz, repo_origin text
+);
+CREATE TABLE IF NOT EXISTS events (
+  build text NOT NULL REFERENCES builds(slug) ON DELETE CASCADE,
+  seq bigint NOT NULL, ts timestamptz NOT NULL, actor jsonb NOT NULL,
+  type text NOT NULL, payload jsonb NOT NULL, PRIMARY KEY (build, seq)
+);
+CREATE TABLE IF NOT EXISTS artifacts (
+  build text NOT NULL REFERENCES builds(slug) ON DELETE CASCADE,
+  kind text NOT NULL, revision bigint NOT NULL, blob_ref text NOT NULL,
+  metadata jsonb NOT NULL, created_at timestamptz NOT NULL,
+  PRIMARY KEY (build, kind, revision)
+);
+CREATE TABLE IF NOT EXISTS repo_streams (
+  repo text PRIMARY KEY, created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL,
+  lease_holder text, lease_expires_at timestamptz, lease_ttl_ms bigint,
+  heartbeat_at timestamptz
+);
+CREATE TABLE IF NOT EXISTS repo_events (
+  repo text NOT NULL REFERENCES repo_streams(repo) ON DELETE CASCADE,
+  seq bigint NOT NULL, ts timestamptz NOT NULL, actor jsonb NOT NULL,
+  type text NOT NULL, payload jsonb NOT NULL, PRIMARY KEY (repo, seq)
+);
+CREATE TABLE IF NOT EXISTS repo_artifacts (
+  repo text NOT NULL REFERENCES repo_streams(repo) ON DELETE CASCADE,
+  kind text NOT NULL, revision bigint NOT NULL, blob_ref text NOT NULL,
+  metadata jsonb NOT NULL, created_at timestamptz NOT NULL,
+  PRIMARY KEY (repo, kind, revision)
+);
+CREATE SEQUENCE IF NOT EXISTS sessions_creation_seq;
+CREATE TABLE IF NOT EXISTS sessions (
+  id text PRIMARY KEY,
+  repo text NOT NULL,
+  operator text NOT NULL,
+  title text,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  creation_seq bigint NOT NULL
+);
+CREATE TABLE IF NOT EXISTS session_events (
+  session text NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  seq bigint NOT NULL, ts timestamptz NOT NULL, actor jsonb NOT NULL,
+  type text NOT NULL, payload jsonb NOT NULL, PRIMARY KEY (session, seq)
+);
+CREATE TABLE IF NOT EXISTS session_artifacts (
+  session text NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  kind text NOT NULL, revision bigint NOT NULL, blob_ref text NOT NULL,
+  metadata jsonb NOT NULL, created_at timestamptz NOT NULL,
+  PRIMARY KEY (session, kind, revision)
+);
+CREATE SEQUENCE IF NOT EXISTS streams_creation_seq;
+CREATE TABLE IF NOT EXISTS streams (
+  id text PRIMARY KEY, scope_kind text NOT NULL,
+  build text REFERENCES builds(slug) ON DELETE CASCADE,
+  repo text REFERENCES repo_streams(repo) ON DELETE CASCADE,
+  label text NOT NULL, format text NOT NULL, status text NOT NULL,
+  outcome text, artifact_kind text, artifact_revision bigint,
+  artifact_blob_ref text, created_at timestamptz NOT NULL, closed_at timestamptz,
+  session text REFERENCES sessions(id) ON DELETE CASCADE,
+  creation_seq bigint NOT NULL,
+  CONSTRAINT streams_scope_kind_check CHECK (scope_kind IN ('build','repo','session')),
+  CONSTRAINT streams_status_check CHECK (status IN ('open','closed')),
+  CONSTRAINT streams_scope_exactly_one_check CHECK (
+    (scope_kind = 'build' AND build IS NOT NULL AND repo IS NULL AND session IS NULL)
+    OR (scope_kind = 'repo' AND build IS NULL AND repo IS NOT NULL AND session IS NULL)
+    OR (scope_kind = 'session' AND build IS NULL AND repo IS NULL AND session IS NOT NULL)
+  )
+);
+CREATE TABLE IF NOT EXISTS stream_chunks (
+  stream text NOT NULL REFERENCES streams(id) ON DELETE CASCADE,
+  seq bigint NOT NULL, ts timestamptz NOT NULL, parts jsonb NOT NULL,
+  PRIMARY KEY (stream, seq)
+);`.trim()
+export const SCHEMA_V6_CHECKSUM = new Bun.CryptoHasher('sha256').update(SCHEMA_V6_DDL).digest('hex')
+
+/** The frozen v7 DDL, kept verbatim so a deployed v7 marker's checksum can be
+ * recognized and upgraded in place (see migratePostgres). v7 is the shape the
+ * hosted service ran immediately before the repository-journal state-read
+ * index (v8, AUT-489). Frozen pre-trimmed (the V1–V6 pattern): a deployed
+ * marker's checksum is taken over the trimmed DDL, so an untrimmed constant
+ * would hash surrounding whitespace no deployed database ever carried and the
+ * promotion branch would never match. */
+export const SCHEMA_V7_DDL = `
+CREATE TABLE IF NOT EXISTS ab_schema_migrations (
+  singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
+  version integer NOT NULL,
+  checksum text NOT NULL,
+  applied_at timestamptz NOT NULL
+);
+CREATE TABLE IF NOT EXISTS builds (
+  slug text PRIMARY KEY, repo text NOT NULL, ticket jsonb, branch text,
+  created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL,
+  lease_holder text, lease_expires_at timestamptz, lease_ttl_ms bigint,
+  heartbeat_at timestamptz, repo_origin text
+);
+CREATE TABLE IF NOT EXISTS events (
+  build text NOT NULL REFERENCES builds(slug) ON DELETE CASCADE,
+  seq bigint NOT NULL, ts timestamptz NOT NULL, actor jsonb NOT NULL,
+  type text NOT NULL, payload jsonb NOT NULL, PRIMARY KEY (build, seq)
+);
+CREATE TABLE IF NOT EXISTS artifacts (
+  build text NOT NULL REFERENCES builds(slug) ON DELETE CASCADE,
+  kind text NOT NULL, revision bigint NOT NULL, blob_ref text NOT NULL,
+  metadata jsonb NOT NULL, created_at timestamptz NOT NULL,
+  PRIMARY KEY (build, kind, revision)
+);
+CREATE TABLE IF NOT EXISTS repo_streams (
+  repo text PRIMARY KEY, created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL,
+  lease_holder text, lease_expires_at timestamptz, lease_ttl_ms bigint,
+  heartbeat_at timestamptz
+);
+CREATE TABLE IF NOT EXISTS repo_events (
+  repo text NOT NULL REFERENCES repo_streams(repo) ON DELETE CASCADE,
+  seq bigint NOT NULL, ts timestamptz NOT NULL, actor jsonb NOT NULL,
+  type text NOT NULL, payload jsonb NOT NULL, PRIMARY KEY (repo, seq)
+);
+CREATE TABLE IF NOT EXISTS repo_artifacts (
+  repo text NOT NULL REFERENCES repo_streams(repo) ON DELETE CASCADE,
+  kind text NOT NULL, revision bigint NOT NULL, blob_ref text NOT NULL,
+  metadata jsonb NOT NULL, created_at timestamptz NOT NULL,
+  PRIMARY KEY (repo, kind, revision)
+);
+CREATE SEQUENCE IF NOT EXISTS sessions_creation_seq;
+CREATE TABLE IF NOT EXISTS sessions (
+  id text PRIMARY KEY,
+  repo text NOT NULL,
+  operator text NOT NULL,
+  title text,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  creation_seq bigint NOT NULL
+);
+CREATE TABLE IF NOT EXISTS session_events (
+  session text NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  seq bigint NOT NULL, ts timestamptz NOT NULL, actor jsonb NOT NULL,
+  type text NOT NULL, payload jsonb NOT NULL, PRIMARY KEY (session, seq)
+);
+CREATE TABLE IF NOT EXISTS session_artifacts (
+  session text NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  kind text NOT NULL, revision bigint NOT NULL, blob_ref text NOT NULL,
+  metadata jsonb NOT NULL, created_at timestamptz NOT NULL,
+  PRIMARY KEY (session, kind, revision)
+);
+CREATE SEQUENCE IF NOT EXISTS streams_creation_seq;
+CREATE TABLE IF NOT EXISTS streams (
+  id text PRIMARY KEY, scope_kind text NOT NULL,
+  build text REFERENCES builds(slug) ON DELETE CASCADE,
+  repo text REFERENCES repo_streams(repo) ON DELETE CASCADE,
+  label text NOT NULL, format text NOT NULL, status text NOT NULL,
+  outcome text, artifact_kind text, artifact_revision bigint,
+  artifact_blob_ref text, created_at timestamptz NOT NULL, closed_at timestamptz,
+  session text REFERENCES sessions(id) ON DELETE CASCADE,
+  creation_seq bigint NOT NULL,
+  CONSTRAINT streams_scope_kind_check CHECK (scope_kind IN ('build','repo','session')),
+  CONSTRAINT streams_status_check CHECK (status IN ('open','closed')),
+  CONSTRAINT streams_scope_exactly_one_check CHECK (
+    (scope_kind = 'build' AND build IS NOT NULL AND repo IS NULL AND session IS NULL)
+    OR (scope_kind = 'repo' AND build IS NULL AND repo IS NOT NULL AND session IS NULL)
+    OR (scope_kind = 'session' AND build IS NULL AND repo IS NULL AND session IS NOT NULL)
+  )
+);
+CREATE TABLE IF NOT EXISTS stream_chunks (
+  stream text NOT NULL REFERENCES streams(id) ON DELETE CASCADE,
+  seq bigint NOT NULL, ts timestamptz NOT NULL, parts jsonb NOT NULL,
+  PRIMARY KEY (stream, seq)
+);
+
+-- The build-digest scan index (AUT-487): type-leading, so the digest query's
+-- cost grows with the observation/terminal events themselves, not with total
+-- history. Created idempotently so pre-v7 databases gain it on migrate.
+CREATE INDEX IF NOT EXISTS events_type_build_seq ON events (type, build, seq);`.trim()
+export const SCHEMA_V7_CHECKSUM = new Bun.CryptoHasher('sha256').update(SCHEMA_V7_DDL).digest('hex')
+
+/** The frozen v8 DDL, kept verbatim so a deployed v8 marker's checksum can be
+ * recognized and upgraded in place (see migratePostgres). v8 is the shape the
+ * hosted service ran immediately before ticket assets (v9). Frozen pre-trimmed
+ * (the V1–V7 pattern): a deployed marker's checksum is taken over the trimmed
+ * DDL. */
+export const SCHEMA_V8_DDL = `
+CREATE TABLE IF NOT EXISTS ab_schema_migrations (
+  singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
+  version integer NOT NULL,
+  checksum text NOT NULL,
+  applied_at timestamptz NOT NULL
+);
+CREATE TABLE IF NOT EXISTS builds (
+  slug text PRIMARY KEY, repo text NOT NULL, ticket jsonb, branch text,
+  created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL,
+  lease_holder text, lease_expires_at timestamptz, lease_ttl_ms bigint,
+  heartbeat_at timestamptz, repo_origin text
+);
+CREATE TABLE IF NOT EXISTS events (
+  build text NOT NULL REFERENCES builds(slug) ON DELETE CASCADE,
+  seq bigint NOT NULL, ts timestamptz NOT NULL, actor jsonb NOT NULL,
+  type text NOT NULL, payload jsonb NOT NULL, PRIMARY KEY (build, seq)
+);
+CREATE TABLE IF NOT EXISTS artifacts (
+  build text NOT NULL REFERENCES builds(slug) ON DELETE CASCADE,
+  kind text NOT NULL, revision bigint NOT NULL, blob_ref text NOT NULL,
+  metadata jsonb NOT NULL, created_at timestamptz NOT NULL,
+  PRIMARY KEY (build, kind, revision)
+);
+CREATE TABLE IF NOT EXISTS repo_streams (
+  repo text PRIMARY KEY, created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL,
+  lease_holder text, lease_expires_at timestamptz, lease_ttl_ms bigint,
+  heartbeat_at timestamptz
+);
+CREATE TABLE IF NOT EXISTS repo_events (
+  repo text NOT NULL REFERENCES repo_streams(repo) ON DELETE CASCADE,
+  seq bigint NOT NULL, ts timestamptz NOT NULL, actor jsonb NOT NULL,
+  type text NOT NULL, payload jsonb NOT NULL, PRIMARY KEY (repo, seq)
+);
+CREATE TABLE IF NOT EXISTS repo_artifacts (
+  repo text NOT NULL REFERENCES repo_streams(repo) ON DELETE CASCADE,
+  kind text NOT NULL, revision bigint NOT NULL, blob_ref text NOT NULL,
+  metadata jsonb NOT NULL, created_at timestamptz NOT NULL,
+  PRIMARY KEY (repo, kind, revision)
+);
+CREATE SEQUENCE IF NOT EXISTS sessions_creation_seq;
+CREATE TABLE IF NOT EXISTS sessions (
+  id text PRIMARY KEY,
+  repo text NOT NULL,
+  operator text NOT NULL,
+  title text,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  creation_seq bigint NOT NULL
+);
+CREATE TABLE IF NOT EXISTS session_events (
+  session text NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  seq bigint NOT NULL, ts timestamptz NOT NULL, actor jsonb NOT NULL,
+  type text NOT NULL, payload jsonb NOT NULL, PRIMARY KEY (session, seq)
+);
+CREATE TABLE IF NOT EXISTS session_artifacts (
+  session text NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  kind text NOT NULL, revision bigint NOT NULL, blob_ref text NOT NULL,
+  metadata jsonb NOT NULL, created_at timestamptz NOT NULL,
+  PRIMARY KEY (session, kind, revision)
+);
+CREATE SEQUENCE IF NOT EXISTS streams_creation_seq;
+CREATE TABLE IF NOT EXISTS streams (
+  id text PRIMARY KEY, scope_kind text NOT NULL,
+  build text REFERENCES builds(slug) ON DELETE CASCADE,
+  repo text REFERENCES repo_streams(repo) ON DELETE CASCADE,
+  label text NOT NULL, format text NOT NULL, status text NOT NULL,
+  outcome text, artifact_kind text, artifact_revision bigint,
+  artifact_blob_ref text, created_at timestamptz NOT NULL, closed_at timestamptz,
+  session text REFERENCES sessions(id) ON DELETE CASCADE,
+  creation_seq bigint NOT NULL,
+  CONSTRAINT streams_scope_kind_check CHECK (scope_kind IN ('build','repo','session')),
+  CONSTRAINT streams_status_check CHECK (status IN ('open','closed')),
+  CONSTRAINT streams_scope_exactly_one_check CHECK (
+    (scope_kind = 'build' AND build IS NOT NULL AND repo IS NULL AND session IS NULL)
+    OR (scope_kind = 'repo' AND build IS NULL AND repo IS NOT NULL AND session IS NULL)
+    OR (scope_kind = 'session' AND build IS NULL AND repo IS NULL AND session IS NOT NULL)
+  )
+);
+CREATE TABLE IF NOT EXISTS stream_chunks (
+  stream text NOT NULL REFERENCES streams(id) ON DELETE CASCADE,
+  seq bigint NOT NULL, ts timestamptz NOT NULL, parts jsonb NOT NULL,
+  PRIMARY KEY (stream, seq)
+);
+
+-- The build-digest scan index (AUT-487): type-leading, so the digest query's
+-- cost grows with the observation/terminal events themselves, not with total
+-- history. Created idempotently so pre-v7 databases gain it on migrate.
+CREATE INDEX IF NOT EXISTS events_type_build_seq ON events (type, build, seq);
+
+-- The repository-journal state read index (AUT-489): (repo, type, seq), so
+-- the bounded state read's anchor query — MAX(seq) over the repo's
+-- run-started facts — and its durable-type select both scan only their own
+-- signal, never the repo's whole journal. Created idempotently so pre-v8
+-- databases gain it on migrate.
+CREATE INDEX IF NOT EXISTS repo_events_type_repo_seq ON repo_events (repo, type, seq);`.trim()
+export const SCHEMA_V8_CHECKSUM = new Bun.CryptoHasher('sha256').update(SCHEMA_V8_DDL).digest('hex')
+
 export const SCHEMA_DDL = `
 CREATE TABLE IF NOT EXISTS ab_schema_migrations (
   singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
@@ -459,6 +749,28 @@ CREATE TABLE IF NOT EXISTS stream_chunks (
   stream text NOT NULL REFERENCES streams(id) ON DELETE CASCADE,
   seq bigint NOT NULL, ts timestamptz NOT NULL, parts jsonb NOT NULL,
   PRIMARY KEY (stream, seq)
+);
+
+-- The build-digest scan index (AUT-487): type-leading, so the digest query's
+-- cost grows with the observation/terminal events themselves, not with total
+-- history. Created idempotently so pre-v7 databases gain it on migrate.
+CREATE INDEX IF NOT EXISTS events_type_build_seq ON events (type, build, seq);
+
+-- The repository-journal state read index (AUT-489): (repo, type, seq), so
+-- the bounded state read's anchor query — MAX(seq) over the repo's
+-- run-started facts — and its durable-type select both scan only their own
+-- signal, never the repo's whole journal. Created idempotently so pre-v8
+-- databases gain it on migrate.
+CREATE INDEX IF NOT EXISTS repo_events_type_repo_seq ON repo_events (repo, type, seq);
+-- Ticket assets (SPEC §7.1): one row per revision, manifest as jsonb, file
+-- bytes in the blob store. A removal is a tombstone row (removed = true, empty
+-- manifest) taking the next revision. No FK to repo_streams: assets can
+-- precede any repo-journal row.
+CREATE TABLE IF NOT EXISTS ticket_assets (
+  repo text NOT NULL, ticket_id text NOT NULL, kind text NOT NULL, name text NOT NULL,
+  revision bigint NOT NULL, layout text NOT NULL, manifest jsonb NOT NULL,
+  size bigint NOT NULL, removed boolean NOT NULL, created_at timestamptz NOT NULL,
+  PRIMARY KEY (repo, ticket_id, kind, name, revision)
 );`.trim()
 
 export const SCHEMA_CHECKSUM = new Bun.CryptoHasher('sha256').update(SCHEMA_DDL).digest('hex')
@@ -495,6 +807,21 @@ export const TICKET_SCHEMA_CHECKSUM = new Bun.CryptoHasher('sha256')
   .update(TICKET_SCHEMA_DDL)
   .digest('hex')
 
+/** Reducer snapshots (core `store/snapshots.ts`): a cache beside the event log.
+ * Deliberately outside `SCHEMA_DDL`, its marker, version and checksum, and
+ * outside `EXPECTED_COLUMNS`: a deployment at the current schema keeps serving
+ * across the upgrade, a new client against a database that lacks the table
+ * degrades to full replay (SQLSTATE 42P01 reads as "no snapshot"), and an older
+ * client never asks for it. Idempotent — `migratePostgres` creates it next to
+ * the ticket tables. */
+export const SNAPSHOT_SCHEMA_DDL = `
+CREATE TABLE IF NOT EXISTS reducer_snapshots (
+  scope_kind text NOT NULL, scope_key text NOT NULL, reducer text NOT NULL,
+  version integer NOT NULL, cursor bigint NOT NULL, state jsonb NOT NULL,
+  updated_at timestamptz NOT NULL,
+  PRIMARY KEY (scope_kind, scope_key, reducer)
+);`.trim()
+
 type ExpectedColumn = readonly [name: string, type: string, notNull: boolean, defaultValue?: string]
 
 const EXPECTED_COLUMNS: Record<string, readonly ExpectedColumn[]> = {
@@ -536,6 +863,18 @@ const EXPECTED_COLUMNS: Record<string, readonly ExpectedColumn[]> = {
     ['metadata', 'jsonb', true],
     ['created_at', 'timestamp with time zone', true],
   ],
+  ticket_assets: [
+    ['repo', 'text', true],
+    ['ticket_id', 'text', true],
+    ['kind', 'text', true],
+    ['name', 'text', true],
+    ['revision', 'bigint', true],
+    ['layout', 'text', true],
+    ['manifest', 'jsonb', true],
+    ['size', 'bigint', true],
+    ['removed', 'boolean', true],
+    ['created_at', 'timestamp with time zone', true],
+  ],
   repo_streams: [
     ['repo', 'text', true],
     ['created_at', 'timestamp with time zone', true],
@@ -647,12 +986,30 @@ const EXPECTED_CONSTRAINTS = [
   'streams|f|repo|repo_streams|repo|c|',
   'streams|f|session|sessions|id|c|',
   'streams|p|id||||',
+  'ticket_assets|p|repo,ticket_id,kind,name,revision||||',
 ] as const
 
 export function schemaError(detail: string): Error {
   return new Error(`PostgreSQL BuildStore schema ${detail}; run: ${MIGRATE_COMMAND}`)
 }
 
+/** The targeted cause text for a marker whose version matches the required
+ * version but whose checksum does not: exactly the shape a checksum-only
+ * re-pin leaves deployed databases in (AUT-548) — and also the shape of a
+ * database built by a different build of the same version, which a marker
+ * alone cannot distinguish, so both causes are named. The guard's failure
+ * output teaches the four-step rule pre-ship; this diagnostic catches the
+ * checksum-only shortcut after the fact. */
+function checksumMismatchCause(version: number): string {
+  return (
+    `its version matches ${version}, but its checksum does not match this build's DDL — the ` +
+    `current DDL was likely edited in place without bumping the version, or the database was ` +
+    `built by a different build of this same version. Never edit deployed DDL; follow the ` +
+    `four-step rule (freeze the previous DDL, add an upgrade branch in migratePostgres, bump ` +
+    `the version, re-pin in schema-guard.test.ts) and redeploy`
+  )
+}
+
 interface CatalogColumn {
   table_name: string
   column_name: string
@@ -775,7 +1132,9 @@ export async function assertSchema(sql: SQL): Promise<void> {
   if (Number(marker.version) !== SCHEMA_VERSION) {
     throw schemaError(`version ${marker.version} does not match required version ${SCHEMA_VERSION}`)
   }
-  if (marker.checksum !== SCHEMA_CHECKSUM) throw schemaError('checksum is mismatched')
+  if (marker.checksum !== SCHEMA_CHECKSUM) {
+    throw schemaError(`checksum is mismatched: ${checksumMismatchCause(SCHEMA_VERSION)}`)
+  }
   await assertCatalogShape(sql)
 }
 
@@ -792,11 +1151,16 @@ export async function assertTicketSchema(sql: SQL): Promise<void> {
   }
   const marker = rows[0]
   if (!marker) throw schemaError('ticket marker is missing')
-  if (
-    Number(marker.version) !== TICKET_SCHEMA_VERSION ||
-    marker.checksum !== TICKET_SCHEMA_CHECKSUM
-  ) {
-    throw schemaError('ticket marker is incompatible')
+  if (Number(marker.version) !== TICKET_SCHEMA_VERSION) {
+    throw schemaError(
+      `ticket marker is incompatible: version ${marker.version} does not match required version ` +
+        `${TICKET_SCHEMA_VERSION}`,
+    )
+  }
+  if (marker.checksum !== TICKET_SCHEMA_CHECKSUM) {
+    throw schemaError(
+      `ticket marker is incompatible: ${checksumMismatchCause(TICKET_SCHEMA_VERSION)}`,
+    )
   }
   const expected: Record<string, Array<[string, string, boolean]>> = {
     ab_ticket_schema_migrations: [
@@ -851,7 +1215,7 @@ export async function assertTicketSchema(sql: SQL): Promise<void> {
   }
 }
 
-/** The guarded streams.creation_seq upgrade, shared by every pre-v6 marker
+/** The guarded streams.creation_seq upgrade, shared by every pre-v7 marker
  * branch whose database carries a pre-existing streams table (v2, v3, v4, v5).
  * The idempotent full DDL above has already created the
  * streams_creation_seq sequence; the column is added only when missing, with
@@ -886,17 +1250,18 @@ export async function migratePostgres(url: string): Promise<void> {
       await tx`SELECT pg_advisory_xact_lock(470281941)`
       await tx.unsafe(SCHEMA_DDL)
       await tx.unsafe(TICKET_SCHEMA_DDL)
+      await tx.unsafe(SNAPSHOT_SCHEMA_DDL)
       await tx.unsafe(AUTH_SCHEMA_DDL)
       const rows: { version: number; checksum: string }[] =
         await tx`SELECT version, checksum FROM ab_schema_migrations WHERE singleton = true FOR UPDATE`
       const marker = rows[0]
       if (marker) {
-        // v1–v5 → v6: the guarded builds.repo_origin column runs for EVERY
-        // pre-v6 marker, before the version branches — not only in a v4
+        // v1–v7 → v9: the guarded builds.repo_origin column runs for EVERY
+        // pre-v7 marker, before the version branches — not only in a v4
         // branch. `CREATE TABLE IF NOT EXISTS builds` does not alter an
         // existing builds table, so without this the internal assertSchema
         // below would fail on every upgraded legacy database. The ALTER is
-        // guarded and idempotent, so re-running it on a v6 database (or a
+        // guarded and idempotent, so re-running it on a v7 database (or a
         // marker that turns out to be rejected below, which rolls this
         // transaction back) is a no-op.
         await tx.unsafe(`
@@ -910,25 +1275,49 @@ export async function migratePostgres(url: string): Promise<void> {
             END IF;
           END $$;
         `)
+        // v6 → v7: the guarded build-digest scan index (AUT-487) likewise
+        // runs for EVERY pre-v7 marker (and, with the state-read index below,
+        // every pre-v8 marker) — the idempotent full DDL above only
+        // creates an index on a database that lacks the events table, never
+        // on a pre-existing one. Guarded and idempotent (the repo_origin
+        // precedent), so it is a no-op on fresh installs, on v7 reruns, and
+        // on markers rejected below (which roll the transaction back).
+        await tx.unsafe(
+          `CREATE INDEX IF NOT EXISTS events_type_build_seq ON events (type, build, seq)`,
+        )
+        // v7 → v9: the guarded repository-journal state-read index (AUT-489)
+        // likewise runs for EVERY pre-v8 marker — same reasoning as the
+        // digest-scan index above. Guarded and idempotent, so it is a no-op
+        // on fresh installs, on v8 reruns, and on markers rejected below
+        // (which roll the transaction back). Indexes are not catalog-asserted,
+        // so no EXPECTED_* change.
+        await tx.unsafe(
+          `CREATE INDEX IF NOT EXISTS repo_events_type_repo_seq ON repo_events (repo, type, seq)`,
+        )
         const version = Number(marker.version)
         if (version === SCHEMA_VERSION) {
-          if (marker.checksum !== SCHEMA_CHECKSUM) throw schemaError('marker is incompatible')
+          if (marker.checksum !== SCHEMA_CHECKSUM) {
+            throw schemaError(`marker is incompatible: ${checksumMismatchCause(SCHEMA_VERSION)}`)
+          }
         } else if (version === 1 && marker.checksum === SCHEMA_V1_CHECKSUM) {
-          // v1 → v6: the idempotent full DDL above already applied the deltas
+          // v1 → v9: the idempotent full DDL above already applied the deltas
           // (the stream tables and the session tables); v1 databases never had
           // a streams or sessions table, so the full DDL created them with the
           // session column, the widened CHECKs, and both creation_seq columns.
-          // The guarded repo_origin ALTER above covered builds. Promote the
-          // marker in this transaction.
+          // The guarded repo_origin ALTER and the guarded digest-scan index
+          // above covered the pre-existing tables. Promote the marker in this
+          // transaction.
           await tx`UPDATE ab_schema_migrations
             SET version = ${SCHEMA_VERSION}, checksum = ${SCHEMA_CHECKSUM},
               applied_at = ${new Date().toISOString()}
             WHERE singleton = true`
         } else if (version === 2 && marker.checksum === SCHEMA_V2_CHECKSUM) {
-          // v2 → v6: the idempotent full DDL above created the session tables
+          // v2 → v9: the idempotent full DDL above created the session tables
           // (with the creation_seq column); a v2 database's streams table
           // needs the guarded session column, the widened CHECK constraints,
-          // and the guarded creation_seq column (shared with v3 and v4).
+          // and the guarded creation_seq column (shared with v3 and v4). The
+          // guarded repo_origin ALTER and the guarded digest-scan index above
+          // covered the pre-existing builds and events tables.
           await tx.unsafe(`
             DO $$ BEGIN
               IF NOT EXISTS (
@@ -958,7 +1347,7 @@ export async function migratePostgres(url: string): Promise<void> {
               applied_at = ${new Date().toISOString()}
             WHERE singleton = true`
         } else if (version === 3 && marker.checksum === SCHEMA_V3_CHECKSUM) {
-          // v3 → v6: the listSessions and listStreams creation-order
+          // v3 → v9: the listSessions and listStreams creation-order
           // tiebreaks (store/types.ts). The idempotent full DDL above created
           // the sessions_creation_seq and streams_creation_seq sequences; a
           // v3 database's sessions and streams tables need the guarded
@@ -967,8 +1356,8 @@ export async function migratePostgres(url: string): Promise<void> {
           // unorderable, so any total order consistent with createdAt is
           // acceptable — SET NOT NULL, and the sequence positioned above the
           // backfilled values so the next nextval continues the counter
-          // without collision. The guarded repo_origin ALTER above covered
-          // builds.
+          // without collision. The guarded repo_origin ALTER and the guarded
+          // digest-scan index above covered the pre-existing tables.
           await tx.unsafe(`
             DO $$ BEGIN
               IF NOT EXISTS (
@@ -994,32 +1383,58 @@ export async function migratePostgres(url: string): Promise<void> {
               applied_at = ${new Date().toISOString()}
             WHERE singleton = true`
         } else if (version === 4 && marker.checksum === SCHEMA_V4_CHECKSUM) {
-          // v4 → v6: the listStreams creation-order tiebreak
+          // v4 → v9: the listStreams creation-order tiebreak
           // (store/types.ts), mirroring the v3→v4 sessions treatment. The
           // idempotent full DDL above created the streams_creation_seq
           // sequence; a v4 database's streams table needs the guarded
           // creation_seq column, backfill, NOT NULL, and sequence continuity
           // (the shared pre-v6 streams migration). The guarded repo_origin
-          // ALTER above covered builds.
+          // ALTER and the guarded digest-scan index above covered the
+          // pre-existing tables.
           await tx.unsafe(STREAMS_CREATION_SEQ_MIGRATION)
           await tx`UPDATE ab_schema_migrations
             SET version = ${SCHEMA_VERSION}, checksum = ${SCHEMA_CHECKSUM},
               applied_at = ${new Date().toISOString()}
             WHERE singleton = true`
         } else if (version === 5 && marker.checksum === SCHEMA_V5_CHECKSUM) {
-          // v5 → v6: the listStreams creation-order tiebreak (store/types.ts)
+          // v5 → v9: the listStreams creation-order tiebreak (store/types.ts)
           // landed on the v5 DDL without a version bump, so the hosted
           // database carries the v5 marker with the pre-tiebreak checksum. The
           // idempotent full DDL above created the streams_creation_seq
           // sequence; a v5 database's streams table needs the guarded
           // creation_seq column, backfill, NOT NULL, and sequence continuity
-          // (the shared pre-v6 streams migration). Every other v6 table and
-          // column already exists in a v5 database.
+          // (the shared pre-v6 streams migration). Every other pre-v7 table
+          // and column already exists in a v5 database; the guarded
+          // digest-scan index above covers events.
           await tx.unsafe(STREAMS_CREATION_SEQ_MIGRATION)
           await tx`UPDATE ab_schema_migrations
             SET version = ${SCHEMA_VERSION}, checksum = ${SCHEMA_CHECKSUM},
               applied_at = ${new Date().toISOString()}
             WHERE singleton = true`
+        } else if (version === 6 && marker.checksum === SCHEMA_V6_CHECKSUM) {
+          // v6 → v9: the guarded digest-scan index above is the v6→v7 delta;
+          // every v6 table and column already exists. Promote the marker in
+          // this transaction.
+          await tx`UPDATE ab_schema_migrations
+            SET version = ${SCHEMA_VERSION}, checksum = ${SCHEMA_CHECKSUM},
+              applied_at = ${new Date().toISOString()}
+            WHERE singleton = true`
+        } else if (version === 7 && marker.checksum === SCHEMA_V7_CHECKSUM) {
+          // v7 → v9: the guarded repository-journal state-read index above
+          // is the entire delta; every v7 table and column already exists.
+          // Promote the marker in this transaction.
+          await tx`UPDATE ab_schema_migrations
+            SET version = ${SCHEMA_VERSION}, checksum = ${SCHEMA_CHECKSUM},
+              applied_at = ${new Date().toISOString()}
+            WHERE singleton = true`
+        } else if (version === 8 && marker.checksum === SCHEMA_V8_CHECKSUM) {
+          // v8 → v9: the idempotent full DDL above created the ticket_assets
+          // table, which is the entire delta (no pre-existing table changes).
+          // Promote the marker in this transaction.
+          await tx`UPDATE ab_schema_migrations
+            SET version = ${SCHEMA_VERSION}, checksum = ${SCHEMA_CHECKSUM},
+              applied_at = ${new Date().toISOString()}
+            WHERE singleton = true`
         } else {
           throw schemaError('marker is incompatible')
         }
@@ -1031,11 +1446,16 @@ export async function migratePostgres(url: string): Promise<void> {
         await tx`SELECT version, checksum FROM ab_ticket_schema_migrations WHERE singleton = true FOR UPDATE`
       const ticketMarker = ticketRows[0]
       if (ticketMarker) {
-        if (
-          Number(ticketMarker.version) !== TICKET_SCHEMA_VERSION ||
-          ticketMarker.checksum !== TICKET_SCHEMA_CHECKSUM
-        ) {
-          throw schemaError('ticket marker is incompatible')
+        if (Number(ticketMarker.version) !== TICKET_SCHEMA_VERSION) {
+          throw schemaError(
+            `ticket marker is incompatible: version ${ticketMarker.version} does not match ` +
+              `required version ${TICKET_SCHEMA_VERSION}`,
+          )
+        }
+        if (ticketMarker.checksum !== TICKET_SCHEMA_CHECKSUM) {
+          throw schemaError(
+            `ticket marker is incompatible: ${checksumMismatchCause(TICKET_SCHEMA_VERSION)}`,
+          )
         }
       } else {
         await tx`INSERT INTO ab_ticket_schema_migrations
@@ -1062,7 +1482,9 @@ export async function migratePostgres(url: string): Promise<void> {
         const authVersion = Number(authMarker.version)
         if (authVersion === AUTH_SCHEMA_VERSION) {
           if (authMarker.checksum !== AUTH_SCHEMA_CHECKSUM) {
-            throw schemaError('auth marker is incompatible')
+            throw schemaError(
+              `auth marker is incompatible: ${checksumMismatchCause(AUTH_SCHEMA_VERSION)}`,
+            )
           }
         } else if (authVersion === 1 && authMarker.checksum === AUTH_SCHEMA_V1_CHECKSUM) {
           // v1 → v3: the idempotent full DDL above already created the four