@owlmeans/planning-postgres 0.1.18-rc.0

package/src/store/transitions.ts

@@ -0,0 +1,221 @@
+import { CommitState, PlanningError, WorkcardConflict } from '@owlmeans/planning'
+import type { Transition, TransitionCommit, TransitionStore, TransitionWhere } from '@owlmeans/planning'
+import type { Criteria, ListResult, Sort } from '@owlmeans/resource'
+import { cleanRecord, col, insertOf, pgFault, recordOf, UNIQUE_VIOLATION, whereOf } from '../sql.js'
+import type { SqlContext } from '../sql.js'
+import type { PlanningTransitionResource } from '../types.js'
+
+const clean = <T extends object>(record: T): T =>
+  Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as T
+
+/** The portable criteria of a transition query — what a resource list reads the log with. */
+export const transitionCriteria = (where: TransitionWhere): Criteria<Transition> => clean({
+  entityId: where.entityId,
+  card: where.card,
+  project: where.project,
+  seq: where.sinceSeq != null ? { $gt: where.sinceSeq } : undefined,
+  'commit.state': where.state,
+  action: where.action,
+}) as Criteria<Transition>
+
+export const transitionOf = (row: Record<string, unknown>, sql: SqlContext): Transition =>
+  recordOf<Transition>(row, sql.tables.transition)
+
+export const readTransition = async (sql: SqlContext, id: string): Promise<Transition | null> => {
+  const spec = sql.tables.transition
+  const rows = await sql.runner.query(`SELECT * FROM ${spec.qualified} WHERE ${col(spec, 'id')} = $1`, [id])
+  return rows[0] == null ? null : transitionOf(rows[0], sql)
+}
+
+export const readTransitionByKey = async (sql: SqlContext, entityId: string, key: string): Promise<Transition | null> => {
+  const spec = sql.tables.transition
+  const rows = await sql.runner.query(
+    `SELECT * FROM ${spec.qualified} WHERE ${col(spec, 'entityId')} = $1 AND ${col(spec, 'key')} = $2`, [entityId, key]
+  )
+  return rows[0] == null ? null : transitionOf(rows[0], sql)
+}
+
+/**
+ * The log of one card (or several) in `seq` order, as a fold reads it: this package's own statement,
+ * so it runs inside a fold's transaction. `size` bounds it (0 is no limit); `total` tells a bounded
+ * read that more remain.
+ */
+export const listTransitions = async (
+  sql: SqlContext, where: TransitionWhere, size: number = 0
+): Promise<ListResult<Transition>> => {
+  const spec = sql.tables.transition
+  const fixed = whereOf(spec, {
+    entityId: where.entityId,
+    card: where.card,
+    project: where.project,
+    action: where.action as string | string[] | undefined,
+  })
+  const params = [...fixed.params]
+  const clauses = [fixed.text]
+  if (where.sinceSeq != null) {
+    params.push(where.sinceSeq)
+    clauses.push(`${col(spec, 'seq')} > $${params.length}`)
+  }
+  if (where.state != null) {
+    params.push(where.state)
+    clauses.push(`(${col(spec, 'commit')}->>'state') = $${params.length}`)
+  }
+  const limit = size > 0 ? ` LIMIT ${Math.floor(size) + 1}` : ''
+  const rows = await sql.runner.query(
+    `SELECT * FROM ${spec.qualified} WHERE ${clauses.join(' AND ')} ORDER BY ${col(spec, 'seq')}, ${col(spec, 'id')}${limit}`, params
+  )
+  const items = rows.map(row => transitionOf(row, sql))
+
+  return size > 0 && items.length > size ? { items: items.slice(0, size), total: items.length } : { items, total: items.length }
+}
+
+export const commitTransition = async (sql: SqlContext, id: string, commit: TransitionCommit): Promise<void> => {
+  const spec = sql.tables.transition
+  await sql.runner.query(
+    `UPDATE ${spec.qualified} SET ${col(spec, 'commit')} = $2::jsonb WHERE ${col(spec, 'id')} = $1`, [id, JSON.stringify(clean(commit))]
+  )
+}
+
+/**
+ * Allocate the next seq — a compare-and-set of `head` on the card row, stamping `headAt`. A card
+ * whose create has not folded yet has no row to count on: it allocates `max(seq) + 1` from the log
+ * and lets the unique `(card, seq)` index refuse a repeat.
+ *
+ * @throws {WorkcardConflict}
+ */
+export const allocateSeq = async (
+  sql: SqlContext, card: string, expect: number | null | undefined, at: string
+): Promise<number> => {
+  const cards = sql.tables.card
+  const head = col(cards, 'head')
+  const seq = col(cards, 'seq')
+  const guarded = expect != null
+  const allocated = await sql.runner.query<{ head: number }>(
+    `UPDATE ${cards.qualified} SET ${head} = COALESCE(${head}, ${seq}) + 1, ${col(cards, 'headAt')} = $2`
+    + ` WHERE ${col(cards, 'id')} = $1${guarded ? ` AND COALESCE(${head}, ${seq}) = $3` : ''} RETURNING ${head} AS head`,
+    guarded ? [card, at, expect] : [card, at]
+  )
+  if (allocated[0] != null) {
+    return Number(allocated[0].head)
+  }
+  const existing = await sql.runner.query<{ head: number }>(
+    `SELECT COALESCE(${head}, ${seq}) AS head FROM ${cards.qualified} WHERE ${col(cards, 'id')} = $1`, [card]
+  )
+  if (existing[0] != null) {
+    throw new WorkcardConflict(`${card}:expected:${expect}:head:${existing[0].head}`)
+  }
+  const last = await lastSeq(sql, card)
+  if (guarded && expect !== last) {
+    throw new WorkcardConflict(`${card}:expected:${expect}:head:${last}`)
+  }
+
+  return last + 1
+}
+
+export const lastSeq = async (sql: SqlContext, card: string): Promise<number> => {
+  const spec = sql.tables.transition
+  const rows = await sql.runner.query<{ last: number }>(
+    `SELECT COALESCE(MAX(${col(spec, 'seq')}), 0) AS last FROM ${spec.qualified} WHERE ${col(spec, 'card')} = $1`, [card]
+  )
+  return Number(rows[0]?.last ?? 0)
+}
+
+/** Give an allocation back when its append failed and nothing was allocated after it. */
+const releaseSeq = async (sql: SqlContext, card: string, seq: number): Promise<void> => {
+  const cards = sql.tables.card
+  await sql.runner.query(
+    `UPDATE ${cards.qualified} SET ${col(cards, 'head')} = $2 - 1 WHERE ${col(cards, 'id')} = $1 AND ${col(cards, 'head')} = $2`,
+    [card, seq]
+  )
+}
+
+export interface TransitionPortDeps {
+  sql: () => Promise<SqlContext>
+  resource: () => PlanningTransitionResource
+  ids: () => string
+  now: () => string
+  /** The card-seq and entity-key unique index names — how a violation is told apart. */
+  indexes: () => Promise<{ cardSeq: string, entityKey: string }>
+}
+
+/**
+ * The log port. `append` is idempotent on its id; a lost race on the key releases the allocation
+ * and answers `PlanningError('duplicate-key')` (the executor then answers the winner's receipt); a
+ * lost race on `(card, seq)` — an allocation the fold gave up for lost and filled with a failed
+ * placeholder — re-allocates once and lands after it, then refuses with `WorkcardConflict`.
+ */
+export const makeTransitionPort = (deps: TransitionPortDeps): TransitionStore => {
+  const insert = async (sql: SqlContext, transition: Transition): Promise<Transition> => {
+    const statement = insertOf(sql.tables.transition, transition as unknown as Record<string, unknown>, { tail: 'RETURNING *' })
+    const rows = await sql.runner.query(statement.text, statement.params)
+    return transitionOf(rows[0], sql)
+  }
+
+  const store: TransitionStore = {
+    append: async transition => {
+      const sql = await deps.sql()
+      const indexes = await deps.indexes()
+      let current: Transition = {
+        ...transition, id: transition.id ?? deps.ids(), commit: transition.commit ?? { state: CommitState.Pending },
+      }
+      for (let attempt = 0; ; attempt++) {
+        try {
+          return await insert(sql, current)
+        } catch (error) {
+          const fault = pgFault(error)
+          if (fault.code !== UNIQUE_VIOLATION) {
+            await releaseSeq(sql, current.card, current.seq).catch(() => undefined)
+            throw error
+          }
+          if (fault.constraint === indexes.entityKey) {
+            await releaseSeq(sql, current.card, current.seq)
+            throw new PlanningError(`duplicate-key:${current.key}`)
+          }
+          if (fault.constraint === indexes.cardSeq) {
+            if (attempt === 0 && current.seq > 1) {
+              current = { ...current, seq: await allocateSeq(sql, current.card, null, deps.now()) }
+              continue
+            }
+            throw new WorkcardConflict(`${current.card}:seq:${current.seq}`)
+          }
+          const existing = await readTransition(sql, current.id!)
+          if (existing != null) {
+            return existing
+          }
+          throw error
+        }
+      }
+    },
+
+    get: async id => await readTransition(await deps.sql(), id),
+
+    byKey: async (entityId, key) => await readTransitionByKey(await deps.sql(), entityId, key),
+
+    list: async (where, opts) => {
+      await deps.sql()
+      const sort: Sort<Transition>[] = opts?.sort ?? (typeof where.card === 'string' ? ['seq'] : ['at', 'seq'])
+      const listed = await deps.resource().list(transitionCriteria(where), { ...opts, sort })
+      return { ...listed, items: listed.items.map(item => cleanRecord(item)) }
+    },
+
+    nextSeq: async (card, expect) => await allocateSeq(await deps.sql(), card, expect, deps.now()),
+
+    head: async card => {
+      const sql = await deps.sql()
+      const cards = sql.tables.card
+      const rows = await sql.runner.query<{ head: number }>(
+        `SELECT COALESCE(${col(cards, 'head')}, ${col(cards, 'seq')}) AS head FROM ${cards.qualified} WHERE ${col(cards, 'id')} = $1`, [card]
+      )
+      return rows[0] != null ? Number(rows[0].head) : await lastSeq(sql, card)
+    },
+
+    commit: async (id, commit) => { await commitTransition(await deps.sql(), id, commit) },
+
+    purge: async where => {
+      await deps.sql()
+      return await deps.resource().purge(transitionCriteria(where))
+    },
+  }
+
+  return store
+}

