@defrex/autobuild-postgres-store 0.11.0 → 0.13.0

package/README.md

@@ -44,10 +44,27 @@ release checkout. The database identity needs permission to create tables,
 constraints, and migration markers during migration and to select, insert,
 update, and delete the resulting tables at runtime. The ticket schema has its
 own version/checksum marker, so migrating an existing BuildStore v1 database
-adds team-scoped tickets, comments, and blockers without replacing the
+adds project-scoped tickets, comments, and blockers without replacing the
 established BuildStore marker. Opening against a missing, older/newer, or
 checksum-mismatched schema fails; schema creation is never implicit.
 
+Populated legacy ticket-v1 upgrades also require the running service's blob
+backend, credentials, access mode and prefix. The environment-aware migration
+CLI opens blobs lazily to read each registered project's selected effective
+configuration when ownership must be inferred. Registered projects without a
+run/config reference make no claim. Unreadable selected configs stop unchanged;
+restoring their bytes or assigning every remaining legacy team unblocks migration.
+Complete registered owner assignments avoid unrelated configuration reads.
+Fresh installs, empty-v1 upgrades and v2 reruns remain SQL-only.
+Released main-v9 upgrades import `AB_WEB_REPOSITORIES` once inside that same
+transaction. On failure, main promotion and registry import roll back with
+tickets. Owner `projects add` and `tickets assign-team` independently bootstrap
+their registry/recovery journals on v9, so they remain usable after rollback.
+Ambiguous teams stop unchanged; the owner resolves them with
+`ab-hosted-store tickets assign-team TEAM REPOSITORY --user IDENTITY` before
+rerunning migration. See the hosted-service migration procedure.
+
+
 The current DDL of every marker — build store, ticket, and auth — is immutable
 once a database has deployed it: deployed databases carry that exact DDL's
 checksum, and editing the DDL in place leaves them all incompatible. Every
@@ -102,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.11.0",
+  "version": "0.13.0",
   "type": "module",
   "license": "Apache-2.0",
   "engines": {
@@ -22,6 +22,26 @@
     "./store": {
       "types": "./src/store.ts",
       "import": "./src/store.ts"
+    },
+    "./projects": {
+      "types": "./src/projects.ts",
+      "import": "./src/projects.ts"
+    },
+    "./credentials": {
+      "types": "./src/credentials.ts",
+      "import": "./src/credentials.ts"
+    },
+    "./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/bin.ts

@@ -1,13 +1,13 @@
 #!/usr/bin/env bun
 import { describePostgresTarget, resolvePostgresUrl } from './env'
-import { migratePostgres } from './schema'
+import { migratePostgresFromEnv } from './config'
 
 async function main(): Promise<void> {
   if (process.argv.length !== 3 || process.argv[2] !== 'migrate') {
     throw new Error('usage: ab-postgres-store migrate')
   }
   const url = resolvePostgresUrl(process.env)
-  await migratePostgres(url)
+  await migratePostgresFromEnv(process.env)
   console.log(`Autobuild PostgreSQL schema is ready on ${describePostgresTarget(url)}`)
 }
 

package/src/config.ts

@@ -1,5 +1,6 @@
+import { migratePostgres } from './schema'
 import { S3Client } from '@aws-sdk/client-s3'
-import type { Clock } from '@defrex/autobuild/plugin-sdk'
+import type { BlobStore, Clock } from '@defrex/autobuild/plugin-sdk'
 import { resolvePostgresUrl } from './env'
 import { S3BlobStore } from './s3'
 import { openPostgresBuildStore, type PostgresBuildStore } from './store'
@@ -117,6 +118,14 @@ export async function openPostgresBuildStoreFromEnv(
     ...options,
     ...(config.retention ? { retention: config.retention } : {}),
   }
+  return openPostgresBuildStore(config.url, openPostgresBlobs(config), storeOptions)
+}
+
+export function openPostgresBlobsFromEnv(env: Env): BlobStore {
+  return openPostgresBlobs(parsePostgresStoreEnv(env))
+}
+
+function openPostgresBlobs(config: PostgresStoreConfig): BlobStore {
   if (config.backend === 's3') {
     const client = new S3Client({
       region: config.region,
@@ -128,25 +137,24 @@ export async function openPostgresBuildStoreFromEnv(
         ...(config.sessionToken ? { sessionToken: config.sessionToken } : {}),
       },
     })
-    return openPostgresBuildStore(
-      config.url,
-      new S3BlobStore({
-        client,
-        bucket: config.bucket,
-        ...(config.prefix ? { prefix: config.prefix } : {}),
-      }),
-      storeOptions,
-    )
-  }
-  return openPostgresBuildStore(
-    config.url,
-    new VercelBlobStore({
-      access: config.access,
+    return new S3BlobStore({
+      client,
+      bucket: config.bucket,
       ...(config.prefix ? { prefix: config.prefix } : {}),
-      ...(config.token
-        ? { token: config.token }
-        : { oidcToken: config.oidcToken!, storeId: config.storeId! }),
-    }),
-    storeOptions,
-  )
+    })
+  }
+  return new VercelBlobStore({
+    access: config.access,
+    ...(config.prefix ? { prefix: config.prefix } : {}),
+    ...(config.token
+      ? { token: config.token }
+      : { oidcToken: config.oidcToken!, storeId: config.storeId! }),
+  })
+}
+
+export async function migratePostgresFromEnv(env: Env): Promise<void> {
+  await migratePostgres(resolvePostgresUrl(env), {
+    openBlobs: () => openPostgresBlobsFromEnv(env),
+    legacyProjectEnv: env,
+  })
 }

