pipework 0.252.0 → 0.252.1

package/src/trace/external/record.ts

@@ -0,0 +1,195 @@
+// `trace.traceparent`, `trace.env` and `trace.record`: carry the current trace
+// to a process outside Node, stage the steps it reports back, and mark point events.
+
+import { randomUUID } from 'node:crypto'
+import { getContext } from '../../request/context/store.js'
+import { getBaseLogger } from '../../core/logging/index.js'
+import { recordFault, faultMessage } from '../../infra/alerts/faults.js'
+import { emitReadTouches } from '../../data/write/audit/read-touches.js'
+import { serializeForTrace } from '../capture/bounded-serializer.js'
+import { projectStepError } from '../runtime/step-error.js'
+import type { BegunStep } from '../runtime/step-buffer.js'
+import {
+  externalStepNameSchema,
+  externalStepReportSchema,
+  parseReportTime,
+  type ExternalRecordResult,
+  type ExternalStepReport,
+} from './report.js'
+
+const NONE: ExternalRecordResult = { recorded: 0, invalid: 0, dropped: 0 }
+
+/** W3C `traceparent` for the current trace and open step, or `null` outside a traced flow or once the trace is truncated. */
+export function traceparent(): string | null {
+  const ctx = getContext()?.trace
+  if (ctx === undefined || ctx === null || ctx.buffer.truncated) return null
+  const traceHex = ctx.id.replaceAll('-', '')
+  const spanSource = (ctx.buffer.openStepId ?? ctx.id).replaceAll('-', '')
+  return `00-${traceHex}-${spanSource.slice(-16)}-01`
+}
+
+/** `{ TRACEPARENT }` for a child process's environment, or `{}` when there is no traceparent. */
+export function env(): Record<string, string> {
+  const value = traceparent()
+  return value === null ? {} : { TRACEPARENT: value }
+}
+
+/**
+ * Records steps reported by an outside process under the step open now (or as
+ * root-level steps when none is open). Synchronous and never throws.
+ */
+export function record(input: string | Iterable<ExternalStepReport>): ExternalRecordResult {
+  try {
+    return recordUnsafe(input)
+  } catch (err) {
+    getBaseLogger().error({ err }, 'trace.record failed; no external steps were recorded')
+    void recordFault('trace-record', faultMessage(err))
+    return NONE
+  }
+}
+
+/**
+ * Records one zero-length step named `external:<name>` under the step open now,
+ * with an optional capture and, when `error` is given, status `error`. Outside a
+ * traced flow, or for an invalid name, it records nothing. Never throws.
+ */
+export function event(name: string, options?: { capture?: unknown; error?: unknown }): void {
+  try {
+    const ctx = getContext()?.trace
+    if (ctx === undefined || ctx === null) return
+    if (!externalStepNameSchema.safeParse(name).success) {
+      getBaseLogger().error({ name }, 'trace.event name is invalid; no event was recorded')
+      return
+    }
+    const now = new Date()
+    const failed = options !== undefined && 'error' in options && options.error !== undefined
+    ctx.buffer.stageExternal({
+      id: randomUUID(),
+      parentStepId: ctx.buffer.openStepId,
+      flowStepRef: `external:${name}`,
+      status: failed ? 'error' : 'ok',
+      startedAt: now,
+      completedAt: now,
+      durationMicros: 0n,
+      capturedInputs: options?.capture === undefined ? null : [serializeForTrace(options.capture)],
+      error: failed ? projectStepError(options.error) : null,
+    })
+  } catch (err) {
+    getBaseLogger().error({ err }, 'trace.event failed; no event was recorded')
+    void recordFault('trace-record', faultMessage(err))
+  }
+}
+
+function recordUnsafe(input: string | Iterable<ExternalStepReport>): ExternalRecordResult {
+  const flow = getContext()
+  const ctx = flow?.trace
+  if (flow === undefined || ctx === undefined || ctx === null) return NONE
+  const buffer = ctx.buffer
+
+  let invalid = 0
+  const valid = new Map<string, ExternalStepReport>()
+  for (const candidate of candidates(input)) {
+    if (candidate === SKIP) continue
+    const parsed = candidate === BAD ? null : externalStepReportSchema.safeParse(candidate)
+    if (parsed === null || !parsed.success || valid.has(parsed.data.id)) {
+      invalid++
+      continue
+    }
+    valid.set(parsed.data.id, parsed.data)
+  }
+
+  // A parent chain that never reaches the calling step (a cycle) invalidates
+  // every report on it. Unknown or self parents end the chain at the caller.
+  const parentOf = (r: ExternalStepReport): ExternalStepReport | undefined =>
+    r.parent == null || r.parent === r.id ? undefined : valid.get(r.parent)
+  const cyclic: string[] = []
+  for (const r of valid.values()) {
+    const seen = new Set<string>()
+    for (let cur: ExternalStepReport | undefined = r; cur !== undefined; cur = parentOf(cur)) {
+      if (seen.has(cur.id)) { cyclic.push(r.id); break }
+      seen.add(cur.id)
+    }
+  }
+  for (const id of cyclic) valid.delete(id)
+  invalid += cyclic.length
+
+  const callerStepId = buffer.openStepId
+  const ordered = [...valid.values()]
+    .map(r => ({ r, start: parseReportTime(r.start)!, end: parseReportTime(r.end)! }))
+    .sort((a, b) => (a.start < b.start ? -1 : a.start > b.start ? 1 : 0))
+
+  const staged = new Map<string, string>()
+  const resolveParent = (r: ExternalStepReport): string | null => {
+    for (let p = parentOf(r); p !== undefined; p = parentOf(p)) {
+      const id = staged.get(p.id)
+      if (id !== undefined) return id
+    }
+    return callerStepId
+  }
+
+  let recorded = 0
+  let dropped = 0
+  const ids = new Map(ordered.map(o => [o.r.id, randomUUID()]))
+  for (const { r, start, end } of ordered) {
+    const id = ids.get(r.id)!
+    const parentStepId = resolveParent(r)
+    const row = buffer.stageExternal({
+      id,
+      parentStepId,
+      flowStepRef: `external:${r.name}`,
+      status: r.status,
+      startedAt: new Date(Number(start / 1000n)),
+      completedAt: new Date(Number(end / 1000n)),
+      durationMicros: end - start,
+      capturedInputs: r.capture === undefined ? null : [serializeForTrace(r.capture)],
+      error: r.status === 'error'
+        ? {
+            name: r.error?.name ?? 'ExternalError',
+            message: r.error?.message ?? 'step reported error',
+            stack: r.error?.stack ?? null,
+          }
+        : null,
+    })
+    if (row === null) { dropped++; continue }
+    staged.set(r.id, id)
+    recorded++
+    if (r.status === 'ok' && r.touches !== undefined && r.touches.length > 0) {
+      const begun: BegunStep = {
+        seq: row.seq,
+        stepId: id,
+        parentStepId: row.parentStepId,
+        flowStepRef: row.flowStepRef,
+        startedAt: row.startedAt,
+        startHrTime: 0n,
+        capturedInputs: row.capturedInputs,
+        touches: r.touches.map(t => {
+          const at = t.indexOf(':')
+          return { entity: t.slice(0, at), verb: t.slice(at + 1) }
+        }),
+        wroteTouches: new Set(),
+      }
+      // Sync like a sync flow step: fire and forget; the emitter logs its own failures.
+      void emitReadTouches(flow, begun)
+    }
+  }
+  return { recorded, invalid, dropped }
+}
+
+const SKIP = Symbol('skip')
+const BAD = Symbol('bad')
+
+function* candidates(input: string | Iterable<ExternalStepReport>): Generator<unknown> {
+  if (typeof input !== 'string') {
+    yield* input
+    return
+  }
+  for (const raw of input.split('\n')) {
+    const line = raw.trim()
+    if (!line.startsWith('{')) { yield SKIP; continue }
+    try {
+      yield JSON.parse(line)
+    } catch {
+      yield BAD
+    }
+  }
+}

