pipework 0.252.0 → 0.253.0

package/src/trace/runtime/step-buffer.ts

@@ -0,0 +1,298 @@
+// The per-trace step buffer. Every Flow that runs under tracing carries one;
+// `__flowStep` records into it and the trace's close drains it to the database
+// in a single batch. The buffer is in-memory and single-trace: a branch opens a
+// child Flow with its own buffer, so the rows here never interleave with
+// another trace's.
+//
+// Three pieces of mutable state, all owned here so `__flowStep` stays a thin
+// wrapper: the `seq` counter (spawn order within the trace), `currentStepId`
+// (the step a nested step records as its parent), and the truncation latch
+// (Q7 — once the step cap is blown the buffer goes no-op for the rest of the
+// trace, mirroring the off-the-traced-path code path exactly).
+
+import { randomUUID } from 'node:crypto'
+import { projectStepError, type StepError } from './step-error.js'
+import type { MetaTouch } from './step-meta.js'
+
+/** A `trace_step` row staged in memory, ready to be flushed. */
+export interface PendingStep {
+  readonly id: string
+  readonly traceDay: string
+  readonly traceId: string
+  readonly tenantId: string | null
+  readonly seq: number
+  readonly parentStepId: string | null
+  readonly flowStepRef: string
+  readonly status: 'ok' | 'error'
+  readonly startedAt: Date
+  readonly completedAt: Date
+  readonly durationMicros: bigint
+  /**
+   * Tier-2 input capture (Q5): one bounded-serialized payload per parameter,
+   * in declaration order. `null` when the transformer emitted no capture
+   * metadata for this step or the `captureInputs` kill-switch is off.
+   */
+  readonly capturedInputs: readonly unknown[] | null
+  readonly error: StepError | null
+}
+
+/** A step that has started but not yet completed — the handle `complete` settles. */
+export interface BegunStep {
+  readonly seq: number
+  readonly stepId: string
+  readonly parentStepId: string | null
+  readonly flowStepRef: string
+  readonly startedAt: Date
+  readonly startHrTime: bigint
+  /** Captured at begin time so a mutating impl can't change what the row records. */
+  readonly capturedInputs: readonly unknown[] | null
+  /**
+   * `@touches Entity:verb` targets baked into this step's meta. Empty means
+   * no audit projection — the executor takes the vanilla-DML branch and
+   * `__flowStep`'s completion path emits no read-touches audit row.
+   */
+  readonly touches: readonly MetaTouch[]
+  /**
+   * The touches the executor audited with a `pipe.*` write under this step.
+   * `__flowStep` reads this at completion and emits a read-touches
+   * `audit_record` row for every touch not in it. The CTE branch handled the
+   * audit for the touches in it.
+   */
+  readonly wroteTouches: Set<MetaTouch>
+}
+
+/**
+ * The active-step handle the write executor reads to compile its CTE. Captures
+ * everything the `audit_inserts` SELECT needs from the step's runtime context:
+ * the step id and trace id that link the audit row back to the source step,
+ * the partition day, the bounded-serialized captured inputs, and the active
+ * touches. Returned by `StepBuffer.currentStep()` only while a step is open
+ * for audit (touches present); otherwise `null` so the executor falls through
+ * to vanilla DML.
+ */
+export interface ActiveAuditStep {
+  readonly traceId: string
+  readonly traceDay: string
+  readonly stepId: string
+  readonly touches: readonly MetaTouch[]
+  readonly capturedInputs: readonly unknown[] | null
+  /** Called by the executor right before it returns — records on the underlying BegunStep that `touch` was audited by a write. */
+  markWrote(touch: MetaTouch): void
+}
+
+export interface StepBufferParams {
+  readonly traceId: string
+  /** The parent trace's `openedDay` — the partition every step row lands in. */
+  readonly traceDay: string
+  /** The trace's tenant, stamped on every staged step row. Default `null`. */
+  readonly tenantId?: string | null
+  /**
+   * The Q7 step cap. The `seq` that first exceeds it trips truncation;
+   * `Infinity` disables the cap (no `structuralMax` resolved yet).
+   */
+  readonly cap: number
+  /**
+   * The Q5 input-capture kill-switch, resolved at trace open from
+   * `instance.config.trace.captureInputs`. When `false`, every step in this
+   * trace stages `capturedInputs: null` regardless of what the transformer
+   * emitted — Tier-1 capture is unaffected.
+   */
+  readonly captureInputs: boolean
+  /**
+   * Per-trace limit on steps staged through `stageExternal` (steps reported by
+   * a process outside Node). They do not count against `cap`. Default 1000.
+   */
+  readonly maxExternalSteps?: number
+}
+
+/** A completed step reported from outside the process, ready for `stageExternal`. */
+export interface ExternalStepInput {
+  readonly id: string
+  readonly parentStepId: string | null
+  readonly flowStepRef: string
+  readonly status: 'ok' | 'error'
+  readonly startedAt: Date
+  readonly completedAt: Date
+  readonly durationMicros: bigint
+  readonly capturedInputs: readonly unknown[] | null
+  readonly error: StepError | null
+}
+
+export class StepBuffer {
+  private readonly traceId: string
+  private readonly traceDay: string
+  private readonly tenantId: string | null
+  private readonly cap: number
+  readonly captureInputs: boolean
+  private seq = 0
+  /** Steps begun through `begin` — the count the step cap applies to. */
+  private structuralCount = 0
+  private externalCount = 0
+  private readonly maxExternalSteps: number
+  private currentStepId: string | null = null
+  /**
+   * The active begun-step at the deepest open nesting level. `__flowStep`
+   * pushes on `begin` and pops on `complete`; the write executor reads the
+   * top of the stack through `currentStep()` to compile its audit CTE.
+   *
+   * The stack pairs with `currentStepId` — both describe step nesting — but
+   * keeps the full `BegunStep` reference so the executor and the read-touches
+   * emitter can reach `touches` and `capturedInputs` without a second lookup.
+   */
+  private readonly active: BegunStep[] = []
+  private pending: PendingStep[] = []
+  private truncatedAtSeqValue: number | null = null
+  private truncationDoneValue: Promise<void> | null = null
+
+  constructor(params: StepBufferParams) {
+    this.traceId = params.traceId
+    this.traceDay = params.traceDay
+    this.tenantId = params.tenantId ?? null
+    this.cap = params.cap
+    this.captureInputs = params.captureInputs
+    this.maxExternalSteps = params.maxExternalSteps ?? 1000
+  }
+
+  /** The id of the step currently open (innermost), or `null` when none is. */
+  get openStepId(): string | null {
+    return this.currentStepId
+  }
+
+  /** True once the step cap has been blown — the trace records no further steps. */
+  get truncated(): boolean {
+    return this.truncatedAtSeqValue !== null
+  }
+
+  /** The `seq` that tripped truncation, for `trace.truncated_at_seq`. */
+  get truncatedAtSeq(): number | null {
+    return this.truncatedAtSeqValue
+  }
+
+  /**
+   * Settles when `truncateTrace`'s side effects have landed (flush + status
+   * `UPDATE`). `closeTrace` awaits this before its copy-on-error so the cold
+   * row reflects `truncated_at_seq`. `null` when the trace was never truncated.
+   */
+  get truncationDone(): Promise<void> | null {
+    return this.truncationDoneValue
+  }
+
+  /** Records the truncation's settle handle. `truncateTrace` calls this once. */
+  markTruncationDone(promise: Promise<void>): void {
+    this.truncationDoneValue = promise
+  }
+
+  /**
+   * Opens a step: assigns its `seq`, mints its id, and nests it under the step
+   * currently executing. Returns `null` when this step is the one that blows
+   * the cap — the caller runs the implementation untraced from here on.
+   *
+   * `capturedInputs` is the bounded-serialized projection of the step's args
+   * (built by `__flowStep` from `meta.capture`), or `null` for Tier-1-only.
+   * `touches` is the `@touches Entity:verb` set baked into the step's meta,
+   * or empty when the step has no audit projection.
+   */
+  begin(
+    flowStepRef: string,
+    capturedInputs: readonly unknown[] | null,
+    touches: readonly MetaTouch[] = [],
+  ): BegunStep | null {
+    const seq = ++this.seq
+    if (++this.structuralCount > this.cap) {
+      this.truncatedAtSeqValue = seq
+      return null
+    }
+    const stepId = randomUUID()
+    const begun: BegunStep = {
+      seq,
+      stepId,
+      parentStepId: this.currentStepId,
+      flowStepRef,
+      startedAt: new Date(),
+      startHrTime: process.hrtime.bigint(),
+      capturedInputs,
+      touches,
+      wroteTouches: new Set(),
+    }
+    this.currentStepId = stepId
+    this.active.push(begun)
+    return begun
+  }
+
+  /**
+   * The active step's audit handle, or `null` when there is no open step or
+   * the open step has no `@touches`. The write executor uses this to decide:
+   * `null` → vanilla DML; non-null → compile the `audit_inserts` CTE. The
+   * returned handle's `markWrote(touch)` records the touch so `__flowStep`
+   * suppresses its read-touches emission at step completion.
+   */
+  currentStep(): ActiveAuditStep | null {
+    const top = this.active[this.active.length - 1]
+    if (top === undefined || top.touches.length === 0) return null
+    return {
+      traceId: this.traceId,
+      traceDay: this.traceDay,
+      stepId: top.stepId,
+      touches: top.touches,
+      capturedInputs: top.capturedInputs,
+      markWrote: (touch) => {
+        // A write also counts for every enclosing step that declares the same touch.
+        for (const step of this.active) {
+          for (const t of step.touches) {
+            if (t === touch || (t.entity === touch.entity && t.verb === touch.verb)) step.wroteTouches.add(t)
+          }
+        }
+      },
+    }
+  }
+
+  /** Settles a begun step: stamps its outcome and timing, stages the row, unnests. */
+  complete(begun: BegunStep, status: 'ok' | 'error', thrown: unknown): void {
+    this.currentStepId = begun.parentStepId
+    const idx = this.active.lastIndexOf(begun)
+    if (idx !== -1) this.active.splice(idx, 1)
+    this.pending.push({
+      id: begun.stepId,
+      traceDay: this.traceDay,
+      traceId: this.traceId,
+      tenantId: this.tenantId,
+      seq: begun.seq,
+      parentStepId: begun.parentStepId,
+      flowStepRef: begun.flowStepRef,
+      status,
+      startedAt: begun.startedAt,
+      completedAt: new Date(),
+      durationMicros: (process.hrtime.bigint() - begun.startHrTime) / 1000n,
+      capturedInputs: begun.capturedInputs,
+      error: status === 'error' ? projectStepError(thrown) : null,
+    })
+  }
+
+  /**
+   * Stages an already-completed step reported from outside the process. Assigns
+   * its `seq`. Returns the staged row, or `null` when nothing was recorded: the
+   * trace is truncated or the external-step limit is reached. External steps
+   * never count toward the structural cap.
+   */
+  stageExternal(step: ExternalStepInput): PendingStep | null {
+    if (this.truncated || this.externalCount >= this.maxExternalSteps) return null
+    this.externalCount++
+    const row: PendingStep = {
+      ...step,
+      traceDay: this.traceDay,
+      traceId: this.traceId,
+      tenantId: this.tenantId,
+      seq: ++this.seq,
+      capturedInputs: this.captureInputs ? step.capturedInputs : null,
+    }
+    this.pending.push(row)
+    return row
+  }
+
+  /** Removes and returns every staged row — the buffer is empty afterwards. */
+  drain(): PendingStep[] {
+    const drained = this.pending
+    this.pending = []
+    return drained
+  }
+}

