pipework 0.252.0 → 0.253.0

package/src/core/pipework.ts

@@ -0,0 +1,566 @@
+import type { ResolvedConfig } from './config/load.js'
+import type { ResolvedDatabase } from './config/load.js'
+import { loadConfig as parseConfig } from './config/load.js'
+import type { AcceptReadonly } from '../data/db/readonly.js'
+import type { BlueprintInput } from './config/schema.js'
+import type { EnvDefs, ResolveEnvDefs } from './config/env-types.js'
+import type { ManagedConnection, ConnectionRole } from '../data/db/pool.js'
+import { createManagedConnection } from '../data/db/pool.js'
+import { createReservationPublisher, computeBudget, BUDGET_QUERY, type ConnectionBudget } from '../data/db/reservation.js'
+import { sql } from '../data/db/sql.js'
+import { InvariantViolation } from '../invariants/assert.js'
+import type { Surface, SurfaceContext, SurfaceKind } from './surface/types.js'
+import type { StartResult } from './surface/start.js'
+import { startSurfaces } from './surface/start.js'
+import { runScript } from '../async/jobs/run-script.js'
+import { orchestrateStartup } from './lifecycle/startup.js'
+import type { LifecycleConfig, StartupHook, ShutdownHook } from './lifecycle/types.js'
+import { getBaseLogger } from './logging/index.js'
+import { validateStartup, type ValidationContext } from './validation/startup.js'
+import { ownerSystemChannelWarnings } from './validation/rls-role.js'
+import { createJobContext } from '../request/context/create.js'
+import { runInContext } from '../request/context/store.js'
+
+/** The application instance — holds config, connection pools, surfaces, and lifecycle. */
+export interface Manifold<TEnv extends EnvDefs = EnvDefs> {
+  /** Resolved configuration derived from the Blueprint passed to createManifold. */
+  readonly config: ResolvedConfig
+  /** The release this process runs, read from the variable `release.env` names; null when no release is configured or the variable is unset or empty. Written on every trace and on the job row of the worker that ran it. */
+  readonly release: string | null
+  /** Typed environment variables resolved from the `env` config field. */
+  readonly env: Readonly<ResolveEnvDefs<TEnv>>
+  /** Database connection pool manager — use `pool.getOrCreate(config.database(name))` outside managed contexts. */
+  readonly pool: PoolState
+  /** Test isolation lifecycle tracker — used internally by pipework/test. */
+  readonly isolation: IsolationState
+  /** Connection leak detector — tracks active connections for assertNoLeaks(). */
+  readonly connections: ConnectionTracker
+  /** Returns the names of all registered surfaces (http, worker, script). */
+  surfaceNames(): readonly string[]
+  /** Returns a copy of the surface map keyed by surface name. */
+  surfaceMap(): Readonly<Record<string, Surface>>
+  /**
+   * Starts all surfaces and installs SIGTERM/SIGINT handlers. Throws if already started.
+   * `options.port` is the port for the http surface that declares none (what `serve --port` / `PORT` set).
+   */
+  start(options?: StartOptions): Promise<void>
+  /**
+   * Runs the startup checks that need no database (domain integrity, surfaces) and throws
+   * `StartupValidationError` listing every issue. What `start()` runs first; call it from an
+   * app's test to catch what `serve` would refuse.
+   */
+  validate(): Promise<void>
+  /**
+   * Runs pre-shutdown hooks, tells every surface to stop accepting work at once, drains them up to
+   * `lifecycle.drainTimeoutMs`, then closes all pools (5s bound). At the deadline the surfaces are forced
+   * (open sockets destroyed, in-flight jobs aborted and handed back) and `forced` is true. A SIGTERM/SIGINT
+   * handler exits 1 when forced or when this rejects, else 0.
+   */
+  stop(): Promise<StopResult>
+  /** Runs a callback in a managed job context — the canonical entry point for seed scripts and one-off tasks. */
+  seed<T>(fn: () => T | Promise<T>, options?: SeedOptions): Promise<T>
+  /**
+   * Runs `fn` as a traced process-level flow: its own trace (phase `script`, surfaces `[name]`, job type `name`),
+   * opened with a step naming this process (host, pid, release) and closed when `fn` settles. With a tenant, the
+   * default database's transaction is bound to the flow. It is what an app uses for work in a standalone script.
+   */
+  script<T>(name: string, fn: () => T | Promise<T>, options?: ScriptOptions): Promise<T>
+}
+
+/** What {@link Manifold.stop} resolves with: `forced` is true when the drain deadline fired. */
+export interface StopResult {
+  readonly forced: boolean
+}
+
+/** Options for {@link Manifold.script}. */
+export interface ScriptOptions {
+  tenant?: string | null
+  auth?: unknown
+}
+
+/** Options for {@link Manifold.start}. */
+export interface StartOptions {
+  /** The port for the http surface that declares none. */
+  port?: number
+  /**
+   * Start only the surfaces of these kinds (for a worker-only process: `['worker']`). Unset starts
+   * every surface. Every surface is still validated; a filter that matches none is a `ConfigError`.
+   */
+  kinds?: readonly SurfaceKind[]
+}
+
+/** ALS context the {@link Manifold.seed} callback runs under — tenant scope, auth principal, and job type. */
+export interface SeedOptions {
+  tenant?: string | null
+  auth?: unknown
+  jobType?: string
+}
+
+/** Manages database connection pools keyed by database name. */
+export interface PoolState {
+  /**
+   * Returns existing pool or creates one for this database config and role. With no role the
+   * default follows the database's mode: `system` (the platform role, `config.systemUrl`) where
+   * `rls.platformRole` is set, `owner` otherwise. The `app` role connects via `config.appUrl`
+   * (falling back to `url` when unset). An explicit `'owner'` always gives the owner connection;
+   * in platform mode that is for DDL only, and `label` names the caller in the one info line it logs.
+   */
+  getOrCreate(config: ResolvedDatabase, role?: ConnectionRole, label?: string): ManagedConnection
+  /** How many owner-role connections this pool has created (test overrides excluded). In platform mode a running manifold keeps it at 0. */
+  ownerConnectionsCreated(): number
+  /**
+   * The connections this database's server can still give this process without starving other
+   * pipework processes: `max_connections` less the reserved slots, the connections held now, and
+   * every other publishing process's unopened reservation. Needs `pool.publishReservation: true` on
+   * the databases whose pools should count. Waits for this process's own pending publication first.
+   */
+  connectionBudget(name: string): Promise<ConnectionBudget>
+  /** Returns pool by name, or undefined if not yet created. */
+  get(name: string): ManagedConnection | undefined
+  /** True when a test-harness override is registered for this database — collapsed (transaction-isolation) mode, where every role shares the single rolled-back connection. */
+  isOverridden(name: string): boolean
+  /** Closes all managed connections; with `timeoutSeconds`, queries still running then are cancelled. */
+  closeAll(options?: { timeoutSeconds?: number }): Promise<void>
+  /** Number of active connection pools. */
+  count(): number
+  /** Registers a test-mode connection override. getOrCreate() returns overrides before creating new connections. */
+  override(name: string, conn: ManagedConnection): void
+  /** Removes all test-mode connection overrides. */
+  clearOverrides(): void
+}
+
+/** Tracks test isolation lifecycle — detects leaked isolation contexts. */
+export interface IsolationState {
+  /** Marks the start of an isolation context (e.g. BEGIN in a test). */
+  markBegin(): void
+  /** Marks the end of an isolation context (e.g. ROLLBACK in a test). */
+  markEnd(): void
+  /** Throws InvariantViolation if any isolation contexts are still active. */
+  assertClean(): void
+  /** Returns counts of active, total begins, and total ends. */
+  stats(): { active: number; totalBegins: number; totalEnds: number }
+  /** Resets all counters — only for test infrastructure. */
+  reset(): void
+}
+
+/** Tracks active database connections for leak detection. */
+export interface ConnectionTracker {
+  /** Records a new active connection with its origin context. */
+  track(id: string, name: string, context: string): void
+  /** Marks a connection as released. */
+  release(id: string): void
+  /** Number of currently tracked connections. */
+  activeCount(): number
+  /** Throws InvariantViolation if active connections exceed maxExpected. */
+  assertNoLeaks(maxExpected: number): void
+}
+
+/**
+ * Creates the Pipework application instance. This is the entry point for every Pipework app.
+ * Define in `pipework.config.ts` and export as default.
+ *
+ * The `env` field declares the app's environment variables — the canonical
+ * home for runtime config (ports, service tokens, bucket names, flags) in
+ * place of scattered `process.env` reads. Each variable is read once at config
+ * load, validated and coerced to its declared type (loud error on a bad or
+ * missing-required value), and exposed typed on `manifold.env`.
+ *
+ * @example
+ * const manifold = createManifold({
+ *   databases: { app: { url: 'DATABASE_URL', testUrl: 'DATABASE_URL_TEST' } },
+ *   env: {
+ *     PORT: { type: 'number', defaults: { development: '3000', test: '0' } },
+ *     S3_BUCKET: { type: 'string', required: true },
+ *     API_TOKEN: { type: 'string', required: true, sensitive: true },
+ *   },
+ * })
+ * manifold.env.PORT       // number — from process.env.PORT, or the per-environment default
+ * manifold.env.S3_BUCKET  // string — startup fails loudly if unset
+ * export default manifold
+ */
+export function createManifold<const TEnv extends EnvDefs = EnvDefs>(
+  raw: AcceptReadonly<Omit<BlueprintInput, 'env'>> & {
+    env?: TEnv | undefined
+    surfaces?: Record<string, Surface>
+    lifecycle?: LifecycleConfig
+  },
+): Manifold<TEnv> {
+  const { surfaces: surfacesDef, lifecycle: lifecycleDef, ...blueprintRaw } = raw
+  const config = parseConfig(blueprintRaw)
+  const pool = createPoolState(config)
+  const isolation = createIsolationState()
+  const connections = createConnectionTracker()
+  const surfaces = surfacesDef ?? {}
+  const lifecycleConfig = lifecycleDef ?? {}
+
+  // The database queue migrations land in: the sole database, or the declared
+  // defaultDatabase. Ambiguous multi-DB configs (no default) already fail at
+  // `pipework generate`, so skipping there loses nothing.
+  const startupContext = (connectivity: boolean): ValidationContext => {
+    const names = config.databaseNames()
+    const defaultDbName = names.length === 1 ? names[0] : config.raw.defaultDatabase
+    return {
+      configuredDatabases: names,
+      environment: config.environment,
+      surfaces,
+      defaultDbAvailable: names.length === 1,
+      ...(connectivity
+        ? {
+            databases: config.databases(),
+            defaultDatabase: defaultDbName !== undefined ? config.database(defaultDbName) : undefined,
+          }
+        : { connectivityCheck: false }),
+    }
+  }
+
+  let running: StartResult | null = null
+  let signalCleanup: (() => void) | null = null
+
+  const manifold: Manifold<TEnv> = {
+    config,
+    release: config.release,
+    env: config.env as ResolveEnvDefs<TEnv>,
+    pool,
+    isolation,
+    connections,
+
+    surfaceNames(): readonly string[] {
+      return Object.keys(surfaces)
+    },
+
+    surfaceMap(): Readonly<Record<string, Surface>> {
+      return { ...surfaces }
+    },
+
+    async start(options?: StartOptions): Promise<void> {
+      if (running !== null) {
+        throw new Error(
+          '[pipework] Manifold is already started.\n\n' +
+          '  Call stop() before starting again.\n',
+        )
+      }
+
+      const startupOpts: import('./lifecycle/startup.js').StartupOptions = {}
+      if (lifecycleConfig.preStart !== undefined) {
+        ;(startupOpts as { hooks: readonly StartupHook[] }).hooks = lifecycleConfig.preStart as readonly StartupHook[]
+      }
+      if (lifecycleConfig.startupTimeoutMs !== undefined) {
+        ;(startupOpts as { timeoutMs: number }).timeoutMs = lifecycleConfig.startupTimeoutMs
+      }
+      await orchestrateStartup(manifold, startupOpts)
+
+      await validateStartup(startupContext(true))
+      for (const message of ownerSystemChannelWarnings(config.databases())) getBaseLogger().warn(message)
+
+      const context: SurfaceContext = manifold
+      running = await startSurfaces(context, config, surfaces, {
+        ...(options?.port === undefined ? {} : { port: options.port }),
+        ...(options?.kinds === undefined ? {} : { kinds: options.kinds }),
+      })
+
+      signalCleanup = installSignalHandlers(manifold, lifecycleConfig.drainTimeoutMs ?? 30_000)
+    },
+
+    async validate(): Promise<void> {
+      await validateStartup(startupContext(false))
+    },
+
+    async seed<T>(fn: () => T | Promise<T>, options?: SeedOptions): Promise<T> {
+      const ctx = createJobContext({
+        instance: manifold,
+        jobType: options?.jobType ?? 'seed',
+        auth: options?.auth ?? null,
+        tenant: options?.tenant ?? null,
+      })
+      return runInContext(ctx, fn)
+    },
+
+    async script<T>(name: string, fn: () => T | Promise<T>, options?: ScriptOptions): Promise<T> {
+      return runScript(manifold, fn, {
+        jobType: name,
+        tenant: options?.tenant ?? null,
+        auth: options?.auth ?? null,
+        process: { phase: 'script', surfaces: [name] },
+      })
+    },
+
+    async stop(): Promise<StopResult> {
+      const logger = getBaseLogger()
+      const deadlineMs = lifecycleConfig.drainTimeoutMs ?? 30_000
+
+      logger.info({ deadlineMs }, 'Shutdown initiated')
+
+      if (signalCleanup !== null) {
+        signalCleanup()
+        signalCleanup = null
+      }
+
+      if (lifecycleConfig.preShutdown) {
+        for (const hook of lifecycleConfig.preShutdown) {
+          try {
+            logger.info({ hook: hook.name }, 'Running pre-shutdown hook')
+            await (hook as ShutdownHook).execute()
+          } catch (err) {
+            logger.error({ hook: hook.name, err }, 'Pre-shutdown hook failed')
+          }
+        }
+      }
+
+      let forced = false
+      const stopFailure: { failed: boolean; err?: unknown } = { failed: false }
+
+      if (running !== null) {
+        const stopping = running
+        logger.info({ surfaces: [...stopping.handles.keys()] }, 'Stopping surfaces')
+        const controller = new AbortController()
+        const settled = stopping.stop(controller.signal).then(
+          () => 'done' as const,
+          (err: unknown) => { stopFailure.failed = true; stopFailure.err = err; return 'done' as const },
+        )
+
+        const drained = await raceDelay(settled, deadlineMs)
+        if (drained === 'timeout') {
+          forced = true
+          logger.warn({ label: 'Surface shutdown', deadlineMs }, `Surface shutdown exceeded ${deadlineMs}ms deadline`)
+          logger.warn({ deadlineMs }, 'Surface shutdown exceeded deadline — forcing close')
+          controller.abort()
+          const returned = await raceDelay(settled, FORCE_WAIT_MS)
+          if (returned === 'timeout') {
+            logger.error(
+              { surfaces: stopping.pending(), waitedMs: FORCE_WAIT_MS },
+              'Surfaces still running after forced shutdown; closing pools anyway',
+            )
+          }
+        }
+        running = null
+      }
+
+      logger.info('Closing connection pools')
+      await pool.closeAll({ timeoutSeconds: POOL_CLOSE_TIMEOUT_S })
+      logger.info('Shutdown complete')
+
+      if (stopFailure.failed) throw stopFailure.err
+      return { forced }
+    },
+  }
+
+  return manifold
+}
+
+const FORCE_WAIT_MS = 5_000
+const POOL_CLOSE_TIMEOUT_S = 5
+const EXIT_BACKSTOP_MS = 15_000
+
+/** Resolves with `work`'s value, or `'timeout'` after `ms`; the timer never holds the process open. */
+async function raceDelay<T>(work: Promise<T>, ms: number): Promise<T | 'timeout'> {
+  let timer: NodeJS.Timeout | undefined
+  const timeout = new Promise<'timeout'>((resolve) => {
+    timer = setTimeout(() => resolve('timeout'), ms)
+    timer.unref()
+  })
+  try {
+    return await Promise.race([work, timeout])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function installSignalHandlers(manifold: Manifold, drainTimeoutMs: number): () => void {
+  const logger = getBaseLogger()
+  let stopping = false
+
+  const handler = (signal: string) => {
+    if (stopping) return
+    stopping = true
+    logger.info({ signal }, 'Shutdown signal received')
+
+    // Backstop: a hang in a pre-shutdown hook or a pool must still end the process.
+    const backstop = setTimeout(() => {
+      logger.fatal({ signal, backstopMs: drainTimeoutMs + EXIT_BACKSTOP_MS }, 'Shutdown did not finish; exiting')
+      process.exit(1)
+    }, drainTimeoutMs + EXIT_BACKSTOP_MS)
+    backstop.unref()
+
+    void manifold.stop().then(({ forced }) => {
+      process.exit(forced ? 1 : 0)
+    }).catch((err) => {
+      logger.error({ err }, 'Error during shutdown')
+      process.exit(1)
+    })
+  }
+
+  const sigterm = () => handler('SIGTERM')
+  const sigint = () => handler('SIGINT')
+
+  process.on('SIGTERM', sigterm)
+  process.on('SIGINT', sigint)
+
+  return () => {
+    process.removeListener('SIGTERM', sigterm)
+    process.removeListener('SIGINT', sigint)
+  }
+}
+
+function createPoolState(resolvedConfig: ResolvedConfig): PoolState {
+  const map = new Map<string, ManagedConnection>()
+  const overrides = new Map<string, ManagedConnection>()
+  let ownerCreated = 0
+  const reservations = createReservationPublisher()
+
+  return {
+    getOrCreate(config: ResolvedDatabase, explicitRole?: ConnectionRole, label?: string): ManagedConnection {
+      const platform = config.rls?.platformRole !== undefined
+      const role: ConnectionRole = explicitRole ?? (platform ? 'system' : 'owner')
+      const key = role === 'owner' ? config.name : `${config.name}::${role}`
+
+      // Role-specific override first; fall back to the base (owner) override so a
+      // test running under transaction-isolation keeps every role on the single
+      // rolled-back connection. A real app-role connection is only created when no
+      // override is registered (i.e. production / database-isolation).
+      const overridden = overrides.get(key) ?? overrides.get(config.name)
+      if (overridden) return overridden
+
+      if (platform && explicitRole === 'owner') {
+        getBaseLogger().info(
+          { database: config.name, caller: label ?? 'unlabelled' },
+          `Owner-role connection requested on platform-mode database "${config.name}" by ${label ?? 'an unlabelled caller'}`,
+        )
+      }
+
+      const existing = map.get(key)
+      if (existing) return existing
+
+      const roleUrl = role === 'app' ? config.appUrl : role === 'system' ? config.systemUrl : undefined
+      const effectiveConfig = roleUrl !== undefined ? { ...config, url: roleUrl } : config
+      const publishing = config.pool.publishReservation === true
+      const release = publishing ? reservations.reserve(effectiveConfig.url, config.pool.max) : undefined
+      const managed = createManagedConnection(
+        effectiveConfig,
+        () => { map.delete(key); release?.() },
+        resolvedConfig.observability,
+        publishing ? reservations.poolTag : undefined,
+      )
+      map.set(key, managed)
+      if (role === 'owner') ownerCreated++
+      return managed
+    },
+
+    ownerConnectionsCreated(): number {
+      return ownerCreated
+    },
+
+    async connectionBudget(name: string): Promise<ConnectionBudget> {
+      const config = resolvedConfig.database(name)
+      await reservations.settled()
+      const rows = await this.getOrCreate(config).drizzle.execute(sql.raw(BUDGET_QUERY))
+      const row = rows[0] as unknown as Parameters<typeof computeBudget>[0]
+      return computeBudget(row, reservations.id)
+    },
+
+    get(name: string): ManagedConnection | undefined {
+      return overrides.get(name) ?? map.get(name)
+    },
+
+    isOverridden(name: string): boolean {
+      return overrides.has(name)
+    },
+
+    async closeAll(options?: { timeoutSeconds?: number }): Promise<void> {
+      const closing = [...map.values()].map(c => c.close(options))
+      await Promise.all(closing)
+      await reservations.closeAll()
+      overrides.clear()
+    },
+
+    count(): number {
+      return map.size + overrides.size
+    },
+
+    override(name: string, conn: ManagedConnection): void {
+      overrides.set(name, conn)
+    },
+
+    clearOverrides(): void {
+      overrides.clear()
+    },
+  }
+}
+
+function createIsolationState(): IsolationState {
+  let active = 0
+  let totalBegins = 0
+  let totalEnds = 0
+
+  return {
+    markBegin() {
+      active++
+      totalBegins++
+    },
+
+    markEnd() {
+      if (active <= 0) {
+        throw new InvariantViolation('isolation-end-without-begin', {
+          activeIsolationContexts: active,
+          totalBegins,
+          totalEnds,
+        })
+      }
+      active--
+      totalEnds++
+    },
+
+    assertClean() {
+      if (active !== 0) {
+        throw new InvariantViolation('isolation-context-leak', {
+          activeIsolationContexts: active,
+          totalBegins,
+          totalEnds,
+          delta: totalBegins - totalEnds,
+        })
+      }
+    },
+
+    stats() {
+      return { active, totalBegins, totalEnds }
+    },
+
+    reset() {
+      active = 0
+      totalBegins = 0
+      totalEnds = 0
+    },
+  }
+}
+
+function createConnectionTracker(): ConnectionTracker {
+  const tracked = new Map<string, { name: string; createdAt: number; context: string }>()
+
+  return {
+    track(id: string, name: string, context: string) {
+      tracked.set(id, { name, createdAt: Date.now(), context })
+    },
+
+    release(id: string) {
+      tracked.delete(id)
+    },
+
+    activeCount() {
+      return tracked.size
+    },
+
+    assertNoLeaks(maxExpected: number) {
+      if (tracked.size > maxExpected) {
+        throw new InvariantViolation('connection-pool-bounded', {
+          active: tracked.size,
+          maxExpected,
+          connections: [...tracked.entries()].map(([id, c]) => ({
+            id,
+            name: c.name,
+            age_ms: Date.now() - c.createdAt,
+            context: c.context,
+          })),
+        })
+      }
+    },
+  }
+}

package/src/core/runtime/broker.ts

@@ -0,0 +1,69 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { readFileSync } from 'node:fs'
+import type { Flow } from '../../request/context/types.js'
+
+// The version this physical pipework copy reports. Read from the package.json that
+// sits three levels above this module — correct whether running from `dist/core/
+// runtime/broker.js` (→ dist/../package.json) or `src/core/runtime/broker.ts`
+// under a type-stripping loader (→ repo-root package.json). Falls back to a sentinel
+// if the file can't be resolved (e.g. an esbuild bundle relocates this module); two
+// copies that both fall back compare equal and simply share the slot, which is the
+// desired "N copies behave as one" outcome.
+// Stryker disable all: readVersion runs only at module load (static init); ignoreStatic makes its
+// mutants unreachable. The version it produces is exercised by the runtime() version-guard tests.
+function readVersion(): string {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(new URL('../../../package.json', import.meta.url), 'utf8'),
+    ) as { version?: string }
+    return pkg.version ?? '0.0.0-unknown'
+  } catch {
+    return '0.0.0-unknown'
+  }
+}
+// Stryker restore all
+
+export const VERSION = readVersion()
+
+// Cross-realm singleton broker. When a self-contained pipework workspace consumes
+// a shared library that ALSO imports pipework at runtime, pnpm resolves two physical
+// copies of pipework. Each copy's module-level singletons (the request ALS) would
+// otherwise be distinct objects, so a context entered by one copy is invisible to
+// `pipe()` in the other. Pinning the ALS to a process-global slot keyed by a global
+// Symbol makes every physical copy of the SAME version share one AsyncLocalStorage —
+// the property the `link:`-shared-leaf topology needs. Two copies of DIFFERENT
+// versions must not share (their Flow shapes may diverge), so the second one throws
+// an actionable error instead of silently forking.
+// Stryker disable next-line StringLiteral: static module-init constant; ignoreStatic makes the mutant
+// unreachable. The slot's identity is covered by the runtime() broker tests.
+const SLOT = Symbol.for('pipework.runtime')
+
+interface RuntimeSlot {
+  readonly version: string
+  readonly flowStorage: AsyncLocalStorage<Flow>
+}
+
+export function runtime(): RuntimeSlot {
+  const slots = globalThis as unknown as Record<symbol, RuntimeSlot | undefined>
+  const existing = slots[SLOT]
+  if (existing !== undefined) {
+    if (existing.version !== VERSION) {
+      throw new Error(
+        '[pipework] Two incompatible pipework versions are loaded in one process:\n\n' +
+        `  ${existing.version} (already initialized) and ${VERSION} (loading now).\n\n` +
+        '  A shared library that imports pipework at runtime must resolve the SAME\n' +
+        '  version as the workspace consuming it. Otherwise their AsyncLocalStorage\n' +
+        '  contexts and error classes are distinct objects, and a context entered by\n' +
+        '  one copy is invisible to pipe() in the other (no active context; 403→500).\n\n' +
+        '  Fix: align the leaf library and the workspace to a single pipework version.\n',
+      )
+    }
+    return existing
+  }
+  const fresh: RuntimeSlot = {
+    version: VERSION,
+    flowStorage: new AsyncLocalStorage<Flow>(),
+  }
+  slots[SLOT] = fresh
+  return fresh
+}