package/src/types.ts

@@ -0,0 +1,73 @@
+import type { BasicContext } from '@owlmeans/context'
+import type {
+  ProjectionStore, Relationship, RelationshipStore, SchemaStore, ScopedSchemaRecord, SpecificationStore,
+  Transition, TransitionStore, Workcard,
+} from '@owlmeans/planning'
+import type { PostgresResource } from '@owlmeans/postgres-resource'
+import type {
+  BindablePlanningStore, CommitHub, FoldResult, PlanningServiceOptions,
+} from '@owlmeans/server-planning'
+import type { DEFAULT_PLANNING_POSTGRES_LIMITS } from './consts.js'
+
+export type PlanningPostgresLimits = { -readonly [K in keyof typeof DEFAULT_PLANNING_POSTGRES_LIMITS]: number }
+
+/** The resource aliases the store resolves its four tables by. */
+export interface PlanningPostgresAliases {
+  card: string
+  transition: string
+  link: string
+  schema: string
+}
+
+export interface PlanningPostgresOptions {
+  aliases?: Partial<PlanningPostgresAliases>
+  /**
+   * NOTIFY every settled commit and schema write on the store's channel, and LISTEN for other
+   * processes' (default `true`). `false` leaves a waiter to its poll and a reader to the revision.
+   */
+  bus?: boolean
+  limits?: Partial<PlanningPostgresLimits>
+  /** Card and transition ids. */
+  ids?: () => string
+  /** ISO-8601 timestamps. */
+  now?: () => string
+}
+
+export interface PostgresPlanningStoreOptions extends PlanningPostgresOptions {
+  /** The context the four resources are registered on — read at call time, never at construction. */
+  context: () => BasicContext<any> | undefined
+}
+
+/** A card row: the record, plus the allocation bookkeeping no caller ever sees. */
+export interface PlanningCardRecord extends Workcard {
+  /** When `head` last moved — how old a gap in the card's log is. Private to the store. */
+  headAt?: string
+}
+
+/** A schema row: a record, or the private per-organization revision counter (`kind: 'head'`). */
+export type PlanningSchemaRow = Omit<ScopedSchemaRecord, 'kind'> & { kind: ScopedSchemaRecord['kind'] | 'head' }
+
+export interface PlanningCardResource extends PostgresResource<PlanningCardRecord> { }
+export interface PlanningTransitionResource extends PostgresResource<Transition> { }
+export interface PlanningLinkResource extends PostgresResource<Relationship> { }
+export interface PlanningSchemaResource extends PostgresResource<PlanningSchemaRow> { }
+
+export interface PostgresPlanningStore extends BindablePlanningStore {
+  transitions: TransitionStore
+  cards: ProjectionStore
+  specs: SpecificationStore
+  links: RelationshipStore
+  commits: CommitHub
+  schemas: SchemaStore
+  /**
+   * Fold what is pending for one card — one transaction under its advisory lock, the settled
+   * events delivered after the commit.
+   */
+  fold: (cardId: string) => Promise<FoldResult>
+  /** Fold every card whose oldest pending row is older than `olderThanMs`. Answers how many. */
+  recover: (opts?: { olderThanMs?: number, limit?: number }) => Promise<number>
+  /** Release the LISTEN connection and stop healing. */
+  close: () => Promise<void>
+}
+
+export interface PostgresPlanningServiceOptions extends Omit<PlanningServiceOptions, 'store'>, PlanningPostgresOptions { }

