@defrex/autobuild-postgres-store 0.12.0 → 0.13.0

package/README.md

@@ -119,9 +119,9 @@ Only an object-store 404 is treated as absent; authorization and service errors
 are propagated. Vercel supports either a Blob read-write token or a Vercel OIDC
 token paired with its Blob store ID.
 
-`PostgresTicketDatabase.source({ teamKey, claimedState?, createState? })` creates
-a request-bound TicketSource view. The deployment supplies four distinct
-lifecycle names; the defaults are Triage, Ready, Doing, and Done. Ticket bodies
+`PostgresTicketDatabase.source({ repo, teamKey, lifecycle, claimedState?, createState? })`
+creates a request-bound TicketSource view. The deployment supplies the project
+identity, readable-id prefix, and lifecycle names. Ticket bodies
 are stored as PostgreSQL `text` and returned unchanged.
 
 For an authenticated HTTP deployment of this adapter, see the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defrex/autobuild-postgres-store",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "license": "Apache-2.0",
   "engines": {
@@ -34,6 +34,14 @@
     "./connections": {
       "types": "./src/connections.ts",
       "import": "./src/connections.ts"
+    },
+    "./ticket-policy": {
+      "types": "./src/ticket-policy.ts",
+      "import": "./src/ticket-policy.ts"
+    },
+    "./ticket-grants": {
+      "types": "./src/ticket-grants.ts",
+      "import": "./src/ticket-grants.ts"
     }
   },
   "bin": {

package/src/schema.ts

@@ -1,7 +1,11 @@
 import { PostgresProjectRegistry } from './projects'
 import type { PostgresEnv } from './env'
 import type { BlobStore } from '@defrex/autobuild/plugin-sdk'
-import { migrateLegacyTickets } from './ticket-migration'
+import {
+  migrateLegacyTickets,
+  migrateReadableTickets,
+  READABLE_TICKET_CONSTRAINTS,
+} from './ticket-migration'
 import { SQL } from 'bun'
 import {
   AUTH_SCHEMA_CHECKSUM,
@@ -12,7 +16,7 @@ import {
   assertAuthSchema,
 } from './auth-schema'
 
-export const SCHEMA_VERSION = 12
+export const SCHEMA_VERSION = 13
 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
@@ -817,12 +821,27 @@ CREATE TABLE IF NOT EXISTS project_connections (
 CREATE TABLE IF NOT EXISTS connection_lookup_limits (
   actor text PRIMARY KEY, started_at timestamptz NOT NULL, attempts integer NOT NULL
 );`.trim()
-export const SCHEMA_DDL = `${SCHEMA_V11_DDL}\n${CONNECTION_SCHEMA_DDL}`
+export const SCHEMA_V12_DDL = `${SCHEMA_V11_DDL}\n${CONNECTION_SCHEMA_DDL}`
+export const SCHEMA_V12_CHECKSUM = new Bun.CryptoHasher('sha256')
+  .update(SCHEMA_V12_DDL)
+  .digest('hex')
+export const TICKET_POLICY_SCHEMA_DDL = `
+CREATE TABLE IF NOT EXISTS project_ticket_policy (
+  repo text PRIMARY KEY, registration bigint NOT NULL, policy jsonb NOT NULL,
+  writer text NOT NULL, updated_at timestamptz NOT NULL
+);`
+export const TICKET_GRANT_SCHEMA_DDL = `
+CREATE TABLE IF NOT EXISTS ticket_grants (
+ id text PRIMARY KEY, digest text NOT NULL UNIQUE, repo text NOT NULL, registration bigint NOT NULL,
+ execution text NOT NULL, kind text NOT NULL CHECK (kind IN ('runner','phase')),
+ parent text REFERENCES ticket_grants(id), expires_at timestamptz NOT NULL, revoked_at timestamptz
+);`
+export const SCHEMA_DDL = `${SCHEMA_V12_DDL}\n${TICKET_POLICY_SCHEMA_DDL}\n${TICKET_GRANT_SCHEMA_DDL}`
 export const SCHEMA_CHECKSUM = new Bun.CryptoHasher('sha256').update(SCHEMA_DDL).digest('hex')
 
 /** Ticket persistence evolves independently so deployed v1 BuildStore markers
  * remain valid while the hosted ticket tables are added. */
-export const TICKET_SCHEMA_VERSION = 2
+export const TICKET_SCHEMA_VERSION = 5
 export const TICKET_SCHEMA_V1_DDL = `
 CREATE TABLE IF NOT EXISTS ab_ticket_schema_migrations (
   singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
@@ -851,7 +870,35 @@ CREATE TABLE IF NOT EXISTS ab_ticket_blockers (
 export const TICKET_SCHEMA_V1_CHECKSUM = new Bun.CryptoHasher('sha256')
   .update(TICKET_SCHEMA_V1_DDL)
   .digest('hex')
-export const TICKET_SCHEMA_DDL = TICKET_SCHEMA_V1_DDL.replaceAll('team', 'repo')
+export const TICKET_SCHEMA_V2_DDL = TICKET_SCHEMA_V1_DDL.replaceAll('team', 'repo')
+export const TICKET_SCHEMA_V2_CHECKSUM = new Bun.CryptoHasher('sha256')
+  .update(TICKET_SCHEMA_V2_DDL)
+  .digest('hex')
+export const TICKET_SCHEMA_V3_DDL = TICKET_SCHEMA_V2_DDL.replace(
+  'updated_at timestamptz NOT NULL,',
+  'updated_at timestamptz NOT NULL, revision bigint NOT NULL DEFAULT 1,',
+)
+export const TICKET_SCHEMA_V3_CHECKSUM = new Bun.CryptoHasher('sha256')
+  .update(TICKET_SCHEMA_V3_DDL)
+  .digest('hex')
+export const TICKET_STATES_DDL = `CREATE TABLE IF NOT EXISTS ab_ticket_states (
+  repo text NOT NULL, name text NOT NULL, about text,
+  PRIMARY KEY (repo, name),
+  CHECK (length(btrim(name)) > 0),
+  CHECK (about IS NULL OR (length(btrim(about)) > 0 AND position(chr(10) in about) = 0 AND position(chr(13) in about) = 0))
+);`
+export const TICKET_SCHEMA_V4_DDL = `${TICKET_SCHEMA_V3_DDL}\n${TICKET_STATES_DDL}`
+export const TICKET_SCHEMA_V4_CHECKSUM = new Bun.CryptoHasher('sha256')
+  .update(TICKET_SCHEMA_V4_DDL)
+  .digest('hex')
+export const TICKET_SCHEMA_DDL =
+  TICKET_SCHEMA_V4_DDL +
+  `
+ALTER TABLE ab_tickets ADD COLUMN IF NOT EXISTS readable_id text;
+ALTER TABLE ab_tickets ADD COLUMN IF NOT EXISTS ticket_number bigint;
+CREATE TABLE IF NOT EXISTS ab_ticket_counters (repo text PRIMARY KEY, last_number bigint NOT NULL CHECK (last_number >= 0));
+` +
+  READABLE_TICKET_CONSTRAINTS.trim()
 export const TICKET_SCHEMA_CHECKSUM = new Bun.CryptoHasher('sha256')
   .update(TICKET_SCHEMA_DDL)
   .digest('hex')
@@ -893,6 +940,24 @@ const EXPECTED_COLUMNS: Record<string, readonly ExpectedColumn[]> = {
     ['started_at', 'timestamp with time zone', true],
     ['attempts', 'integer', true],
   ],
+  project_ticket_policy: [
+    ['repo', 'text', true],
+    ['registration', 'bigint', true],
+    ['policy', 'jsonb', true],
+    ['writer', 'text', true],
+    ['updated_at', 'timestamp with time zone', true],
+  ],
+  ticket_grants: [
+    ['id', 'text', true],
+    ['digest', 'text', true],
+    ['repo', 'text', true],
+    ['registration', 'bigint', true],
+    ['execution', 'text', true],
+    ['kind', 'text', true],
+    ['parent', 'text', false],
+    ['expires_at', 'timestamp with time zone', true],
+    ['revoked_at', 'timestamp with time zone', false],
+  ],
   project_credentials: [
     ['id', 'text', true],
     ['digest', 'text', true],
@@ -1048,6 +1113,10 @@ const EXPECTED_COLUMNS: Record<string, readonly ExpectedColumn[]> = {
 }
 
 const EXPECTED_CONSTRAINTS = [
+  'project_ticket_policy|p|repo||||',
+  'ticket_grants|p|id||||',
+  'ticket_grants|c|||||',
+  'ticket_grants|f|parent|ticket_grants|id|a|',
   'project_connections|p|id||||',
   'project_connections|c|||||',
   'connection_lookup_limits|p|actor||||',
@@ -1279,6 +1348,18 @@ export async function assertTicketSchema(sql: SQL): Promise<void> {
       ['labels', 'text[]', true],
       ['created_at', 'timestamp with time zone', true],
       ['updated_at', 'timestamp with time zone', true],
+      ['revision', 'bigint', true],
+      ['readable_id', 'text', true],
+      ['ticket_number', 'bigint', true],
+    ],
+    ab_ticket_counters: [
+      ['repo', 'text', true],
+      ['last_number', 'bigint', true],
+    ],
+    ab_ticket_states: [
+      ['repo', 'text', true],
+      ['name', 'text', true],
+      ['about', 'text', false],
     ],
     ab_ticket_comments: [
       ['repo', 'text', true],
@@ -1303,7 +1384,7 @@ export async function assertTicketSchema(sql: SQL): Promise<void> {
     WHERE n.nspname = current_schema() AND c.relkind IN ('r', 'p')
       AND a.attnum > 0 AND NOT a.attisdropped
       AND c.relname = ANY(ARRAY['ab_ticket_schema_migrations', 'ab_tickets',
-        'ab_ticket_comments', 'ab_ticket_blockers'])
+        'ab_ticket_comments', 'ab_ticket_blockers', 'ab_ticket_counters', 'ab_ticket_states'])
     ORDER BY c.relname, a.attnum`
   for (const [table, shape] of Object.entries(expected)) {
     const actual = columns
@@ -1313,13 +1394,32 @@ export async function assertTicketSchema(sql: SQL): Promise<void> {
       throw schemaError(`ticket table ${table} is missing or mismatched`)
     }
   }
+  const indexes =
+    await sql`SELECT indexdef FROM pg_indexes WHERE schemaname = current_schema() AND tablename = 'ab_tickets' AND indexname = 'ab_tickets_readable_id_key'`
+  if (
+    !indexes[0] ||
+    !String(indexes[0].indexdef).includes('UNIQUE INDEX') ||
+    !String(indexes[0].indexdef).endsWith('(repo, lower(readable_id))')
+  )
+    throw schemaError('ticket readable id unique index is missing or mismatched')
   const constraints: { table_name: string; definition: string }[] = await sql`
     SELECT c.relname AS table_name, pg_get_constraintdef(k.oid) AS definition
     FROM pg_constraint k JOIN pg_class c ON c.oid = k.conrelid
     JOIN pg_namespace n ON n.oid = c.relnamespace
-    WHERE n.nspname = current_schema() AND k.contype IN ('p', 'u', 'f', 'c') AND c.relname IN ('ab_tickets', 'ab_ticket_comments', 'ab_ticket_blockers')`
+    WHERE n.nspname = current_schema() AND k.contype IN ('p', 'u', 'f', 'c') AND c.relname IN ('ab_tickets', 'ab_ticket_comments', 'ab_ticket_blockers', 'ab_ticket_counters', 'ab_ticket_states')`
   const expectedConstraints: Record<string, string[]> = {
-    ab_tickets: ['PRIMARY KEY (repo, id)', 'UNIQUE (repo, creation_key)'],
+    ab_ticket_states: [
+      'PRIMARY KEY (repo, name)',
+      'CHECK ((length(btrim(name)) > 0))',
+      'CHECK (((about IS NULL) OR ((length(btrim(about)) > 0) AND (POSITION((chr(10)) IN (about)) = 0) AND (POSITION((chr(13)) IN (about)) = 0))))',
+    ],
+    ab_tickets: [
+      'PRIMARY KEY (repo, id)',
+      'UNIQUE (repo, creation_key)',
+      'UNIQUE (repo, ticket_number)',
+      'CHECK ((ticket_number > 0))',
+    ],
+    ab_ticket_counters: ['PRIMARY KEY (repo)', 'CHECK ((last_number >= 0))'],
     ab_ticket_comments: [
       'PRIMARY KEY (repo, ticket_id, seq)',
       'FOREIGN KEY (repo, ticket_id) REFERENCES ab_tickets(repo, id) ON DELETE CASCADE',
@@ -1381,7 +1481,8 @@ export async function migratePostgres(
     await sql.begin(async (tx) => {
       await tx`SELECT pg_advisory_xact_lock(470281941)`
       await tx.unsafe(SCHEMA_DDL)
-      await tx.unsafe(TICKET_SCHEMA_DDL)
+      await tx.unsafe(TICKET_SCHEMA_V2_DDL)
+      await tx.unsafe(TICKET_STATES_DDL)
       await tx.unsafe(SNAPSHOT_SCHEMA_DDL)
       await tx.unsafe(AUTH_SCHEMA_DDL)
       const rows: { version: number; checksum: string }[] =
@@ -1559,6 +1660,9 @@ export async function migratePostgres(
             SET version = ${SCHEMA_VERSION}, checksum = ${SCHEMA_CHECKSUM},
               applied_at = ${new Date().toISOString()}
             WHERE singleton = true`
+        } else if (version === 12 && marker.checksum === SCHEMA_V12_CHECKSUM) {
+          await tx`UPDATE ab_schema_migrations SET version = ${SCHEMA_VERSION}, checksum = ${SCHEMA_CHECKSUM},
+            applied_at = ${new Date().toISOString()} WHERE singleton = true`
         } else if (version === 11 && marker.checksum === SCHEMA_V11_CHECKSUM) {
           await tx`UPDATE ab_schema_migrations SET version = ${SCHEMA_VERSION}, checksum = ${SCHEMA_CHECKSUM},
             applied_at = ${new Date().toISOString()} WHERE singleton = true`
@@ -1600,8 +1704,32 @@ export async function migratePostgres(
         ticketMarker.checksum === TICKET_SCHEMA_V1_CHECKSUM
       ) {
         await migrateLegacyTickets(tx as SQL, options.openBlobs)
+        await tx`ALTER TABLE ab_tickets ADD COLUMN IF NOT EXISTS revision bigint NOT NULL DEFAULT 1`
+        await migrateReadableTickets(tx as SQL, options.openBlobs)
         await tx`UPDATE ab_ticket_schema_migrations SET version = ${TICKET_SCHEMA_VERSION},
           checksum = ${TICKET_SCHEMA_CHECKSUM}, applied_at = ${new Date().toISOString()} WHERE singleton = true`
+      } else if (
+        ticketMarker &&
+        Number(ticketMarker.version) === 2 &&
+        ticketMarker.checksum === TICKET_SCHEMA_V2_CHECKSUM
+      ) {
+        await tx`ALTER TABLE ab_tickets ADD COLUMN revision bigint NOT NULL DEFAULT 1`
+        await migrateReadableTickets(tx as SQL, options.openBlobs)
+        await tx`UPDATE ab_ticket_schema_migrations SET version = ${TICKET_SCHEMA_VERSION}, checksum = ${TICKET_SCHEMA_CHECKSUM}, applied_at = ${new Date().toISOString()} WHERE singleton = true`
+      } else if (
+        ticketMarker &&
+        Number(ticketMarker.version) === 3 &&
+        ticketMarker.checksum === TICKET_SCHEMA_V3_CHECKSUM
+      ) {
+        await migrateReadableTickets(tx as SQL, options.openBlobs)
+        await tx`UPDATE ab_ticket_schema_migrations SET version = ${TICKET_SCHEMA_VERSION}, checksum = ${TICKET_SCHEMA_CHECKSUM}, applied_at = ${new Date().toISOString()} WHERE singleton = true`
+      } else if (
+        ticketMarker &&
+        Number(ticketMarker.version) === 4 &&
+        ticketMarker.checksum === TICKET_SCHEMA_V4_CHECKSUM
+      ) {
+        await migrateReadableTickets(tx as SQL, options.openBlobs)
+        await tx`UPDATE ab_ticket_schema_migrations SET version = ${TICKET_SCHEMA_VERSION}, checksum = ${TICKET_SCHEMA_CHECKSUM}, applied_at = ${new Date().toISOString()} WHERE singleton = true`
       } else if (ticketMarker) {
         if (Number(ticketMarker.version) !== TICKET_SCHEMA_VERSION) {
           throw schemaError(
@@ -1615,10 +1743,19 @@ export async function migratePostgres(
           )
         }
       } else {
+        await tx`ALTER TABLE ab_tickets ADD COLUMN IF NOT EXISTS revision bigint NOT NULL DEFAULT 1`
+        await migrateReadableTickets(tx as SQL, options.openBlobs)
         await tx`INSERT INTO ab_ticket_schema_migrations
           (singleton, version, checksum, applied_at)
           VALUES (true, ${TICKET_SCHEMA_VERSION}, ${TICKET_SCHEMA_CHECKSUM}, ${new Date().toISOString()})`
       }
+      await tx`INSERT INTO ab_ticket_states (repo, name)
+        SELECT DISTINCT repo, state FROM ab_tickets ON CONFLICT DO NOTHING`
+      await tx`INSERT INTO ab_ticket_states (repo, name)
+        SELECT p.repo, value FROM project_ticket_policy p,
+          LATERAL jsonb_each_text(p.policy->'tickets') AS field(key, value)
+        WHERE key IN ('triageState', 'readyState', 'claimedState', 'doneState', 'createState', 'proposalState')
+        ON CONFLICT DO NOTHING`
       const authRows: { version: number; checksum: string }[] =
         await tx`SELECT version, checksum FROM ab_auth_schema_migrations WHERE singleton = true FOR UPDATE`
       const authMarker = authRows[0]

package/src/store.ts

@@ -248,23 +248,48 @@ export class PostgresBuildStore implements BuildStore {
         ON CONFLICT (slug) DO NOTHING RETURNING slug`
       const row = await this.lockBuild(q, input.slug)
       if (!inserted[0]) throw new Error(`build "${input.slug}" already exists`)
-      if (created === undefined) return this.record(row)
+      if (created === undefined) return this.currentRecord(q, row)
       await this.appendLocked(q, input.slug, created, true)
-      return this.record(await this.lockBuild(q, input.slug))
+      return this.currentRecord(q, await this.lockBuild(q, input.slug))
     })
   }
 
+  /** Current ticket identity is a read projection; event/artifact bytes remain historical. */
+  private async currentRecord(q: Exec, row: Row): Promise<BuildRecord> {
+    const record = this.record(row)
+    if (record.ticket?.source !== 'hosted') return record
+    const ticket = await this.hostedTicketRow(q, record.repo, record.ticket.id)
+    const id = ticket?.readable_id
+    return id ? { ...record, ticket: { ...record.ticket, id: String(id) } } : record
+  }
+
   async getBuild(slug: string): Promise<BuildRecord | null> {
     return this.run(async (q) => {
       const rows: Row[] = await q`SELECT * FROM builds WHERE slug = ${slug}`
-      return rows[0] ? this.record(rows[0]) : null
+      return rows[0] ? this.currentRecord(q, rows[0]) : null
     })
   }
 
   async listBuilds(): Promise<BuildRecord[]> {
     return this.run(async (q) => {
-      const rows: Row[] = await q`SELECT * FROM builds ORDER BY created_at, slug`
-      return rows.map((row) => this.record(row))
+      if (!(await this.hasReadableTicketSchema(q))) {
+        const rows: Row[] = await q`SELECT * FROM builds ORDER BY created_at, slug`
+        return rows.map((row) => this.record(row))
+      }
+      const rows: Row[] = await q`SELECT b.*, t.readable_id AS projected_ticket_id FROM builds b
+        LEFT JOIN LATERAL (
+          SELECT readable_id FROM ab_tickets
+          WHERE b.ticket->>'source' = 'hosted' AND repo = b.repo
+            AND (id = b.ticket->>'id' OR lower(readable_id) = lower(b.ticket->>'id'))
+          LIMIT 1
+        ) t ON true
+        ORDER BY b.created_at, b.slug`
+      return rows.map((row) => {
+        const record = this.record(row)
+        return record.ticket && row.projected_ticket_id
+          ? { ...record, ticket: { ...record.ticket, id: String(row.projected_ticket_id) } }
+          : record
+      })
     })
   }
 
@@ -1209,6 +1234,39 @@ export class PostgresBuildStore implements BuildStore {
     }
   }
 
+  private readableTicketSchema = false
+
+  /** Ticket tables are an independently migrated, optional store extension. */
+  private async hasReadableTicketSchema(q: Exec): Promise<boolean> {
+    if (!this.readableTicketSchema) {
+      const tables: Row[] = await q`SELECT to_regclass('ab_ticket_schema_migrations') AS tickets`
+      if (!tables[0]?.tickets) return false
+      const markers: Row[] =
+        await q`SELECT version FROM ab_ticket_schema_migrations WHERE singleton = true`
+      if (Number(markers[0]?.version ?? 0) < 3) return false
+      // Cache only presence: a store opened before migration must discover a later upgrade.
+      this.readableTicketSchema = true
+    }
+    return true
+  }
+
+  private async hostedTicketRow(q: Exec, repo: string, id: string): Promise<Row | undefined> {
+    if (!(await this.hasReadableTicketSchema(q))) return undefined
+    const rows: Row[] = await q`SELECT id, readable_id FROM ab_tickets
+      WHERE repo = ${repo} AND (id = ${id} OR lower(readable_id) = lower(${id}))`
+    return rows[0]
+  }
+
+  private async currentAssetMeta(q: Exec, row: Row): Promise<TicketAssetMeta> {
+    const meta = this.ticketAssetMeta(row)
+    const ticket = await this.hostedTicketRow(q, meta.repo, meta.ticketId)
+    return ticket?.readable_id ? { ...meta, ticketId: String(ticket.readable_id) } : meta
+  }
+
+  private async ticketStorageKey(q: Exec, repo: string, id: string): Promise<string> {
+    return String((await this.hostedTicketRow(q, repo, id))?.id ?? id)
+  }
+
   async putTicketAsset(
     repo: string,
     ticketId: string,
@@ -1218,16 +1276,28 @@ export class PostgresBuildStore implements BuildStore {
     const entries = await storeTicketAssetBlobs(this.blobs, asset.entries)
     const manifest = JSON.stringify(entries)
     return this.tx(async (q) => {
+      const key = await this.ticketStorageKey(q, repo, ticketId)
       // Serialize revision assignment per (repo, ticket, kind, name).
-      await q`SELECT pg_advisory_xact_lock(hashtextextended(${JSON.stringify([repo, ticketId, asset.kind, asset.name])}, 0))`
+      await q`SELECT pg_advisory_xact_lock(hashtextextended(${JSON.stringify([repo, key, asset.kind, asset.name])}, 0))`
       const tails: Row[] =
-        await q`SELECT COALESCE(MAX(revision), -1) AS revision FROM ticket_assets WHERE repo=${repo} AND ticket_id=${ticketId} AND kind=${asset.kind} AND name=${asset.name}`
+        await q`SELECT COALESCE(MAX(revision), -1) AS revision FROM ticket_assets WHERE repo=${repo} AND ticket_id=${key} AND kind=${asset.kind} AND name=${asset.name}`
       const revision = num(tails[0]?.revision) + 1
       const createdAt = this.now()
-      await q`INSERT INTO ticket_assets (repo,ticket_id,kind,name,revision,layout,manifest,size,removed,created_at) VALUES (${repo},${ticketId},${asset.kind},${asset.name},${revision},${asset.layout},${manifest}::jsonb,${size},false,${createdAt})`
+      await q`INSERT INTO ticket_assets (repo,ticket_id,kind,name,revision,layout,manifest,size,removed,created_at) VALUES (${repo},${key},${asset.kind},${asset.name},${revision},${asset.layout},${manifest}::jsonb,${size},false,${createdAt})`
+      const display = await this.currentAssetMeta(q, {
+        repo,
+        ticket_id: key,
+        kind: asset.kind,
+        name: asset.name,
+        revision,
+        layout: asset.layout,
+        size,
+        manifest: entries,
+        created_at: createdAt,
+      })
       return {
         repo,
-        ticketId,
+        ticketId: display.ticketId,
         kind: asset.kind,
         name: asset.name,
         revision,
@@ -1246,14 +1316,15 @@ export class PostgresBuildStore implements BuildStore {
     name: string,
     rev?: number,
   ): Promise<TicketAsset | null> {
-    const rows: Row[] = await this.run((q) =>
-      rev === undefined
-        ? q`SELECT * FROM ticket_assets WHERE repo=${repo} AND ticket_id=${ticketId} AND kind=${kind} AND name=${name} ORDER BY revision DESC LIMIT 1`
-        : q`SELECT * FROM ticket_assets WHERE repo=${repo} AND ticket_id=${ticketId} AND kind=${kind} AND name=${name} AND revision=${rev}`,
-    )
+    const rows: Row[] = await this.run(async (q) => {
+      const key = await this.ticketStorageKey(q, repo, ticketId)
+      return rev === undefined
+        ? q`SELECT * FROM ticket_assets WHERE repo=${repo} AND ticket_id=${key} AND kind=${kind} AND name=${name} ORDER BY revision DESC LIMIT 1`
+        : q`SELECT * FROM ticket_assets WHERE repo=${repo} AND ticket_id=${key} AND kind=${kind} AND name=${name} AND revision=${rev}`
+    })
     const row = rows[0]
     if (!row || row.removed === true) return null
-    return loadTicketAsset(this.blobs, this.ticketAssetMeta(row))
+    return loadTicketAsset(this.blobs, await this.run((q) => this.currentAssetMeta(q, row)))
   }
 
   async getPinnedTicketAsset(
@@ -1270,10 +1341,15 @@ export class PostgresBuildStore implements BuildStore {
     ticketId: string,
     opts?: { revisions?: boolean },
   ): Promise<TicketAssetSummary[]> {
-    const rows: Row[] = await this.run(
-      (q) =>
-        q`SELECT * FROM ticket_assets WHERE repo=${repo} AND ticket_id=${ticketId} ORDER BY kind, name, revision`,
-    )
+    const rows: Row[] = await this.run(async (q) => {
+      const key = await this.ticketStorageKey(q, repo, ticketId)
+      const rows: Row[] =
+        await q`SELECT * FROM ticket_assets WHERE repo=${repo} AND ticket_id=${key} ORDER BY kind, name, revision`
+      const projected: Row[] = []
+      for (const row of rows)
+        projected.push({ ...row, ticket_id: (await this.currentAssetMeta(q, row)).ticketId })
+      return projected
+    })
     if (opts?.revisions) {
       return rows
         .filter((row) => row.removed !== true)
@@ -1293,13 +1369,14 @@ export class PostgresBuildStore implements BuildStore {
     name: string,
   ): Promise<TicketAssetMeta | null> {
     return this.tx(async (q) => {
-      await q`SELECT pg_advisory_xact_lock(hashtextextended(${JSON.stringify([repo, ticketId, kind, name])}, 0))`
+      const key = await this.ticketStorageKey(q, repo, ticketId)
+      await q`SELECT pg_advisory_xact_lock(hashtextextended(${JSON.stringify([repo, key, kind, name])}, 0))`
       const rows: Row[] =
-        await q`SELECT * FROM ticket_assets WHERE repo=${repo} AND ticket_id=${ticketId} AND kind=${kind} AND name=${name} ORDER BY revision DESC LIMIT 1`
+        await q`SELECT * FROM ticket_assets WHERE repo=${repo} AND ticket_id=${key} AND kind=${kind} AND name=${name} ORDER BY revision DESC LIMIT 1`
       const latest = rows[0]
       if (!latest || latest.removed === true) return null
-      await q`INSERT INTO ticket_assets (repo,ticket_id,kind,name,revision,layout,manifest,size,removed,created_at) VALUES (${repo},${ticketId},${kind},${name},${num(latest.revision) + 1},${String(latest.layout)},${'[]'}::jsonb,0,true,${this.now()})`
-      return this.ticketAssetMeta(latest)
+      await q`INSERT INTO ticket_assets (repo,ticket_id,kind,name,revision,layout,manifest,size,removed,created_at) VALUES (${repo},${key},${kind},${name},${num(latest.revision) + 1},${String(latest.layout)},${'[]'}::jsonb,0,true,${this.now()})`
+      return this.currentAssetMeta(q, latest)
     })
   }
 

package/src/ticket-grants.ts

@@ -0,0 +1,86 @@
+import { createHash, randomBytes } from 'node:crypto'
+import type { SQL } from 'bun'
+
+export interface TicketGrant {
+  id: string
+  repo: string
+  execution: string
+  kind: 'runner' | 'phase'
+  parent: string | null
+  expiresAt: string
+}
+export interface TicketGrantStore {
+  authenticate(token: string, now: Date): Promise<TicketGrant | null>
+  issue(
+    repo: string,
+    execution: string,
+    kind: 'runner' | 'phase',
+    parent: TicketGrant | null,
+    now: Date,
+  ): Promise<{ token: string; grant: TicketGrant }>
+  revoke(id: string, repo: string): Promise<void>
+  renew(id: string, repo: string, now: Date): Promise<void>
+}
+const digest = (token: string) => createHash('sha256').update(token).digest('hex')
+const ttl = 5 * 60_000
+export class PostgresTicketGrantStore implements TicketGrantStore {
+  constructor(private readonly sql: SQL) {}
+  async authenticate(token: string, now: Date): Promise<TicketGrant | null> {
+    const [row] = await this.sql`SELECT g.* FROM ticket_grants g JOIN LATERAL
+      (SELECT seq, action FROM project_journal WHERE repo = g.repo ORDER BY seq DESC LIMIT 1) r
+      ON r.seq = g.registration AND r.action = 'added'
+      WHERE g.digest = ${digest(token)} AND g.revoked_at IS NULL AND g.expires_at > ${now.toISOString()}
+      AND (g.parent IS NULL OR EXISTS (SELECT 1 FROM ticket_grants p WHERE p.id = g.parent
+        AND p.revoked_at IS NULL AND p.expires_at > ${now.toISOString()} AND p.registration = g.registration))`
+    return row
+      ? {
+          id: row.id,
+          repo: row.repo,
+          execution: row.execution,
+          kind: row.kind,
+          parent: row.parent,
+          expiresAt: new Date(row.expires_at).toISOString(),
+        }
+      : null
+  }
+  async issue(
+    repo: string,
+    execution: string,
+    kind: 'runner' | 'phase',
+    parent: TicketGrant | null,
+    now: Date,
+  ) {
+    if (
+      (kind === 'phase' &&
+        (parent?.kind !== 'runner' || parent.repo !== repo || parent.execution !== execution)) ||
+      (kind === 'runner' && parent)
+    )
+      throw new Error('invalid ticket grant parent')
+    const id = randomBytes(16).toString('hex')
+    const token = `abt_${randomBytes(32).toString('hex')}`
+    const expiresAt = new Date(
+      Math.min(now.getTime() + ttl, parent ? Date.parse(parent.expiresAt) : Infinity),
+    ).toISOString()
+    const rows = await this
+      .sql`INSERT INTO ticket_grants (id, digest, repo, registration, execution, kind, parent, expires_at)
+      SELECT ${id}, ${digest(token)}, ${repo}, r.seq, ${execution}, ${kind}, ${parent?.id ?? null}, ${expiresAt}
+      FROM (SELECT seq, action FROM project_journal WHERE repo = ${repo} ORDER BY seq DESC LIMIT 1) r
+      WHERE r.action = 'added' AND (${parent?.id ?? null}::text IS NULL OR EXISTS
+        (SELECT 1 FROM ticket_grants p WHERE p.id = ${parent?.id ?? null} AND p.registration = r.seq
+          AND p.revoked_at IS NULL AND p.expires_at > ${now.toISOString()})) RETURNING id`
+    if (!rows.length) throw new Error('project or parent grant is no longer active')
+    return { token, grant: { id, repo, execution, kind, parent: parent?.id ?? null, expiresAt } }
+  }
+  async revoke(id: string, repo: string) {
+    await this
+      .sql`UPDATE ticket_grants SET revoked_at = COALESCE(revoked_at, ${new Date().toISOString()}) WHERE id = ${id} AND repo = ${repo}`
+  }
+  async renew(id: string, repo: string, now: Date) {
+    await this.sql`WITH renewed AS (
+      UPDATE ticket_grants SET expires_at = ${new Date(now.getTime() + ttl).toISOString()}
+      WHERE id = ${id} AND repo = ${repo} AND kind = 'runner' AND revoked_at IS NULL AND expires_at > ${now.toISOString()}
+      RETURNING id, expires_at)
+      UPDATE ticket_grants SET expires_at = renewed.expires_at FROM renewed
+      WHERE ticket_grants.parent = renewed.id AND ticket_grants.revoked_at IS NULL`
+  }
+}

package/src/ticket-migration.ts

@@ -2,6 +2,7 @@ import type { SQL } from 'bun'
 import type { BlobStore, RepositoryEvent } from '@defrex/autobuild/plugin-sdk'
 import { findEffectiveConfigRef, decodeEffectiveConfig } from '@defrex/autobuild/operator'
 import { TICKET_ASSIGNMENTS_DDL } from './ticket-assignments'
+import { PostgresTicketPolicyStore } from './ticket-policy'
 
 /** Called only inside the schema migration transaction. Locks preserve the
  * registry/config/ownership snapshot across immutable blob reads and rekeying. */
@@ -41,41 +42,8 @@ export async function migrateLegacyTickets(
       )
     const claimants = new Map<string, string[]>()
     for (const { repo } of remaining.length > 0 ? projects : []) {
-      const rows: { seq: number; ts: string; actor: unknown; type: string; payload: unknown }[] =
-        await sql`SELECT seq, ts, actor, type, payload FROM repo_events WHERE repo = ${repo} ORDER BY seq`
-      const events = rows.map((row) => ({
-        ...row,
-        repo,
-        seq: Number(row.seq),
-        ts: new Date(row.ts).toISOString(),
-      })) as RepositoryEvent[]
-      const ref = findEffectiveConfigRef(events)
-      // Registration/onboarding alone makes no team claim.
-      if (ref === undefined) continue
-      const [artifact] =
-        await sql`SELECT blob_ref FROM repo_artifacts WHERE repo = ${repo} AND kind = ${ref.kind} AND revision = ${ref.rev}`
-      if (!artifact)
-        throw configFailure(`effective config ${ref.kind}@${ref.rev} unavailable for ${repo}`)
-      let bytes: Uint8Array | null
-      try {
-        bytes = await blobs.get(artifact.blob_ref)
-      } catch {
-        throw configFailure(
-          `cannot read effective configuration blob for ${repo}; check blob access and prefix`,
-        )
-      }
-      if (bytes === null)
-        throw configFailure(
-          `missing effective configuration blob for ${repo}; check blob backend and prefix`,
-        )
-      let config: ReturnType<typeof decodeEffectiveConfig>
-      try {
-        config = decodeEffectiveConfig(bytes, `${repo} ${ref.kind}@${ref.rev}`)
-      } catch {
-        throw configFailure(
-          `selected effective config ${ref.kind}@${ref.rev} for ${repo} is invalid`,
-        )
-      }
+      const config = await loadTicketConfig(sql, blobs, repo, configFailure)
+      if (!config) continue
       const team = config.tickets.teamKey
       if (team !== undefined) claimants.set(team, [...(claimants.get(team) ?? []), repo])
     }
@@ -145,3 +113,96 @@ export async function migrateLegacyTickets(
     ALTER TABLE ab_ticket_blockers ADD FOREIGN KEY (repo,ticket_id) REFERENCES ab_tickets(repo,id) ON DELETE CASCADE;
     ALTER TABLE ab_ticket_blockers ADD FOREIGN KEY (repo,blocker_id) REFERENCES ab_tickets(repo,id) ON DELETE CASCADE;`)
 }
+
+/** Load exactly the durable effective config selected by the repository log. */
+async function loadTicketConfig(
+  sql: SQL,
+  blobs: BlobStore,
+  repo: string,
+  configFailure: (detail: string) => Error,
+) {
+  const rows: { seq: number; ts: string; actor: unknown; type: string; payload: unknown }[] =
+    await sql`SELECT seq, ts, actor, type, payload FROM repo_events WHERE repo = ${repo} ORDER BY seq`
+  const events = rows.map((row) => ({
+    ...row,
+    repo,
+    seq: Number(row.seq),
+    ts: new Date(row.ts).toISOString(),
+  })) as RepositoryEvent[]
+  const ref = findEffectiveConfigRef(events)
+  // Registration/onboarding alone makes no team claim.
+  if (ref === undefined) return undefined
+  const [artifact] =
+    await sql`SELECT blob_ref FROM repo_artifacts WHERE repo = ${repo} AND kind = ${ref.kind} AND revision = ${ref.rev}`
+  if (!artifact)
+    throw configFailure(`effective config ${ref.kind}@${ref.rev} unavailable for ${repo}`)
+  let bytes: Uint8Array | null
+  try {
+    bytes = await blobs.get(artifact.blob_ref)
+  } catch {
+    throw configFailure(
+      `cannot read effective configuration blob for ${repo}; check blob access and prefix`,
+    )
+  }
+  if (bytes === null)
+    throw configFailure(
+      `missing effective configuration blob for ${repo}; check blob backend and prefix`,
+    )
+  let config: ReturnType<typeof decodeEffectiveConfig>
+  try {
+    config = decodeEffectiveConfig(bytes, `${repo} ${ref.kind}@${ref.rev}`)
+  } catch {
+    throw configFailure(`selected effective config ${ref.kind}@${ref.rev} for ${repo} is invalid`)
+  }
+  return config
+}
+
+export const READABLE_TICKET_CONSTRAINTS = `
+ALTER TABLE ab_tickets ALTER COLUMN readable_id SET NOT NULL;
+ALTER TABLE ab_tickets ALTER COLUMN ticket_number SET NOT NULL;
+ALTER TABLE ab_tickets ADD CONSTRAINT ab_tickets_ticket_number_check CHECK (ticket_number > 0);
+ALTER TABLE ab_tickets ADD CONSTRAINT ab_tickets_repo_ticket_number_key UNIQUE (repo, ticket_number);
+CREATE UNIQUE INDEX ab_tickets_readable_id_key ON ab_tickets (repo, lower(readable_id));
+`
+
+/** Runs once, under the schema marker transaction; no historical foreign keys move. */
+export async function migrateReadableTickets(
+  sql: SQL,
+  openBlobs?: () => BlobStore | Promise<BlobStore>,
+): Promise<void> {
+  await sql`LOCK TABLE ab_tickets, ab_ticket_comments, ab_ticket_blockers, ticket_assets,
+    repo_events, repo_artifacts, project_ticket_policy, project_journal IN SHARE ROW EXCLUSIVE MODE`
+  await sql.unsafe(`ALTER TABLE ab_tickets ADD COLUMN readable_id text;
+    ALTER TABLE ab_tickets ADD COLUMN ticket_number bigint;
+    CREATE TABLE ab_ticket_counters (repo text PRIMARY KEY, last_number bigint NOT NULL CHECK (last_number >= 0));`)
+  const projects: { repo: string }[] = await sql`SELECT DISTINCT repo FROM ab_tickets ORDER BY repo`
+  const fail = (detail: string) =>
+    new Error(
+      `Readable ticket migration stopped unchanged: ${detail}. Restore the project's effective configuration and blob access, then rerun migration.`,
+    )
+  let blobs: BlobStore | undefined
+  for (const { repo } of projects) {
+    // Independent hosted policy is authoritative; projects using local build
+    // storage need not have an uploaded config or any configuration blobs.
+    const policy = await new PostgresTicketPolicyStore(sql).get(repo)
+    let prefix = policy?.tickets.teamKey
+    if (!policy) {
+      if (!blobs) {
+        if (!openBlobs) throw fail(`project ${repo}: populated projects require blob access`)
+        try {
+          blobs = await openBlobs()
+        } catch {
+          throw fail(`project ${repo}: cannot open blob storage`)
+        }
+      }
+      const config = await loadTicketConfig(sql, blobs, repo, fail)
+      prefix = config?.tickets.teamKey
+    }
+    if (!prefix?.trim()) throw fail(`project ${repo} has no nonblank effective tickets.teamKey`)
+    await sql`WITH numbered AS (SELECT id, row_number() OVER (ORDER BY created_at, id) AS n FROM ab_tickets WHERE repo = ${repo})
+      UPDATE ab_tickets t SET ticket_number = numbered.n, readable_id = ${prefix} || '-' || numbered.n::text
+      FROM numbered WHERE t.repo = ${repo} AND t.id = numbered.id`
+    await sql`INSERT INTO ab_ticket_counters (repo, last_number) SELECT ${repo}, max(ticket_number) FROM ab_tickets WHERE repo = ${repo}`
+  }
+  await sql.unsafe(READABLE_TICKET_CONSTRAINTS)
+}

package/src/ticket-policy.ts

@@ -0,0 +1,60 @@
+import { seedTicketStates, policyStateNames } from './ticket-states'
+import type { Exec } from './retry'
+import type { SQL } from 'bun'
+import { hostedTicketPolicySchema, type HostedTicketPolicy } from '@defrex/autobuild/hosted-tickets'
+
+export interface TicketPolicyStore {
+  get(repo: string): Promise<HostedTicketPolicy | null>
+  put(repo: string, policy: HostedTicketPolicy, writer: string): Promise<void>
+}
+
+/** Registration sequence scopes policy to the current project incarnation. */
+export class PostgresTicketPolicyStore implements TicketPolicyStore {
+  constructor(private readonly sql: SQL) {}
+  async get(repo: string): Promise<HostedTicketPolicy | null> {
+    const [row] = await this.sql`SELECT p.policy FROM project_ticket_policy p JOIN LATERAL
+      (SELECT seq, action FROM project_journal WHERE repo = ${repo} ORDER BY seq DESC LIMIT 1) r
+      ON r.seq = p.registration AND r.action = 'added' WHERE p.repo = ${repo}`
+    return row
+      ? hostedTicketPolicySchema.parse(
+          typeof row.policy === 'string' ? JSON.parse(row.policy) : row.policy,
+        )
+      : null
+  }
+  async put(repo: string, policy: HostedTicketPolicy, writer: string): Promise<void> {
+    const parsed = hostedTicketPolicySchema.parse(policy)
+    await this.sql.begin(async (tx) => {
+      await tx`SELECT singleton FROM project_registry_state WHERE singleton = true FOR UPDATE`
+      const [registration] =
+        await tx`SELECT seq, action FROM project_journal WHERE repo = ${repo} ORDER BY seq DESC LIMIT 1`
+      if (registration?.action !== 'added') throw new Error('project not registered')
+      const [previous] =
+        await tx`SELECT policy FROM project_ticket_policy WHERE repo = ${repo} AND registration = ${registration.seq}`
+      const old = previous
+        ? hostedTicketPolicySchema.parse(
+            typeof previous.policy === 'string' ? JSON.parse(previous.policy) : previous.policy,
+          )
+        : undefined
+      await seedTicketStates(tx as unknown as Exec, repo, [
+        ...(old ? policyStateNames(old) : []),
+        ...policyStateNames(parsed),
+      ])
+      await tx`INSERT INTO project_ticket_policy (repo, registration, policy, writer, updated_at)
+        VALUES (${repo}, ${registration.seq}, ${parsed}, ${writer}, ${new Date().toISOString()})
+        ON CONFLICT (repo) DO UPDATE SET registration = EXCLUDED.registration, policy = EXCLUDED.policy,
+          writer = EXCLUDED.writer, updated_at = EXCLUDED.updated_at
+        WHERE project_ticket_policy.registration <> EXCLUDED.registration OR project_ticket_policy.policy <> EXCLUDED.policy`
+    })
+  }
+}
+
+/** Explicit test seam; production always composes the PostgreSQL adapter. */
+export class MemoryTicketPolicyStore implements TicketPolicyStore {
+  private readonly policies = new Map<string, HostedTicketPolicy>()
+  async get(repo: string) {
+    return structuredClone(this.policies.get(repo) ?? null)
+  }
+  async put(repo: string, policy: HostedTicketPolicy, _writer: string) {
+    this.policies.set(repo, hostedTicketPolicySchema.parse(policy))
+  }
+}

package/src/ticket-states.ts

@@ -0,0 +1,15 @@
+import type { Exec } from './retry'
+import type { HostedTicketPolicy } from '@defrex/autobuild/hosted-tickets'
+
+export function policyStateNames(policy: HostedTicketPolicy): string[] {
+  const t = policy.tickets
+  return [t.triageState, t.readyState, t.claimedState, t.doneState, t.createState, t.proposalState]
+}
+
+/** All writers share this project lock, including policy publication. */
+export async function seedTicketStates(q: Exec, repo: string, names: string[]): Promise<void> {
+  await q`SELECT pg_advisory_xact_lock(hashtextextended(${repo}, 731926))`
+  for (const name of new Set(names)) {
+    await q`INSERT INTO ab_ticket_states (repo, name) VALUES (${repo}, ${name}) ON CONFLICT DO NOTHING`
+  }
+}

package/src/tickets.ts

@@ -1,3 +1,12 @@
+import { hostedRequestedIds, MAX_TICKET_NUMBER } from '@defrex/autobuild/hosted-tickets'
+import {
+  orderStates,
+  resolveState,
+  validateStateName,
+  validateStatePurpose,
+} from '@defrex/autobuild/hosted-tickets'
+import { seedTicketStates } from './ticket-states'
+import { TicketRevisionConflict } from '@defrex/autobuild/hosted-tickets'
 import { SQL } from 'bun'
 import type {
   DependencyState,
@@ -7,6 +16,8 @@ import type {
   TicketListing,
   TicketSource,
   TicketUpdate,
+  TicketStateInfo,
+  TicketMutation,
 } from '@defrex/autobuild/plugin-sdk'
 import { validateTicketUpdate } from '@defrex/autobuild/ticket-update'
 import { assertTicketSchema } from './schema'
@@ -23,6 +34,7 @@ export interface PostgresTicketLifecycle {
 
 export interface PostgresTicketContext {
   repo: string
+  teamKey: string
   lifecycle: PostgresTicketLifecycle
   proposalState?: string
   claimedState?: string
@@ -67,10 +79,11 @@ export async function openPostgresTicketDatabase(url: string): Promise<PostgresT
 
 export class PostgresTicketSource implements TicketSource {
   readonly name = 'database'
+  private readonly teamKey: string
   private readonly repo: string
   private readonly claimedState: string
   private readonly createState: string
-  private readonly allowed: Set<string>
+  private readonly configured: string[]
 
   constructor(
     private readonly sql: SQL,
@@ -82,41 +95,86 @@ export class PostgresTicketSource implements TicketSource {
     private readonly retry: PlanRetryRunner = new PlanRetryRunner(),
   ) {
     if (!context.repo.trim()) throw new Error('ticket repo must be nonblank')
+    this.teamKey = context.teamKey
     this.repo = context.repo
-    this.allowed = new Set(
-      [
-        ...Object.values(lifecycle),
-        context.claimedState ?? lifecycle.doing,
-        context.createState ?? lifecycle.triage,
-        context.proposalState ?? lifecycle.triage,
-      ].map((value) => requiredState(value, 'ticket state')),
+    this.configured = Array.from(
+      new Set(
+        [
+          ...Object.values(lifecycle),
+          context.claimedState ?? lifecycle.doing,
+          context.createState ?? lifecycle.triage,
+          context.proposalState ?? lifecycle.triage,
+        ].map((value) => requiredState(value, 'ticket state')),
+      ),
     )
     this.claimedState = context.claimedState ?? lifecycle.doing
     this.createState = context.createState ?? lifecycle.triage
-    this.assertState(this.claimedState)
-    this.assertState(this.createState)
   }
 
-  private assertState(state: string): void {
-    if (!this.allowed.has(state)) {
-      throw new Error(
-        `database ticket state "${state}" is not configured; allowed states: ${[...this.allowed].join(', ')}`,
-      )
-    }
+  private async states(q: Exec): Promise<TicketStateInfo[]> {
+    await seedTicketStates(q, this.repo, this.configured)
+    const rows: Row[] = await q`SELECT s.name, s.about, count(t.id)::integer AS tickets
+      FROM ab_ticket_states s LEFT JOIN ab_tickets t ON t.repo = s.repo AND t.state = s.name
+      WHERE s.repo = ${this.repo} GROUP BY s.name, s.about`
+    const infos = rows.map((row) => ({
+      name: String(row.name),
+      tickets: Number(row.tickets),
+      ...(row.about === null ? {} : { about: String(row.about) }),
+    }))
+    return orderStates(
+      infos.map((s) => s.name),
+      [this.lifecycle.triage, this.lifecycle.ready, this.lifecycle.doing, this.lifecycle.done],
+    ).map((name) => infos.find((s) => s.name === name)!)
+  }
+
+  async listStates(): Promise<TicketStateInfo[]> {
+    return this.retry.tx(this.sql, (q) => this.states(q))
+  }
+
+  async addState(
+    name: string,
+    opts: { about?: string } = {},
+  ): Promise<{ state: TicketStateInfo; created: boolean }> {
+    validateStateName(name, 'database ticket source')
+    const about = validateStatePurpose(opts.about, 'database ticket source')
+    return this.retry.tx(this.sql, async (q) => {
+      const states = await this.states(q)
+      const clash = states.find((s) => s.name.toLowerCase() === name.toLowerCase())
+      if (clash)
+        throw new Error(
+          `database ticket source: state "${name}" already exists as "${clash.name}"; state names are compared case-insensitively`,
+        )
+      await q`INSERT INTO ab_ticket_states (repo, name, about) VALUES (${this.repo}, ${name}, ${about ?? null})`
+      return {
+        state: { name, tickets: 0, ...(about === undefined ? {} : { about }) },
+        created: true,
+      }
+    })
+  }
+
+  private async state(q: Exec, name: string): Promise<string> {
+    return resolveState(
+      name,
+      (await this.states(q)).map((s) => s.name),
+      'database ticket source',
+    )
   }
 
   private async blockers(executor: Exec, id: string): Promise<string[]> {
-    const rows: Row[] = await executor`SELECT blocker_id FROM ab_ticket_blockers
-      WHERE repo = ${this.repo} AND ticket_id = ${id} ORDER BY blocker_id`
+    const rows: Row[] = await executor`SELECT t.readable_id AS blocker_id FROM ab_ticket_blockers b
+      JOIN ab_tickets t ON t.repo = b.repo AND t.id = b.blocker_id
+      WHERE b.repo = ${this.repo} AND b.ticket_id = ${id} ORDER BY t.readable_id`
     return rows.map((row) => String(row.blocker_id))
   }
 
   private async record(executor: Exec, row: Row): Promise<Ticket> {
     const id = String(row.id)
     const title = String(row.title)
-    const blockedBy = await this.blockers(executor, id)
+    const blockedBy =
+      row.blockers === undefined ? await this.blockers(executor, id) : strings(row.blockers)
     return {
-      ref: { source: this.name, id, title },
+      ref: { source: this.name, id: String(row.readable_id), title },
+      revision: String(row.revision),
       ...(row.creation_key !== null && row.creation_key !== undefined
         ? { creationKey: String(row.creation_key) }
         : {}),
@@ -129,21 +187,28 @@ export class PostgresTicketSource implements TicketSource {
     }
   }
 
-  private async require(executor: Exec, id: string, operation: string, lock = false): Promise<Row> {
+  private async lookup(executor: Exec, id: string, lock = false): Promise<Row | undefined> {
     const rows: Row[] = lock
-      ? await executor`SELECT * FROM ab_tickets WHERE repo = ${this.repo} AND id = ${id} FOR UPDATE`
-      : await executor`SELECT * FROM ab_tickets WHERE repo = ${this.repo} AND id = ${id}`
-    const row = rows[0]
+      ? await executor`SELECT *, revision::text AS revision FROM ab_tickets WHERE repo = ${this.repo} AND (id = ${id} OR lower(readable_id) = lower(${id})) FOR UPDATE`
+      : await executor`SELECT *, revision::text AS revision FROM ab_tickets WHERE repo = ${this.repo} AND (id = ${id} OR lower(readable_id) = lower(${id}))`
+    return rows[0]
+  }
+
+  private async require(executor: Exec, id: string, operation: string, lock = false): Promise<Row> {
+    const row = await this.lookup(executor, id, lock)
     if (!row) throw new Error(`database ticket source: ${operation} on unknown ticket "${id}"`)
     return row
   }
 
   async listReady(criteria: { labels?: string[]; state?: string }): Promise<TicketListing> {
     const labels = criteria.labels ?? []
-    return this.retry.run(this.sql, async (q) => {
-      const rows: Row[] = await q`SELECT * FROM ab_tickets
+    return this.retry.tx(this.sql, async (q) => {
+      await seedTicketStates(q, this.repo, this.configured)
+      const state = criteria.state === undefined ? null : await this.state(q, criteria.state)
+      const rows: Row[] =
+        await q`SELECT *, revision::text AS revision, ARRAY(SELECT t.readable_id FROM ab_ticket_blockers b JOIN ab_tickets t ON t.repo = b.repo AND t.id = b.blocker_id WHERE b.repo = ab_tickets.repo AND b.ticket_id = ab_tickets.id ORDER BY t.readable_id) AS blockers FROM ab_tickets
         WHERE repo = ${this.repo}
-          AND (${criteria.state ?? null}::text IS NULL OR state = ${criteria.state ?? null})
+          AND (${state}::text IS NULL OR state = ${state})
           AND labels @> ${q.array(labels, 'text')}
         ORDER BY created_at, id`
       // Sequential, not `Promise.all`: every statement of a body runs on one
@@ -156,17 +221,36 @@ export class PostgresTicketSource implements TicketSource {
   }
 
   async get(id: string): Promise<Ticket | null> {
-    return this.retry.run(this.sql, async (q) => {
-      const rows: Row[] = await q`SELECT * FROM ab_tickets WHERE repo = ${this.repo} AND id = ${id}`
-      return rows[0] ? this.record(q, rows[0]) : null
+    return this.retry.tx(this.sql, async (q) => {
+      await seedTicketStates(q, this.repo, this.configured)
+      const rows: Row[] =
+        await q`SELECT *, revision::text AS revision, ARRAY(SELECT t.readable_id FROM ab_ticket_blockers b JOIN ab_tickets t ON t.repo = b.repo AND t.id = b.blocker_id WHERE b.repo = ab_tickets.repo AND b.ticket_id = ab_tickets.id ORDER BY t.readable_id) AS blockers FROM ab_tickets WHERE repo = ${this.repo} AND (id = ${id} OR lower(readable_id) = lower(${id}))`
+      if (!rows[0]) return null
+      const ticket = await this.record(q, rows[0])
+      const storageId = String(rows[0].id)
+      const comments: Row[] = await q`SELECT body, created_at FROM ab_ticket_comments
+        WHERE repo = ${this.repo} AND ticket_id = ${storageId}
+        ORDER BY created_at ASC, seq ASC`
+      return {
+        ...ticket,
+        comments: comments.map((row) => ({
+          body: String(row.body),
+          createdAt: new Date(row.created_at as string | Date).toISOString(),
+        })),
+      }
     })
   }
 
   async claim(id: string): Promise<boolean> {
-    return this.retry.run(this.sql, async (q) => {
-      const rows: Row[] = await q`UPDATE ab_tickets SET state = ${this.claimedState},
+    return this.retry.tx(this.sql, async (q) => {
+      await seedTicketStates(q, this.repo, this.configured)
+      const row = await this.lookup(q, id)
+      if (!row) return false
+      const storageId = String(row.id)
+      const rows: Row[] =
+        await q`UPDATE ab_tickets SET state = ${this.claimedState}, revision = revision + 1,
         updated_at = ${new Date().toISOString()}
-        WHERE repo = ${this.repo} AND id = ${id}
+        WHERE repo = ${this.repo} AND id = ${storageId}
           AND state <> ${this.claimedState} AND state <> ${this.lifecycle.done} RETURNING id`
       return rows.length === 1
     })
@@ -174,53 +258,71 @@ export class PostgresTicketSource implements TicketSource {
 
   async comment(id: string, body: string): Promise<void> {
     await this.retry.tx(this.sql, async (q) => {
-      await this.require(q, id, 'comment', true)
+      const storageId = String((await this.require(q, id, 'comment', true)).id)
       const tails: Row[] = await q`SELECT COALESCE(MAX(seq), 0) AS seq FROM ab_ticket_comments
-        WHERE repo = ${this.repo} AND ticket_id = ${id}`
+        WHERE repo = ${this.repo} AND ticket_id = ${storageId}`
       await q`INSERT INTO ab_ticket_comments (repo, ticket_id, seq, body, created_at)
-        VALUES (${this.repo}, ${id}, ${Number(tails[0]?.seq ?? 0) + 1}, ${body}, ${new Date().toISOString()})`
+        VALUES (${this.repo}, ${storageId}, ${Number(tails[0]?.seq ?? 0) + 1}, ${body}, ${new Date().toISOString()})`
     })
   }
 
   async transition(id: string, state: string): Promise<void> {
-    this.assertState(state)
-    await this.retry.run(this.sql, async (q) => {
-      const rows: Row[] = await q`UPDATE ab_tickets SET state = ${state},
-        updated_at = ${new Date().toISOString()} WHERE repo = ${this.repo} AND id = ${id} RETURNING id`
-      if (!rows[0]) throw new Error(`database ticket source: transition on unknown ticket "${id}"`)
-    })
+    await this.mutate(id, { kind: 'transition', state })
+  }
+
+  get requestedIds() {
+    return hostedRequestedIds(this.teamKey)
   }
 
   async create(draft: TicketDraft, options: TicketCreateOptions = {}): Promise<Ticket> {
     if (!draft.title.trim()) throw new Error('database ticket create: title must be nonblank')
-    if (!draft.body.trim()) throw new Error('database ticket create: body must be nonblank')
-    const state = options.state ?? this.createState
-    this.assertState(state)
+    if (!draft.body.trim() && options.requestedId === undefined)
+      throw new Error('database ticket create: body must be nonblank')
+    requiredState(this.teamKey, 'ticket teamKey')
     return this.retry.tx(this.sql, async (q) => {
+      await q`INSERT INTO ab_ticket_counters (repo, last_number) VALUES (${this.repo}, 0) ON CONFLICT DO NOTHING`
+      await q`SELECT last_number FROM ab_ticket_counters WHERE repo = ${this.repo} FOR UPDATE`
       if (options.idempotencyKey !== undefined) {
-        const adopted: Row[] = await q`SELECT * FROM ab_tickets
+        const adopted: Row[] = await q`SELECT *, revision::text AS revision FROM ab_tickets
           WHERE repo = ${this.repo} AND creation_key = ${options.idempotencyKey} FOR UPDATE`
         if (adopted[0]) return this.record(q, adopted[0])
       }
+      const state = await this.state(q, options.state ?? this.createState)
+      const blockers: string[] = []
       for (const blocker of draft.blockedBy ?? []) {
-        await this.require(q, blocker, 'create blocker')
+        blockers.push(String((await this.require(q, blocker, 'create blocker')).id))
       }
+      const policy = hostedRequestedIds(this.teamKey)
+      const kept =
+        options.requestedId === undefined ? undefined : policy.preserve(options.requestedId)
+      const rows: Row[] = await q`SELECT GREATEST(
+        (SELECT last_number FROM ab_ticket_counters WHERE repo = ${this.repo}),
+        COALESCE(MAX(ticket_number), 0))::text AS high FROM ab_tickets WHERE repo = ${this.repo}`
+      const high = BigInt(String(rows[0]!.high))
+      const chosen = kept === undefined ? high + 1n : BigInt(kept.slice(this.teamKey.length + 1))
+      if (chosen > MAX_TICKET_NUMBER) throw new Error('ticket numbers exhausted')
+      const clashes: Row[] =
+        await q`SELECT id FROM ab_tickets WHERE repo = ${this.repo} AND ticket_number = ${String(chosen)}::bigint`
+      if (clashes.length) throw new Error(`requested ticket id already occupied: ${kept}`)
+      const number = String(chosen)
+      await q`UPDATE ab_ticket_counters SET last_number = ${String(chosen > high ? chosen : high)}::bigint WHERE repo = ${this.repo}`
+      const readable = `${this.teamKey}-${number}`
       const id = `ticket-${crypto.randomUUID()}`
       const now = new Date().toISOString()
       const inserted: Row[] = await q`INSERT INTO ab_tickets
-        (repo, id, creation_key, title, body, state, labels, created_at, updated_at)
-        VALUES (${this.repo}, ${id}, ${options.idempotencyKey ?? null}, ${draft.title}, ${draft.body},
+        (repo, id, readable_id, ticket_number, creation_key, title, body, state, labels, created_at, updated_at)
+        VALUES (${this.repo}, ${id}, ${readable}, ${number}::bigint, ${options.idempotencyKey ?? null}, ${draft.title}, ${draft.body},
           ${state}, ${q.array(draft.labels ?? [], 'text')}, ${now}, ${now})
-        ON CONFLICT (repo, creation_key) DO NOTHING RETURNING *`
+        ON CONFLICT (repo, creation_key) DO NOTHING RETURNING *, revision::text AS revision`
       let row = inserted[0]
       if (!row && options.idempotencyKey !== undefined) {
-        const adopted: Row[] = await q`SELECT * FROM ab_tickets
+        const adopted: Row[] = await q`SELECT *, revision::text AS revision FROM ab_tickets
           WHERE repo = ${this.repo} AND creation_key = ${options.idempotencyKey} FOR UPDATE`
         row = adopted[0]
       }
       if (!row) throw new Error('database ticket create failed')
       if (String(row.id) === id) {
-        for (const blocker of [...new Set(draft.blockedBy ?? [])]) {
+        for (const blocker of [...new Set(blockers)]) {
           if (blocker === id)
             throw new Error(`database ticket source: ticket "${id}" cannot block itself`)
           await q`INSERT INTO ab_ticket_blockers (repo, ticket_id, blocker_id)
@@ -232,37 +334,71 @@ export class PostgresTicketSource implements TicketSource {
   }
 
   async update(id: string, patch: TicketUpdate): Promise<void> {
-    const validated = validateTicketUpdate(patch)
-    await this.retry.tx(this.sql, async (q) => {
-      const row = await this.require(q, id, 'update', true)
-      await q`UPDATE ab_tickets SET
-        title = ${validated.title ?? String(row.title)},
-        body = ${validated.body ?? String(row.body)},
-        labels = ${q.array(validated.labels ?? strings(row.labels), 'text')},
-        updated_at = ${new Date().toISOString()}
-        WHERE repo = ${this.repo} AND id = ${id}`
-    })
+    await this.mutate(id, { kind: 'update', patch })
   }
 
   async addBlocker(id: string, blockerId: string): Promise<void> {
-    await this.retry.tx(this.sql, async (q) => {
-      await this.require(q, id, 'addBlocker', true)
-      if (id === blockerId)
-        throw new Error(`database ticket source: ticket "${id}" cannot block itself`)
-      await this.require(q, blockerId, 'addBlocker')
-      await q`INSERT INTO ab_ticket_blockers (repo, ticket_id, blocker_id)
-        VALUES (${this.repo}, ${id}, ${blockerId}) ON CONFLICT DO NOTHING`
-    })
+    await this.mutate(id, { kind: 'blockers', operation: 'block', ids: [blockerId] })
   }
 
   async removeBlocker(id: string, blockerId: string): Promise<void> {
-    // Require + DELETE are one coherent body on a pinned connection: the
-    // require's `SELECT *` is a migration-poisonable plan, and the pair must
-    // re-run together on the retry.
-    await this.retry.run(this.sql, async (q) => {
-      await this.require(q, id, 'removeBlocker')
-      await q`DELETE FROM ab_ticket_blockers
-        WHERE repo = ${this.repo} AND ticket_id = ${id} AND blocker_id = ${blockerId}`
+    await this.mutate(id, { kind: 'blockers', operation: 'unblock', ids: [blockerId] })
+  }
+
+  async mutateIfRevision(id: string, expected: string, mutation: TicketMutation): Promise<void> {
+    if (!expected.trim()) throw new Error('expected revision must be nonblank')
+    await this.mutate(id, mutation, expected)
+  }
+
+  private async mutate(id: string, mutation: TicketMutation, expected?: string): Promise<void> {
+    const patch = mutation.kind === 'update' ? validateTicketUpdate(mutation.patch) : undefined
+    await this.retry.tx(this.sql, async (q) => {
+      const state = mutation.kind === 'transition' ? await this.state(q, mutation.state) : undefined
+      const row = await this.require(q, id, 'mutation', true)
+      const storageId = String(row.id)
+      const revision = String(row.revision)
+      if (expected !== undefined && revision !== expected)
+        throw new TicketRevisionConflict(id, expected, revision)
+      let changed = false
+      if (patch) {
+        const title = patch.title ?? String(row.title)
+        const body = patch.body ?? String(row.body)
+        const labels = patch.labels ?? strings(row.labels)
+        changed =
+          title !== row.title ||
+          body !== row.body ||
+          JSON.stringify([...new Set(labels)].sort()) !==
+            JSON.stringify([...new Set(strings(row.labels))].sort())
+        if (changed)
+          await q`UPDATE ab_tickets SET title = ${title}, body = ${body}, labels = ${q.array(labels, 'text')} WHERE repo = ${this.repo} AND id = ${storageId}`
+      } else if (mutation.kind === 'transition') {
+        changed = row.state !== state
+        if (changed)
+          await q`UPDATE ab_tickets SET state = ${state} WHERE repo = ${this.repo} AND id = ${storageId}`
+      } else if (mutation.kind === 'blockers') {
+        const keys = new Set<string>()
+        for (const blocker of mutation.ids) {
+          const target =
+            mutation.operation === 'block' || expected !== undefined
+              ? await this.require(q, blocker, 'blocker')
+              : await this.lookup(q, blocker)
+          if (!target) continue
+          const key = String(target.id)
+          if (mutation.operation === 'block' && key === storageId)
+            throw new Error(`ticket "${id}" cannot block itself`)
+          keys.add(key)
+        }
+        const ids = [...keys]
+        for (const blocker of ids) {
+          const rows: Row[] =
+            mutation.operation === 'block'
+              ? await q`INSERT INTO ab_ticket_blockers (repo, ticket_id, blocker_id) VALUES (${this.repo}, ${storageId}, ${blocker}) ON CONFLICT DO NOTHING RETURNING blocker_id`
+              : await q`DELETE FROM ab_ticket_blockers WHERE repo = ${this.repo} AND ticket_id = ${storageId} AND blocker_id = ${blocker} RETURNING blocker_id`
+          changed ||= rows.length > 0
+        }
+      }
+      if (changed)
+        await q`UPDATE ab_tickets SET revision = revision + 1, updated_at = ${new Date().toISOString()} WHERE repo = ${this.repo} AND id = ${storageId}`
     })
   }
 
@@ -272,14 +408,13 @@ export class PostgresTicketSource implements TicketSource {
         // One run per id keeps each id's state read + blockers query
         // sequential on one pinned connection; the ids stay concurrent.
         this.retry.run(this.sql, async (q) => {
-          const rows: Row[] = await q`SELECT state FROM ab_tickets
-          WHERE repo = ${this.repo} AND id = ${id}`
-          if (!rows[0]) return { id, exists: false, resolved: false, blockedBy: [] }
+          const row = await this.lookup(q, id)
+          if (!row) return { id, exists: false, resolved: false, blockedBy: [] }
           return {
             id,
             exists: true,
-            resolved: String(rows[0].state) === this.lifecycle.done,
-            blockedBy: await this.blockers(q, id),
+            resolved: String(row.state) === this.lifecycle.done,
+            blockedBy: await this.blockers(q, String(row.id)),
           }
         }),
       ),