package/src/connections.ts

@@ -0,0 +1,160 @@
+import { insertPreparedCredential } from './credentials'
+import { SQL } from 'bun'
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
+import type { ConnectionProposal, ConnectionOutcome } from '@defrex/autobuild/connection'
+import { normalizeProjectRepository, PostgresProjectRegistry } from './projects'
+import { resolvePostgresUrl, type PostgresEnv } from './env'
+import { assertSchema } from './schema'
+
+const hash = (value: string) => createHash('sha256').update(value).digest('hex')
+export class ConnectionError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+export interface ConnectionRecord extends ConnectionOutcome {
+  id: string
+  code: string
+  expiresAt: string
+}
+export interface ConnectionStore {
+  start(proposal: ConnectionProposal): Promise<ConnectionRecord & { capability: string }>
+  poll(id: string, capability: string, cancel?: boolean): Promise<ConnectionOutcome>
+  lookup(code: string, actor: string): Promise<ConnectionRecord | null>
+  decide(code: string, actor: string, approve: boolean): Promise<ConnectionRecord>
+}
+function record(row: Record<string, unknown>): ConnectionRecord {
+  return {
+    id: String(row.id),
+    repo: String(row.repo),
+    credentialId: String(row.credential_id),
+    code: String(row.code),
+    status: row.status as ConnectionOutcome['status'],
+    expiresAt: new Date(row.expires_at as string).toISOString(),
+  }
+}
+export class PostgresConnectionStore implements ConnectionStore {
+  constructor(
+    private readonly sql: SQL,
+    private readonly now = () => new Date(),
+  ) {}
+  async start(input: ConnectionProposal) {
+    if (
+      typeof input.repo !== 'string' ||
+      input.repo.length > 2048 ||
+      !/^[a-f0-9]{32}$/.test(input.credentialId) ||
+      !/^[a-f0-9]{64}$/.test(input.digest)
+    )
+      throw new ConnectionError(400, 'invalid connection proposal')
+    let repo: string
+    try {
+      repo = normalizeProjectRepository(input.repo)
+    } catch {
+      throw new ConnectionError(400, 'invalid repository identity')
+    }
+    const now = this.now()
+    // Bounded expiry retention; never deletes an active capability.
+    await this
+      .sql`DELETE FROM project_connections WHERE id IN (SELECT id FROM project_connections WHERE expires_at < ${new Date(now.getTime() - 86400000).toISOString()} LIMIT 100)`
+    const capability = randomBytes(32).toString('hex')
+    for (let attempt = 0; attempt < 5; attempt++) {
+      const id = randomBytes(16).toString('hex')
+      const code = randomBytes(5).toString('hex').toUpperCase()
+      const [row] = await this
+        .sql`INSERT INTO project_connections (id, repo, credential_id, digest, capability_hash, code, created_at, expires_at, status)
+        VALUES (${id}, ${repo}, ${input.credentialId}, ${input.digest}, ${hash(capability)}, ${code}, ${now.toISOString()}, ${new Date(now.getTime() + 600000).toISOString()}, 'pending') ON CONFLICT DO NOTHING RETURNING *`
+      if (row) return { ...record(row), capability }
+    }
+    throw new ConnectionError(503, 'connection creation unavailable; retry')
+  }
+  async poll(id: string, capability: string, cancel = false): Promise<ConnectionOutcome> {
+    if (!/^[a-f0-9]{32}$/.test(id) || !/^[a-f0-9]{64}$/.test(capability))
+      throw new ConnectionError(404, 'unknown connection')
+    return this.sql.begin(async (tx) => {
+      const [row] = await tx`SELECT * FROM project_connections WHERE id = ${id} FOR UPDATE`
+      if (
+        !row ||
+        !timingSafeEqual(
+          Buffer.from(row.capability_hash, 'hex'),
+          Buffer.from(hash(capability), 'hex'),
+        )
+      )
+        throw new ConnectionError(404, 'unknown connection')
+      const now = this.now()
+      if (!cancel && row.polled_at && now.getTime() - new Date(row.polled_at).getTime() < 4500)
+        throw new ConnectionError(429, 'poll again in five seconds')
+      if (!cancel && row.poll_attempts >= 130)
+        throw new ConnectionError(429, 'connection polling limit reached')
+      let status = row.status
+      if (cancel) {
+        if (status === 'approved')
+          await tx`UPDATE project_credentials SET revoked_at = COALESCE(revoked_at, ${now.toISOString()}) WHERE id = ${row.credential_id} AND repo = ${row.repo}`
+        status = 'denied'
+      } else if (status === 'pending' && new Date(row.expires_at) <= now) status = 'expired'
+      await tx`UPDATE project_connections SET status = ${status}, polled_at = ${now.toISOString()}, poll_attempts = poll_attempts + 1 WHERE id = ${id}`
+      return { ...record(row), status }
+    }) as Promise<ConnectionOutcome>
+  }
+  async lookup(code: string, actor: string): Promise<ConnectionRecord | null> {
+    if (!actor || actor.length > 320 || !/^[A-F0-9]{10}$/.test(code))
+      throw new ConnectionError(400, 'enter the ten-character connection code')
+    const now = this.now()
+    const [limit] = await this
+      .sql`INSERT INTO connection_lookup_limits (actor, started_at, attempts) VALUES (${actor}, ${now.toISOString()}, 1)
+      ON CONFLICT (actor) DO UPDATE SET
+        attempts = CASE WHEN connection_lookup_limits.started_at < ${new Date(now.getTime() - 60000).toISOString()} THEN 1 ELSE connection_lookup_limits.attempts + 1 END,
+        started_at = CASE WHEN connection_lookup_limits.started_at < ${new Date(now.getTime() - 60000).toISOString()} THEN ${now.toISOString()} ELSE connection_lookup_limits.started_at END RETURNING attempts`
+    if (limit.attempts > 20)
+      throw new ConnectionError(429, 'too many code lookups; retry in a minute')
+    const [row] = await this.sql`SELECT * FROM project_connections WHERE code = ${code}`
+    if (!row) return null
+    const result = record(row)
+    if (result.status === 'pending' && new Date(result.expiresAt) <= now) result.status = 'expired'
+    return result
+  }
+  async decide(code: string, actor: string, approve: boolean): Promise<ConnectionRecord> {
+    if (!(await this.lookup(code, actor))) throw new ConnectionError(404, 'unknown connection')
+    return this.sql.begin(async (tx) => {
+      const [row] = await tx`SELECT * FROM project_connections WHERE code = ${code} FOR UPDATE`
+      const now = this.now()
+      if (row.status !== 'pending') return record(row)
+      const status = new Date(row.expires_at) <= now ? 'expired' : approve ? 'approved' : 'denied'
+      if (status === 'approved') {
+        // Same lock order as registry mutations, with the request locked first.
+        await tx`INSERT INTO project_registry_state (singleton, legacy_imported) VALUES (true, false) ON CONFLICT DO NOTHING`
+        await tx`SELECT singleton FROM project_registry_state WHERE singleton = true FOR UPDATE`
+        const [previous] =
+          await tx`SELECT action FROM project_journal WHERE repo = ${row.repo} ORDER BY seq DESC LIMIT 1`
+        if (previous?.action !== 'added')
+          await tx`INSERT INTO project_journal (seq, repo, action, actor, ts) VALUES (nextval('project_journal_seq'), ${row.repo}, 'added', ${actor}, ${now.toISOString()})`
+        // A collision aborts the whole transaction, including project registration.
+        await insertPreparedCredential(tx as SQL, {
+          id: row.credential_id,
+          digest: row.digest,
+          repo: row.repo,
+          now,
+          user: actor,
+        })
+      }
+      const [updated] =
+        await tx`UPDATE project_connections SET status = ${status}, approved_by = ${status === 'approved' ? actor : null} WHERE id = ${row.id} RETURNING *`
+      return record(updated)
+    }) as Promise<ConnectionRecord>
+  }
+}
+export async function openPostgresConnectionStoreFromEnv(
+  env: PostgresEnv,
+): Promise<PostgresConnectionStore> {
+  const sql = new SQL(resolvePostgresUrl(env))
+  try {
+    await assertSchema(sql)
+    await new PostgresProjectRegistry(sql).initializeFromEnv(env)
+    return new PostgresConnectionStore(sql)
+  } catch (error) {
+    await sql.close()
+    throw error
+  }
+}