package/src/trace/external/report.ts

@@ -0,0 +1,66 @@
+// The language-neutral report a process outside Node sends back: one JSON
+// object per line. `parseReportTime` reads RFC 3339 timestamps to microsecond
+// precision (a JS `Date` keeps only milliseconds).
+
+import { z } from '../../data/schema/index.js'
+
+const RFC3339 = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?([Zz]|[+-]\d{2}:\d{2})$/
+
+/** Microseconds since the Unix epoch for an RFC 3339 timestamp with offset, or `null` when malformed. */
+export function parseReportTime(text: string): bigint | null {
+  const m = RFC3339.exec(text)
+  if (m === null) return null
+  const [year, month, day, hour, minute, second] = m.slice(1, 7).map(Number) as [number, number, number, number, number, number]
+  if (month < 1 || month > 12 || day < 1 || hour > 23 || minute > 59 || second > 60) return null
+  const probe = new Date(Date.UTC(year, month - 1, day))
+  if (probe.getUTCMonth() !== month - 1 || probe.getUTCDate() !== day) return null
+  let offsetSeconds = 0
+  const zone = m[8] as string
+  if (zone !== 'Z' && zone !== 'z') {
+    const oh = Number(zone.slice(1, 3))
+    const om = Number(zone.slice(4, 6))
+    if (oh > 23 || om > 59) return null
+    offsetSeconds = (oh * 3600 + om * 60) * (zone.startsWith('-') ? -1 : 1)
+  }
+  const wholeMs = Date.UTC(year, month - 1, day, hour, minute, second)
+  const fraction = Number((m[7] ?? '').padEnd(6, '0').slice(0, 6))
+  return (BigInt(wholeMs) / 1000n - BigInt(offsetSeconds)) * 1000000n + BigInt(fraction)
+}
+
+const timestamp = z.string().refine(v => parseReportTime(v) !== null, 'expected an RFC 3339 timestamp with offset')
+
+/** The name rule for an external step and a point event. */
+export const externalStepNameSchema = z.string().min(1).max(200)
+
+export const externalStepReportSchema = z.object({
+  v: z.literal(1),
+  id: z.string().min(1).max(128),
+  parent: z.string().nullable().optional(),
+  name: externalStepNameSchema,
+  start: timestamp,
+  end: timestamp,
+  status: z.enum(['ok', 'error']),
+  error: z.object({
+    name: z.string().optional(),
+    message: z.string(),
+    stack: z.string().optional(),
+  }).optional(),
+  capture: z.unknown().optional(),
+  touches: z.array(z.string().regex(/^[A-Za-z_][A-Za-z0-9_.]*:[A-Za-z_][A-Za-z0-9_-]*$/)).optional(),
+}).refine(
+  r => parseReportTime(r.end)! >= parseReportTime(r.start)!,
+  { message: 'end is before start' },
+)
+
+/** One step reported by an outside process. */
+export type ExternalStepReport = z.infer<typeof externalStepReportSchema>
+
+/** What `trace.record` did with a report. */
+export interface ExternalRecordResult {
+  /** Steps staged into the trace. */
+  readonly recorded: number
+  /** Reports skipped as malformed, duplicate, time-inverted or cyclic. */
+  readonly invalid: number
+  /** Valid reports not recorded: over `trace.maxExternalSteps`, or the trace is truncated. */
+  readonly dropped: number
+}