package/src/trace/runtime/step-error.ts

@@ -0,0 +1,21 @@
+// Tier-1 error capture: the JSON projection of a thrown value for the
+// `trace_step.error` column. Errors are always captured (Tier 1) — unlike
+// inputs, an error carries no tenant data of its own, only the failure shape a
+// reader needs. A non-`Error` throw still gets a record so the step is never
+// silently marked failed with nothing to show.
+
+export interface StepError {
+  readonly name: string
+  readonly message: string
+  readonly stack: string | null
+  /** Facts about the failure the recorder chose to keep (an http error's route, status and code); absent on a thrown step. */
+  readonly detail?: unknown
+}
+
+/** The `trace_step.error` projection of a thrown value. */
+export function projectStepError(thrown: unknown): StepError {
+  if (thrown instanceof Error) {
+    return { name: thrown.name, message: thrown.message, stack: thrown.stack ?? null }
+  }
+  return { name: 'NonError', message: String(thrown), stack: null }
+}

package/src/trace/runtime/step-meta.ts

@@ -0,0 +1,55 @@
+// The compile-time identity of a flow step. The build transformer (component 5)
+// bakes one of these in as a literal at every wrapped call site — `__flowStep`
+// never computes it. `ref` is the `path:symbol` node id, matching the
+// `@upstream` / `@downstream` targets the annotation grammar produces.
+
+/**
+ * Per-arg projection emitted by the build transformer for Tier-2 input capture.
+ *
+ * The projection turns a raw argument into a trace-safe payload, derived at
+ * compile time from the parameter's type and the `.traceSafe()` markings in
+ * the `pipe.define()` registry. The runtime then runs the projected value
+ * through the bounded serializer before staging it on
+ * `trace_step.captured_inputs`.
+ *
+ * The projection may return any JSON-shaped value, including `undefined` for
+ * "this arg has no safe fields to capture" (fail-closed default).
+ */
+export type CaptureProjection = (arg: unknown) => unknown
+
+/**
+ * One `@touches Entity:verb` target baked into a step's meta. Mirrors the
+ * `EntityTouch` shape the annotation parser produces — duplicated here so the
+ * runtime has no compile-time dependency on `src/trace/annotation/*` (the
+ * transformer is the only thing that bridges the two).
+ */
+export interface MetaTouch {
+  readonly entity: string
+  readonly verb: string
+}
+
+/** Trace metadata for one documented flow-step: its `path:symbol` graph node id and the per-argument capture projections. */
+export interface FlowStepMeta {
+  /** The `path:symbol` flow-graph node id of the documented function. */
+  readonly ref: string
+  /**
+   * Per-arg capture projections, in parameter order. `null` at a slot means
+   * "no projection — pass the raw arg through to the bounded serializer"
+   * (primitives, or `any`-typed parameters with no registry entry).
+   *
+   * Absent entirely means the transformer chose to skip Tier-2 capture for
+   * this step. The runtime stages `capturedInputs: null` and incurs no
+   * per-arg cost.
+   */
+  readonly capture?: ReadonlyArray<CaptureProjection | null>
+  /**
+   * `@touches Entity:verb` targets declared on this step. Empty / absent means
+   * the step has no audit projection — the write surface emits vanilla DML
+   * (no CTE) and the runtime emits no read-touches `audit_record` row.
+   *
+   * When present, the active step's touches surface through the trace's
+   * `StepBuffer` for the executor's CTE generator (write-touches) and for
+   * `__flowStep`'s step-completion path (read-touches).
+   */
+  readonly touches?: ReadonlyArray<MetaTouch>
+}