package/src/credentials.ts

@@ -0,0 +1,157 @@
+import { SQL } from 'bun'
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
+import {
+  normalizeProjectRepository,
+  PostgresProjectRegistry,
+  type ProjectRegistryReader,
+} from './projects'
+import { resolvePostgresUrl, type PostgresEnv } from './env'
+import { assertSchema } from './schema'
+
+export interface CredentialMetadata {
+  id: string
+  repo: string
+  createdAt: string
+  createdBy: string
+  lastUsedAt: string | null
+  revokedAt: string | null
+  expiresAt: string | null
+  purpose: 'project-owner' | 'dispatcher'
+}
+export interface CredentialReader {
+  authenticate(token: string, now: Date): Promise<CredentialMetadata | null>
+}
+export interface CredentialStore extends CredentialReader {
+  issue(
+    repo: string,
+    user: string,
+    options?: { expiresAt?: Date; purpose?: CredentialMetadata['purpose'] },
+  ): Promise<{ token: string; credential: CredentialMetadata }>
+  list(repo: string): Promise<CredentialMetadata[]>
+  revoke(repo: string, id: string, user: string): Promise<void>
+  close(): Promise<void>
+}
+export class ProjectNotRegisteredError extends Error {
+  constructor() {
+    super('project not registered')
+  }
+}
+const hash = (secret: string) => createHash('sha256').update(secret).digest()
+const stamp = (value: unknown): string | null =>
+  value == null ? null : new Date(value as string).toISOString()
+function metadata(row: Record<string, unknown>): CredentialMetadata {
+  return {
+    id: String(row.id),
+    repo: String(row.repo),
+    createdAt: stamp(row.created_at)!,
+    createdBy: String(row.created_by),
+    lastUsedAt: stamp(row.last_used_at),
+    revokedAt: stamp(row.revoked_at),
+    expiresAt: stamp(row.expires_at),
+    purpose: row.purpose as CredentialMetadata['purpose'],
+  }
+}
+function actor(user: string): string {
+  if (!user.trim()) throw new Error('credential creator must be nonblank')
+  return user.trim()
+}
+/** Insert a CLI-prepared digest using the caller's transaction, never a raw token. */
+export async function insertPreparedCredential(
+  sql: SQL,
+  input: {
+    id: string
+    digest: string
+    repo: string
+    user: string
+    now: Date
+    purpose?: CredentialMetadata['purpose']
+    expiresAt?: Date
+  },
+): Promise<CredentialMetadata> {
+  if (!/^[a-f0-9]{32}$/.test(input.id) || !/^[a-f0-9]{64}$/.test(input.digest))
+    throw new Error('invalid prepared credential')
+  const repo = normalizeProjectRepository(input.repo),
+    by = actor(input.user)
+  const [row] =
+    await sql`INSERT INTO project_credentials (id, digest, repo, created_at, created_by, purpose, expires_at)
+    VALUES (${input.id}, ${input.digest}, ${repo}, ${input.now.toISOString()}, ${by}, ${input.purpose ?? 'project-owner'}, ${input.expiresAt?.toISOString() ?? null}) RETURNING *`
+  return metadata(row)
+}
+export class PostgresCredentialStore implements CredentialStore {
+  constructor(
+    private readonly sql: SQL,
+    private readonly projects: ProjectRegistryReader,
+    private readonly ownsPool = false,
+  ) {}
+  async issue(
+    raw: string,
+    user: string,
+    options: { expiresAt?: Date; purpose?: CredentialMetadata['purpose'] } = {},
+  ): Promise<{ token: string; credential: CredentialMetadata }> {
+    const repo = normalizeProjectRepository(raw)
+    const by = actor(user)
+    if (!(await this.projects.has(repo))) throw new ProjectNotRegisteredError()
+    const now = new Date()
+    if (
+      options.expiresAt &&
+      (!Number.isFinite(options.expiresAt.getTime()) || options.expiresAt <= now)
+    )
+      throw new Error('credential expiry must be in the future')
+    const id = randomBytes(16).toString('hex')
+    const secret = randomBytes(32).toString('hex')
+    const credential = await insertPreparedCredential(this.sql, {
+      id,
+      digest: hash(secret).toString('hex'),
+      repo,
+      user: by,
+      now,
+      ...options,
+    })
+    return { token: `abp_1_${id}_${secret}`, credential }
+  }
+
+  async authenticate(token: string, now: Date): Promise<CredentialMetadata | null> {
+    const parts = /^abp_1_([a-f0-9]{32})_([a-f0-9]{64})$/.exec(token)
+    if (!parts) return null
+    const [row] = await this.sql`SELECT * FROM project_credentials WHERE id = ${parts[1]!}`
+    if (
+      !row ||
+      !timingSafeEqual(hash(parts[2]!), Buffer.from(row.digest, 'hex')) ||
+      row.revoked_at ||
+      (row.expires_at && new Date(row.expires_at) <= now)
+    )
+      return null
+    if (!(await this.projects.has(row.repo))) throw new ProjectNotRegisteredError()
+    // The conditional update also closes a revoke racing the initial read.
+    const [used] = await this.sql`UPDATE project_credentials SET last_used_at = ${now.toISOString()}
+      WHERE id = ${row.id} AND revoked_at IS NULL RETURNING *`
+    return used ? metadata(used) : null
+  }
+  async list(raw: string): Promise<CredentialMetadata[]> {
+    const rows = await this
+      .sql`SELECT * FROM project_credentials WHERE repo = ${normalizeProjectRepository(raw)} ORDER BY created_at, id`
+    return rows.map(metadata)
+  }
+  async revoke(raw: string, id: string, user: string): Promise<void> {
+    actor(user)
+    await this
+      .sql`UPDATE project_credentials SET revoked_at = COALESCE(revoked_at, ${new Date().toISOString()}) WHERE repo = ${normalizeProjectRepository(raw)} AND id = ${id}`
+  }
+  async close(): Promise<void> {
+    if (this.ownsPool) await this.sql.close()
+  }
+}
+export async function openPostgresCredentialStoreFromEnv(
+  env: PostgresEnv,
+): Promise<CredentialStore> {
+  const sql = new SQL(resolvePostgresUrl(env))
+  try {
+    await assertSchema(sql)
+    const projects = new PostgresProjectRegistry(sql)
+    await projects.initializeFromEnv(env)
+    return new PostgresCredentialStore(sql, projects, true)
+  } catch (error) {
+    await sql.close()
+    throw error
+  }
+}