package/src/trace/namespace.ts

@@ -0,0 +1,19 @@
+import { env, event, record, traceparent } from './external/record.js'
+import { tree } from './read/tree.js'
+
+/** Trace namespace — hand the current trace to a process outside Node, record the steps it reports back, mark point events, and read a trace tree. */
+export const trace = {
+  /** W3C `traceparent` for the current trace and open step; `null` outside a traced flow or when the trace is truncated. */
+  traceparent,
+  /** `{ TRACEPARENT }` for a child process's environment, or `{}` when there is no traceparent. */
+  env,
+  /** Records steps reported as JSON lines (or objects) by an outside process under the step open now. Synchronous; never throws. */
+  record,
+  /** Records one zero-length step `external:<name>` under the step open now, with an optional `capture` and `error`. A no-op outside a traced flow; never throws. */
+  event,
+  /**
+   * Reads every hot trace sharing `rootId` (a request's trace and the jobs it queued) with their steps. Runs on the
+   * given `db`, so tenant policies apply: only an unrestricted connection (table owner, tests) sees every tenant's rows.
+   */
+  tree,
+}

package/src/trace/partition/day.ts

@@ -0,0 +1,47 @@
+// Day arithmetic for trace partitioning. Trace tables are RANGE-partitioned by
+// a `date` column, one partition per calendar day, reckoned in UTC — the same
+// frame the `date` column stores. All helpers take and return `YYYY-MM-DD`.
+
+const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+const MS_PER_DAY = 86_400_000
+
+/** The UTC calendar day of an instant, as `YYYY-MM-DD`. */
+export function toDay(date: Date): string {
+  return date.toISOString().slice(0, 10)
+}
+
+function parseDay(day: string): number {
+  if (!DAY_PATTERN.test(day)) {
+    throw new Error(
+      `[pipework] Invalid day "${day}" — expected YYYY-MM-DD.\n\n` +
+      '  Trace partition days are UTC calendar dates with no time component.\n'
+    )
+  }
+  const ms = Date.parse(`${day}T00:00:00.000Z`)
+  // Date.parse rolls overflow (`2026-02-30` → March 2) instead of failing, so a
+  // well-formed string that isn't a real calendar date round-trips to a
+  // different day. Reject those rather than silently shifting the partition.
+  if (Number.isNaN(ms) || new Date(ms).toISOString().slice(0, 10) !== day) {
+    throw new Error(
+      `[pipework] Invalid day "${day}" — well-formed but not a real date.\n\n` +
+      '  Check the month and day are within range.\n'
+    )
+  }
+  return ms
+}
+
+/** The day `n` days after `day` (negative `n` moves backward). */
+export function addDays(day: string, n: number): string {
+  return toDay(new Date(parseDay(day) + n * MS_PER_DAY))
+}
+
+/** Every day in `[from, to]` inclusive, ascending. Empty when `from > to`. */
+export function dayRange(from: string, to: string): string[] {
+  const start = parseDay(from)
+  const end = parseDay(to)
+  const days: string[] = []
+  for (let ms = start; ms <= end; ms += MS_PER_DAY) {
+    days.push(toDay(new Date(ms)))
+  }
+  return days
+}

