pipework 0.251.0 → 0.252.1

package/src/trace/codemod/add-cardinality.ts

@@ -0,0 +1,152 @@
+// The cardinality codemod (component 4). For every `@downstream path:symbol`
+// JSDoc line that omits its cardinality, classify the edge structurally and
+// append `step` or `branch`. Edges the analyzer cannot classify (indirection)
+// and edges declared on non-trivial textual forms (continuation lines) are
+// left untouched and reported as `unresolved` for the user to address by hand.
+//
+// Scope is deliberately narrow: the codemod only *fills blanks*. It never
+// rewrites an existing cardinality, never touches a method flow step (those
+// are banned by the `flow` check), and never re-flows the surrounding JSDoc.
+// Minimal churn — one token per line, in place.
+
+import { collectFlowStepSites, type FlowStepSite } from '../check/flow-step-site.js'
+import { classifyEdge } from '../cardinality/classify-edge.js'
+
+export interface CardinalityFill {
+  /** 1-based file line of the `@downstream` tag the codemod filled. */
+  readonly line: number
+  /** `path:symbol` target of the edge that received a cardinality. */
+  readonly target: string
+  /** The cardinality that was appended. */
+  readonly kind: 'step' | 'branch'
+}
+
+export interface UnresolvedEdge {
+  /** 1-based file line of the `@downstream` tag the codemod left untouched. */
+  readonly line: number
+  /** `path:symbol` target the codemod could not fill. */
+  readonly target: string
+  /**
+   * - `ambiguous` — analyzer could not classify the edge; needs a human.
+   * - `non-trivial-form` — the `@downstream` declaration spans lines or
+   *   carries trailing text the codemod won't blindly rewrite.
+   */
+  readonly reason: 'ambiguous' | 'non-trivial-form'
+}
+
+export interface RewriteResult {
+  /** The rewritten source — strictly equal to the input when nothing changed. */
+  readonly text: string
+  /** Every edge whose cardinality the codemod filled in. */
+  readonly fills: readonly CardinalityFill[]
+  /** Every edge the codemod left untouched but a human still needs to address. */
+  readonly unresolved: readonly UnresolvedEdge[]
+}
+
+/**
+ * Walks `source` for `@flow_step` sites, classifies each `@downstream` edge
+ * whose cardinality is missing, and returns the rewritten text plus a record
+ * of what was filled and what remains for the user.
+ *
+ * `source` must be parseable TypeScript. Files whose parse fails are the
+ * caller's concern — the codemod surfaces `collectFlowStepSites`'s throw.
+ */
+export function rewriteFlowCardinality(source: string, fileName?: string): RewriteResult {
+  const sites = collectFlowStepSites(source, fileName)
+  if (sites.length === 0) {
+    return { text: source, fills: [], unresolved: [] }
+  }
+
+  const lineEnding = detectLineEnding(source)
+  const lines = source.split(/\r?\n/)
+  const replacements = new Map<number, string>()
+  const fills: CardinalityFill[] = []
+  const unresolved: UnresolvedEdge[] = []
+
+  for (const site of sites) {
+    processSite(site, lines, replacements, fills, unresolved)
+  }
+
+  if (replacements.size === 0) return { text: source, fills: [], unresolved }
+
+  const rewritten = lines.map((line, i) => replacements.get(i) ?? line)
+  return { text: rewritten.join(lineEnding), fills, unresolved }
+}
+
+function processSite(
+  site: FlowStepSite,
+  lines: readonly string[],
+  replacements: Map<number, string>,
+  fills: CardinalityFill[],
+  unresolved: UnresolvedEdge[],
+): void {
+  // The `flow` check rejects invalid annotations, method shapes, and orphans
+  // as their own diagnostics — fixing them is the user's job. The codemod's
+  // only job is to fill missing cardinality on legal flow-step functions.
+  if (site.annotation.kind !== 'annotation') return
+  if (site.subject.shape !== 'function') return
+
+  const edges = site.annotation.annotation.downstream
+  if (edges.length === 0) return
+
+  const blockStart = site.commentLine - 1
+  const blockEnd = findBlockEnd(lines, blockStart)
+
+  // The parser produces one `DownstreamEdge` per `@downstream` tag in source
+  // order; scanning the JSDoc lines in the same order keeps the two streams
+  // aligned, so the Nth `@downstream` line corresponds to `edges[N]`.
+  let edgeIndex = -1
+  for (let i = blockStart; i <= blockEnd; i++) {
+    const raw = lines[i]
+    if (raw === undefined) continue
+    if (!isDownstreamLine(raw)) continue
+    edgeIndex++
+
+    const edge = edges[edgeIndex]
+    if (edge === undefined) continue
+    if (edge.cardinality !== null) continue
+
+    const target = `${edge.path}:${edge.symbol}`
+    const match = BARE_DOWNSTREAM.exec(raw)
+    if (match === null) {
+      unresolved.push({ line: i + 1, target, reason: 'non-trivial-form' })
+      continue
+    }
+
+    const classification = classifyEdge('', site, edge)
+    if (classification.structural === 'ambiguous') {
+      unresolved.push({ line: i + 1, target, reason: 'ambiguous' })
+      continue
+    }
+
+    const prefix = match[1] ?? ''
+    const targetText = match[2] ?? ''
+    replacements.set(i, `${prefix}${targetText} ${classification.structural}`)
+    fills.push({ line: i + 1, target, kind: classification.structural })
+  }
+}
+
+function findBlockEnd(lines: readonly string[], start: number): number {
+  for (let i = start; i < lines.length; i++) {
+    if ((lines[i] ?? '').includes('*/')) return i
+  }
+  return lines.length - 1
+}
+
+function detectLineEnding(source: string): string {
+  return source.includes('\r\n') ? '\r\n' : '\n'
+}
+
+// Matches `@downstream path:symbol` on a line by itself (with optional JSDoc
+// leader and trailing whitespace). The capture groups preserve the prefix and
+// the target verbatim so the rebuilt line differs from the original only by a
+// trailing ` step` or ` branch`.
+const BARE_DOWNSTREAM = /^(\s*\*?\s*@downstream\s+)(\S+:\S+)\s*$/
+
+// A weaker match used only to count `@downstream` lines so the codemod's
+// scanner stays aligned with the parser's edge ordering.
+const DOWNSTREAM_TAG = /^\s*\*?\s*@downstream\b/
+
+function isDownstreamLine(text: string): boolean {
+  return DOWNSTREAM_TAG.test(text)
+}