package/src/trace/runtime/thenable.ts

@@ -0,0 +1,12 @@
+// A flow step's implementation may be synchronous or return a promise, and so
+// may an entry's work. Both `__flowStep` and `finalizeTrace` have to settle the
+// trace exactly when the work does — which means recognising a thenable
+// (anything with a callable `then`, not just a native `Promise`) without
+// awaiting code that never needed to be async.
+
+/** True for any thenable — a native `Promise` or a custom PromiseLike. */
+export function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return value !== null
+    && (typeof value === 'object' || typeof value === 'function')
+    && typeof (value as { then?: unknown }).then === 'function'
+}

package/src/trace/runtime/truncate-trace.ts

@@ -0,0 +1,62 @@
+// Q7 truncation. The step cap fired — the trace's longest non-branch path was
+// supposed to be bounded by `structuralMax`, and we just crossed
+// `structuralMax × safetyFactor`. That means the static DAG analysis was wrong
+// (a branch the cardinality check missed) or unannotated recursion slipped
+// validation. Either way it's a bug signal, not a load condition: the cap
+// firing is loud on purpose.
+//
+// The work itself keeps running: `__flowStep` already flips to its
+// off-the-traced-path pass-through, so the rest of the trace costs nothing.
+// Here we finalize the trace as a casualty — flush whatever's buffered so far,
+// stamp `status = 'truncated'` and `truncated_at_seq` on the row, and log loud.
+//
+// `closedAt` is *not* set: the entry hasn't finished yet. When it does,
+// `closeTrace` fills it in and triggers the copy-on-error so the cold row
+// reflects the final state (Q4). The truncation's settle handle is stored on
+// the buffer so `closeTrace` can wait for `truncated_at_seq` to land before it
+// copies.
+
+import type { Manifold } from '../../core/pipework.js'
+import { getBaseLogger } from '../../core/logging/index.js'
+import { recordFaultFor, faultMessage } from '../../infra/alerts/faults.js'
+import { eq, and, getTableColumns } from '../../data/query/index.js'
+import type { Column } from '../../data/db/types.js'
+import { trace } from '../schema/trace.js'
+import { trackTraceWrite } from './pending-writes.js'
+import { flushSteps } from './flush-steps.js'
+import { withMaintenance } from '../../data/db/maintenance.js'
+import type { DB } from '../../data/db/index.js'
+import type { TraceContext } from '../entry/trace-context.js'
+
+/** Fires Q7 truncation: flushes the buffer and stamps `truncated` on the trace row. */
+export function truncateTrace(instance: Manifold, ctx: TraceContext): Promise<void> {
+  const truncatedAtSeq = ctx.buffer.truncatedAtSeq
+  getBaseLogger().error(
+    { traceId: ctx.id, truncatedAtSeq },
+    'Trace truncated — step cap exceeded; the flow DAG analysis missed a branch or unannotated recursion',
+  )
+  const done = trackTraceWrite(ctx.persisted
+    .then(async () => {
+      const stepFlush = flushSteps(instance, ctx.buffer.drain())
+      const db = instance.pool.getOrCreate(instance.config.database()).drizzle
+      const table = trace.table()
+      const cols = getTableColumns(table) as Record<'id' | 'openedDay', Column>
+      // The pooled connection carries no tenant setting, so the UPDATE runs as a maintenance pass.
+      const traceUpdate = withMaintenance(db as unknown as DB, async tx => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Drizzle's update needs the concrete runtime table type
+        await (tx as any).update(table)
+          .set({ status: 'truncated', truncatedAtSeq })
+          .where(and(eq(cols.id, ctx.id), eq(cols.openedDay, ctx.openedDay)))
+      })
+      await Promise.all([stepFlush, traceUpdate])
+    })
+    .catch((err: unknown) => {
+      getBaseLogger().error(
+        { err, traceId: ctx.id },
+        'Failed to persist trace truncation — the trace row is missing its `truncated` stamp',
+      )
+      void recordFaultFor(instance, 'trace-write', `trace truncation not persisted: ${faultMessage(err)}`, { traceId: ctx.id, step: 'truncate' })
+    }))
+  ctx.buffer.markTruncationDone(done)
+  return done
+}