package/src/trace/partition/index.ts

@@ -0,0 +1,14 @@
+export { syncTracePartitions } from './sync.js'
+export type { PartitionSyncSummary } from './sync.js'
+export { planPartitions } from './plan.js'
+export type { TracePartitionConfig, DayPartition, PartitionPlan, PartitionPlanInput } from './plan.js'
+export { PARTITIONED_TRACE_TABLES } from './tables.js'
+export type { PartitionedTraceTable, RetentionClass } from './tables.js'
+export { partitionName, parsePartitionDay } from './partition-name.js'
+export { toDay, addDays, dayRange } from './day.js'
+export { createTracePartitionStartupHook, TRACE_PARTITION_HOOK_NAME } from './startup-hook.js'
+export {
+  scheduleTracePartitionMaintenance,
+  TRACE_PARTITION_MAINTENANCE_JOB,
+  TRACE_PARTITION_MAINTENANCE_CRON,
+} from './schedule.js'

package/src/trace/partition/partition-name.ts

@@ -0,0 +1,23 @@
+// The naming convention that ties a day partition back to its parent table and
+// calendar day. `trace` + `2026-05-14` ⇄ `trace_p20260514`. The `_p` separator
+// plus a fixed 8-digit date keeps real table names (`trace_step`,
+// `trace_retained`) from ever parsing as partitions of `trace`.
+
+const DIGITS_PATTERN = /^\d{8}$/
+
+/** The partition table name for `parent`'s slice covering `day` (`YYYY-MM-DD`). */
+export function partitionName(parent: string, day: string): string {
+  return `${parent}_p${day.replace(/-/g, '')}`
+}
+
+/**
+ * The calendar day a partition name encodes, or `null` when `name` is not a day
+ * partition of `parent`. Used to tell which catalog children are ours to manage.
+ */
+export function parsePartitionDay(parent: string, name: string): string | null {
+  const prefix = `${parent}_p`
+  if (!name.startsWith(prefix)) return null
+  const digits = name.slice(prefix.length)
+  if (!DIGITS_PATTERN.test(digits)) return null
+  return `${digits.slice(0, 4)}-${digits.slice(4, 6)}-${digits.slice(6, 8)}`
+}

package/src/trace/partition/plan.ts