package/tests/bus.spec.ts

@@ -0,0 +1,142 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { uuid } from '@owlmeans/basic-ids'
+import { CommitState, IntrinsicStatus, TransitionAction, WorkcardKind } from '@owlmeans/planning'
+import type { CommitEvent, Transition } from '@owlmeans/planning'
+import { createBook, createBranch, LIBRARY } from '@owlmeans/server-planning/conformance'
+
+import type { Booted } from './context.js'
+import { eventually, gate, makeSuite } from './context.js'
+
+/**
+ * Two (and three) processes over one schema — each a booted context of its own, exactly as two
+ * replicas share a database. A lending library's branches and books travel between them.
+ */
+const suite = makeSuite('bus')
+const it = gate.skip ? test.skip : test
+
+describe('@owlmeans/planning-postgres — the commit bus', () => {
+  if (gate.skip) {
+    test.skip(gate.reason ?? 'postgres gate closed', () => {})
+
+    return
+  }
+
+  let first: Booted
+  let second: Booted
+  let silent: Booted
+
+  beforeAll(async () => {
+    first = await suite.boot()
+    second = await suite.boot()
+    silent = await suite.boot({ bus: false })
+  })
+
+  afterAll(async () => {
+    await suite.teardown()
+  })
+
+  const pendingRow = (org: string, card: string, seq: number): Transition => ({
+    entityId: org, card, kind: WorkcardKind.Card, type: LIBRARY.book, seq, action: TransitionAction.Update,
+    changes: { title: `Edition ${seq}` }, actor: {}, at: new Date().toISOString(), commit: { state: CommitState.Pending },
+  })
+
+  it('another process hears a commit; a process hears its own exactly once', async () => {
+    const org = `library-${uuid()}`
+    const heard: CommitEvent[] = []
+    const unsubscribe = await first.facade(org).commits.subscribe(event => { heard.push(event) })
+    try {
+      const branch = await createBranch(second.facade(org))
+      // The LISTEN connection opens with the first subscription; write until it carries a frame.
+      await eventually(async () => {
+        if (heard.some(event => event.card === branch.id)) {
+          return true
+        }
+        await second.facade(org).execute({ card: branch.id!, action: TransitionAction.Transit, transition: 'activate' }).catch(() => undefined)
+        return heard.some(event => event.card === branch.id)
+      })
+      const remote = heard.find(event => event.card === branch.id)!
+      expect(remote.record).toBeUndefined()
+      expect(remote.entityId).toBe(org)
+
+      const own = await createBook(first.facade(org), branch.id!)
+      const receipt = (await first.facade(org).transitions.list({ card: own.id!, size: 0 })).items[0]
+      expect(heard.filter(event => event.transition === receipt.id)).toHaveLength(1)
+      expect(heard.find(event => event.transition === receipt.id)?.record?.id).toBe(own.id)
+    } finally {
+      unsubscribe()
+    }
+  })
+
+  it('concurrent writers in two processes each commit once, and the card folds every one', async () => {
+    const org = `library-${uuid()}`
+    const book = await createBook(first.facade(org), (await createBranch(first.facade(org))).id!)
+    const writes = Array.from({ length: 24 }, (_, index) => (index % 2 === 0 ? first : second).facade(org)
+      .execute({ card: book.id!, action: TransitionAction.Update, changes: { fields: { signed: index % 3 === 0 } } }))
+    const receipts = await Promise.all(writes)
+
+    const settled = await Promise.all(receipts.map(receipt => receipt.committed({ timeout: 15_000 })))
+    expect(settled.every(card => card != null)).toBe(true)
+    const log = (await first.facade(org).transitions.list({ card: book.id!, size: 0 })).items
+    const states = log.filter(entry => entry.action === TransitionAction.Update).map(entry => entry.commit.state)
+    expect(states.filter(state => state === CommitState.Committed).length + states.filter(state => state === CommitState.Failed).length)
+      .toBe(states.length)
+    const card = await first.facade(org).cards.get(book.id!)
+    expect([card.seq, card.head]).toEqual([log.at(-1)!.seq, log.at(-1)!.seq])
+    // Every write that landed a row is committed: no transient gap turned into a failure.
+    expect(receipts.every(receipt => log.find(entry => entry.id === receipt.transition.id)?.commit.state === CommitState.Committed)).toBe(true)
+  }, 30_000)
+
+  it('a waiter in one process is answered when another process folds', async () => {
+    const org = `library-${uuid()}`
+    const book = await createBook(second.facade(org), (await createBranch(second.facade(org))).id!)
+    const row = await second.store.transitions.append(pendingRow(org, book.id!, await second.store.transitions.nextSeq(book.id!, null)))
+
+    const waiting = first.facade(org).commits.wait(row.id!, { timeout: 8_000 })
+    await second.store.cards.project(book.id!)
+
+    expect((await waiting)?.title).toBe(`Edition ${row.seq}`)
+  })
+
+  it('a schema write in one process reaches the watchers of another', async () => {
+    const org = `library-${uuid()}`
+    const heard: string[] = []
+    const unwatch = first.store.schemas.watch!(entityId => { heard.push(entityId) })
+    try {
+      await eventually(async () => {
+        await second.facade(org).definitions!.define({
+          flows: [{ id: `library:shelving-${uuid()}`, version: 1, statuses: [{ key: 'open', intrinsic: IntrinsicStatus.Planned }], transitions: [] }],
+        })
+        return heard.includes(org)
+      })
+      expect(heard).toContain(org)
+    } finally {
+      unwatch()
+    }
+  })
+
+  it('without the bus nothing is sent or heard, and a wait still resolves by polling', async () => {
+    const org = `library-${uuid()}`
+    const quiet: CommitEvent[] = []
+    const loud: CommitEvent[] = []
+    const releaseQuiet = await silent.facade(org).commits.subscribe(event => { quiet.push(event) })
+    const releaseLoud = await first.facade(org).commits.subscribe(event => { loud.push(event) })
+    try {
+      const branch = await createBranch(second.facade(org), 'Heard by the loud one')
+      await eventually(() => loud.some(event => event.card === branch.id))
+      const unheard = await createBranch(silent.facade(org), 'Never announced')
+      await new Promise(resolve => setTimeout(resolve, 300))
+
+      expect(quiet.some(event => event.card === branch.id)).toBe(false)
+      expect(loud.some(event => event.card === unheard.id)).toBe(false)
+
+      const book = await createBook(second.facade(org), branch.id!)
+      const row = await second.store.transitions.append(pendingRow(org, book.id!, await second.store.transitions.nextSeq(book.id!, null)))
+      const waiting = silent.facade(org).commits.wait(row.id!, { timeout: 8_000 })
+      await second.store.cards.project(book.id!)
+      expect((await waiting)?.title).toBe(`Edition ${row.seq}`)
+    } finally {
+      releaseQuiet()
+      releaseLoud()
+    }
+  }, 15_000)
+})

