pipework 0.251.0 → 0.252.1

package/src/core/config/schema.ts

@@ -0,0 +1,488 @@
+import { z } from 'zod/v4'
+import type { StatementObserver } from './statement-observer.js'
+
+const SETTING_NAME = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/
+
+const databaseSchema = z.object({
+  url: z.string().describe('Environment variable name that holds the connection URL'),
+  testUrl: z.string().optional().describe('Environment variable name for the test database URL — required when environment is "test"'),
+  adminUrl: z.string().optional().describe('Environment variable name for the admin connection URL — used by `pipework db setup`'),
+  appUrl: z.string().optional().describe('Environment variable name for the runtime app-role connection URL — a non-owner, non-BYPASSRLS role that RLS policies enforce against. Runtime transactions use this; falls back to url when unset (RLS then inert).'),
+  appTestUrl: z.string().optional().describe('Environment variable name for the test app-role connection URL'),
+  systemUrl: z.string().optional().describe('Environment variable name for the platform-role connection URL — the role `pipe.system()` and `pipe.door()` run on when `rls.platformRole` is set. Must be a non-owner, non-BYPASSRLS, non-superuser role named `rls.platformRole`; it reaches a tenant table only through a declared door.'),
+  systemTestUrl: z.string().optional().describe('Environment variable name for the test platform-role connection URL'),
+  testOwnerUrl: z.string().optional().describe('Environment variable name for the connection URL whose ROLE migrates the test template — test mode only. Production migrates as the database owner, so a SECURITY DEFINER function a migration creates runs with that role\'s rights; in test the same function used to be owned by the ordinary test login and behaved differently. Point this at a role that owns migrated objects the way production does (typically BYPASSRLS). Only the template\'s migrations run on it: the template is still created, cloned, and connected to as testUrl, so the RLS bootstrap probe and tenant isolation are unchanged.'),
+  schema: z.union([z.string(), z.array(z.string())]).optional().describe('Path(s) or glob(s) to Drizzle table definition files, relative to repo root'),
+  migrations: z.string().optional().describe('Path to migrations directory, relative to repo root'),
+  extensions: z.array(z.string()).optional().describe('PostgreSQL extensions to ensure exist'),
+  migrationTable: z.string().optional().describe('Custom migration tracking table name'),
+  pool: z.object({
+    max: z.number().int().positive().optional(),
+    idleTimeout: z.number().int().nonnegative().optional(),
+    publishReservation: z.boolean().optional().describe('Publish this database\'s pool capacity (the sum of its pools\' `max`) to the server as pools are created and closed, so `pool.connectionBudget(name)` in any pipework process on the server can subtract it. Adds one presence connection per server and tags pool connections with application_name "pipework:<id>" (a `settings.application_name` of your own wins, and those connections are then counted as held but not attributed to this process). Default false.'),
+    settings: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).superRefine((settings, ctx) => {
+      for (const name of Object.keys(settings)) {
+        if (!SETTING_NAME.test(name)) {
+          ctx.addIssue({
+            code: 'custom',
+            path: [name],
+            message: `"${name}" is not a valid session setting name: use letters, digits and underscores, optionally one dot for a custom setting (for example "statement_timeout" or "myapp.tenant"). Fix: rename the key.`,
+          })
+        }
+      }
+    }).optional().describe('Session settings (GUCs) sent in the startup packet of every pooled connection, so a connection replaced at max_lifetime carries them again. An unknown non-dotted name makes the connection fail.'),
+  }).optional(),
+  rls: z.object({
+    sessionVar: z.string().default('pipework.tenant_id'),
+    force: z.boolean().default(true),
+    platformRole: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, 'platformRole must be a plain Postgres role name (letters, digits, underscores)').optional().describe('Name of the platform role (set `systemUrl` to a connection as it). Setting it turns platform mode on: the system channel runs on that role, generated policies name it, and a tenant table is readable by it only through a door declared in `doors`.'),
+  }).optional(),
+}).superRefine((db, ctx) => {
+  const platformRole = db.rls?.platformRole
+  if (db.systemUrl !== undefined && platformRole === undefined) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['systemUrl'],
+      message: '`systemUrl` is set but `rls.platformRole` is not. Fix: name the platform role in `rls: { platformRole: \'...\' }`, or remove `systemUrl`.',
+    })
+  }
+  if (platformRole !== undefined && db.systemUrl === undefined) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['rls', 'platformRole'],
+      message: `\`rls.platformRole\` ("${platformRole}") is set but \`systemUrl\` is not. Fix: set \`systemUrl\` (and \`systemTestUrl\`) to the environment variable that holds the connection URL for that role.`,
+    })
+  }
+})
+
+const DOOR_NAME = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/
+
+const doorSchema = z.object({
+  table: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, 'table is a plain SQL table name').describe('SQL name of the tenant-scoped table the door opens to SELECT'),
+  database: z.string().optional().describe('Database the table lives in; defaults to the default database'),
+  reason: z.string().min(1).describe('Why platform code reads this table across tenants'),
+})
+
+const testIsolationStrategy = z.enum(['transaction', 'database', 'container'])
+
+const testSchema = z.object({
+  isolation: testIsolationStrategy.default('transaction'),
+  templateBuildWaitMs: z.number().int().positive().optional().describe(
+    'How long a test process waits for another process to finish building the shared template before failing (default 120000)',
+  ),
+  dropBatchSize: z.number().int().positive().optional().describe(
+    'How many finished per-file test databases pile up before they are dropped together (default 8). Every DROP DATABASE forces an immediate cluster-wide checkpoint that the dropping backend waits out, so dropping one per test file puts that wait on every teardown; 1 restores the drop-per-file behaviour',
+  ),
+  databasePerFile: z.boolean().optional().describe(
+    'Give every test file its own freshly cloned database (default false). By default a test process clones its database once and returns it to the template\'s state between files, cloning again only when a file changed something a reset cannot undo (schema, database settings, prepared transactions, materialized views). true restores a clone and a queued drop per file; each clone writes the whole template to disk and each drop forces a checkpoint. A reset restores: every row of every table (cleared and reloaded to the clone\'s contents, even a change rolled back), every sequence, and the database\'s name (it is renamed before each file, so a timer, job loop or pool left by an earlier file cannot reach the next one\'s database). It does not restore, and the next file takes a fresh clone instead: schema (tables, columns, indexes, constraints, functions, triggers, policies, types, extensions), ALTER DATABASE settings and privileges, large objects, materialized view contents, prepared transactions, and rows of a table row-level security hides from the admin role (one it does not own); with such a table the database is not kept at all. Never restored: anything outside the database (roles and their settings, other databases, files, S3, caches in your process, module state, timers) and server statistics',
+  ),
+  setupStallMs: z.number().int().positive().optional().describe(
+    'How long test setup may make no progress before it fails by name (default 120000). The bound is on phase advance, not on total elapsed time, so a healthy setup queued behind other processes never trips it',
+  ),
+  statementTimeoutMs: z.number().int().nonnegative().optional().describe(
+    'statement_timeout set on every per-test database (default 120000; 0 disables). A test process killed mid-statement leaves a backend that runs to completion — Postgres notices a dead client only when it next writes to the socket — holding locks and blocking the drop',
+  ),
+  idleInTransactionTimeoutMs: z.number().int().nonnegative().optional().describe(
+    'idle_in_transaction_session_timeout set on every per-test database (default 120000; 0 disables). Reaps a backend left inside an open transaction by a process killed between statements',
+  ),
+  clientCheckIntervalMs: z.number().int().nonnegative().optional().describe(
+    'client_connection_check_interval set on every per-test database (default 1000; 0 disables). Makes a backend poll the client socket mid-statement and abort when the peer is gone, which is the case a statement_timeout alone waits out. Linux only; elsewhere Postgres accepts the setting and ignores it',
+  ),
+  databases: z.record(z.string(), z.object({
+    isolation: testIsolationStrategy.optional(),
+  })).optional(),
+})
+
+const environmentSchema = z.enum(['development', 'test', 'production'])
+
+const releaseSchema = z.object({
+  env: z.string().min(1).describe('Name of the environment variable that holds the app\'s release (a deploy number, tag or commit)'),
+  requiredIn: z.array(environmentSchema).optional().describe('Environments in which the app refuses to start when the variable is unset or empty'),
+})
+
+const ioPatternKey = z.string().regex(
+  /^[A-Za-z_$][A-Za-z0-9_$]*(\.[A-Za-z_$][A-Za-z0-9_$]*)?$/,
+  'I/O pattern must be a bare identifier ("fetch") or a single member access ("cache.get")',
+)
+
+const traceSchema = z.object({
+  hotRetentionDays: z.number().int().positive().default(7).describe('Days of `trace` / `trace_step` partitions kept before they are dropped'),
+  errorRetentionDays: z.number().int().positive().default(30).describe('Days of `trace_retained` / `trace_step_retained` partitions kept before they are dropped'),
+  partitionLeadDays: z.number().int().nonnegative().default(2).describe('Days of partitions pre-created ahead of today so writes never race partition creation'),
+  safetyFactor: z.number().int().positive().default(4).describe('Per-trace step cap is `structuralMax × safetyFactor`; the cap firing is a bug signal, not a load condition'),
+  structuralMax: z.number().int().nonnegative().optional().describe('Longest chain of `step` edges through the flow graph, derived by `pipework check` from `@downstream` annotations. Unset → no runtime cap (truncation never fires). Set by hand or copied from the value `pipework check` prints; the check refuses to pass if the configured value diverges from what the analyzer derives'),
+  captureInputs: z.boolean().default(true).describe('Tier-2 input capture kill-switch; set false to suppress `trace_step.captured_inputs` framework-wide while keeping Tier-1 (timing, status, error) intact'),
+  maxExternalSteps: z.number().int().nonnegative().default(1000).describe('Per-trace limit on steps recorded from outside the Node process with `trace.record`; they do not count against the structural step cap, and reports over the limit are dropped'),
+  io: z.record(ioPatternKey, z.enum(['read', 'write'])).optional().describe('Consumer extension of the Tier-2 I/O call-target registry. Keys are call patterns ("fetch" or "cache.get"); values declare whether the call is a read or a write. Patterns match lexically against the call\'s callee — no type resolution.'),
+  auditChunkSize: z.number().int().positive().default(5000).describe('Maximum audit rows emitted in a single write+audit statement. Bulk inserts under @flow_step that would exceed this are split into N chunks executed sequentially inside a transaction. Counted as `values.length × touches.length` so multi-target writes do not slip through. Engineering knob — the runtime always preserves atomicity across chunks via savepoint or transaction wrap.'),
+})
+
+const auditSchema = z.object({
+  retentionDays: z.union([z.number().int().positive(), z.literal('keep')]).default(365).describe('Days of `audit_record` partitions kept before they are dropped, or `\'keep\'` to never drop them (remove one tenant\'s records with `audit.removeTenant`); the audit substrate has its own retention independent of trace storage'),
+  chain: z.boolean().default(false).describe('Hash-link every `audit_record` row to the one before it, per tenant, so an edited or deleted row is detectable (`audit.verify`). Opt-in: a trigger takes a row lock on the tenant\'s chain head, so one tenant\'s audited writes serialize from the first audit row until their transaction commits'),
+})
+
+const valveSchema = z.object({})
+
+const accessLinksSchema = z.object({})
+
+const joinRequestsSchema = z.object({})
+
+const creditsSchema = z.object({})
+
+const creditLineSchema = z.object({})
+
+const quotaSchema = z.object({})
+
+const storageSchema = z.object({})
+const crawlSchema = z.object({
+  requireApproval: z.boolean().default(false).describe('When true, `start` records a crawl as awaiting_approval and queues nothing until `approve(id)`'),
+})
+const alertsSchema = z.object({})
+const supportSchema = z.object({})
+
+const sessionsSchema = z.object({})
+
+const orgsSchema = z.object({})
+
+const passwordsSchema = z.object({})
+
+const guardsSchema = z.object({})
+
+const emailLinksSchema = z.object({})
+
+const rateLimitsSchema = z.object({})
+
+const emailSchema = z.object({})
+
+// Issue #325 — opt-in fast path for `check` / `test`. The fast path may trade
+// coverage (fewer modules/tiers now, all of it at the gate) but never accuracy.
+const fastPathSchema = z.object({
+  default: z.enum(['fast', 'full']).default('full').describe('Verdict for a `check`/`test` invocation with no --fast/--full flag'),
+  baseBranches: z.array(z.string().regex(/^[A-Za-z0-9._/-]+$/)).optional().describe(
+    'Base refs a branch-scoped diff (--fast, bare check/test) is taken against, first match wins. '
+    + 'Any committish works — a local branch, "origin/main", a tag. Default: [\'integration\', \'main\'].',
+  ),
+  test: z.object({
+    tiers: z.array(z.string()).default(['unit', 'contract', 'isolation']).describe('Test profiles a --fast run includes; property/stress tiers are deferred to the full run'),
+    propertyNumRuns: z.number().int().positive().optional().describe('fast-check numRuns for property tests on the fast path — a quantified statistical trade'),
+  }).optional(),
+})
+
+const observabilitySchema = z.object({
+  slowQueryMs: z.number().int().positive().optional().describe('Warn when a query exceeds this duration in ms'),
+  inFlightQueryMs: z.number().int().positive().optional().describe('While a statement is still running, log what it is waiting on every this many ms (unset = off)'),
+  logAllQueries: z.boolean().optional().describe('Log every query at debug level'),
+  poolMetricsInterval: z.number().int().nonnegative().optional().describe('Seconds between pool metric summaries (0 = disabled)'),
+  // NOT z.function(): in zod 4 that returns a *validating wrapper*, so the
+  // parsed value is not the function the caller passed (identity is lost, and
+  // every call pays argument validation) — on a hook that fires once per wire
+  // statement, both are disqualifying. z.custom admits the function unchanged.
+  onStatement: z.custom<StatementObserver>(v => typeof v === 'function', { message: 'Expected a function' })
+    .optional()
+    .describe('Per-statement observer — fires once per statement written to the wire, including driver-issued BEGIN/SAVEPOINT/COMMIT/ROLLBACK'),
+})
+
+const envVarDefSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('string'), required: z.boolean().optional(), default: z.string().optional(), sensitive: z.boolean().optional(), defaults: z.record(z.string(), z.string()).optional() }),
+  z.object({ type: z.literal('number'), required: z.boolean().optional(), default: z.number().optional(), sensitive: z.boolean().optional(), defaults: z.record(z.string(), z.string()).optional() }),
+  z.object({ type: z.literal('boolean'), required: z.boolean().optional(), default: z.boolean().optional(), sensitive: z.boolean().optional(), defaults: z.record(z.string(), z.string()).optional() }),
+  z.object({ type: z.literal('string[]'), separator: z.string().optional(), required: z.boolean().optional(), default: z.array(z.string()).optional(), sensitive: z.boolean().optional(), defaults: z.record(z.string(), z.string()).optional() }),
+])
+
+const exportsValueSchema = z.union([
+  z.string().describe('Source file path — projected to { types, import } in dist'),
+  z.object({
+    types: z.string(),
+    import: z.string(),
+  }).describe('Explicit dist paths (escape hatch)'),
+])
+
+const GENERATED_ONLY_MODULE_FIELDS = [
+  'dependencies', 'devDependencies', 'peerDependencies', 'exports', 'scripts',
+  'tsconfig', 'name', 'version', 'private', 'files', 'publishConfig',
+] as const
+
+const moduleConfigSchema = z.object({
+  managed: z.boolean().optional().describe('false: the module\'s package.json and tsconfig files are hand-written; sync writes none of them, and the package name is read from its own package.json (default: true)'),
+  dependencies: z.record(z.string(), z.string()).optional().describe('Runtime dependencies (npm packages and workspace:* refs)'),
+  devDependencies: z.record(z.string(), z.string().nullable()).optional().describe('Dev dependencies merged with top-level defaults; null removes a key that would otherwise be generated (typescript, vitest, or a top-level devDependency)'),
+  peerDependencies: z.record(z.string(), z.string()).optional().describe('Peer dependencies for a shared/published "leaf" library — e.g. { pipework: "^0.14.0" } so each consuming workspace provides one pipework instance instead of the leaf bundling its own'),
+  exports: z.record(z.string(), exportsValueSchema).optional().describe('Export map — subpath → source file or { types, import }'),
+  scripts: z.record(z.string(), z.string().nullable()).optional().describe('npm scripts merged with defaults (build, lint, test, type-check); null removes a key, including a default'),
+  tsconfig: z.record(z.string(), z.unknown()).optional().describe('Merged into the module\'s tsconfig.json compilerOptions over the generated base, e.g. { noUnusedLocals: false } or { noUnusedParameters: true }'),
+  name: z.string().optional().describe('Override package name (default: @{project}/{basename})'),
+  version: z.string().optional().describe('Package version (default: 0.0.0)'),
+  private: z.boolean().optional().describe('Whether package is private (default: true)'),
+  files: z.array(z.string()).optional().describe('npm "files" allowlist for a published module'),
+  publishConfig: z.record(z.string(), z.unknown()).optional().describe('npm "publishConfig" (e.g. access, registry) for a published module'),
+}).superRefine((mod, ctx) => {
+  if (mod.managed !== false) return
+  for (const field of GENERATED_ONLY_MODULE_FIELDS) {
+    if (mod[field] !== undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: [field],
+        message: `"${field}" has no effect on a module with managed: false, because sync writes none of its package.json or tsconfig files. Fix: remove "${field}" (it belongs in the module's own package.json), or remove managed: false.`,
+      })
+    }
+  }
+})
+
+const coverageConfigSchema = z.object({
+  enabled: z.boolean().optional().describe(
+    'Collect coverage for this run. Vitest treats coverage as a root-level option, so this ' +
+    'belongs on the top-level `vitest.coverage` — a module or profile that sets `coverage` ' +
+    'is refused by name rather than silently ignored. Gate it on an env var by computing ' +
+    'the boolean in pipework.config.ts.',
+  ),
+  provider: z.enum(['v8', 'istanbul']).optional(),
+  include: z.array(z.string()).optional(),
+  exclude: z.array(z.string()).optional(),
+  reporter: z.array(z.string()).optional(),
+  reportsDirectory: z.string().optional(),
+  thresholds: z.object({
+    lines: z.number().min(0).max(100).optional(),
+    functions: z.number().min(0).max(100).optional(),
+    branches: z.number().min(0).max(100).optional(),
+    statements: z.number().min(0).max(100).optional(),
+  }).optional(),
+})
+
+const poolSchema = z.enum(['threads', 'forks', 'vmThreads', 'vmForks']).describe(
+  'Vitest worker pool. Pipework defaults to "forks" — a test that sets a process-wide ' +
+  'Postgres session must not share a worker with another.',
+)
+
+const vitestProfileSchema = z.object({
+  include: z.array(z.string()).optional(),
+  exclude: z.array(z.string()).optional().describe(
+    'Extra exclude globs, MERGED with vitest\'s own defaults (node_modules, .git) rather ' +
+    'than replacing them — vitest replaces, which silently un-excludes node_modules.',
+  ),
+  pool: poolSchema.optional(),
+  isolate: z.boolean().optional().describe(
+    'Run each test file in a fresh worker. Pipework defaults to `false` — pipework\'s own ' +
+    'per-test database isolation already separates test state, and re-isolating the worker ' +
+    'costs a process spawn per file. Set `true` for a suite that relies on vitest\'s default.',
+  ),
+  database: z.boolean().optional(),
+  setupFiles: z.array(z.string()).optional(),
+  testTimeout: z.number().int().positive().optional(),
+  hookTimeout: z.number().int().positive().optional(),
+  env: z.record(z.string(), z.string()).optional(),
+  coverage: coverageConfigSchema.optional(),
+  extra: z.record(z.string(), z.unknown()).optional(),
+  manual: z.boolean().optional().describe('Exclude from default and --all runs — only run via --suite'),
+})
+
+const vitestModuleSchema = vitestProfileSchema.extend({
+  profiles: z.record(
+    z.string().refine(s => !s.includes(':'), 'Profile names cannot contain ":" — it is used as the project name separator'),
+    vitestProfileSchema,
+  ).optional(),
+})
+
+const lintModuleSchema = z.object({
+  include: z.array(z.string().min(1)).min(1).optional().describe(
+    'File globs this module lints, relative to the module directory, replacing the default. ' +
+    'Set it when the module\'s sources are not under `src` (e.g. ["app/src/**/*.ts"]). ' +
+    'A module whose globs match no file fails the lint pass rather than reporting green.',
+  ),
+  rules: z.record(z.string(), z.unknown()).optional().describe(
+    'Rule entries applied only to this module. Merged after `extra.rules`, so a module ' +
+    'rule overrides the global one. Reference plugins registered via `extra.plugins`.',
+  ),
+  configs: z.array(z.unknown()).optional().describe(
+    'Additional flat-config entries applied only to this module. Each entry is a ' +
+    'standalone eslint flat-config block.',
+  ),
+})
+
+const lintSchema = z.object({
+  include: z.array(z.string().min(1)).min(1).optional().describe(
+    'File globs every module lints, relative to the module directory, replacing the default. ' +
+    'The default covers `src` plus the `src` of each workspace package under the module. ' +
+    'Override per module with `modules.<path>.include`.',
+  ),
+  extra: z.object({
+    plugins: z.record(z.string(), z.unknown()).optional().describe(
+      'Plugin instances registered in pipework\'s lint block (e.g. { react: reactPlugin }). ' +
+      'Rules under `extra.rules` (or any `modules` entry) can then reference them as `pluginName/ruleName`.',
+    ),
+    rules: z.record(z.string(), z.unknown()).optional().describe(
+      'Rule entries merged into pipework\'s lint block. ' +
+      'Can override pipework defaults or add rules from `extra.plugins` or built-in eslint.',
+    ),
+    configs: z.array(z.unknown()).optional().describe(
+      'Additional flat-config entries appended to the returned array (e.g. test-file overrides, ' +
+      'per-glob rule relaxations). Each entry is a standalone eslint flat-config block.',
+    ),
+  }).optional().describe(
+    'Consumer extensions to pipework\'s generated eslint config, applied everywhere. ' +
+    'Pipework owns the base block (typescript-eslint plugin/parser, `pipework` plugin, default rules); ' +
+    '`extra` lets consumers register additional plugins, override or add rules, and append config blocks.',
+  ),
+  modules: z.record(z.string(), lintModuleSchema).optional().describe(
+    'Per-module lint overrides keyed by relative path or glob (e.g. "packages/warehouse" or ' +
+    '"packages/*"), resolved the same way as the top-level `modules` map. Rules and config blocks ' +
+    'declared here apply only to the matching module, on top of `extra`. Plugins stay global — ' +
+    'register them under `extra.plugins` and reference their rules from any module.',
+  ),
+})
+
+const vitestSchema = z.object({
+  testTimeout: z.number().int().positive().optional(),
+  hookTimeout: z.number().int().positive().optional(),
+  inlineDeps: z.array(z.string().min(1)).optional(),
+  database: z.boolean().optional(),
+  include: z.array(z.string()).optional(),
+  exclude: z.array(z.string()).optional().describe(
+    'Extra exclude globs, MERGED with vitest\'s own defaults (node_modules, .git) rather ' +
+    'than replacing them — vitest replaces, which silently un-excludes node_modules.',
+  ),
+  pool: poolSchema.optional(),
+  isolate: z.boolean().optional().describe(
+    'Run each test file in a fresh worker. Pipework defaults to `false`; set `true` for a ' +
+    'suite that relies on vitest\'s own default. Overridable per module and per profile.',
+  ),
+  coverage: coverageConfigSchema.optional().describe(
+    'Coverage, applied at the vitest root where vitest reads it. A module or profile that ' +
+    'sets `coverage` is refused by name — vitest ignores coverage inside a project.',
+  ),
+  modules: z.record(z.string(), vitestModuleSchema).optional(),
+  extra: z.record(z.string(), z.unknown()).optional().describe(
+    'Top-level vitest config — spread into defineConfig({...}). ' +
+    'Put `test`-level keys (reporters, sequence, cache, bail, etc.) under `extra.test`; ' +
+    'put outer Vite-level keys (resolve, plugins, etc.) at the top of `extra`. ' +
+    'Pipework owns `test.projects` — define modules in `vitest.modules` instead.',
+  ),
+})
+
+const modulesSchema = z.record(
+  z.string(),
+  z.union([
+    moduleConfigSchema,
+    z.string().describe('Shorthand — empty config, value is ignored (key is the path)'),
+  ]),
+).describe('Modules keyed by relative path (or glob). Value is package.json fields or empty string shorthand.')
+
+export const trunkConfigSchema = z.object({
+  doors: z.record(z.string().regex(DOOR_NAME, 'a door name is lowercase dotted words such as "admission.ledger"'), doorSchema).optional().describe('Named cross-tenant read doors. `pipe.door(name, fn)` reads the door\'s table across tenants on the platform role; generated migrations create a policy for exactly that table. Needs `rls.platformRole` on the door\'s database.'),
+  name: z.string().optional().describe('Project name — used as npm scope for generated packages'),
+  databases: z.record(z.string(), databaseSchema),
+  defaultDatabase: z.string().optional().describe('Name of the database a no-name `db()` / `pipe()` resolves to when multiple databases are configured — must be a key of `databases`. Unnecessary with a single database (that one is always the default).'),
+  scripts: z.record(z.string(), z.string()).optional().describe('Root-level npm scripts merged into generated package.json (preinstall is reserved)'),
+  packageManager: z.string()
+    .regex(
+      /^pnpm@\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/,
+      'packageManager must be "pnpm@<major>.<minor>.<patch>" — the generated workspace is pnpm-only '
+      + '(pnpm-workspace.yaml, `pnpm install`), so npm and yarn are not accepted.',
+    )
+    .optional()
+    .describe('The packageManager field written to the generated root package.json. The pnpm version is a fact about your box, not about pipework; unset, pipework writes its own default.'),
+  dependencies: z.record(z.string(), z.string()).optional().describe('Root-level runtime dependencies'),
+  devDependencies: z.record(z.string(), z.string()).optional().describe('Shared dev dependencies — merged into every module'),
+  modules: modulesSchema.optional().describe('Module definitions keyed by path or glob'),
+  vitest: vitestSchema.optional().describe('Centralized vitest configuration — workspace defaults and per-module overrides'),
+  lint: lintSchema.optional().describe('Centralized eslint configuration — consumer plugins, rules, and extra flat-config blocks'),
+  environment: environmentSchema.optional(),
+  requireEnvironment: z.boolean().optional().describe('When true and `environment` is not set, an unset or unknown PIPEWORK_ENV / NODE_ENV is a ConfigError naming the variable and value, instead of resolving to development'),
+  release: releaseSchema.optional().describe('The release this process runs, read from an environment variable; written on every trace and on the job row of the worker that ran it'),
+  test: testSchema.optional(),
+  trace: traceSchema.optional().describe('Trace substrate retention and partitioning'),
+  audit: auditSchema.optional().describe('Audit substrate retention; independent of trace storage'),
+  valve: valveSchema.optional().describe('Valve substrate — opts the valve_crossing ledger table into generated migrations'),
+  accessLinks: accessLinksSchema.optional().describe('Access links — opts the access_link_code, access_link, access_link_use and access_link_check_spent tables into generated migrations'),
+  joinRequests: joinRequestsSchema.optional().describe('Join requests — opts the join_request table into generated migrations'),
+  credits: creditsSchema.optional().describe('Prepaid usage credits — opts the credit_grant, credit_reservation, credit_draw, credit_ledger and credit_account tables into generated migrations'),
+  creditLine: creditLineSchema.optional().describe('Postpaid credit line — opts the credit_line, credit_line_reservation, credit_line_entry, credit_line_payment, credit_line_payment_application and credit_line_authorization tables into generated migrations'),
+  quota: quotaSchema.optional().describe('Outbound quota — opts the outbound_quota table into generated migrations'),
+  alerts: alertsSchema.optional().describe('Alerts — opts the pipework_alerts, pipework_alert_deliveries and pipework_alert_source_state pipework_unit_faults and pipework_loop_beats tables into generated migrations'),
+  support: supportSchema.optional().describe('Support tickets — opts the support_ticket, support_message, support_link and support_event_delivery tables into generated migrations'),
+  crawl: crawlSchema.optional().describe('Site crawler — opts the pipework_crawl, pipework_crawl_url, pipework_crawl_host and pipework_crawl_resource tables into generated migrations; without it `crawl.create` refuses'),
+  storage: storageSchema.optional().describe('File storage — opts the storage_file table into generated migrations'),
+  sessions: sessionsSchema.optional().describe('Sessions — opts the pipework_refresh_tokens and pipework_auth_versions tables into generated migrations'),
+  orgs: orgsSchema.optional().describe('Multi-org — opts the pipework_user_orgs table into generated migrations'),
+  passwords: passwordsSchema.optional().describe('Password sign-in — opts the pipework_signin_attempts table into generated migrations'),
+  guards: guardsSchema.optional().describe('Guarded secrets — opts the pipework_guard_attempts table into generated migrations'),
+  emailLinks: emailLinksSchema.optional().describe('Emailed single-use links (password reset, address verification) — opts the pipework_email_links and pipework_email_link_requests tables into generated migrations'),
+  rateLimits: rateLimitsSchema.optional().describe('Per-route-class rate limits — opts the pipework_rate_limit_counts table into generated migrations'),
+  email: emailSchema.optional().describe('Email — opts the pipework_email_messages, pipework_email_suppressions, pipework_email_inbound and pipework_email_unsubscribes tables into generated migrations'),
+  fastPath: fastPathSchema.optional().describe('Opt-in fast path for `check` / `test` — affected-scoped, tier-trimmed iteration'),
+  observability: observabilitySchema.optional(),
+  env: z.record(z.string(), envVarDefSchema).optional().describe(
+    'Declared environment variables — the canonical home for runtime config (ports, service tokens, '
+    + 'bucket names, feature flags). Each is read once, validated/coerced to its declared type, and exposed '
+    + 'typed on `manifold.env`, instead of scattered ad-hoc `process.env` reads across handlers.',
+  ),
+}).superRefine((config, ctx) => {
+  const names = Object.keys(config.databases)
+  const defaultName = config.defaultDatabase ?? (names.length === 1 ? names[0] : undefined)
+  for (const [door, def] of Object.entries(config.doors ?? {})) {
+    if (door.startsWith('pipework.')) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['doors', door],
+        message: `door "${door}": names starting "pipework." are reserved for doors pipework declares itself. Fix: rename the door.`,
+      })
+      continue
+    }
+    const database = def.database ?? defaultName
+    if (database === undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['doors', door, 'database'],
+        message: `door "${door}" names no database and there is no default database. Fix: set \`database\` on the door or \`defaultDatabase\` in the config.`,
+      })
+      continue
+    }
+    const db = config.databases[database]
+    if (db === undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['doors', door, 'database'],
+        message: `door "${door}" names database "${database}", which is not declared. Declared databases: ${names.join(', ')}.`,
+      })
+      continue
+    }
+    if (db.rls?.platformRole === undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['doors', door],
+        message: `door "${door}" is declared on database "${database}", which has no \`rls.platformRole\`. Doors need a platform role that is not BYPASSRLS. Fix: set \`rls.platformRole\` and \`systemUrl\` on "${database}", or remove the door.`,
+      })
+    }
+  }
+})
+
+export type Blueprint = z.infer<typeof trunkConfigSchema>
+// The shape a caller passes to `createManifold` — fields with schema defaults
+// (e.g. everything under `trace`) are optional here, where `Blueprint` (the
+// parsed result) has them filled in.
+export type BlueprintInput = z.input<typeof trunkConfigSchema>
+export type DatabaseConfig = z.infer<typeof databaseSchema>
+export type DoorConfig = z.infer<typeof doorSchema>
+export type TestConfig = z.infer<typeof testSchema>
+export type Environment = z.infer<typeof environmentSchema>
+export type TraceConfig = z.infer<typeof traceSchema>
+export type AuditConfig = z.infer<typeof auditSchema>
+export type ValveConfig = z.infer<typeof valveSchema>
+export type AccessLinksConfig = z.infer<typeof accessLinksSchema>
+export type JoinRequestsBlueprintConfig = z.infer<typeof joinRequestsSchema>
+export type CreditsBlueprintConfig = z.infer<typeof creditsSchema>
+export type CreditLineBlueprintConfig = z.infer<typeof creditLineSchema>
+export type QuotaBlueprintConfig = z.infer<typeof quotaSchema>
+export type AlertsBlueprintConfig = z.infer<typeof alertsSchema>
+export type CrawlBlueprintConfig = z.infer<typeof crawlSchema>
+export type StorageBlueprintConfig = z.infer<typeof storageSchema>
+export type FastPathConfig = z.infer<typeof fastPathSchema>
+export type IsolationStrategy = z.infer<typeof testIsolationStrategy>
+export type ObservabilityConfig = z.infer<typeof observabilitySchema>
+export type ModuleConfig = z.infer<typeof moduleConfigSchema>
+export type VitestConfig = z.infer<typeof vitestSchema>
+export type LintConfig = z.infer<typeof lintSchema>
+export type LintModuleConfig = z.infer<typeof lintModuleSchema>
+export type VitestModuleConfig = z.infer<typeof vitestModuleSchema>
+export type VitestProfileConfig = z.infer<typeof vitestProfileSchema>
+export type CoverageConfig = z.infer<typeof coverageConfigSchema>