package/src/index.ts

@@ -40,3 +40,8 @@ export {
 export type { PostgresTicketContext, PostgresTicketLifecycle } from './tickets'
 export { VercelBlobStore } from './vercel'
 export type { VercelBlobStoreOptions } from './vercel'
+export * from './projects'
+export * from './credentials'
+
+export { openPostgresBlobsFromEnv, migratePostgresFromEnv } from './config'
+export * from './ticket-assignments'

package/src/projects.ts

@@ -0,0 +1,171 @@
+import { SQL } from 'bun'
+import { normalizeConnectionRepository as normalizeProjectRepository } from '@defrex/autobuild/connection'
+import { resolvePostgresUrl, type PostgresEnv } from './env'
+import { assertSchema, PROJECT_SCHEMA_DDL } from './schema'
+
+export interface ProjectEntry {
+  repo: string
+  addedAt: string
+  addedBy: string
+}
+export interface ProjectRegistryReader {
+  list(): Promise<ProjectEntry[]>
+  has(repo: string): Promise<boolean>
+}
+export interface ProjectRegistry extends ProjectRegistryReader {
+  add(repo: string, user: string): Promise<ProjectEntry>
+  remove(repo: string, user: string): Promise<void>
+  close(): Promise<void>
+}
+
+/** Repository identities use the same normalization as checkout origins. */
+export { normalizeConnectionRepository as normalizeProjectRepository } from '@defrex/autobuild/connection'
+
+export function legacyProjectRepositories(env: PostgresEnv): string[] {
+  const raw = env.AB_WEB_REPOSITORIES?.trim()
+  if (!raw) return []
+  return [...new Set(raw.split(',').map(normalizeProjectRepository))]
+}
+
+function actor(user: string): string {
+  const value = user.trim()
+  if (!value) throw new Error('project administrator identity must be nonblank')
+  return value
+}
+function entry(row: { repo: string; ts: Date | string; actor: string }): ProjectEntry {
+  return { repo: row.repo, addedAt: new Date(row.ts).toISOString(), addedBy: row.actor }
+}
+
+export class PostgresProjectRegistry implements ProjectRegistry {
+  constructor(
+    private readonly sql: SQL,
+    private readonly ownsPool = false,
+  ) {}
+
+  private async locked<T>(work: (tx: SQL) => Promise<T>): Promise<T> {
+    return this.sql.begin(async (tx) => {
+      await tx`INSERT INTO project_registry_state (singleton, legacy_imported)
+        VALUES (true, false) ON CONFLICT (singleton) DO NOTHING`
+      await tx`SELECT singleton FROM project_registry_state WHERE singleton = true FOR UPDATE`
+      return work(tx as SQL)
+    }) as Promise<T>
+  }
+
+  async initialize(repositories: readonly string[]): Promise<void> {
+    if (repositories.length === 0) return
+    await this.importOnce(() => repositories)
+  }
+
+  async initializeFromEnv(env: PostgresEnv): Promise<void> {
+    await this.importOnce(() => legacyProjectRepositories(env))
+  }
+
+  /** The migration owns this transaction; do not open a nested connection. */
+  async initializeFromEnvInTransaction(env: PostgresEnv): Promise<void> {
+    await this.sql`INSERT INTO project_registry_state (singleton, legacy_imported)
+      VALUES (true, false) ON CONFLICT (singleton) DO NOTHING`
+    await this.sql`SELECT singleton FROM project_registry_state WHERE singleton = true FOR UPDATE`
+    await this.importIn(this.sql, () => legacyProjectRepositories(env))
+  }
+
+  private async importOnce(source: () => readonly string[]): Promise<void> {
+    await this.locked((tx) => this.importIn(tx, source))
+  }
+
+  private async importIn(tx: SQL, source: () => readonly string[]): Promise<void> {
+    const [state] =
+      await tx`SELECT legacy_imported FROM project_registry_state WHERE singleton = true`
+    if (state.legacy_imported) return
+    // Read the retired environment only until the one-time import succeeds.
+    const normalized = source().map(normalizeProjectRepository)
+    if (normalized.length === 0) return
+    for (const repo of normalized) await this.addIn(tx, repo, 'system:AB_WEB_REPOSITORIES')
+    await tx`UPDATE project_registry_state SET legacy_imported = true WHERE singleton = true`
+  }
+
+  async list(): Promise<ProjectEntry[]> {
+    const rows = await this.sql`SELECT repo, actor, ts FROM (
+      SELECT DISTINCT ON (repo) repo, action, actor, ts FROM project_journal ORDER BY repo, seq DESC
+    ) latest WHERE action = 'added' ORDER BY repo`
+    return rows.map(entry)
+  }
+
+  async has(repo: string): Promise<boolean> {
+    const [row] = await this
+      .sql`SELECT action FROM project_journal WHERE repo = ${repo} ORDER BY seq DESC LIMIT 1`
+    return row?.action === 'added'
+  }
+
+  private async addIn(tx: SQL, repo: string, user: string): Promise<ProjectEntry> {
+    const [previous] =
+      await tx`SELECT repo, action, actor, ts FROM project_journal WHERE repo = ${repo} ORDER BY seq DESC LIMIT 1`
+    if (previous?.action === 'added') return entry(previous)
+    const [row] = await tx`INSERT INTO project_journal (seq, repo, action, actor, ts)
+      VALUES (nextval('project_journal_seq'), ${repo}, 'added', ${user}, ${new Date().toISOString()})
+      RETURNING repo, actor, ts`
+    return entry(row)
+  }
+
+  async add(raw: string, user: string): Promise<ProjectEntry> {
+    const repo = normalizeProjectRepository(raw)
+    const by = actor(user)
+    return this.locked((tx) => this.addIn(tx, repo, by))
+  }
+
+  async remove(raw: string, user: string): Promise<void> {
+    const repo = normalizeProjectRepository(raw)
+    const by = actor(user)
+    await this.locked(async (tx) => {
+      const [previous] =
+        await tx`SELECT action FROM project_journal WHERE repo = ${repo} ORDER BY seq DESC LIMIT 1`
+      if (previous?.action !== 'added') return
+      await tx`INSERT INTO project_journal (seq, repo, action, actor, ts)
+        VALUES (nextval('project_journal_seq'), ${repo}, 'removed', ${by}, ${new Date().toISOString()})`
+    })
+  }
+
+  async close(): Promise<void> {
+    if (this.ownsPool) await this.sql.close()
+  }
+}
+
+export async function openPostgresProjectRegistryFromEnv(
+  env: PostgresEnv,
+): Promise<ProjectRegistry> {
+  const sql = new SQL(resolvePostgresUrl(env))
+  try {
+    await assertSchema(sql)
+    const registry = new PostgresProjectRegistry(sql, true)
+    await registry.initializeFromEnv(env)
+    return registry
+  } catch (error) {
+    await sql.close()
+    throw error
+  }
+}
+
+/** Owner recovery must work while the main-schema promotion is rolled back by
+ * a stopped ticket migration. Bootstrap only the independent registry tables. */
+export async function initializeProjectRegistryForRecovery(
+  sql: SQL,
+  env: PostgresEnv,
+): Promise<void> {
+  await sql.begin(async (tx) => {
+    await tx`SELECT pg_advisory_xact_lock(470281941)`
+    await tx.unsafe(PROJECT_SCHEMA_DDL)
+    await new PostgresProjectRegistry(tx as SQL).initializeFromEnvInTransaction(env)
+  })
+}
+
+export async function openPostgresProjectRegistryForRecoveryFromEnv(
+  env: PostgresEnv,
+): Promise<ProjectRegistry> {
+  const sql = new SQL(resolvePostgresUrl(env))
+  try {
+    await initializeProjectRegistryForRecovery(sql, env)
+    return new PostgresProjectRegistry(sql, true)
+  } catch (error) {
+    await sql.close()
+    throw error
+  }
+}