@defrex/autobuild-postgres-store 0.14.0 → 1.0.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defrex/autobuild-postgres-store",
-  "version": "0.14.0",
+  "version": "1.0.0-beta.1",
   "type": "module",
   "license": "Apache-2.0",
   "engines": {
@@ -42,13 +42,17 @@
     "./ticket-grants": {
       "types": "./src/ticket-grants.ts",
       "import": "./src/ticket-grants.ts"
+    },
+    "./request-context": {
+      "types": "./src/request-context.ts",
+      "import": "./src/request-context.ts"
     }
   },
   "bin": {
     "ab-postgres-store": "./src/bin.ts"
   },
   "peerDependencies": {
-    "@defrex/autobuild": ">=0.7.0"
+    "@defrex/autobuild": ">=0.7.0 || >=1.0.0-0 <1.0.0"
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.0.0",

package/src/credentials.ts

@@ -19,6 +19,7 @@ export interface CredentialMetadata {
   purpose: 'project-owner' | 'dispatcher'
 }
 export interface CredentialReader {
+  /** Success includes fresh project registration validation. */
   authenticate(token: string, now: Date): Promise<CredentialMetadata | null>
 }
 export interface CredentialStore extends CredentialReader {
@@ -36,6 +37,7 @@ export class ProjectNotRegisteredError extends Error {
     super('project not registered')
   }
 }
+export const LAST_USE_INTERVAL_MS = 60_000
 const hash = (secret: string) => createHash('sha256').update(secret).digest()
 const stamp = (value: unknown): string | null =>
   value == null ? null : new Date(value as string).toISOString()
@@ -113,7 +115,9 @@ export class PostgresCredentialStore implements CredentialStore {
   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]!}`
+    const [row] = await this.sql`SELECT c.*, (SELECT action FROM project_journal
+      WHERE repo = c.repo ORDER BY seq DESC LIMIT 1) AS project_action
+      FROM project_credentials c WHERE id = ${parts[1]!}`
     if (
       !row ||
       !timingSafeEqual(hash(parts[2]!), Buffer.from(row.digest, 'hex')) ||
@@ -121,11 +125,21 @@ export class PostgresCredentialStore implements CredentialStore {
       (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.
+    if (row.project_action !== 'added') throw new ProjectNotRegisteredError()
+    const cutoff = new Date(now.getTime() - LAST_USE_INTERVAL_MS).toISOString()
+    if (
+      row.last_used_at &&
+      new Date(row.last_used_at).getTime() > now.getTime() - LAST_USE_INTERVAL_MS
+    )
+      return metadata(row)
+    // Competing writers recheck the cutoff after waiting for the row lock.
+    // An in-flight authentication may finish after revocation.
     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
+      WHERE id = ${row.id} AND revoked_at IS NULL
+        AND (expires_at IS NULL OR expires_at > ${now.toISOString()})
+        AND (last_used_at IS NULL OR last_used_at <= ${cutoff})
+      RETURNING *`
+    return metadata(used ?? row)
   }
   async list(raw: string): Promise<CredentialMetadata[]> {
     const rows = await this

package/src/request-context.ts

@@ -0,0 +1,51 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+interface ReadContext {
+  records: WeakMap<object, Map<string, Promise<unknown>>>
+  existence: WeakMap<object, Map<string, boolean>>
+}
+const reads = new AsyncLocalStorage<ReadContext>()
+
+/** One HTTP invocation; nested server composition shares only repository reads. */
+export function withRepositoryReads<T>(work: () => T): T {
+  return reads.getStore()
+    ? work()
+    : reads.run({ records: new WeakMap(), existence: new WeakMap() }, work)
+}
+
+export function hasRepositoryReadContext(): boolean {
+  return reads.getStore() !== undefined
+}
+
+export function repositoryRead<T>(store: object, repo: string, read: () => Promise<T>): Promise<T> {
+  const context = reads.getStore()
+  if (!context) return read()
+  let entries = context.records.get(store)
+  if (!entries) {
+    entries = new Map()
+    context.records.set(store, entries)
+  }
+  let result = entries.get(repo)
+  if (!result) {
+    result = read()
+    entries.set(repo, result)
+  }
+  return result as Promise<T>
+}
+
+/** Existence only: a positive event tail proves its foreign-key parent exists.
+ * Never use this evidence instead of a mutation lock or an authorization check. */
+export function knownRepositoryExists(store: object, repo: string): boolean | undefined {
+  return reads.getStore()?.existence.get(store)?.get(repo)
+}
+
+export function recordRepositoryExistence(store: object, repo: string, exists: boolean): void {
+  const context = reads.getStore()
+  if (!context) return
+  let entries = context.existence.get(store)
+  if (!entries) {
+    entries = new Map()
+    context.existence.set(store, entries)
+  }
+  entries.set(repo, exists)
+}

package/src/schema.ts

@@ -16,7 +16,7 @@ import {
   assertAuthSchema,
 } from './auth-schema'
 
-export const SCHEMA_VERSION = 14
+export const SCHEMA_VERSION = 15
 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
@@ -840,12 +840,19 @@ export const SCHEMA_V13_DDL = `${SCHEMA_V12_DDL}\n${TICKET_POLICY_SCHEMA_DDL}\n$
 export const SCHEMA_V13_CHECKSUM = new Bun.CryptoHasher('sha256')
   .update(SCHEMA_V13_DDL)
   .digest('hex')
-export const SCHEMA_DDL = `${SCHEMA_V13_DDL}\nALTER TABLE repo_streams ADD COLUMN IF NOT EXISTS tick jsonb;`
+export const SCHEMA_V14_DDL = `${SCHEMA_V13_DDL}\nALTER TABLE repo_streams ADD COLUMN IF NOT EXISTS tick jsonb;`
+export const SCHEMA_V14_CHECKSUM = new Bun.CryptoHasher('sha256')
+  .update(SCHEMA_V14_DDL)
+  .digest('hex')
+const NODE_WRITER_DDL = `ALTER TABLE builds ADD COLUMN IF NOT EXISTS node_writer_holder text;
+ALTER TABLE builds ADD COLUMN IF NOT EXISTS node_writer_expires_at timestamptz;
+ALTER TABLE builds ADD COLUMN IF NOT EXISTS node_writer_ttl_ms bigint;`
+export const SCHEMA_DDL = `${SCHEMA_V14_DDL}\n${NODE_WRITER_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 = 5
+export const TICKET_SCHEMA_VERSION = 6
 export const TICKET_SCHEMA_V1_DDL = `
 CREATE TABLE IF NOT EXISTS ab_ticket_schema_migrations (
   singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
@@ -895,7 +902,7 @@ export const TICKET_SCHEMA_V4_DDL = `${TICKET_SCHEMA_V3_DDL}\n${TICKET_STATES_DD
 export const TICKET_SCHEMA_V4_CHECKSUM = new Bun.CryptoHasher('sha256')
   .update(TICKET_SCHEMA_V4_DDL)
   .digest('hex')
-export const TICKET_SCHEMA_DDL =
+export const TICKET_SCHEMA_V5_DDL =
   TICKET_SCHEMA_V4_DDL +
   `
 ALTER TABLE ab_tickets ADD COLUMN IF NOT EXISTS readable_id text;
@@ -903,6 +910,19 @@ 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_V5_CHECKSUM = new Bun.CryptoHasher('sha256')
+  .update(TICKET_SCHEMA_V5_DDL)
+  .digest('hex')
+
+const TICKET_TREE_DELTA = `
+ALTER TABLE ab_tickets ADD COLUMN kind text NOT NULL DEFAULT 'work';
+ALTER TABLE ab_tickets ADD COLUMN target_id text;
+ALTER TABLE ab_tickets ADD CONSTRAINT ab_tickets_kind_check CHECK (kind IN ('work', 'node'));
+ALTER TABLE ab_tickets ADD CONSTRAINT ab_tickets_target_fk FOREIGN KEY (repo, target_id) REFERENCES ab_tickets(repo, id);
+ALTER TABLE ab_tickets ADD CONSTRAINT ab_tickets_target_self_check CHECK (target_id <> id);
+CREATE INDEX ab_tickets_target_idx ON ab_tickets (repo, target_id);
+`
+export const TICKET_SCHEMA_DDL = TICKET_SCHEMA_V5_DDL + TICKET_TREE_DELTA
 export const TICKET_SCHEMA_CHECKSUM = new Bun.CryptoHasher('sha256')
   .update(TICKET_SCHEMA_DDL)
   .digest('hex')
@@ -1005,6 +1025,9 @@ const EXPECTED_COLUMNS: Record<string, readonly ExpectedColumn[]> = {
     // the end, so migrated and fresh databases assert identically (the
     // sessions.creation_seq and streams.session comments above).
     ['repo_origin', 'text', false],
+    ['node_writer_holder', 'text', false],
+    ['node_writer_expires_at', 'timestamp with time zone', false],
+    ['node_writer_ttl_ms', 'bigint', false],
   ],
   events: [
     ['build', 'text', true],
@@ -1356,6 +1379,8 @@ export async function assertTicketSchema(sql: SQL): Promise<void> {
       ['revision', 'bigint', true],
       ['readable_id', 'text', true],
       ['ticket_number', 'bigint', true],
+      ['kind', 'text', true],
+      ['target_id', 'text', false],
     ],
     ab_ticket_counters: [
       ['repo', 'text', true],
@@ -1407,6 +1432,10 @@ export async function assertTicketSchema(sql: SQL): Promise<void> {
     !String(indexes[0].indexdef).endsWith('(repo, lower(readable_id))')
   )
     throw schemaError('ticket readable id unique index is missing or mismatched')
+  const targetIndexes =
+    await sql`SELECT indexdef FROM pg_indexes WHERE schemaname = current_schema() AND tablename = 'ab_tickets' AND indexname = 'ab_tickets_target_idx'`
+  if (!targetIndexes[0] || !String(targetIndexes[0].indexdef).endsWith('(repo, target_id)'))
+    throw schemaError('ticket target 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
@@ -1423,6 +1452,9 @@ export async function assertTicketSchema(sql: SQL): Promise<void> {
       'UNIQUE (repo, creation_key)',
       'UNIQUE (repo, ticket_number)',
       'CHECK ((ticket_number > 0))',
+      "CHECK ((kind = ANY (ARRAY['work'::text, 'node'::text])))",
+      'FOREIGN KEY (repo, target_id) REFERENCES ab_tickets(repo, id)',
+      'CHECK ((target_id <> id))',
     ],
     ab_ticket_counters: ['PRIMARY KEY (repo)', 'CHECK ((last_number >= 0))'],
     ab_ticket_comments: [
@@ -1485,10 +1517,11 @@ export async function migratePostgres(
   try {
     await sql.begin(async (tx) => {
       await tx`SELECT pg_advisory_xact_lock(470281941)`
-      await tx.unsafe(SCHEMA_DDL)
+      await tx.unsafe(SCHEMA_V14_DDL)
       await tx.unsafe(TICKET_SCHEMA_V2_DDL)
       await tx.unsafe(TICKET_STATES_DDL)
       await tx.unsafe(SNAPSHOT_SCHEMA_DDL)
+      await tx.unsafe(REPO_CHANGE_DDL)
       await tx.unsafe(AUTH_SCHEMA_DDL)
       const rows: { version: number; checksum: string }[] =
         await tx`SELECT version, checksum FROM ab_schema_migrations WHERE singleton = true FOR UPDATE`
@@ -1665,6 +1698,8 @@ export async function migratePostgres(
             SET version = ${SCHEMA_VERSION}, checksum = ${SCHEMA_CHECKSUM},
               applied_at = ${new Date().toISOString()}
             WHERE singleton = true`
+        } else if (version === 14 && marker.checksum === SCHEMA_V14_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 === 13 && marker.checksum === SCHEMA_V13_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 === 12 && marker.checksum === SCHEMA_V12_CHECKSUM) {
@@ -1697,6 +1732,9 @@ export async function migratePostgres(
         await tx`INSERT INTO ab_schema_migrations (singleton, version, checksum, applied_at)
           VALUES (true, ${SCHEMA_VERSION}, ${SCHEMA_CHECKSUM}, ${new Date().toISOString()})`
       }
+      // Preserve historical physical column order: legacy repo_origin must
+      // precede the new writer columns just as it does in fresh databases.
+      await tx.unsafe(NODE_WRITER_DDL)
       if (options.legacyProjectEnv !== undefined) {
         await new PostgresProjectRegistry(tx as SQL).initializeFromEnvInTransaction(
           options.legacyProjectEnv,
@@ -1713,6 +1751,7 @@ export async function migratePostgres(
         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.unsafe(TICKET_TREE_DELTA)
         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 (
@@ -1722,6 +1761,7 @@ export async function migratePostgres(
       ) {
         await tx`ALTER TABLE ab_tickets ADD COLUMN revision bigint NOT NULL DEFAULT 1`
         await migrateReadableTickets(tx as SQL, options.openBlobs)
+        await tx.unsafe(TICKET_TREE_DELTA)
         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 &&
@@ -1729,6 +1769,7 @@ export async function migratePostgres(
         ticketMarker.checksum === TICKET_SCHEMA_V3_CHECKSUM
       ) {
         await migrateReadableTickets(tx as SQL, options.openBlobs)
+        await tx.unsafe(TICKET_TREE_DELTA)
         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 &&
@@ -1736,6 +1777,14 @@ export async function migratePostgres(
         ticketMarker.checksum === TICKET_SCHEMA_V4_CHECKSUM
       ) {
         await migrateReadableTickets(tx as SQL, options.openBlobs)
+        await tx.unsafe(TICKET_TREE_DELTA)
+        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) === 5 &&
+        ticketMarker.checksum === TICKET_SCHEMA_V5_CHECKSUM
+      ) {
+        await tx.unsafe(TICKET_TREE_DELTA)
         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) {
@@ -1752,6 +1801,7 @@ 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.unsafe(TICKET_TREE_DELTA)
         await tx`INSERT INTO ab_ticket_schema_migrations
           (singleton, version, checksum, applied_at)
           VALUES (true, ${TICKET_SCHEMA_VERSION}, ${TICKET_SCHEMA_CHECKSUM}, ${new Date().toISOString()})`
@@ -1820,3 +1870,31 @@ export async function migratePostgres(
     await sql.close()
   }
 }
+
+/** Additive invalidation plumbing; independent of the core lockstep marker. */
+export const REPO_CHANGE_DDL = `
+CREATE TABLE IF NOT EXISTS repo_change_positions (repo text PRIMARY KEY, position bigint NOT NULL);
+CREATE INDEX IF NOT EXISTS builds_repo_created_slug ON builds(repo, created_at, slug);
+CREATE OR REPLACE FUNCTION ab_repo_changed() RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN
+ INSERT INTO repo_change_positions(repo, position) VALUES (NEW.repo, 1)
+ ON CONFLICT(repo) DO UPDATE SET position = repo_change_positions.position + 1;
+ RETURN NEW;
+END $$;
+CREATE OR REPLACE FUNCTION ab_build_changed() RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN
+ INSERT INTO repo_change_positions(repo, position)
+ SELECT repo, 1 FROM builds WHERE slug = NEW.build
+ ON CONFLICT(repo) DO UPDATE SET position = repo_change_positions.position + 1;
+ RETURN NEW;
+END $$;
+DROP TRIGGER IF EXISTS builds_repo_change ON builds;
+CREATE TRIGGER builds_repo_change AFTER INSERT ON builds FOR EACH ROW EXECUTE FUNCTION ab_repo_changed();
+DROP TRIGGER IF EXISTS repo_events_repo_change ON repo_events;
+CREATE TRIGGER repo_events_repo_change AFTER INSERT ON repo_events FOR EACH ROW EXECUTE FUNCTION ab_repo_changed();
+DROP TRIGGER IF EXISTS events_repo_change ON events;
+CREATE TRIGGER events_repo_change AFTER INSERT ON events FOR EACH ROW EXECUTE FUNCTION ab_build_changed();
+DROP TRIGGER IF EXISTS repo_holder_change ON repo_streams;
+CREATE TRIGGER repo_holder_change AFTER UPDATE OF lease_holder ON repo_streams
+FOR EACH ROW WHEN (OLD.lease_holder IS DISTINCT FROM NEW.lease_holder) EXECUTE FUNCTION ab_repo_changed();
+`

package/src/store.ts

@@ -1,3 +1,9 @@
+import {
+  repositoryRead,
+  hasRepositoryReadContext,
+  knownRepositoryExists,
+  recordRepositoryExistence,
+} from './request-context'
 import { readPersistedBuildDigests } from '@defrex/autobuild/store-adapter'
 import { assertPublicSnapshotReducer } from '@defrex/autobuild/store-adapter'
 import {
@@ -159,6 +165,7 @@ export interface PostgresBuildStoreOptions {
 }
 
 export class PostgresBuildStore implements BuildStore {
+  readonly networkReads = true
   readonly blobs: BlobStore
   private readonly clock: Clock
   private readonly maxRevisions: number
@@ -283,12 +290,42 @@ export class PostgresBuildStore implements BuildStore {
   }
 
   async listBuilds(): Promise<BuildRecord[]> {
+    return this.listBuildRecords()
+  }
+
+  async getRepoChangePosition(repo: string): Promise<string> {
+    return this.run(async (q) => {
+      const rows: Row[] =
+        await q`SELECT position::text AS position FROM repo_change_positions WHERE repo = ${repo}`
+      return rows[0] ? String(rows[0].position) : '0'
+    })
+  }
+
+  async listBuildsForRepo(repo: string): Promise<BuildRecord[]> {
+    return this.listBuildRecords(repo)
+  }
+
+  private async listBuildRecords(repo?: string): Promise<BuildRecord[]> {
     return this.run(async (q) => {
       if (!(await this.hasReadableTicketSchema(q))) {
-        const rows: Row[] = await q`SELECT * FROM builds ORDER BY created_at, slug`
+        const rows: Row[] =
+          repo === undefined
+            ? await q`SELECT * FROM builds ORDER BY created_at, slug`
+            : await q`SELECT * FROM builds WHERE repo = ${repo} 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
+      const rows: Row[] =
+        repo === undefined
+          ? 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`
+          : await q`SELECT b.*, t.readable_id AS projected_ticket_id
+        FROM (SELECT * FROM builds WHERE repo = ${repo}) b
         LEFT JOIN LATERAL (
           SELECT readable_id FROM ab_tickets
           WHERE b.ticket->>'source' = 'hosted' AND repo = b.repo
@@ -556,6 +593,43 @@ export class PostgresBuildStore implements BuildStore {
     })
   }
 
+  async claimNodeWriter(slug: string, holder: string, ttlMs: number): Promise<boolean> {
+    return this.tx(async (q) => {
+      const row = await this.lockBuild(q, slug)
+      const now = this.clock().getTime()
+      if (
+        row.node_writer_holder &&
+        row.node_writer_holder !== holder &&
+        row.node_writer_expires_at &&
+        Date.parse(iso(row.node_writer_expires_at)) > now
+      )
+        return false
+      const expires = new Date(now + ttlMs).toISOString()
+      await q`UPDATE builds SET node_writer_holder=${holder}, node_writer_expires_at=${expires}, node_writer_ttl_ms=${ttlMs}, updated_at=${new Date(now).toISOString()} WHERE slug=${slug}`
+      return true
+    })
+  }
+  async renewNodeWriter(slug: string, holder: string): Promise<boolean> {
+    return this.tx(async (q) => {
+      const row = await this.lockBuild(q, slug)
+      const now = this.clock().getTime()
+      if (
+        row.node_writer_holder !== holder ||
+        !row.node_writer_expires_at ||
+        Date.parse(iso(row.node_writer_expires_at)) <= now
+      )
+        return false
+      const expires = new Date(now + num(row.node_writer_ttl_ms)).toISOString()
+      await q`UPDATE builds SET node_writer_expires_at=${expires}, updated_at=${new Date(now).toISOString()} WHERE slug=${slug}`
+      return true
+    })
+  }
+  async releaseNodeWriter(slug: string, holder: string): Promise<void> {
+    await this.tx(async (q) => {
+      await this.lockBuild(q, slug)
+      await q`UPDATE builds SET node_writer_holder=NULL, node_writer_expires_at=NULL, node_writer_ttl_ms=NULL, updated_at=${this.now()} WHERE slug=${slug} AND node_writer_holder=${holder}`
+    })
+  }
   async claimLease(slug: string, holder: string, ttlMs: number): Promise<boolean> {
     return this.claim('builds', slug, holder, ttlMs)
   }
@@ -923,10 +997,13 @@ export class PostgresBuildStore implements BuildStore {
   }
 
   async getRepo(repo: string): Promise<RepositoryRecord | null> {
-    return this.run(async (q) => {
-      const rows: Row[] = await q`SELECT * FROM repo_streams WHERE repo=${repo}`
-      return rows[0] ? this.repoRecord(rows[0]) : null
-    })
+    return repositoryRead(this, repo, () =>
+      this.run(async (q) => {
+        const rows: Row[] = await q`SELECT * FROM repo_streams WHERE repo=${repo}`
+        recordRepositoryExistence(this, repo, !!rows[0])
+        return rows[0] ? this.repoRecord(rows[0]) : null
+      }),
+    )
   }
 
   private async appendRepoLocked(
@@ -1019,8 +1096,8 @@ export class PostgresBuildStore implements BuildStore {
     sinceSeq = 0,
     opts?: { waitSeconds?: number; signal?: AbortSignal },
   ): Promise<RepositoryEvent[]> {
+    if (!(await this.getRepo(repo))) throw new Error(`unknown repo "${repo}"`)
     const read = async (): Promise<RepositoryEvent[]> => {
-      if (!(await this.getRepo(repo))) throw new Error(`unknown repo "${repo}"`)
       const rows: Row[] = await this.run(
         (q) => q`SELECT * FROM repo_events WHERE repo=${repo} AND seq>${sinceSeq} ORDER BY seq`,
       )
@@ -1123,6 +1200,19 @@ export class PostgresBuildStore implements BuildStore {
 
   private async valueTail(scope: SnapshotScope): Promise<number | undefined> {
     const key = scope.kind === 'build' ? scope.slug : scope.repo
+    if (scope.kind === 'repo' && hasRepositoryReadContext()) {
+      if (knownRepositoryExists(this, key) === false) return undefined
+      const rows: Row[] = await this.run(
+        (q) => q`SELECT COALESCE(MAX(seq),0) AS tail FROM repo_events WHERE repo=${key}`,
+      )
+      const tail = num(rows[0]?.tail ?? 0)
+      // A nonempty journal proves its FK parent exists, without an unlocked
+      // record read before a delegated harvest mutation takes its own lock.
+      if (tail > 0) recordRepositoryExistence(this, key, true)
+      else if (knownRepositoryExists(this, key) === undefined && !(await this.getRepo(key)))
+        return undefined
+      return tail
+    }
     const rows: Row[] =
       scope.kind === 'build'
         ? await this.run(
@@ -1143,6 +1233,10 @@ export class PostgresBuildStore implements BuildStore {
   ): Promise<ReducerSnapshot | null> {
     assertPublicSnapshotReducer(reducer)
     const key = scope.kind === 'build' ? scope.slug : scope.repo
+    const repoExists =
+      scope.kind === 'repo' && hasRepositoryReadContext()
+        ? (knownRepositoryExists(this, key) ?? (await this.getRepo(key)) !== null)
+        : undefined
     try {
       const rows: Row[] = await this.run(
         (q) => q`SELECT s.version, s.cursor, s.state FROM reducer_snapshots s
@@ -1153,7 +1247,11 @@ export class PostgresBuildStore implements BuildStore {
               ELSE COALESCE((SELECT MAX(seq) FROM repo_events WHERE repo=${key}), 0) END
             AND CASE WHEN ${scope.kind}='build'
               THEN EXISTS (SELECT 1 FROM builds WHERE slug=${key})
-              ELSE EXISTS (SELECT 1 FROM repo_streams WHERE repo=${key}) END`,
+              ELSE ${
+                repoExists === undefined
+                  ? this.sql`EXISTS (SELECT 1 FROM repo_streams WHERE repo=${key})`
+                  : this.sql`${repoExists}::boolean`
+              } END`,
       )
       const row = rows[0]
       if (row === undefined) return null
@@ -1180,9 +1278,14 @@ export class PostgresBuildStore implements BuildStore {
   ): Promise<boolean> {
     const key = scope.kind === 'build' ? scope.slug : scope.repo
     const state = JSON.stringify(snapshot.state ?? null)
+    const repoExists =
+      scope.kind === 'repo' && hasRepositoryReadContext()
+        ? (knownRepositoryExists(this, key) ?? (await this.getRepo(key)) !== null)
+        : undefined
     try {
-      // One statement: the existence and log-tail guards, and the
-      // never-decrease rule, evaluate atomically against concurrent writers.
+      // Tail bounds and never-decrease guards remain atomic. Outside a request
+      // the existence guard is atomic too; request-scoped reuse is safe because
+      // repository journals have no deletion API.
       const rows: Row[] = await this.run(
         (q) => q`INSERT INTO reducer_snapshots
             (scope_kind, scope_key, reducer, version, cursor, state, updated_at)
@@ -1193,7 +1296,11 @@ export class PostgresBuildStore implements BuildStore {
               ELSE COALESCE((SELECT MAX(seq) FROM repo_events WHERE repo=${key}), 0) END
             AND CASE WHEN ${scope.kind}='build'
               THEN EXISTS (SELECT 1 FROM builds WHERE slug=${key})
-              ELSE EXISTS (SELECT 1 FROM repo_streams WHERE repo=${key}) END
+              ELSE ${
+                repoExists === undefined
+                  ? this.sql`EXISTS (SELECT 1 FROM repo_streams WHERE repo=${key})`
+                  : this.sql`${repoExists}::boolean`
+              } END
           ON CONFLICT (scope_kind, scope_key, reducer) DO UPDATE SET
             version = EXCLUDED.version, cursor = EXCLUDED.cursor,
             state = EXCLUDED.state, updated_at = EXCLUDED.updated_at

package/src/tickets.ts

@@ -79,6 +79,7 @@ export async function openPostgresTicketDatabase(url: string): Promise<PostgresT
 
 export class PostgresTicketSource implements TicketSource {
   readonly name = 'database'
+  readonly integrationTree = true
   private readonly teamKey: string
   private readonly repo: string
   private readonly claimedState: string
@@ -178,6 +179,14 @@ export class PostgresTicketSource implements TicketSource {
       ...(row.creation_key !== null && row.creation_key !== undefined
         ? { creationKey: String(row.creation_key) }
         : {}),
+      kind: row.kind === 'node' ? 'node' : 'work',
+      ...(row.target_id == null
+        ? {}
+        : {
+            target: String(
+              (await this.require(executor, String(row.target_id), 'target')).readable_id,
+            ),
+          }),
       title,
       body: String(row.body),
       state: String(row.state),
@@ -200,6 +209,49 @@ export class PostgresTicketSource implements TicketSource {
     return row
   }
 
+  listAll(): Promise<TicketListing> {
+    return this.listReady({})
+  }
+
+  // Creates and metadata mutations take this project lock before any ticket row
+  // lock, so ancestor validation cannot race reparenting or node demotion.
+  private async graphLock(q: Exec): Promise<void> {
+    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`
+  }
+
+  private async tree(
+    q: Exec,
+    row: Row | undefined,
+    patch: TicketDraft | TicketUpdate,
+  ): Promise<string | null> {
+    if (patch.kind !== undefined && patch.kind !== 'work' && patch.kind !== 'node')
+      throw new Error('kind must be work or node')
+    if (typeof patch.target === 'string' && !patch.target.trim())
+      throw new Error('target must not be blank')
+    if (row && row.kind === 'node' && patch.kind === 'work') {
+      const children: Row[] =
+        await q`SELECT readable_id FROM ab_tickets WHERE repo = ${this.repo} AND target_id = ${String(row.id)} LIMIT 1`
+      if (children.length)
+        throw new Error(`cannot demote node: ticket ${children[0]!.readable_id} targets it`)
+    }
+    if (patch.target === undefined) return row?.target_id == null ? null : String(row.target_id)
+    if (patch.target === null) return null
+    const seen = new Set(row ? [String(row.id)] : [])
+    let next: string | null = patch.target
+    let target: string | null = null
+    while (next !== null) {
+      const ancestor = await this.require(q, next, 'target')
+      if (ancestor.kind !== 'node') throw new Error(`target ${next} is not a node`)
+      const key = String(ancestor.id)
+      if (seen.has(key)) throw new Error(`target ${next} would create a cycle`)
+      seen.add(key)
+      target ??= key
+      next = ancestor.target_id == null ? null : String(ancestor.target_id)
+    }
+    return target
+  }
+
   async listReady(criteria: { labels?: string[]; state?: string }): Promise<TicketListing> {
     const labels = criteria.labels ?? []
     return this.retry.tx(this.sql, async (q) => {
@@ -280,13 +332,13 @@ export class PostgresTicketSource implements TicketSource {
       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`
+      await this.graphLock(q)
       if (options.idempotencyKey !== undefined) {
         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 target = await this.tree(q, undefined, draft)
       const state = await this.state(q, options.state ?? this.createState)
       const blockers: string[] = []
       for (const blocker of draft.blockedBy ?? []) {
@@ -310,9 +362,9 @@ export class PostgresTicketSource implements TicketSource {
       const id = `ticket-${crypto.randomUUID()}`
       const now = new Date().toISOString()
       const inserted: Row[] = await q`INSERT INTO ab_tickets
-        (repo, id, readable_id, ticket_number, creation_key, title, body, state, labels, created_at, updated_at)
+        (repo, id, readable_id, ticket_number, creation_key, title, body, state, labels, created_at, updated_at, kind, target_id)
         VALUES (${this.repo}, ${id}, ${readable}, ${number}::bigint, ${options.idempotencyKey ?? null}, ${draft.title}, ${draft.body},
-          ${state}, ${q.array(draft.labels ?? [], 'text')}, ${now}, ${now})
+          ${state}, ${q.array(draft.labels ?? [], 'text')}, ${now}, ${now}, ${draft.kind ?? 'work'}, ${target})
         ON CONFLICT (repo, creation_key) DO NOTHING RETURNING *, revision::text AS revision`
       let row = inserted[0]
       if (!row && options.idempotencyKey !== undefined) {
@@ -353,6 +405,7 @@ export class PostgresTicketSource implements TicketSource {
   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) => {
+      if (patch && (patch.kind !== undefined || patch.target !== undefined)) await this.graphLock(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)
@@ -361,16 +414,20 @@ export class PostgresTicketSource implements TicketSource {
         throw new TicketRevisionConflict(id, expected, revision)
       let changed = false
       if (patch) {
+        const target = await this.tree(q, row, patch)
+        const kind = patch.kind ?? String(row.kind)
         const title = patch.title ?? String(row.title)
         const body = patch.body ?? String(row.body)
         const labels = patch.labels ?? strings(row.labels)
         changed =
+          kind !== row.kind ||
+          target !== row.target_id ||
           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}`
+          await q`UPDATE ab_tickets SET kind = ${kind}, target_id = ${target}, 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)