package/src/core/config/statement-observer.ts

@@ -0,0 +1,48 @@
+/**
+ * One statement as it is handed to the driver for writing to the wire —
+ * including the transaction-control statements the driver issues on its own
+ * (`BEGIN`, `SAVEPOINT`, `COMMIT`, `ROLLBACK`), which no application-level hook
+ * can see.
+ */
+export interface StatementEvent {
+  /**
+   * The driver's connection ordinal — a process-local monotonic counter
+   * assigned when the connection object is constructed. It is NOT the
+   * PostgreSQL backend pid: it is unique and stable per connection for that
+   * connection's lifetime within this process, and meaningless across
+   * processes. Correct as a key for per-connection accounting (a transaction is
+   * pinned to one connection); wrong for correlating with `pg_stat_activity`.
+   */
+  readonly connectionId: number
+  /** The statement text, untruncated. */
+  readonly query: string
+  /** Bind parameters for this statement, in ordinal position. */
+  readonly parameters: readonly unknown[]
+}
+
+/**
+ * Caller-supplied per-statement observer. Fires once per statement written to
+ * the wire, on every connection the manifold owns — pooled connections and the
+ * test harness's own connections alike.
+ *
+ * Pure observation: the return value is discarded and the statement is never
+ * mutated. It runs synchronously on the driver's write path, so it must be
+ * cheap and must not throw.
+ *
+ * Counts wire truth, not application intent. Two consequences worth knowing
+ * before you assert on a total: the driver issues its own transaction control
+ * (`BEGIN`/`SAVEPOINT`/`COMMIT`/`ROLLBACK`), and it issues one `pg_catalog.pg_type`
+ * lookup per connection the first time that connection is used.
+ *
+ * Adds no leak surface. Installing an observer requires turning on the driver's
+ * `debug` hook, which would otherwise start serializing bind parameters onto
+ * every query error; pipework's driver error boundary puts those errors back to
+ * their unobserved shape, so **every statement path pipework mediates —
+ * `pipe()`, every `pipe.*` write, `connection.drizzle`, transactions and
+ * savepoints — exposes exactly what it exposed before**. The single exception
+ * is the raw `ManagedConnection.client` door: queries issued through it are
+ * outside the boundary and their errors do serialize bind parameters. Reading
+ * `.client` on an observed connection logs a warning saying so, once per
+ * database.
+ */
+export type StatementObserver = (event: StatementEvent) => void