package/src/trace/codemod/run.ts

@@ -0,0 +1,80 @@
+// File-scanning wrapper around the cardinality codemod: reads each source
+// file, applies `rewriteFlowCardinality`, and writes the result back unless
+// `dryRun` is set. Mirrors `flow-check.ts`'s shape — file I/O lives here, the
+// rewrite logic stays pure in add-cardinality.ts.
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import {
+  rewriteFlowCardinality,
+  type CardinalityFill,
+  type UnresolvedEdge,
+} from './add-cardinality.js'
+
+export interface CodemodRunOptions {
+  readonly cwd: string
+  readonly files: readonly string[]
+  /** When true, compute everything but do not write to disk. */
+  readonly dryRun: boolean
+}
+
+export interface FileResult {
+  /** Source path relative to `cwd`. */
+  readonly file: string
+  readonly fills: readonly CardinalityFill[]
+  readonly unresolved: readonly UnresolvedEdge[]
+  /** True when the codemod produced a different text than the input. */
+  readonly changed: boolean
+}
+
+export interface CodemodRunResult {
+  /** One entry per file that had at least one fill or unresolved edge. */
+  readonly files: readonly FileResult[]
+  readonly totalFills: number
+  readonly totalUnresolved: number
+  readonly filesChanged: number
+}
+
+/** Runs the cardinality codemod across `files`. Missing or unparseable files are skipped. */
+export function runFlowCardinalityCodemod(opts: CodemodRunOptions): CodemodRunResult {
+  const fileResults: FileResult[] = []
+  let totalFills = 0
+  let totalUnresolved = 0
+  let filesChanged = 0
+
+  for (const file of opts.files) {
+    const abs = join(opts.cwd, file)
+    if (!existsSync(abs)) continue
+
+    const source = readFileSync(abs, 'utf-8')
+
+    let rewrite
+    try {
+      rewrite = rewriteFlowCardinality(source, file)
+    } catch {
+      // A file the AST parser cannot read — leave its syntax errors to the
+      // type checker, exactly as `flow-check.ts` does.
+      continue
+    }
+
+    if (rewrite.fills.length === 0 && rewrite.unresolved.length === 0) continue
+
+    const changed = rewrite.text !== source
+    if (changed && !opts.dryRun) {
+      writeFileSync(abs, rewrite.text, 'utf-8')
+    }
+
+    fileResults.push({
+      file,
+      fills: rewrite.fills,
+      unresolved: rewrite.unresolved,
+      changed,
+    })
+    totalFills += rewrite.fills.length
+    totalUnresolved += rewrite.unresolved.length
+    if (changed) filesChanged++
+  }
+
+  return { files: fileResults, totalFills, totalUnresolved, filesChanged }
+}