package/src/trace/schema/trace-fields.ts

@@ -0,0 +1,52 @@
+// The column shape shared by the hot `trace` table and the cold
+// `trace_retained` table. A trace is one execution rooted at an entry point
+// (HTTP request, job, cron tick, test); its steps live in `trace_step`.
+//
+// Field descriptors are immutable, so the same record is handed to both
+// `define()` calls — the hot and retained tables are structurally identical
+// and differ only in retention policy.
+//
+// Self-reference (`rootId`, `parentId` → `trace.id`) and forward-reference
+// (`parentStepId` → `trace_step.id`) resolve their targets lazily via the
+// global registry. Importing `trace` / `traceStep` directly would create a
+// load-order trap: `trace-retained.ts` imports this module before `trace.ts`
+// has run, so a direct cycle leaves `trace` in TDZ when `define()` reads
+// `traceFields`. Resolving by name dodges the cycle entirely; the validator
+// catches a bad name. `enforced: false` keeps the brand inheritance — and
+// therefore the validator's recognition that the reuse is intentional —
+// without emitting a physical FK; retention is free to drop ancestor
+// partitions out from under these columns.
+
+import { field, definitions } from '../../data/domain/index.js'
+import type { DefinedTable } from '../../data/domain/types.js'
+
+const lazyTrace = (): DefinedTable => definitions().get('trace') as DefinedTable
+const lazyTraceStep = (): DefinedTable => definitions().get('trace_step') as DefinedTable
+
+export const traceFields = {
+  id: field.uuid().brand('TraceId').defaultRandom(),
+  // Partition key — the calendar day the trace opened. Retention drops whole
+  // day-partitions, so every row carries the day it belongs to.
+  openedDay: field.date(),
+  // The root of the trace tree. Equals `id` for a root trace.
+  rootId: field.uuid().brand('TraceId').references(lazyTrace, 'id', { enforced: false }),
+  parentId: field.uuid().brand('TraceId').references(lazyTrace, 'id', { enforced: false }).nullable(),
+  parentStepId: field.uuid().brand('TraceStepId').references(lazyTraceStep, 'id', { enforced: false }).nullable(),
+  entryKind: field.enum(['http', 'job', 'cron', 'test']),
+  status: field.enum(['open', 'closed', 'error', 'truncated', 'expired']),
+  tenantId: field.uuid().tenant().nullable(),
+  requestId: field.text().nullable(),
+  sessionId: field.text().nullable(),
+  userId: field.text().nullable(),
+  openedAt: field.timestamp(),
+  closedAt: field.timestamp().nullable(),
+  // Force-close deadline: openedAt + hotRetentionDays. A trace must not outlive
+  // its own oldest day-partition.
+  expiresAt: field.timestamp(),
+  // Set when the step cap is hit and the trace is truncated — the seq at which
+  // capture stopped.
+  truncatedAtSeq: field.integer().nullable(),
+  // The release of the process that opened the trace; null when the app
+  // configures none.
+  release: field.text().nullable(),
+}