package/src/core/config/ts-inline-hooks.ts

@@ -0,0 +1,75 @@
+import { register } from 'node:module'
+import { existsSync } from 'node:fs'
+
+export const TS_HOOKS = Symbol.for('pipework.tsHooks')
+
+export function registerTsResolveHooks(): void {
+  if (Reflect.get(globalThis, TS_HOOKS) !== undefined) return
+  // Built package: the compiled transforming hook sits beside this file, so every
+  // in-process CLI path (run, seed, ...) applies @flow_step like serve and dev do.
+  if (existsSync(new URL('./ts-resolve-hooks.js', import.meta.url))) {
+    register('./ts-resolve-hooks.js', import.meta.url)
+    Reflect.set(globalThis, TS_HOOKS, 'transforming')
+    return
+  }
+  {
+    // Marker contract: globalThis[Symbol.for('pipework.tsHooks')] is 'transforming'
+    // once the @flow_step-applying loader is installed (by ts-register.js, or by this
+    // function when the built ts-resolve-hooks.js sits beside it); a hook registered
+    // later would run first and shadow it, so then nothing more is installed.
+    // Source-mode runs, where the compiled hook does not exist, install one inline
+    // hook and mark 'inline'.
+    // Self-contained mirror of ts-resolve-hooks.ts, registered as a `data:` URL so
+    // it works during pipework's own source-mode runs where the compiled
+    // ts-resolve-hooks.js does not exist yet. `resolve` maps a relative specifier
+    // to its backing TS file (.js→.ts + extensionless); `load` fully transpiles it
+    // (parameter properties, enums, namespaces) via Node's bundled
+    // `stripTypeScriptTypes` — `--experimental-strip-types` only erases annotations
+    // and rejects those features. Keep resolve and strip in sync with ts-resolve-hooks.ts, which also applies @flow_step.
+    const code = `
+      import { existsSync } from 'node:fs'
+      import { readFile } from 'node:fs/promises'
+      import { fileURLToPath } from 'node:url'
+      import { stripTypeScriptTypes } from 'node:module'
+
+      function tsCandidates(specifier) {
+        const jsMatch = specifier.match(/\\.([cm]?)js$/);
+        if (jsMatch !== null) {
+          return [specifier.slice(0, -jsMatch[0].length) + '.' + (jsMatch[1] || '') + 'ts'];
+        }
+        if (/\\.[cm]?tsx?$/.test(specifier)) return [];
+        return [specifier + '.ts', specifier + '.js', specifier + '/index.ts', specifier + '/index.js'];
+      }
+
+      export function resolve(specifier, context, nextResolve) {
+        const parent = context.parentURL || '';
+        const isLocal = (specifier.startsWith('./') || specifier.startsWith('../'))
+          && !parent.includes('/node_modules/') && !parent.includes('/dist/');
+        if (isLocal) {
+          for (const candidate of tsCandidates(specifier)) {
+            let candidatePath = null;
+            try {
+              const url = new URL(candidate, parent);
+              if (url.protocol === 'file:') candidatePath = fileURLToPath(url);
+            } catch {}
+            if (candidatePath !== null && existsSync(candidatePath)) {
+              return nextResolve(candidate, context);
+            }
+          }
+        }
+        return nextResolve(specifier, context);
+      }
+
+      export async function load(url, context, nextLoad) {
+        if (url.endsWith('.ts') && !url.includes('/node_modules/')) {
+          const source = await readFile(fileURLToPath(url), 'utf8');
+          const transformed = stripTypeScriptTypes(source, { mode: 'transform', sourceMap: true, sourceUrl: url });
+          return { format: 'module', source: transformed, shortCircuit: true };
+        }
+        return nextLoad(url, context);
+      }
+    `
+    register(`data:text/javascript,${encodeURIComponent(code)}`)
+    Reflect.set(globalThis, TS_HOOKS, 'inline')
+  }
+}

package/src/core/config/ts-register.ts

@@ -0,0 +1,4 @@
+import { register } from 'node:module'
+register('./ts-resolve-hooks.js', import.meta.url)
+// Tells registerTsResolveHooks() this loader is installed; it must not shadow it.
+Reflect.set(globalThis, Symbol.for('pipework.tsHooks'), 'transforming')