package/src/trace/entry/child-trace.ts

@@ -0,0 +1,21 @@
+// A trace for work a Flow runs under another tenant and principal. It hangs off
+// the Flow's own trace at the step open now, so the tenant it names can read it.
+
+import type { Flow } from '../../request/context/types.js'
+import { openTrace } from './open-trace.js'
+import type { TraceContext } from './trace-context.js'
+
+/** Opens a child of `flow`'s trace for `tenant` and `auth`, or returns `null` when the Flow is untraced. */
+export function openChildTrace(flow: Flow, tenant: string, auth: unknown): TraceContext | null {
+  const parent = flow.trace
+  if (parent === null) return null
+  return openTrace({
+    instance: flow.instance,
+    entryKind: parent.entryKind,
+    parent: { id: parent.id, rootId: parent.rootId, stepId: parent.buffer.openStepId },
+    tenant,
+    auth,
+    requestId: flow.requestId,
+    sessionId: flow.metadata?.sessionId ?? null,
+  })
+}

package/src/trace/entry/close-trace.ts

@@ -0,0 +1,87 @@
+// Closes the `trace` row an entry opened: stamps the final status and the
+// close time, and flushes the in-memory `trace_step` buffer in the same beat.
+// Like the open, the write is fire-and-forget and never throws — but it first
+// waits on `persisted`, so neither the closing `UPDATE` nor the step `INSERT`s
+// can outrun the opening `INSERT` and miss the row.
+//
+// **Ordering: step inserts settle before the status UPDATE.** Without this,
+// an outside observer polling the trace row sees `status='error'/'closed'`
+// the moment the UPDATE commits, but the step rows for that trace can still
+// be in flight — a race that flakes any test of the shape "wait for status,
+// then assert on step rows." Sequencing here makes the published status the
+// settled-trace signal it visually appears to be. The hot path is unaffected
+// because the caller ignores the returned promise; step-write failures are
+// already swallowed inside `flushSteps`, so the UPDATE still runs.
+//
+// A truncated trace (Q7) keeps its `truncated` status here: `truncateTrace`
+// already settled the cap-blowing path, and `closeTrace` running last must not
+// downgrade a casualty to `closed` / `error`. The buffer drain is still safe —
+// `truncateTrace` already drained it, and `__flowStep` records nothing after
+// truncation, so `drain()` returns the empty array.
+//
+// The returned promise settles once the step `INSERT`s and then the `UPDATE`
+// have — callers on the hot path ignore it (the close must not block the
+// entry's response), but it gives a test a handle to await before asserting
+// on rows.
+
+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 '../runtime/pending-writes.js'
+import { flushSteps } from '../runtime/flush-steps.js'
+import { copyTraceOnError } from '../retain/copy-on-error.js'
+import { withMaintenance } from '../../data/db/maintenance.js'
+import type { DB } from '../../data/db/index.js'
+import type { TraceContext } from './trace-context.js'
+
+/** How an entry ended — a clean return, or a thrown error. */
+export type TraceOutcome = 'closed' | 'error'
+
+/** Closes `ctx`'s trace row with `outcome` and flushes its step buffer. No-op when the entry ran untraced. */
+export function closeTrace(
+  instance: Manifold,
+  ctx: TraceContext | null,
+  outcome: TraceOutcome,
+): Promise<void> {
+  if (ctx === null) return Promise.resolve()
+  const closedAt = new Date()
+  return trackTraceWrite(ctx.persisted
+    .then(async () => {
+      const status: 'closed' | 'error' | 'truncated' = ctx.buffer.truncated ? 'truncated' : outcome
+      // Step inserts MUST settle before the status UPDATE — see file header
+      // for the race this prevents. `flushSteps` swallows its own errors, so
+      // a failed batch still lets the UPDATE proceed.
+      await flushSteps(instance, ctx.buffer.drain())
+      const db = instance.pool.getOrCreate(instance.config.database()).drizzle
+      const table = trace.table()
+      // The composite primary key is `[id, openedDay]` — both are matched so the
+      // UPDATE targets exactly one partition's one row.
+      const cols = getTableColumns(table) as Record<'id' | 'openedDay', Column>
+      // The pooled connection carries no tenant setting, so the UPDATE runs as a maintenance pass.
+      await 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, closedAt })
+          .where(and(eq(cols.id, ctx.id), eq(cols.openedDay, ctx.openedDay)))
+      })
+      // Copy errored / truncated traces to the cold set before their hot
+      // partition retires (Q4). For a truncated trace, `truncationDone` is the
+      // settle handle from `truncateTrace`; awaiting it ensures the cold row
+      // reflects `truncated_at_seq`. For a normal error close the handle is
+      // `null`, and `await null` is a no-op — no branch needed.
+      if (status !== 'closed') {
+        await ctx.buffer.truncationDone
+        await copyTraceOnError(db as unknown as DB, ctx.id)
+      }
+    })
+    .catch((err: unknown) => {
+      getBaseLogger().error(
+        { err, traceId: ctx.id },
+        'Failed to persist trace close — the trace row is stuck open',
+      )
+      void recordFaultFor(instance, 'trace-write', `trace close not persisted: ${faultMessage(err)}`, { traceId: ctx.id, step: 'close' })
+    }))
+}