package/tests/conformance.spec.ts

@@ -0,0 +1,37 @@
+import { afterAll, beforeAll, describe, test } from 'bun:test'
+import { planningConformance } from '@owlmeans/server-planning/conformance'
+import type { ConformanceSubject } from '@owlmeans/server-planning/conformance'
+
+import type { Booted } from './context.js'
+import { gate, makeSuite } from './context.js'
+
+/**
+ * The store conformance suite of `@owlmeans/server-planning`, against a real database: the same
+ * cases the memory store answers, every one of them — the Postgres store implements the schema port.
+ * Each case works in its own organization, so one booted context serves them all.
+ */
+const suite = makeSuite('conformance')
+
+describe('@owlmeans/planning-postgres — store conformance', () => {
+  if (gate.skip) {
+    test.skip(gate.reason ?? 'postgres gate closed', () => {})
+
+    return
+  }
+
+  let booted: Booted
+  let subject: ConformanceSubject
+
+  beforeAll(async () => {
+    booted = await suite.boot()
+    subject = { service: booted.service, store: booted.store, facade: booted.facade }
+  })
+
+  afterAll(async () => {
+    await suite.teardown()
+  })
+
+  for (const entry of planningConformance) {
+    test(entry.name, async () => { await entry.run(subject) }, 20_000)
+  }
+})