@@ -0,0 +1,82 @@
+// The pure core of partition maintenance: given the clock, the retention
+// windows, and the partitions that currently exist, decide which day
+// partitions to create and which to drop. No database access — every decision
+// here is a function of its inputs, so the whole policy is unit-testable.
+
+import { PARTITIONED_TRACE_TABLES, type RetentionClass } from './tables.js'
+import { partitionName, parsePartitionDay } from './partition-name.js'
+import { toDay, addDays, dayRange } from './day.js'
+
+export interface TracePartitionConfig {
+  /** Days of hot partitions kept for `trace` / `trace_step`. */
+  readonly hotRetentionDays: number
+  /** Days of cold partitions kept for `trace_retained` / `trace_step_retained`. */
+  readonly errorRetentionDays: number
+  /** Days of audit partitions kept for `audit_record` — independent of trace storage. `null` keeps them all: none is dropped and none is created for the past. */
+  readonly auditRetentionDays: number | null
+  /** Days of partitions pre-created ahead of today so writes never race creation. */
+  readonly partitionLeadDays: number
+}
+
+/** A single day partition: which parent it belongs to, its name, and its day. */
+export interface DayPartition {
+  readonly parent: string
+  readonly name: string
+  readonly day: string
+}
+
+export interface PartitionPlan {
+  readonly create: readonly DayPartition[]
+  readonly drop: readonly DayPartition[]
+}
+
+export interface PartitionPlanInput {
+  readonly now: Date
+  readonly config: TracePartitionConfig
+  /** Existing child partition names per parent table, as found in the catalog. */
+  readonly existing: ReadonlyMap<string, ReadonlySet<string>>
+}
+
+/**
+ * Reconcile desired partitions against existing ones.
+ *
+ * For each table the desired set spans `[today - retentionDays, today + leadDays]`.
+ * `create` is every desired day with no partition yet. `drop` is every existing
+ * partition whose day has fallen before the retention cutoff — retention is the
+ * dropping of day partitions, never a DELETE. Catalog children that don't parse
+ * as our day partitions are left untouched.
+ */
+export function planPartitions(input: PartitionPlanInput): PartitionPlan {
+  const { config } = input
+  const today = toDay(input.now)
+  const create: DayPartition[] = []
+  const drop: DayPartition[] = []
+
+  for (const { parent, retention } of PARTITIONED_TRACE_TABLES) {
+    const retentionDays = retentionDaysFor(retention, config)
+    const keep = retentionDays === null
+    // Kept partitions are never dropped, and none is back-filled beyond yesterday.
+    const cutoff = addDays(today, keep ? -1 : -retentionDays)
+    const existing = input.existing.get(parent) ?? new Set<string>()
+
+    for (const day of dayRange(cutoff, addDays(today, config.partitionLeadDays))) {
+      const name = partitionName(parent, day)
+      if (!existing.has(name)) create.push({ parent, name, day })
+    }
+
+    for (const name of existing) {
+      const day = parsePartitionDay(parent, name)
+      if (!keep && day !== null && day < cutoff) drop.push({ parent, name, day })
+    }
+  }
+
+  return { create, drop }
+}
+
+function retentionDaysFor(retention: RetentionClass, config: TracePartitionConfig): number | null {
+  switch (retention) {
+    case 'hot': return config.hotRetentionDays
+    case 'cold': return config.errorRetentionDays
+    case 'audit': return config.auditRetentionDays
+  }
+}

package/src/trace/partition/schedule.ts

@@ -0,0 +1,26 @@
+// Registers trace maintenance as a recurring job on the cron scheduler. The
+// startup hook covers the boot moment; this keeps things rolling forward for a
+// long-lived process. The consumer's worker dispatch routes
+// `TRACE_PARTITION_MAINTENANCE_JOB` to a body that runs both `syncTracePartitions`
+// (rolls day partitions forward, drops retired ones) and `expireStaleTraces`
+// (force-closes orphan traces past their hot retention window — Q7).
+
+import type { DB } from '../../data/db/index.js'
+
+export const TRACE_PARTITION_MAINTENANCE_JOB = 'pipework.trace.partition-maintenance'
+
+/** Daily at 01:10 UTC — past the midnight day rollover, before business hours. */
+export const TRACE_PARTITION_MAINTENANCE_CRON = '10 1 * * *'
+
+/** The scheduler surface this helper needs — structural so it doesn't couple to the job queue. */
+interface SchedulerLike {
+  schedule(db: DB, spec: { readonly name: string; readonly cron: string }): Promise<void>
+}
+
+export async function scheduleTracePartitionMaintenance(
+  scheduler: SchedulerLike,
+  db: DB,
+  cron: string = TRACE_PARTITION_MAINTENANCE_CRON,
+): Promise<void> {
+  await scheduler.schedule(db, { name: TRACE_PARTITION_MAINTENANCE_JOB, cron })
+}

package/src/trace/partition/startup-hook.ts