package/src/trace/entry/finalize-trace.ts

@@ -0,0 +1,28 @@
+// Ties a trace's close to the settling of the entry's work: `closed` on a
+// clean return, `error` on a throw. An entry's work may be synchronous or a
+// promise — this handles both and hands the result straight back, so an
+// ingress can wrap its return value inline without restructuring.
+
+import type { Manifold } from '../../core/pipework.js'
+import { closeTrace } from './close-trace.js'
+import { isThenable } from '../runtime/thenable.js'
+import type { TraceContext } from './trace-context.js'
+
+/** Wraps `result`, closing `ctx`'s trace when it settles. Returns `result` unchanged. */
+export function finalizeTrace<T>(instance: Manifold, ctx: TraceContext | null, result: T): T {
+  if (ctx === null) return result
+  if (isThenable(result)) {
+    return result.then(
+      (value: unknown) => {
+        void closeTrace(instance, ctx, 'closed')
+        return value
+      },
+      (err: unknown) => {
+        void closeTrace(instance, ctx, 'error')
+        throw err
+      },
+    ) as T
+  }
+  void closeTrace(instance, ctx, 'closed')
+  return result
+}

package/src/trace/entry/open-trace.ts

@@ -0,0 +1,138 @@
+// Opens the `trace` row for an entry. The row is written eagerly — a trace
+// exists the moment an entry is reached — but the write itself is fire-and-
+// forget: the id and the tree wiring are computed synchronously, so the entry
+// pays no latency, and the `INSERT` runs in the background. Failure to persist
+// is logged, never thrown: a broken trace table must not break the request.
+//
+// The write goes through `instance.pool` directly, not the request transaction
+// — an errored request rolls back, but its trace must survive to be inspected.
+
+import { trackTraceWrite } from '../runtime/pending-writes.js'
+import { randomUUID } from 'node:crypto'
+import type { Manifold } from '../../core/pipework.js'
+import { getBaseLogger } from '../../core/logging/index.js'
+import { recordFaultFor, faultMessage } from '../../infra/alerts/faults.js'
+import { trace } from '../schema/trace.js'
+import { toDay } from '../partition/day.js'
+import { StepBuffer } from '../runtime/step-buffer.js'
+import type { TraceContext, TraceEntryKind } from './trace-context.js'
+
+const MS_PER_DAY = 86_400_000
+
+/**
+ * The parent reference openTrace actually consumes. Two shapes satisfy it:
+ * an in-process `TraceContext` (the active trace on the surrounding Flow) and
+ * a synthesized `{ id, rootId }` derived from an ingested W3C `traceparent`
+ * header. Either way, only the two fields are needed to wire the trace tree.
+ */
+export interface ParentTraceRef {
+  readonly id: string
+  readonly rootId: string
+  /** The step open on the parent when this entry began — written to `trace.parent_step_id`. */
+  readonly stepId?: string | null
+}
+
+export interface OpenTraceParams {
+  readonly instance: Manifold
+  readonly entryKind: TraceEntryKind
+  /** The parent trace, or `null` for a root entry. */
+  readonly parent: ParentTraceRef | null
+  readonly tenant: string | null
+  /** The entry's auth principal — `userId` is read off it when present. */
+  readonly auth: unknown
+  readonly requestId: string | null
+  readonly sessionId: string | null
+}
+
+/** Generates a trace id, wires it into the tree, and kicks off the opening `INSERT`. */
+export function openTrace(params: OpenTraceParams): TraceContext {
+  const id = randomUUID()
+  const openedAt = new Date()
+  const openedDay = toDay(openedAt)
+  const rootId = params.parent?.rootId ?? id
+  const expiresAt = new Date(
+    openedAt.getTime() + params.instance.config.trace.hotRetentionDays * MS_PER_DAY,
+  )
+
+  const persisted = insertTraceRow(params.instance, {
+    id,
+    openedDay,
+    rootId,
+    parentId: params.parent?.id ?? null,
+    parentStepId: params.parent?.stepId ?? null,
+    entryKind: params.entryKind,
+    status: 'open',
+    tenantId: params.tenant,
+    requestId: params.requestId,
+    sessionId: params.sessionId,
+    userId: extractUserId(params.auth),
+    openedAt,
+    closedAt: null,
+    expiresAt,
+    truncatedAtSeq: null,
+    release: params.instance.release,
+  })
+
+  // The step cap is `structuralMax × safetyFactor` (Q7). `structuralMax` is the
+  // longest chain of `step` edges through the flow graph, derived by
+  // `pipework check` from the `@downstream` annotations and pinned in
+  // `config.trace.structuralMax`. Unset → no cap; the truncation mechanism is
+  // live but never fires. The cap firing is a bug signal — DAG analysis was
+  // wrong, or unannotated recursion slipped validation — not a load condition.
+  const traceConfig = params.instance.config.trace
+  const cap = traceConfig.structuralMax !== undefined
+    ? traceConfig.structuralMax * traceConfig.safetyFactor
+    : Infinity
+  const buffer = new StepBuffer({
+    traceId: id,
+    traceDay: openedDay,
+    tenantId: params.tenant,
+    cap,
+    captureInputs: traceConfig.captureInputs,
+    maxExternalSteps: traceConfig.maxExternalSteps,
+  })
+
+  return { id, rootId, entryKind: params.entryKind, openedDay, persisted, buffer }
+}
+
+interface TraceRow {
+  readonly id: string
+  readonly openedDay: string
+  readonly rootId: string
+  readonly parentId: string | null
+  readonly parentStepId: string | null
+  readonly entryKind: TraceEntryKind
+  readonly status: 'open'
+  readonly tenantId: string | null
+  readonly requestId: string | null
+  readonly sessionId: string | null
+  readonly userId: string | null
+  readonly openedAt: Date
+  readonly closedAt: null
+  readonly expiresAt: Date
+  readonly truncatedAtSeq: null
+  readonly release: string | null
+}
+
+function insertTraceRow(instance: Manifold, row: TraceRow): Promise<void> {
+  const db = instance.pool.getOrCreate(instance.config.database()).drizzle
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Drizzle's insert needs the concrete runtime table type
+  return trackTraceWrite((db as any).insert(trace.table()).values(row)
+    .then(() => undefined)
+    .catch((err: unknown) => {
+      getBaseLogger().error(
+        { err, traceId: row.id },
+        'Failed to persist trace open — the trace row is missing',
+      )
+      void recordFaultFor(instance, 'trace-write', `trace open not persisted: ${faultMessage(err)}`, { traceId: row.id, step: 'open' })
+    }))
+}
+
+/** Reads `userId` off the auth principal, following the same convention the logger uses. */
+function extractUserId(auth: unknown): string | null {
+  if (auth !== null && typeof auth === 'object' && 'userId' in auth) {
+    const userId = (auth as { userId: unknown }).userId
+    if (typeof userId === 'string') return userId
+  }
+  return null
+}