package/tests/context.ts

@@ -0,0 +1,143 @@
+import { postgresGate, randomNamespace } from '@owlmeans/test-integration'
+import type { IntegrationGate, PostgresEnv } from '@owlmeans/test-integration'
+import { PgAutoSync } from '@owlmeans/postgres-resource'
+import { config, makeServerContext } from '@owlmeans/server-context'
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import type { PlanningFacade, PlanningPlugin } from '@owlmeans/planning'
+import type { PlanningHostService } from '@owlmeans/server-planning'
+import { conformanceClock, planningConformancePlugin } from '@owlmeans/server-planning/conformance'
+import { Pool } from 'pg'
+
+import { appendPostgres } from '@owlmeans/postgres'
+import type { PostgresService } from '@owlmeans/postgres'
+
+import {
+  appendPostgresPlanning, makePlanningCardPostgres, makePlanningLinkPostgres, makePlanningSchemaPostgres,
+  makePlanningTransitionPostgres, makePostgresPlanningService,
+} from '../src/index.js'
+import type { PlanningPostgresLimits, PostgresPlanningStore } from '../src/index.js'
+
+/**
+ * Env-gated integration harness, the shape `@owlmeans/marketing-consent-postgres` uses: a real
+ * `ServerContext` per boot against a throwaway schema, dropped in `teardown()`. Specs skip cleanly
+ * when `POSTGRES_URL` is unset or nothing answers at it.
+ */
+export const gate: IntegrationGate<PostgresEnv> = postgresGate()
+
+const url = (): string => gate.env.POSTGRES_URL as string
+
+export const raw = async <R>(fn: (pool: Pool) => Promise<R>): Promise<R> => {
+  const pool = new Pool({ connectionString: url(), max: 1 })
+  try {
+    return await fn(pool)
+  } finally {
+    await pool.end().catch(() => undefined)
+  }
+}
+
+export interface BootOptions {
+  limits?: Partial<PlanningPostgresLimits>
+  bus?: boolean
+  plugins?: PlanningPlugin[]
+  /** `files` registers each resource the way a target's `resources/planning/*.ts` does; `append` uses `appendPostgresPlanning`. */
+  wiring?: 'files' | 'append' | 'none'
+}
+
+export interface Booted {
+  context: ServerContext<ServerConfig>
+  pg: PostgresService
+  service: PlanningHostService
+  store: PostgresPlanningStore
+  facade: (entityId: string) => PlanningFacade
+}
+
+export interface Suite {
+  schema: string
+  boot: (opts?: BootOptions) => Promise<Booted>
+  teardown: () => Promise<void>
+}
+
+export const makeSuite = (label: string): Suite => {
+  const prefix = process.env.POSTGRES_TEST_DB_PREFIX ?? 'omt'
+  const schema = randomNamespace(`${prefix}_${label}`)
+  const pools: Pool[] = []
+  const stores: PostgresPlanningStore[] = []
+
+  const boot = async (opts: BootOptions = {}): Promise<Booted> => {
+    const cfg: ServerConfig = config('planning-pg-test', {
+      dbs: [{
+        service: 'postgres', alias: 'postgres', host: '127.0.0.1', schema,
+        meta: { url: url(), max: 4, retries: 3, retryDelayMillis: 200, autoSync: PgAutoSync.Full },
+      }],
+    } as Partial<ServerConfig>)
+
+    const context = makeServerContext(cfg) as ServerContext<ServerConfig>
+    appendPostgres(context)
+    const serviceOptions = {
+      plugins: opts.plugins ?? [planningConformancePlugin],
+      now: conformanceClock(),
+      ...(opts.limits != null ? { limits: opts.limits } : {}),
+      ...(opts.bus != null ? { bus: opts.bus } : {}),
+    }
+    if (opts.wiring === 'append') {
+      appendPostgresPlanning(context, serviceOptions)
+    } else {
+      if (opts.wiring !== 'none') {
+        for (const make of [makePlanningCardPostgres, makePlanningTransitionPostgres, makePlanningLinkPostgres, makePlanningSchemaPostgres]) {
+          context.registerResource(make())
+        }
+      }
+      context.registerService(makePostgresPlanningService(serviceOptions))
+    }
+
+    context.configure()
+    const pg = context.service<PostgresService>('postgres')
+    try {
+      await context.init()
+    } finally {
+      for (const pool of Object.values(pg.clients ?? {})) {
+        if (!pools.includes(pool)) {
+          pools.push(pool)
+        }
+      }
+    }
+    const service = context.service<PlanningHostService>('planning')
+    const store = service.store() as PostgresPlanningStore
+    stores.push(store)
+
+    return {
+      context,
+      pg,
+      service,
+      store,
+      facade: entityId => service.for({ entityId, profileId: 'librarian', channel: 'test' }),
+    }
+  }
+
+  const teardown = async (): Promise<void> => {
+    if (gate.skip) {
+      return
+    }
+    for (const store of stores.splice(0)) {
+      await store.close().catch(() => undefined)
+    }
+    await raw(async pool => { await pool.query(`DROP SCHEMA IF EXISTS "${schema}" CASCADE`) })
+      .catch(error => console.error(`planning-postgres test teardown (${schema}):`, error))
+    while (pools.length > 0) {
+      await pools.pop()?.end().catch(() => undefined)
+    }
+  }
+
+  return { schema, boot, teardown }
+}
+
+/** Wait until `check` answers true, polling — for what another process's delivery settles. */
+export const eventually = async (check: () => boolean | Promise<boolean>, timeout: number = 5_000): Promise<void> => {
+  const deadline = Date.now() + timeout
+  while (!await check()) {
+    if (Date.now() > deadline) {
+      throw new Error('eventually: timed out')
+    }
+    await new Promise(resolve => setTimeout(resolve, 25))
+  }
+}