package/src/trace/schema/trace-retained.ts

@@ -0,0 +1,22 @@
+// The cold `trace_retained` table — structurally identical to `trace`, but
+// holds traces copied out on error so they survive past `hotRetentionDays`.
+// RANGE-partitioned the same way; retention drops day-partitions older than
+// `errorRetentionDays`.
+
+import { define, definitions, field } from "../../data/domain/index.js";
+import { traceFields } from './trace-fields.js'
+
+export const traceRetained = define('trace_retained', {
+  ...traceFields,
+  // A retained row is a *copy* of a hot row and holds the same id value — the
+  // same TraceId id-space, not a fresh one. The enforced:false reference to
+  // `trace.id` emits no physical FK (retention may drop the hot partition out
+  // from under the copy) but tells the brand-uniqueness validator the TraceId
+  // reuse is intentional (isInheritedFromFK), mirroring trace-fields' rootId.
+  // Thunk form defers resolution past the import cycle — `trace.ts` has not run
+  // yet when this module loads — so the brand is restated explicitly.
+  id: field.uuid().brand('TraceId').references(() => definitions().get('trace')!, 'id', { enforced: false }).defaultRandom(),
+}, {
+  primaryKey: ['id', 'openedDay'],
+  partitionBy: { strategy: 'range', column: 'openedDay' },
+})