package/src/trace/entry/parent-trace.ts

@@ -0,0 +1,20 @@
+// Traces form a tree. A new entry's parent is the trace already running on the
+// active Flow — a job enqueued and awaited inside a request, a nested test
+// context. With no active Flow (the common case for an inbound HTTP request or
+// a worker-claimed job), the new entry is a root.
+
+import { getContext } from '../../request/context/store.js'
+import type { TraceContext } from './trace-context.js'
+import type { ParentTraceRef } from './open-trace.js'
+
+/** The trace on the active Flow, or `null` when there is none — the new entry's parent. */
+export function parentTrace(): TraceContext | null {
+  return getContext()?.trace ?? null
+}
+
+/** The active trace as a parent reference carrying the step open on it, or `null` when there is none. */
+export function parentTraceRef(): ParentTraceRef | null {
+  const active = parentTrace()
+  if (active === null) return null
+  return { id: active.id, rootId: active.rootId, stepId: active.buffer.openStepId }
+}

package/src/trace/entry/parse-traceparent.ts

@@ -0,0 +1,39 @@
+// Parses the W3C `traceparent` HTTP header (Q10 — cross-team contract with
+// plumb). Format: `version-trace-id-parent-id-trace-flags`, version-00 only.
+// The spec is strict: any deviation from the format means the header is
+// invalid and the receiver MUST start a new trace as if it weren't there.
+// We return the trace-id formatted as a UUID so it can land in
+// `trace.parent_id` directly; the parent-id and trace-flags fields are
+// validated but not surfaced — pipework's parent_id wiring uses the
+// distributed trace-id, not the W3C parent-span-id.
+//
+// Spec: https://www.w3.org/TR/trace-context/#traceparent-header
+
+const TRACE_ID_RE = /^[0-9a-f]{32}$/
+const PARENT_ID_RE = /^[0-9a-f]{16}$/
+const FLAGS_RE = /^[0-9a-f]{2}$/
+const TRACE_ID_ZERO = '0'.repeat(32)
+const PARENT_ID_ZERO = '0'.repeat(16)
+
+/** A parsed traceparent — only the fields pipework actually wires through. */
+export interface ParsedTraceparent {
+  /** The W3C trace-id, formatted as a UUID for direct use in `trace.parent_id`. */
+  readonly traceId: string
+}
+
+/** Parses a `traceparent` header value; returns `null` for missing or malformed input. */
+export function parseTraceparent(header: string | string[] | undefined): ParsedTraceparent | null {
+  if (typeof header !== 'string') return null
+  const parts = header.split('-')
+  if (parts.length !== 4) return null
+  const [version, traceId, parentId, flags] = parts as [string, string, string, string]
+  if (version !== '00') return null
+  if (!TRACE_ID_RE.test(traceId) || traceId === TRACE_ID_ZERO) return null
+  if (!PARENT_ID_RE.test(parentId) || parentId === PARENT_ID_ZERO) return null
+  if (!FLAGS_RE.test(flags)) return null
+  return { traceId: formatAsUuid(traceId) }
+}
+
+function formatAsUuid(hex32: string): string {
+  return `${hex32.slice(0, 8)}-${hex32.slice(8, 12)}-${hex32.slice(12, 16)}-${hex32.slice(16, 20)}-${hex32.slice(20, 32)}`
+}