@@ -0,0 +1,39 @@
+// Trace maintenance as a startup hook. Running it at boot guarantees the
+// near-term partitions exist before the app takes its first request — a fresh
+// deploy on a new day must not write a trace into a partition that doesn't
+// exist yet — and clears any orphan traces left open by a process that died
+// without closing them (Q7 expiry). The cron schedule keeps both current after
+// that.
+
+import type { DB } from '../../data/db/index.js'
+import type { StartupHook } from '../../core/lifecycle/types.js'
+import { syncTracePartitions } from './sync.js'
+import { expireStaleTraces } from '../runtime/expire-stale-traces.js'
+import type { TracePartitionConfig } from './plan.js'
+import { installAuditChain } from '../../audit/chain/install.js'
+import { sql } from '../../data/db/sql.js'
+
+export const TRACE_PARTITION_HOOK_NAME = 'trace-partition-maintenance'
+
+export interface TracePartitionHookOptions {
+  /** Blueprint `audit.chain`: (re)install the audit hash chain before partitions are synced. */
+  readonly auditChain?: boolean
+}
+
+export function createTracePartitionStartupHook(
+  db: DB,
+  config: TracePartitionConfig,
+  options: TracePartitionHookOptions = {},
+): StartupHook {
+  return {
+    name: TRACE_PARTITION_HOOK_NAME,
+    async execute(): Promise<void> {
+      if (options.auditChain === true) {
+        const present = await db.execute(sql`SELECT to_regclass('audit_record') IS NOT NULL AS present`)
+        if (present[0]?.['present'] === true) await installAuditChain(db)
+      }
+      await syncTracePartitions(db, config)
+      await expireStaleTraces(db)
+    },
+  }
+}

package/src/trace/partition/sync.ts