package/src/trace/schema/trace-step-fields.ts

@@ -0,0 +1,44 @@
+// The column shape shared by the hot `trace_step` table and the cold
+// `trace_step_retained` table. One row per flow step that executed under an
+// active Flow.
+//
+// Field descriptors are immutable, so the same record is handed to both
+// `define()` calls.
+//
+// `traceId` and `parentStepId` declare logical references resolved lazily via
+// the registry — see the same pattern in `trace-fields.ts`. The actual
+// `trace` FK lives in the composite (`traceId`, `traceDay`) on the table; the
+// field-level reference exists only to inherit the brand and surface a
+// `references` annotation to the validator.
+
+import { field, definitions } from '../../data/domain/index.js'
+import { schema } from '../../data/schema/namespace.js'
+import type { DefinedTable } from '../../data/domain/types.js'
+
+const lazyTrace = (): DefinedTable => definitions().get('trace') as DefinedTable
+const lazyTraceStep = (): DefinedTable => definitions().get('trace_step') as DefinedTable
+
+export const traceStepFields = {
+  id: field.uuid().brand('TraceStepId').defaultRandom(),
+  // Partition key — the parent trace's `openedDay`, NOT the step's own
+  // timestamp. This keeps the foreign key into `trace` partition-local: a
+  // step and its trace always sit in the same day-partition, so the two
+  // tables' partitions retire together.
+  traceDay: field.date(),
+  traceId: field.uuid().brand('TraceId').references(lazyTrace, 'id', { enforced: false }),
+  // The parent trace's tenant, stamped on every step so the row-level security policy can guard steps like traces.
+  tenantId: field.uuid().tenant().nullable(),
+  // Spawn order within the trace. Branch vs step is an edge property, not a
+  // node property — `seq` only records sequencing.
+  seq: field.integer(),
+  parentStepId: field.uuid().brand('TraceStepId').references(lazyTraceStep, 'id', { enforced: false }).nullable(),
+  // The `path:symbol` identity of the flow step, matching the annotation's
+  // upstream/downstream targets.
+  flowStepRef: field.text(),
+  status: field.enum(['ok', 'error']),
+  startedAt: field.timestamp(),
+  completedAt: field.timestamp().nullable(),
+  durationMicros: field.bigint().nullable(),
+  capturedInputs: field.jsonb(schema.check.json()).nullable(),
+  error: field.jsonb(schema.check.json()).nullable(),
+}