package/src/trace/entry/process-start.ts

@@ -0,0 +1,38 @@
+// The opening step of a trace that is not an ingress: a process start, a script
+// surface, a public script entry. It names which process did the work.
+
+import { randomUUID } from 'node:crypto'
+import { hostname } from 'node:os'
+import type { Manifold } from '../../core/pipework.js'
+import { serializeForTrace } from '../capture/bounded-serializer.js'
+import type { TraceContext } from './trace-context.js'
+
+export const PROCESS_START_REF = 'external:pipework.process.start'
+
+export interface ProcessStartInfo {
+  readonly phase: 'preStart' | 'script'
+  readonly surfaces: readonly string[]
+  readonly release: Manifold['release']
+}
+
+/** Stages the zero-length `external:pipework.process.start` step naming this process (host, pid, surfaces, release, phase). */
+export function stageProcessStart(trace: TraceContext, info: ProcessStartInfo): void {
+  const now = new Date()
+  trace.buffer.stageExternal({
+    id: randomUUID(),
+    parentStepId: null,
+    flowStepRef: PROCESS_START_REF,
+    status: 'ok',
+    startedAt: now,
+    completedAt: now,
+    durationMicros: 0n,
+    capturedInputs: [serializeForTrace({
+      host: hostname(),
+      pid: process.pid,
+      surfaces: info.surfaces,
+      release: info.release,
+      phase: info.phase,
+    })],
+    error: null,
+  })
+}

