@defrex/autobuild-postgres-store 0.12.0 → 0.14.0

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)),
           }
         }),
       ),