package/src/trace/schema/trace-step-retained.ts

@@ -0,0 +1,25 @@
+// The cold `trace_step_retained` table — structurally identical to
+// `trace_step`, holding steps copied out on error. Its foreign key targets
+// `trace_retained`: copy-on-error writes the trace and its steps together, so
+// referential integrity holds in the cold tables exactly as it does in the hot
+// ones.
+
+import { define, definitions, field } from "../../data/domain/index.js";
+import { traceStepFields } from './trace-step-fields.js'
+import { traceRetained } from './trace-retained.js'
+
+export const traceStepRetained = define('trace_step_retained', {
+  ...traceStepFields,
+  // Same id-space as the hot `trace_step` row it mirrors — see trace-retained
+  // for why the enforced:false self-space reference is what keeps the
+  // brand-uniqueness validator from flagging the intentional TraceStepId reuse.
+  id: field.uuid().brand('TraceStepId').references(() => definitions().get('trace_step')!, 'id', { enforced: false }).defaultRandom(),
+}, {
+  primaryKey: ['id', 'traceDay'],
+  partitionBy: { strategy: 'range', column: 'traceDay' },
+  foreignKeys: [{
+    columns: ['traceId', 'traceDay'],
+    references: { definition: traceRetained, columns: ['id', 'openedDay'] },
+    onDelete: 'cascade',
+  }],
+})

package/src/trace/schema/trace-step.ts

@@ -0,0 +1,18 @@
+// The hot `trace_step` table — one row per flow step executed under a Flow.
+// Partitioned by `traceDay` (the parent trace's `openedDay`), so the foreign
+// key into `trace` is partition-local and both tables' partitions retire
+// together.
+
+import { define } from '../../data/domain/index.js'
+import { traceStepFields } from './trace-step-fields.js'
+import { trace } from './trace.js'
+
+export const traceStep = define('trace_step', traceStepFields, {
+  primaryKey: ['id', 'traceDay'],
+  partitionBy: { strategy: 'range', column: 'traceDay' },
+  foreignKeys: [{
+    columns: ['traceId', 'traceDay'],
+    references: { definition: trace, columns: ['id', 'openedDay'] },
+    onDelete: 'cascade',
+  }],
+})

package/src/trace/schema/trace.ts

@@ -0,0 +1,12 @@
+// The hot `trace` table — one row per execution, rooted at an entry point.
+// RANGE-partitioned by `openedDay`; retention drops day-partitions older than
+// `hotRetentionDays`. Errored traces are copied to `trace_retained` before
+// their partition is dropped.
+
+import { define } from '../../data/domain/index.js'
+import { traceFields } from './trace-fields.js'
+
+export const trace = define('trace', traceFields, {
+  primaryKey: ['id', 'openedDay'],
+  partitionBy: { strategy: 'range', column: 'openedDay' },
+})