@@ -0,0 +1,154 @@
+// The impure half of partition maintenance: read the catalog for partitions
+// that exist, ask the planner what should exist, and apply the difference.
+// Creating and dropping day partitions is idempotent — `IF NOT EXISTS` /
+// `IF EXISTS` make a re-run after a crash a no-op — so this is safe to run on
+// every boot and on a cron without coordination.
+
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import { quoteIdentifier } from '../../data/db/identifiers.js'
+import { getBaseLogger } from '../../core/logging/index.js'
+import { PARTITIONED_TRACE_TABLES, STEP_TABLE_PARENTS } from './tables.js'
+import { planPartitions, type DayPartition, type TracePartitionConfig } from './plan.js'
+import { addDays } from './day.js'
+import { auditRecord } from '../../audit/schema/audit-record.js'
+import { withMaintenance } from '../../data/db/maintenance.js'
+import { retireAuditPartition, auditChainInstalled } from '../../audit/chain/retire.js'
+
+export interface PartitionSyncOptions {
+  /** Called as each partition's CREATE starts; `index` is 1-based of `total` creations. */
+  readonly onPartition?: (name: string, index: number, total: number) => void
+}
+
+export interface PartitionSyncSummary {
+  readonly created: readonly string[]
+  readonly dropped: readonly string[]
+}
+
+/**
+ * Reconcile the trace tables' day partitions with the retention policy.
+ *
+ * `now` is injectable so the maintenance window is testable without mocking the
+ * clock. `options.onPartition` reports each creation as it starts, so a hung
+ * CREATE is named. Returns the names created and dropped so a job runner can
+ * record them.
+ */
+export async function syncTracePartitions(
+  db: DB,
+  config: TracePartitionConfig,
+  now: Date = new Date(),
+  options: PartitionSyncOptions = {},
+): Promise<PartitionSyncSummary> {
+  const existingParents = await readExistingParents(db)
+  const existing = await readExistingPartitions(db)
+  const plan = planPartitions({ now, config, existing })
+
+  // A parent pipework never provisioned (e.g. `audit` disabled, so no
+  // `audit_record`) has no table to attach a partition to — `CREATE TABLE ...
+  // PARTITION OF` it would abort the whole pass. Drop those from the plan so
+  // the summary reports only partitions actually applied. Issue #313.
+  const toCreate = plan.create.filter(partition => existingParents.has(partition.parent))
+
+  for (const [i, partition] of toCreate.entries()) {
+    options.onPartition?.(partition.name, i + 1, toCreate.length)
+    const child = quoteIdentifier(partition.name, 'trace partition')
+    const parent = quoteIdentifier(partition.parent, 'trace table')
+    // addDays re-validates the day; the bound is a generated YYYY-MM-DD literal.
+    const upper = addDays(partition.day, 1)
+    await db.execute(sql.raw(
+      `CREATE TABLE IF NOT EXISTS ${child} PARTITION OF ${parent} ` +
+      `FOR VALUES FROM ('${partition.day}') TO ('${upper}')`,
+    ))
+  }
+
+  const chained = plan.drop.some(p => p.parent === auditRecord.$name) && await auditChainInstalled(db)
+
+  const traceParents = new Set(STEP_TABLE_PARENTS.values())
+  const stepDrops = new Map<string, DayPartition>()
+  for (const partition of plan.drop) {
+    if (STEP_TABLE_PARENTS.has(partition.parent)) stepDrops.set(`${partition.parent}:${partition.day}`, partition)
+  }
+
+  for (const partition of plan.drop) {
+    const child = quoteIdentifier(partition.name, 'trace partition')
+    if (chained && partition.parent === auditRecord.$name) {
+      // Keep the dropped rows' hashes so what remains still links back to them.
+      // It reads every tenant's rows, so it runs as a maintenance pass.
+      await withMaintenance(db, tx => retireAuditPartition(tx, child))
+      continue
+    }
+    if (STEP_TABLE_PARENTS.has(partition.parent)) continue // dropped with its trace partition's day
+    if (traceParents.has(partition.parent)) {
+      // The step table's foreign key points at this partition: drop the day's
+      // step partition first, then detach the trace partition (Postgres will
+      // not drop a referenced partition while attached), all or nothing.
+      const stepParent = [...STEP_TABLE_PARENTS].find(([, traceParent]) => traceParent === partition.parent)![0]
+      const step = stepDrops.get(`${stepParent}:${partition.day}`)
+      const parent = quoteIdentifier(partition.parent, 'trace table')
+      await db.transaction(async tx => {
+        if (step !== undefined) {
+          await tx.execute(sql.raw(`DROP TABLE IF EXISTS ${quoteIdentifier(step.name, 'trace partition')}`))
+          stepDrops.delete(`${stepParent}:${partition.day}`)
+        }
+        await tx.execute(sql.raw(`ALTER TABLE ${parent} DETACH PARTITION ${child}`))
+        await tx.execute(sql.raw(`DROP TABLE IF EXISTS ${child}`))
+      })
+      continue
+    }
+    await db.execute(sql.raw(`DROP TABLE IF EXISTS ${child}`))
+  }
+
+  // A step partition left over has no trace partition planned for its day.
+  for (const step of stepDrops.values()) {
+    await db.execute(sql.raw(`DROP TABLE IF EXISTS ${quoteIdentifier(step.name, 'trace partition')}`))
+  }
+
+  const summary: PartitionSyncSummary = {
+    created: toCreate.map(p => p.name),
+    dropped: plan.drop.map(p => p.name),
+  }
+
+  if (summary.created.length > 0 || summary.dropped.length > 0) {
+    getBaseLogger().info(
+      { created: summary.created, dropped: summary.dropped },
+      'Trace partition maintenance applied',
+    )
+  }
+
+  return summary
+}
+
+/**
+ * Which of the partitioned trace parents actually exist as partitioned tables.
+ * A parent pipework never provisioned — `audit` disabled, or a non-default
+ * database — must be skipped: `CREATE TABLE ... PARTITION OF` a missing parent
+ * aborts the maintenance pass. Issue #313.
+ */
+async function readExistingParents(db: DB): Promise<Set<string>> {
+  const parents = PARTITIONED_TRACE_TABLES.map(t => t.parent)
+  const rows = await db.execute(sql`
+    SELECT relname FROM pg_class
+    WHERE relkind = 'p' AND relname ${sql.inList(parents)}
+  `)
+  return new Set(rows.map(row => row['relname'] as string))
+}
+
+async function readExistingPartitions(db: DB): Promise<Map<string, Set<string>>> {
+  const parents = PARTITIONED_TRACE_TABLES.map(t => t.parent)
+  const rows = await db.execute(sql`
+    SELECT p.relname AS parent, c.relname AS child
+    FROM pg_inherits i
+    JOIN pg_class c ON c.oid = i.inhrelid
+    JOIN pg_class p ON p.oid = i.inhparent
+    WHERE p.relname ${sql.inList(parents)}
+  `)
+
+  const byParent = new Map<string, Set<string>>()
+  for (const parent of parents) byParent.set(parent, new Set())
+  for (const row of rows) {
+    const parent = row['parent'] as string
+    const child = row['child'] as string
+    byParent.get(parent)?.add(child)
+  }
+  return byParent
+}