package/src/trace/entry/trace-context.ts

@@ -0,0 +1,26 @@
+// The trace's runtime handle on the Flow. Every Flow that runs under tracing
+// carries one; flow steps record `trace_step` rows into `buffer`, and a child
+// entry reads `id` / `rootId` to wire itself into the trace tree.
+
+import type { StepBuffer } from '../runtime/step-buffer.js'
+
+/** The ingress point a trace was opened at. Mirrors `traceFields.entryKind`. */
+export type TraceEntryKind = 'http' | 'job' | 'cron' | 'test'
+
+export interface TraceContext {
+  /** This trace's id — the `trace.id` of the row opened at the entry. */
+  readonly id: string
+  /** The root of the trace tree. Equals `id` for a root trace. */
+  readonly rootId: string
+  /** The ingress kind the trace was opened at — a child trace opened inside the entry (asLink) copies it. */
+  readonly entryKind: TraceEntryKind
+  /** The UTC calendar day the trace opened — the partition its row lives in. */
+  readonly openedDay: string
+  /**
+   * Resolves once the opening `INSERT` has settled. The closing `UPDATE` waits
+   * on this so it can never race ahead of the row it means to close.
+   */
+  readonly persisted: Promise<void>
+  /** The in-memory `trace_step` buffer flow steps record into — drained at close. */
+  readonly buffer: StepBuffer
+}

package/src/trace/entry/tracing-enabled.ts

@@ -0,0 +1,10 @@
+// Tracing is opt-in: a Blueprint with no `trace` block runs untraced and pays
+// zero overhead at the ingress points. Configuring `trace` — even as `{}`, which
+// resolves entirely to defaults — turns it on.
+
+import type { Manifold } from '../../core/pipework.js'
+
+/** Whether trace rows should be opened for this manifold's entries. */
+export function isTracingEnabled(instance: Manifold): boolean {
+  return instance.config.raw.trace !== undefined
+}