From de35e09d67702b6ce3b4ed77e743e449fdc5ea2f Mon Sep 17 00:00:00 2001
From: yyyyaaa <phatghaa@gmail.com>
Date: Mon, 6 Jul 2026 17:20:33 +0700
Subject: [PATCH] chore(perf): cperf regression harness + scale-validate rig +
 capacity docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tooling + documentation only — zero runtime code changes. This is the
apparatus that produced every number cited in this stack, landed so the
results are reproducible and regressions are catchable.

packages/perf-harness (cperf):
- Reusable perf/regression CLI: fleet provision/teardown (tenant factories,
  canary seeding, drift detection), load harness (authenticated zipf traffic,
  churn driver), measurement (per-instance retained heap via heap snapshots,
  PG-side sampler, JSON-line collector), regression suites with baselines +
  compare, ramp/soak/soakOps runners, capacity prediction from the sizing
  model. 21 jest suites over the pure logic (histograms, RNG, fleetfiles,
  merge/summarize, scenario matrices).

scripts/scale-validate:
- The V1-V4 validation rig used for #1325: plans, drivers, samplers,
  summarizers. Kept as scripts (not a package) — they orchestrate a live
  fleet against a dedicated PG and document the exact invocations used.
- SIZING.md: catalog-driven capacity model — the heap-aware instance budget,
  the R(H) law with worked examples, shard guidance, and the measured
  constants (filtered instance ~15MB, unfiltered ~1.3GB at 61k pg_class).
- VALIDATION-REPORT.md / V2-RESULTS.md: findings ledger V1-V4 — every crash,
  root cause, fix, and the final verdicts (47-tenant headline run; churn
  storm; 24h-soak OOM root cause; heap floor 1024MB guidance).

.gitignore: rig output artifacts (fleet manifests, metrics.jsonl, perf-out).

Extracted from #1325 (commits 2eeaefbc1, f13857373, e54596547, 143f4795a,
8eec3cd7c, aeb8c35b4, acc035c98, f95d59fda and the rig fix-ups).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0122xqM2VkNbuAmZshK1YNSb
---
 .gitignore                                    |    6 +
 packages/perf-harness/.gitignore              |    3 +
 packages/perf-harness/DESIGN.md               |  168 +++
 packages/perf-harness/README.md               |  465 +++++++
 packages/perf-harness/jest.config.js          |   18 +
 packages/perf-harness/package.json            |   58 +
 packages/perf-harness/src/commands/fleet.ts   |  120 ++
 packages/perf-harness/src/commands/load.ts    |   31 +
 packages/perf-harness/src/commands/measure.ts |   34 +
 .../perf-harness/src/commands/regression.ts   |   44 +
 packages/perf-harness/src/commands/report.ts  |   34 +
 packages/perf-harness/src/commands/run.ts     |   28 +
 .../src/core/__tests__/args.test.ts           |   65 +
 .../src/core/__tests__/config.test.ts         |   83 ++
 .../src/core/__tests__/fixtures/drifted.json  |    6 +
 .../core/__tests__/fixtures/empty-fleet.json  |    1 +
 .../src/core/__tests__/fixtures/fleet.json    |   13 +
 .../src/core/__tests__/fleetfile.test.ts      |   84 ++
 .../src/core/__tests__/histogram.test.ts      |   55 +
 .../src/core/__tests__/proc.test.ts           |   86 ++
 .../src/core/__tests__/rng.test.ts            |   88 ++
 packages/perf-harness/src/core/args.ts        |   63 +
 packages/perf-harness/src/core/config.ts      |   96 ++
 packages/perf-harness/src/core/fleetfile.ts   |  116 ++
 packages/perf-harness/src/core/gql.ts         |  271 ++++
 packages/perf-harness/src/core/histogram.ts   |   74 +
 packages/perf-harness/src/core/pgc.ts         |   46 +
 packages/perf-harness/src/core/proc.ts        |  163 +++
 packages/perf-harness/src/core/rng.ts         |   71 +
 .../src/fleet/__tests__/canary.test.ts        |   44 +
 .../src/fleet/__tests__/provision.test.ts     |   93 ++
 .../src/fleet/__tests__/teardown.test.ts      |   27 +
 packages/perf-harness/src/fleet/canary.ts     |  170 +++
 packages/perf-harness/src/fleet/discover.ts   |  105 ++
 packages/perf-harness/src/fleet/drift.ts      |  105 ++
 packages/perf-harness/src/fleet/provision.ts  |  433 ++++++
 packages/perf-harness/src/fleet/teardown.ts   |  175 +++
 packages/perf-harness/src/index.ts            |  141 ++
 .../src/load/__tests__/harness.test.ts        |  126 ++
 packages/perf-harness/src/load/churn.ts       |  127 ++
 packages/perf-harness/src/load/harness.ts     |  784 +++++++++++
 .../src/measure/__tests__/collector.test.ts   |  115 ++
 .../src/measure/__tests__/pgSampler.test.ts   |   35 +
 .../perf-harness/src/measure/collector.ts     |  266 ++++
 .../perf-harness/src/measure/instanceHeap.ts  |  206 +++
 .../perf-harness/src/measure/pgSampler.ts     |  146 ++
 .../regression/__tests__/baselines.test.ts    |   45 +
 .../src/regression/__tests__/compare.test.ts  |  105 ++
 .../regression/__tests__/scenarios.test.ts    |  200 +++
 .../src/regression/__tests__/sql.test.ts      |  136 ++
 .../perf-harness/src/regression/baselines.ts  |   94 ++
 .../perf-harness/src/regression/compare.ts    |  143 ++
 .../perf-harness/src/regression/scenarios.ts  | 1209 +++++++++++++++++
 packages/perf-harness/src/regression/sql.ts   |  191 +++
 packages/perf-harness/src/regression/suite.ts |  410 ++++++
 .../src/report/__tests__/merge.test.ts        |  164 +++
 .../src/report/__tests__/summarize.test.ts    |   98 ++
 packages/perf-harness/src/report/merge.ts     |  387 ++++++
 packages/perf-harness/src/report/predict.ts   |   99 ++
 packages/perf-harness/src/report/summarize.ts |   83 ++
 .../src/run/__tests__/ramp.test.ts            |   48 +
 .../src/run/__tests__/soak.test.ts            |   20 +
 .../src/run/__tests__/soakOps.test.ts         |   55 +
 packages/perf-harness/src/run/ramp.ts         |  376 +++++
 packages/perf-harness/src/run/server.ts       |  200 +++
 packages/perf-harness/src/run/soak.ts         |  363 +++++
 packages/perf-harness/src/run/soakOps.ts      |  149 ++
 packages/perf-harness/tsconfig.esm.json       |    9 +
 packages/perf-harness/tsconfig.json           |    9 +
 pnpm-lock.yaml                                |  161 +++
 scripts/scale-validate/SIZING.md              |  205 +++
 scripts/scale-validate/V2-RESULTS.md          |  115 ++
 scripts/scale-validate/VALIDATION-REPORT.md   |  189 +++
 scripts/scale-validate/_lib.mjs               |  456 +++++++
 scripts/scale-validate/canary-seed.mjs        |  159 +++
 scripts/scale-validate/churn-driver.mjs       |  116 ++
 scripts/scale-validate/collector.mjs          |  207 +++
 scripts/scale-validate/drift-tenants.mjs      |   81 ++
 scripts/scale-validate/drop-tenants.mjs       |  155 +++
 scripts/scale-validate/fleet.mjs              |  107 ++
 scripts/scale-validate/harness.mjs            |  694 ++++++++++
 .../scale-validate/measure-instance-heap.mjs  |  235 ++++
 scripts/scale-validate/pg-sampler.mjs         |  112 ++
 scripts/scale-validate/plans/v2-1152.json     |   13 +
 scripts/scale-validate/plans/v2-1536.json     |   13 +
 .../plans/v2-2048-rps-single.json             |   16 +
 .../scale-validate/plans/v2-2048-tuned.json   |   26 +
 scripts/scale-validate/plans/v2-2048.json     |   25 +
 scripts/scale-validate/plans/v2-3584-r2.json  |   13 +
 scripts/scale-validate/plans/v2-3584.json     |   19 +
 scripts/scale-validate/plans/v2-896.json      |   13 +
 scripts/scale-validate/soak-ops.mjs           |   86 ++
 scripts/scale-validate/subset-fleet.mjs       |  102 ++
 scripts/scale-validate/summarize-results.mjs  |   46 +
 scripts/scale-validate/tenant-factory.mjs     |  421 ++++++
 scripts/scale-validate/v2-ramps.mjs           |  342 +++++
 96 files changed, 14208 insertions(+)
 create mode 100644 packages/perf-harness/.gitignore
 create mode 100644 packages/perf-harness/DESIGN.md
 create mode 100644 packages/perf-harness/README.md
 create mode 100644 packages/perf-harness/jest.config.js
 create mode 100644 packages/perf-harness/package.json
 create mode 100644 packages/perf-harness/src/commands/fleet.ts
 create mode 100644 packages/perf-harness/src/commands/load.ts
 create mode 100644 packages/perf-harness/src/commands/measure.ts
 create mode 100644 packages/perf-harness/src/commands/regression.ts
 create mode 100644 packages/perf-harness/src/commands/report.ts
 create mode 100644 packages/perf-harness/src/commands/run.ts
 create mode 100644 packages/perf-harness/src/core/__tests__/args.test.ts
 create mode 100644 packages/perf-harness/src/core/__tests__/config.test.ts
 create mode 100644 packages/perf-harness/src/core/__tests__/fixtures/drifted.json
 create mode 100644 packages/perf-harness/src/core/__tests__/fixtures/empty-fleet.json
 create mode 100644 packages/perf-harness/src/core/__tests__/fixtures/fleet.json
 create mode 100644 packages/perf-harness/src/core/__tests__/fleetfile.test.ts
 create mode 100644 packages/perf-harness/src/core/__tests__/histogram.test.ts
 create mode 100644 packages/perf-harness/src/core/__tests__/proc.test.ts
 create mode 100644 packages/perf-harness/src/core/__tests__/rng.test.ts
 create mode 100644 packages/perf-harness/src/core/args.ts
 create mode 100644 packages/perf-harness/src/core/config.ts
 create mode 100644 packages/perf-harness/src/core/fleetfile.ts
 create mode 100644 packages/perf-harness/src/core/gql.ts
 create mode 100644 packages/perf-harness/src/core/histogram.ts
 create mode 100644 packages/perf-harness/src/core/pgc.ts
 create mode 100644 packages/perf-harness/src/core/proc.ts
 create mode 100644 packages/perf-harness/src/core/rng.ts
 create mode 100644 packages/perf-harness/src/fleet/__tests__/canary.test.ts
 create mode 100644 packages/perf-harness/src/fleet/__tests__/provision.test.ts
 create mode 100644 packages/perf-harness/src/fleet/__tests__/teardown.test.ts
 create mode 100644 packages/perf-harness/src/fleet/canary.ts
 create mode 100644 packages/perf-harness/src/fleet/discover.ts
 create mode 100644 packages/perf-harness/src/fleet/drift.ts
 create mode 100644 packages/perf-harness/src/fleet/provision.ts
 create mode 100644 packages/perf-harness/src/fleet/teardown.ts
 create mode 100644 packages/perf-harness/src/index.ts
 create mode 100644 packages/perf-harness/src/load/__tests__/harness.test.ts
 create mode 100644 packages/perf-harness/src/load/churn.ts
 create mode 100644 packages/perf-harness/src/load/harness.ts
 create mode 100644 packages/perf-harness/src/measure/__tests__/collector.test.ts
 create mode 100644 packages/perf-harness/src/measure/__tests__/pgSampler.test.ts
 create mode 100644 packages/perf-harness/src/measure/collector.ts
 create mode 100644 packages/perf-harness/src/measure/instanceHeap.ts
 create mode 100644 packages/perf-harness/src/measure/pgSampler.ts
 create mode 100644 packages/perf-harness/src/regression/__tests__/baselines.test.ts
 create mode 100644 packages/perf-harness/src/regression/__tests__/compare.test.ts
 create mode 100644 packages/perf-harness/src/regression/__tests__/scenarios.test.ts
 create mode 100644 packages/perf-harness/src/regression/__tests__/sql.test.ts
 create mode 100644 packages/perf-harness/src/regression/baselines.ts
 create mode 100644 packages/perf-harness/src/regression/compare.ts
 create mode 100644 packages/perf-harness/src/regression/scenarios.ts
 create mode 100644 packages/perf-harness/src/regression/sql.ts
 create mode 100644 packages/perf-harness/src/regression/suite.ts
 create mode 100644 packages/perf-harness/src/report/__tests__/merge.test.ts
 create mode 100644 packages/perf-harness/src/report/__tests__/summarize.test.ts
 create mode 100644 packages/perf-harness/src/report/merge.ts
 create mode 100644 packages/perf-harness/src/report/predict.ts
 create mode 100644 packages/perf-harness/src/report/summarize.ts
 create mode 100644 packages/perf-harness/src/run/__tests__/ramp.test.ts
 create mode 100644 packages/perf-harness/src/run/__tests__/soak.test.ts
 create mode 100644 packages/perf-harness/src/run/__tests__/soakOps.test.ts
 create mode 100644 packages/perf-harness/src/run/ramp.ts
 create mode 100644 packages/perf-harness/src/run/server.ts
 create mode 100644 packages/perf-harness/src/run/soak.ts
 create mode 100644 packages/perf-harness/src/run/soakOps.ts
 create mode 100644 packages/perf-harness/tsconfig.esm.json
 create mode 100644 packages/perf-harness/tsconfig.json
 create mode 100644 scripts/scale-validate/SIZING.md
 create mode 100644 scripts/scale-validate/V2-RESULTS.md
 create mode 100644 scripts/scale-validate/VALIDATION-REPORT.md
 create mode 100644 scripts/scale-validate/_lib.mjs
 create mode 100644 scripts/scale-validate/canary-seed.mjs
 create mode 100644 scripts/scale-validate/churn-driver.mjs
 create mode 100644 scripts/scale-validate/collector.mjs
 create mode 100644 scripts/scale-validate/drift-tenants.mjs
 create mode 100644 scripts/scale-validate/drop-tenants.mjs
 create mode 100644 scripts/scale-validate/fleet.mjs
 create mode 100644 scripts/scale-validate/harness.mjs
 create mode 100644 scripts/scale-validate/measure-instance-heap.mjs
 create mode 100644 scripts/scale-validate/pg-sampler.mjs
 create mode 100644 scripts/scale-validate/plans/v2-1152.json
 create mode 100644 scripts/scale-validate/plans/v2-1536.json
 create mode 100644 scripts/scale-validate/plans/v2-2048-rps-single.json
 create mode 100644 scripts/scale-validate/plans/v2-2048-tuned.json
 create mode 100644 scripts/scale-validate/plans/v2-2048.json
 create mode 100644 scripts/scale-validate/plans/v2-3584-r2.json
 create mode 100644 scripts/scale-validate/plans/v2-3584.json
 create mode 100644 scripts/scale-validate/plans/v2-896.json
 create mode 100644 scripts/scale-validate/soak-ops.mjs
 create mode 100644 scripts/scale-validate/subset-fleet.mjs
 create mode 100644 scripts/scale-validate/summarize-results.mjs
 create mode 100644 scripts/scale-validate/tenant-factory.mjs
 create mode 100644 scripts/scale-validate/v2-ramps.mjs

diff --git a/.gitignore b/.gitignore
index f2471a36d3..74875645f9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,3 +13,9 @@ postgres/pgsql-test/output/
 .env.local
 graphql/server/logs/
 graphql/server/*.heapsnapshot
+scripts/scale-validate/out/
+scripts/scale-validate/fleet*.json
+scripts/scale-validate/drifted.json
+scripts/scale-spike/
+packages/perf-harness/perf-out/
+/metrics.jsonl
diff --git a/packages/perf-harness/.gitignore b/packages/perf-harness/.gitignore
new file mode 100644
index 0000000000..c71e46e3f3
--- /dev/null
+++ b/packages/perf-harness/.gitignore
@@ -0,0 +1,3 @@
+dist/
+.smoke-out/
+perf-out/
diff --git a/packages/perf-harness/DESIGN.md b/packages/perf-harness/DESIGN.md
new file mode 100644
index 0000000000..faf0846ec4
--- /dev/null
+++ b/packages/perf-harness/DESIGN.md
@@ -0,0 +1,168 @@
+# @constructive-io/perf-harness — Design
+
+Reusable performance / regression harness for the Constructive GraphQL server.
+Port of the ad-hoc `scripts/scale-validate/*.mjs` tooling (built during the
+2026-07 blueprint-pooling validation program) into a proper monorepo package,
+so the next time a memory/scale regression appears it is re-run with one
+command instead of hand-driven scripts.
+
+**The originals in `scripts/scale-validate/` are the behavioral source of
+truth. Port faithfully: every CLI flag, default, output field, and exit code is
+preserved unless this document says otherwise. Do not redesign algorithms.**
+
+## Package identity
+
+- Directory: `packages/perf-harness` (auto-included by `pnpm-workspace.yaml` glob `packages/*`; lerna derives from pnpm — no registration anywhere)
+- Name: `@constructive-io/perf-harness`, version `0.1.0`, license MIT, author `Constructive <developers@constructive.io>`
+- Bin: `{ "perf-harness": "index.js", "cperf": "index.js" }` (dist-relative like `packages/cli`; shebang `#!/usr/bin/env node` as FIRST line of `src/index.ts` — makage preserves it; no makage config file exists or is needed)
+- `main: index.js`, `module: esm/index.js`, `types: index.d.ts`, `publishConfig: { access: public, directory: dist }`, NO `files` field (no sibling has one)
+- Scripts (verbatim sibling standard):
+  `clean: makage clean` / `prepack: npm run build` / `build: makage build` / `build:dev: makage build --dev` / `dev: ts-node ./src/index.ts` / `lint: eslint . --fix` / `test: jest --passWithNoTests` / `test:watch: jest --watch`
+- dependencies: `pg ^8.21.0` (imported directly), `inquirerer ^4.9.1`, `@inquirerer/utils ^3.3.9`, `graphile-cache workspace:^` (lazy-required ONLY inside `report predict` — see below)
+- devDependencies: `@types/pg ^8.20.0`, `@types/node ^22.19.11`, `makage ^0.3.0`, `ts-node ^10.9.2`, `@inquirerer/test ^1.4.3`
+- Do NOT declare typescript / jest / ts-jest / eslint / graphql — root-hoisted or irrelevant.
+- `tsconfig.json`, `tsconfig.esm.json`, `jest.config.js`: byte-identical to `packages/server-utils` versions (extends `../../tsconfig.json`; ESM variant outDir `dist/esm`, module es2022, declaration false; jest = ts-jest preset, testRegex `(/__tests__/.*|(\.|/)(test|spec))\.(jsx?|tsx?)$`, modulePathIgnorePatterns `['dist/*']`, NO trailing commas).
+- NO eslint config file in the package (root `.eslintrc.json` governs). Code style: 2-space, single quotes, semicolons, no trailing commas, `_`-prefixed unused args.
+
+## Hard rules (safety + fidelity)
+
+1. **Hub guardrail**: `HUB_PORTS = [5432, 3000, 3001, 3002, 9000]`. EVERY command that dials Postgres or a server port calls `assertPortAllowed(port, allowHub)` and fails with a clear error naming the flag `--allow-hub` to override. PG port default is **5433, never 5432** (preserve the `_lib.mjs` comment's intent).
+2. **Credentials**: never hardcoded. `--email` defaults to `seeder@gmail.com`; `--password` has NO default — resolution order: flag > `PERF_PASSWORD` env. Commands needing auth error out with guidance when it is missing. Never interpolate creds into shell strings (we spawn with arg arrays only).
+3. **No absolute paths** in code. Repo root discovered by walking up from cwd to the first `pnpm-workspace.yaml` (`findRepoRoot()`); server command defaults to `['node', '<repoRoot>/packages/cli/dist/index.js']`, overridable via `--server-cmd`.
+4. All outputs under `--out-dir` (default `./perf-out`), created with mkdir -p. File naming: `metrics-<label>.jsonl`, `harness-<label>.json`, `pg-<label>.jsonl`, `<label>-results.jsonl`, `<name>.log`, `<name>.pid`, `<name>.done`.
+5. Exit codes preserved: harness `0` ok / `1` fatal / `2` bleed-sentinel violation. Regression: `0` pass / `1` fail / `2` bleed.
+6. TypeScript per root config (`strict: true`, `strictNullChecks: false`). `any` is allowed. Plain `console` for CLI output — stdout is reserved for machine-readable JSON/JSONL protocol lines exactly like the originals; human logs go to stderr where the originals did.
+
+## Module layout & interface contract
+
+Domain modules code against these EXACT `core/` signatures (foundation implements them; behavior ports from `scripts/scale-validate/_lib.mjs` unless noted).
+
+```
+src/
+  index.ts               CLI entry (shebang) — routes `perf-harness <domain> <sub> [flags]`
+  commands/{fleet,load,measure,run,report,regression}.ts
+  core/{args,config,rng,histogram,gql,pgc,proc,fleetfile}.ts
+  fleet/{discover,provision,drift,canary,teardown}.ts
+  load/{harness,churn}.ts
+  measure/{collector,pgSampler,instanceHeap}.ts
+  run/{server,ramp,soak,soakOps}.ts
+  report/{summarize,merge,predict}.ts
+  regression/{suite,baselines,compare}.ts
+  __tests__/  (per-domain, colocated under src/<domain>/__tests__/)
+```
+
+### core/args.ts  (port of _lib parseArgs + coercions)
+```ts
+export type Argv = Record<string, any> & { _: string[] };
+export function parseArgv(raw: string[]): Argv;          // --flag value | --flag=value | --flag → true; positionals into _
+export function asBool(v: any, dflt?: boolean): boolean; // '1'|'true'|'yes'|'on'
+export function asInt(v: any, dflt?: number): number;
+export function asFloat(v: any, dflt?: number): number;
+export function usageExit(usage: string, code?: number): number; // prints usage, returns code
+```
+
+### core/config.ts
+```ts
+export interface PgConfig { host: string; port: number; user: string; password: string; database: string }
+export const HUB_PORTS: number[]; // [5432, 3000, 3001, 3002, 9000]
+export function assertPortAllowed(port: number, allowHub: boolean, what?: string): void; // throws Error mentioning --allow-hub
+export function pgConfigFromArgv(argv: Argv): PgConfig;  // --pg-host/--pg-port/--pg-user/--pg-password/--pg-database > PGHOST/PGPORT/PGUSER/PGPASSWORD/PGDATABASE > localhost/5433/postgres/password/constructive; calls assertPortAllowed with asBool(argv['allow-hub'])
+export function findRepoRoot(startDir?: string): string; // walk up to pnpm-workspace.yaml; throws if not found
+export function resolveOutDir(argv: Argv): string;       // --out-dir default './perf-out', mkdir -p
+export function resolveServerCmd(argv: Argv, repoRoot: string): string[]; // --server-cmd (space-split) or default
+export function resolveCreds(argv: Argv): { email: string; password: string | null }; // --email/--password > PERF_PASSWORD
+```
+
+### core/rng.ts — `makeRng(seed)` (mulberry32), `makeZipfSampler(n, rng)`, `makeMixSampler(mixStr, rng)` — verbatim ports.
+
+### core/histogram.ts — `export class Histogram` with `record(ms)`, `percentile(p)`, `summary()` and the DEFAULT_BUCKETS table, verbatim port.
+
+### core/gql.ts — verbatim ports of `gqlFetch` (host-in-URL trick, AbortController timeout, Bearer token), `INTROSPECTION_QUERY`, `isRotating`, `gqlErrors`, `isUnauthenticated`, `unwrapType`, `isNonNull`, `buildTypeIndex`, `discoverOps`, `buildCreateRecord` (+ `export interface GqlResponse { status: number; ok: boolean; json?: any; text?: string; elapsedMs: number; error?: string }` and a `DiscoveredOps` interface matching discoverOps' return).
+
+### core/pgc.ts
+```ts
+export function getPg(): { Client: any; Pool: any };     // = require('pg') — real dependency now, NOT the resolvePg chain
+export function withFreshClient<T>(pg: PgConfig, fn: (client: any) => Promise<T>): Promise<T>; // connect/fn/end in finally
+export function isConnLoss(err: any): boolean;           // 57P01/57P02/57P03/08006/08003/53300 + message sniff (port from tenant-factory)
+export function isRetryableTxn(err: any): boolean;       // 40P01/40001
+```
+
+### core/proc.ts (new — replaces the nohup/python-setsid launcher pattern AND the inline child management)
+```ts
+export interface SpawnDetachedOpts { name: string; cmd: string; args: string[]; env?: Record<string, string>; cwd?: string; outDir: string }
+export function spawnDetached(o: SpawnDetachedOpts): { pid: number; logPath: string; pidPath: string }; // spawn(detached:true, stdio ['ignore', logFd, logFd]), unref(), write <outDir>/<name>.pid
+export function isAlive(pid: number): boolean;                       // kill(pid, 0)
+export function stopPid(pid: number, termTimeoutMs?: number): Promise<'term' | 'kill' | 'gone'>; // SIGTERM → poll → SIGKILL (default 15000)
+export function readPid(outDir: string, name: string): number | null;
+export function waitForPort(port: number, timeoutMs: number): Promise<void>; // probe BOTH 127.0.0.1 and ::1 (macOS binds ::1)
+export function readJsonl(file: string): any[];                      // parse-guarded per line
+export function writeDone(outDir: string, name: string, content?: string): void;
+```
+
+### core/fleetfile.ts
+```ts
+export interface Tenant { dbname: string; databaseId?: string; apiHost?: string; authHost?: string; schemas?: string[]; appPublicSchema?: string }
+export function loadFleet(file: string): { manifest: any; tenants: Tenant[] };  // array | {tenants}; throws if empty
+export const CANARY_PREFIX: string;  // 'CANARY-'
+export function canaryName(t: Tenant): string;
+export interface SubsetOpts { blueprints?: number; perBlueprint?: number; tenants?: number; sameBpRegex?: string }
+export function buildSubset(fleet: Tenant[], drifted: { groups?: Record<string, string[]>; columnDrift?: string[] }, o: SubsetOpts): { subset: any; tenants: Tenant[]; warnings: string[] }; // pure port of subset-fleet.mjs
+```
+
+### run/server.ts (shared by ramp / soak / instanceHeap)
+```ts
+export interface ServerSpawnOpts { name: string; port: number; heapMb: number; metricsFile: string; pg: PgConfig; repoRoot: string; outDir: string; serverCmd?: string[]; cacheMax?: number; instanceHeapBytes?: number; metricsEndpoint?: boolean; extraEnv?: Record<string, string>; detached?: boolean; allowHub?: boolean }
+export function spawnServer(o: ServerSpawnOpts): Promise<{ pid: number; stop: () => Promise<void> }>;
+```
+Env it sets on the child (from the validated soak recipe): `NODE_ENV=production`, `NODE_OPTIONS=--max-old-space-size=<heapMb>`, `GRAPHILE_DEBUG_METRICS=1`, `GRAPHILE_DEBUG_METRICS_FILE=<metricsFile>`, `GRAPHILE_BLUEPRINT_POOLING=1`, `GRAPHILE_METRICS_ENDPOINT=1` when metricsEndpoint, `GRAPHILE_CACHE_MAX=<cacheMax>` when set, `GRAPHILE_CACHE_INSTANCE_HEAP_BYTES=<instanceHeapBytes>` when set, PG* from PgConfig, plus extraEnv. Args: `server --port <port> --origin * --simpleInflection --postgis --servicesApi`. Waits for the port (120s, dual-stack) before resolving.
+
+### Command registration contract
+Each `src/commands/<domain>.ts` exports:
+```ts
+export const domain: string;                       // e.g. 'fleet'
+export const summary: string;                      // one-liner for top-level help
+export interface Subcommand { usage: string; run(argv: Argv): Promise<number> }
+export const subcommands: Record<string, Subcommand>;
+```
+`src/index.ts` (CLI agent) routes `argv._[0]` → domain, `argv._[1]` → subcommand, prints composed help for `--help`/unknown, `process.exitCode = await run(argv)`. Prefer the `inquirerer` CLI shell as `packages/cli` uses it, BUT: never define interactive Questions (automation must not prompt); if nested subcommand routing fights the framework, a hand-rolled router over `parseArgv` is acceptable — working non-interactive CLI beats framework conformance.
+
+## Command tree (source .mjs in parentheses — preserve its flags)
+
+- `fleet discover` (fleet.mjs) · `fleet provision` (tenant-factory.mjs) · `fleet drift` (drift-tenants.mjs — REPLACE its inline pg/defaults with core; ADD --pg-* flag support + --help) · `fleet canary` (canary-seed.mjs) · `fleet subset` (subset-fleet.mjs; pure logic in core/fleetfile buildSubset) · `fleet teardown` (drop-tenants.mjs — keep GUC `constructive.allow_super_constructive`, partman part_config(_sub) cleanup, VACUUM ANALYZE list, `--dry-run`)
+- `load harness` (harness.mjs — THE critical port: token-bucket pacer, mix/shape samplers, auth signIn + token-field scoring, relogin scan, bleed sentinel w/ exit 2, rolling progress JSONL on stdout, SIGTERM-flushed final `--out` JSON, drain ≤15s) · `load churn` (churn-driver.mjs — fresh Client per NOTIFY, stop line on signal)
+- `measure collector` (collector.mjs — `ps -o rss=` sampling, metrics tail, last-half linreg slope MB/h, schema-tolerant counter pick) · `measure pg` (pg-sampler.mjs — docker stats + pg_stat_activity/pg_class/db size) · `measure instance-heap` (measure-instance-heap.mjs — fresh cap=1 server per class via run/server.ts, baseline→cold→settle→delta)
+- `run ramp` (v2-ramps.mjs — RampPlan `{ port?, defaults, steps[] }` typed interface, `cfg = {...defaults, ...step}`, fresh server per step, crash-tolerated-and-recorded, pg backend sampler w/ reconnect, cold-burst mode) · `run soak` — NEW orchestrator replacing run-soak-*.sh: `run soak start` spawns detached server + harness + churn + soak-ops + collector + pg-sampler (pid files), `run soak status` (pids alive, last harness progress line, /metrics snapshot), `run soak stop` (signal fan-out IN ORDER: harness → collector → churn → soak-ops → pg-sampler → server; then writes `<label>.done`) · `run soak-ops` (soak-ops.mjs — ADD the missing SIGTERM handler: finish current cycle child, then final-drop and exit)
+- `report summarize` (summarize-results.mjs) · `report merge` — NEW: merge server metrics JSONL + harness progress JSONL + churn/ops event lines + pg-sampler JSONL into one `report-data.json` (aligned time series, event markers, heap slope, counter deltas) + a markdown summary table printed to stdout · `report predict` — capacity/sizing: lazy `require('graphile-cache')` (typed via a minimal local declaration; the workspace dep exists but MUST NOT be imported at module top level — it pulls the PostGraphile chain into every CLI start) and call `computeCapacityFromBudget(heapLimitBytes, perInstanceBytes, baseReserve?, buildReserve?)`; print capacity + a small sizing table for a list of heap sizes
+- `regression run` — the one-command suite (below) · `regression baselines` — list known baselines
+
+## Regression suite (`regression run`)
+
+Flags: `--fleet <manifest>` (required), `--suite quick|standard` (default quick), `--baseline <name>` (default `catalog61k-2026-07`), `--port` (default 3345), `--heap-mb` (default 3584), `--out-dir`.
+Preflight: PG reachable, catalog `pg_class` count recorded, server dist exists, port free + allowed.
+Checks (each returns `{ name, pass, value, threshold, note }`):
+1. `instance-heap` (standard suite only): `measure instance-heap` on one tenant-api class → KB/pg_class-row ≤ `maxInstanceHeapKBPerRow`
+2. `healthy-single-bp`: ramp step vs same-shape subset at capacity → errRate ≤ 0.005, p99 ≤ 150ms, 0 bleed
+3. `zero-marginal-tenants`: two tenant-count steps (e.g. 10 vs max available) → heapMax delta ≤ 100MB
+4. `thrash-not-crash` (standard): over-capacity diversity step → server process must SURVIVE (crash = FAIL; degraded latency/errors are EXPECTED and not failures)
+5. `bleed`: sentinel violations across all steps == 0 (exit 2 anywhere → suite exit 2)
+Verdict: JSON (`regression-results.json`) + human table; exit 0/1/2.
+
+### regression/baselines.ts (typed const, from the 2026-07 program — V2-RESULTS.md/SIZING.md)
+```ts
+export interface Baseline { name: string; capturedAt: string; catalogPgClassRows: number; instanceHeapKBPerRow: number; pgIntrospectionSpikeKBPerRow: number; minViableHeapMB: number; baseReserveMB: number; buildReserveMB: number; zeroMarginal: { tenants: number[]; heapMaxMB: number[] }; healthy: { rps: number; p99Ms: number; errRate: number }; capacityByHeapMB: Record<string, number>; thresholds: { maxInstanceHeapKBPerRow: number; maxZeroMarginalDeltaMB: number; maxHealthyErrRate: number; maxHealthyP99Ms: number; maxHeapSlopeMBPerHour: number } }
+```
+Seed entry `catalog61k-2026-07`: rows 61238, 21 KB/row, 37 KB/row PG spike, minViable 1536, reserves 256/768, zeroMarginal tenants [10,20,32] → heapMax [1460.1, 1459.6, 1464.1], healthy { rps: 188, p99Ms: 21, errRate: 0 }, capacity { '2048': 1, '3584': 2 }, thresholds { 28, 100, 0.005, 150, 5 }.
+
+## Testing (default `jest` run needs NO network/PG/docker)
+
+Unit tests (fixtures inline or under `__tests__/fixtures/`): parseArgv/coercions; hub-guardrail (5432 throws, 5433 passes, --allow-hub overrides); mulberry32 determinism; zipf/mix samplers (seeded distributions); Histogram percentiles; buildSubset (diversity, tenant-count, warnings — pure JSON); linregSlope + pickCounter + flattenNumeric (collector); dockerMem toBytes; token-field scoring (scoreTokenField/findTokenSelection — export them from load/harness.ts); RampPlan cfg merge; summarize + merge on fixture JSONL; baseline comparator; canary valueForColumn; tenant-factory shape-fingerprint sha256 (fixture pairs) + retry classification. Anything needing a live server/PG: guard behind `process.env.PERF_E2E === '1'` with `describe.skip`-style gating.
+
+## README.md (the runbook)
+
+Must contain: 30-second "regression reappeared" quickstart (rig up via pgpm docker on a NON-hub port → `fleet provision` or existing fleet → `regression run --fleet ...`); the full soak recipe (`run soak start/status/stop`); a metrics-tracking section (what each artifact file is: metrics JSONL fields incl. counters.connGuard/evictions, /metrics endpoint + loopback gating, pg-sampler line, collector summary, report merge output); the sizing model one-liner (capacity law + 21KB/row + 37KB/row constants, shard-per-PG-database guidance); env knob table (GRAPHILE_* from the instrument recon); hub-safety note; creds via PERF_PASSWORD.
+
+## Out of scope (deliberate)
+
+- Do NOT modify or delete `scripts/scale-validate/` (a live soak uses it; retirement happens later).
+- Do NOT touch `graphql/server` / `graphile-cache` source.
+- No CI wiring in this pass.
diff --git a/packages/perf-harness/README.md b/packages/perf-harness/README.md
new file mode 100644
index 0000000000..14259b3001
--- /dev/null
+++ b/packages/perf-harness/README.md
@@ -0,0 +1,465 @@
+# @constructive-io/perf-harness
+
+Reusable performance / regression harness for the Constructive GraphQL server
+(`cnc server` / PostGraphile v5 with blueprint pooling).
+
+It is the packaged form of the ad-hoc `scripts/scale-validate/*.mjs` tooling built
+during the 2026-07 blueprint-pooling scale-validation program. When a memory or
+scale regression reappears, re-run it with **one command** instead of hand-driving
+scripts.
+
+Binary: `perf-harness` (alias `cperf`). Everything is non-interactive — it never
+prompts, so it is safe in CI and unattended soaks.
+
+```
+perf-harness <domain> <subcommand> [flags]
+```
+
+| Domain | What it does |
+|---|---|
+| `fleet` | discover / provision / drift / canary / subset / teardown tenant fleets |
+| `load` | `harness` (paced authenticated workload + cross-tenant bleed sentinel), `churn` (NOTIFY schema:update driver) |
+| `measure` | `collector` (RSS + metrics tail), `pg` (Postgres-side sampler), `instance-heap` (per-blueprint resident heap) |
+| `run` | `ramp` (multi-step regime sweep), `soak` (`start`/`status`/`stop` orchestrator), `soak-ops` (provision/teardown cycler) |
+| `report` | `summarize` (per-step ramp results), `merge` (unified time series), `predict` (capacity / sizing) |
+| `regression` | `run` (one-command pass/fail suite), `baselines` (list known baselines) |
+
+Run `perf-harness <domain> --help` for a domain's subcommands.
+
+---
+
+## 30-second quickstart — "the regression is back"
+
+Everything runs against an **isolated** Postgres and an **isolated** server port so
+it can never touch a running hub (see [Hub safety](#hub-safety)). The rig used
+throughout the program is Postgres on **:5433** in container `constructive-scale-pg`.
+
+```bash
+# 0. credentials (never passed on the command line / interpolated into shells)
+export PERF_PASSWORD='…'          # seeder password; --email defaults to seeder@gmail.com
+
+# 1. bring up an isolated Postgres on a NON-hub port (5433, never 5432)
+pgpm docker start --recreate      # then point PG* at it:
+export PGHOST=localhost PGPORT=5433 PGUSER=postgres PGPASSWORD=password PGDATABASE=constructive
+
+# 2. a fleet: reuse an existing manifest, or provision fresh tenants
+perf-harness fleet provision --count 10 --prefix factory --blueprint marketplace
+perf-harness fleet discover  --like 'marketplace%' --out perf-out/fleet.json
+perf-harness fleet canary    --fleet perf-out/fleet.json         # seed bleed canaries
+
+# 3. run the regression suite (builds a fresh server, ramps, verdicts, tears down)
+perf-harness regression run --fleet perf-out/fleet.json --suite quick
+echo "exit=$?"                     # 0 pass · 1 fail · 2 cross-tenant bleed
+```
+
+`regression run` preflights (PG reachable, catalog `pg_class` count recorded, server
+dist present, port free + allowed), then evaluates each check
+`{ name, pass, value, threshold, note }` against the baseline (default
+`catalog61k-2026-07`) and writes `regression-results.json` plus a human table.
+
+Suite flags: `--fleet <manifest>` (required) · `--suite quick|standard|deep` (default
+`quick`) · `--baseline <name>` · `--port` (default 3345) · `--heap-mb` (default
+3584) · `--deep-heap-mb` (default 7168, `deep` only) · `--out-dir` (default
+`./perf-out`) · `--only`/`--skip` (deep-check filter).
+
+Checks: `healthy-single-bp` (errRate ≤ 0.005, p99 ≤ 150ms, 0 bleed) ·
+`zero-marginal-tenants` (heapMax delta ≤ 100MB across tenant counts) · `bleed`
+(sentinel violations == 0). The `standard` suite adds `instance-heap`
+(≤ 28 KB/pg_class row) and `thrash-not-crash` (over-capacity step must **survive** —
+degraded latency/errors are expected, a crashed process is the only failure). The
+`deep` suite adds four rig-mutating scenarios that cover the axes the other suites
+never touch — see [Deep suite](#deep-suite).
+
+---
+
+## Deep suite
+
+**`--suite deep`** runs everything in `standard` **plus** four scenarios that exercise
+scaling axes the quick/standard checks never touch: multiple hot API surfaces on one
+node, settings-driven pool splits, the cost of a realtime (unpoolable) tenant, and
+catalog creep from `pg_partman`. Unlike the other suites these checks **mutate the
+rig** — they `INSERT` `services_public.database_settings` rows and `CREATE` a
+partition — so each one is wrapped in `try/finally` teardown that returns the rig
+**exactly** to how it was found, each is individually selectable via `--only`/`--skip`,
+its mutating SQL is kept minimal and reversible, and every Postgres/server dial still
+goes through the [hub guardrail](#hub-safety) (`--allow-hub` to override; PG on
+:5433). `--deep-heap-mb` (default **7168**) sizes the server for the multi-API check,
+which needs capacity ≥ 4; the other checks run at the normal `--heap-mb`.
+
+Two of the four can fail the suite (exit 1); the other two are **advisory** — they
+report pass/fail and record their findings but **never** change the verdict or exit
+code (`bleed` remains the only exit-2 trigger):
+
+| Check | Advisory? | Asserts |
+|---|---|---|
+| `multi-api-residency` | no | 4 surfaces resident, 0 evictions, heap ≈ base + 4×I |
+| `settings-variant-split` | no | a settings row forks a 2nd pooled instance; both serve errRate 0 |
+| `realtime-dedicated-cost` | **yes** | a realtime tenant is unpoolable (or captures why it cannot build) |
+| `partition-creep` | **yes** | rows added per partition → projected catalog/heap creep per tenant per month |
+
+### `multi-api-residency` (R=4)
+
+Using 8–10 same-blueprint tenants, it derives one fleet **per surface** by rewriting
+each tenant's `apiHost` to its `admin-…` / `usage-…` host (those domains exist on the
+rig; the `auth-…` host stays for login). At `--deep-heap-mb` (capacity ≥ 4 — verified
+via `computeCapacityFromBudget` or `/metrics`) it cold-builds all four surfaces (api,
+auth via login, admin, usage), then holds all four **hot** for ~120s (a light
+`gqlFetch` loop per surface every 1–2s; the harness child on the api fleet optionally
+supplies the main load). **Asserts** the cache reaches size 4 with **zero LRU
+evictions** during the hold, every surface keeps answering (a 2xx / valid GraphQL
+response on a meta/introspection-safe op), and `heapUsed` plateaus at base + 4×I within
+±20% (`multiApiHeapTolerance`). Records the measured heap-per-instance. Informational
+sub-assert: repeated at heap 3584 (capacity 2), the same four-surface pattern must show
+eviction **churn without process death** — thrash-not-crash at the surface level.
+
+### `settings-variant-split`
+
+`INSERT`s `services_public.database_settings` rows with `enable_aggregates=true` (every
+other column left at its declared default) for exactly **2** same-blueprint tenants,
+triggers them to take effect (a `pg_notify` on `schema:update` carrying those
+`databaseId`s, or the documented flush), then drives one variant tenant and one control
+tenant on the api surface. **Asserts** two **distinct** pooled instances for the same
+relation shape (the builds counter climbs by 2 for the api surface, or the cache-key
+count shows the split) and both groups serve errRate 0 (`settingsSplitExpectedInstances`
+= 2). **Teardown** `DELETE`s the rows and re-flushes, then verifies the pool
+**re-collapses** (or documents the one extra rebuild). If the flush does not pick the
+settings up, the check asserts whatever the recon establishes as the actual contract and
+is marked advisory.
+
+### `realtime-dedicated-cost` (advisory)
+
+`INSERT`s a `database_settings` row with `enable_realtime=true` for **one** tenant,
+flushes, and hits that tenant's api host. Per
+`graphql/server/src/middleware/pooling-decision.ts` a realtime service is unpoolable,
+so the check **either** asserts a dedicated instance (pooling refused — the cache gains
+a non-blueprint key / the pooling-attach counter does not tick for it) and measures its
+heap cost, **or**, if the server cannot build realtime without the module infra,
+captures the exact failure mode as the check result (that is useful data, not a suite
+failure). Either way it confirms the other tenants stay pooled and serving. **Teardown**
+`DELETE`s the row, re-flushes, and verifies the tenant returns to pooled serving.
+Advisory: never flips the verdict.
+
+### `partition-creep` (advisory)
+
+A pure-SQL measurement — **no server**. It reads the `partman.part_config` rows for one
+tenant's schema set (`parent_table LIKE '<tenant-schema>%'`), records each parent's
+`partition_interval` and `premake`, `CREATE`s exactly one additional future partition
+for one `events` parent (via the partman API, or a plain `CREATE TABLE … PARTITION OF`
+with the correct bounds), and measures the `pg_class` row delta for that one partition
+(table + indexes + toast). **Teardown** `DROP`s the partition and verifies the delta
+returns to zero. From rows-per-partition × partitioned-parents-per-tenant ×
+partitions-per-interval it projects catalog rows/tenant/month and, at 22KB/row, heap
+creep MB/tenant/month. Reported as informational against a generous advisory threshold
+(`partitionCreepMaxRowsPerTenantMonth` = 200). Advisory: never flips the verdict.
+
+The four scenarios live in `src/regression/scenarios.ts` (SQL helpers in
+`src/regression/sql.ts`), registered behind the `deep` tier. The baseline
+(`catalog61k-2026-07`) gains deep thresholds `multiApiHeapTolerance: 0.2` ·
+`settingsSplitExpectedInstances: 2` · `partitionCreepMaxRowsPerTenantMonth: 200` and
+expected constants `apiSurfacesRoutable: 8` · `instanceHeapKBPerRow: 21`.
+
+---
+
+## Full soak recipe
+
+A soak is a long-running background rig: one detached server plus five detached
+workers, each with its own `<name>.pid` / `<name>.log` under `--out-dir`.
+
+```bash
+# start: spawns server + harness + churn + soak-ops + collector + pg-sampler (detached)
+perf-harness run soak start \
+  --fleet perf-out/fleet.json --label v3 \
+  --port 3333 --heap-mb 3584 --duration-sec 18000 --out-dir perf-out
+
+# status: pids alive? + last harness progress line + /metrics snapshot
+perf-harness run soak status --label v3 --out-dir perf-out
+
+# stop: ordered signal fan-out, then writes <label>.done
+perf-harness run soak stop --label v3 --out-dir perf-out
+```
+
+`stop` signals the workers **in this order** so the workload quiesces before the
+data collectors and the server go down (and provisioning/teardown finishes its
+current cycle cleanly):
+
+```
+harness → collector → churn → soak-ops → pg-sampler → server
+```
+
+then writes `<label>.done`. Each worker flushes on `SIGTERM`: the harness drains
+in-flight requests (≤ 15s) and writes its final `harness-<label>.json`; `soak-ops`
+finishes the current provision/teardown cycle and drops its last tenant so the
+fleet returns to baseline; the pg-sampler and metrics JSONL are append-per-line
+(nothing to flush).
+
+The server the soak launches gets the validated recipe: `NODE_ENV=production`,
+`NODE_OPTIONS=--max-old-space-size=<heap-mb>`, `GRAPHILE_DEBUG_METRICS=1` +
+`GRAPHILE_DEBUG_METRICS_FILE=<metrics-…>`, `GRAPHILE_BLUEPRINT_POOLING=1`,
+`GRAPHILE_METRICS_ENDPOINT=1`, and `GRAPHILE_CACHE_*` when set, with args
+`server --port <port> --origin * --simpleInflection --postgis --servicesApi`.
+
+---
+
+## Metrics tracking — what each artifact is
+
+All artifacts land under `--out-dir` (default `./perf-out`, created `mkdir -p`).
+File naming is `<kind>-<label>` so a soak's files group together:
+
+| File | Producer | Contents |
+|---|---|---|
+| `metrics-<label>.jsonl` | server (`GRAPHILE_DEBUG_METRICS`) | ~10s server self-report lines (below) |
+| `harness-<label>.json` | `load harness` | final workload report + all rolling progress lines |
+| `pg-<label>.jsonl` | `measure pg` | one Postgres-side sample per interval |
+| `<name>.json` (collector) | `measure collector` | RSS series + slope + metrics counter totals |
+| `<label>-results.jsonl` | `run ramp` | one JSON object per ramp step |
+| `report-data.json` | `report merge` | aligned, merged time series across all of the above |
+| `<name>.log` / `.pid` / `.done` | `run soak` | per-worker stdout+stderr / pid / completion marker |
+
+### Server metrics JSONL — `metrics-<label>.jsonl`
+
+The schema is owned by the server instrumentation; the harness treats it as
+schema-tolerant (flattens the last line, picks the best numeric per counter
+family). Each ~10s line carries heap/RSS, build/eviction/drain activity, the build
+queue depth, and a `counters` block. The counters that matter for regressions:
+
+- `counters.evictions` — LRU evictions of resident blueprint instances. **Non-zero
+  under a steady same-blueprint workload is the classic capacity-1 thrash signal**
+  (batch relogins colliding with api traffic → api↔auth oscillation).
+- `counters.connGuard` — connection-class errors **absorbed** by the guard
+  (57P01 / 08006 / ECONNRESET / …) during a PG crash-recovery window. Counting up
+  is healthy (the node survived); the alternative is a process death.
+- `counters.buildWaitTimeouts` — requests that hit `GRAPHILE_BUILD_TIMEOUT_MS` and
+  returned `503 BUILD_TIMEOUT` (the build still completes in the background). Rising
+  under load means the build queue is backing up.
+- `builds` / `drains` — schema build and drain totals.
+- `heapUsedMB` / `rssMB` / `buildQueueDepth` — sampled gauges; `summarize` surfaces
+  the `heapUsedMaxMB` / `rssMaxMB` / `buildQueueDepthMax` per ramp step.
+
+### `/metrics` endpoint (live snapshot)
+
+Set `GRAPHILE_METRICS_ENDPOINT=1` to expose the same snapshot as JSON at
+`GET /metrics`. It is **loopback-guarded** — only requests from `127.0.0.1` / `::1`
+are served (never reachable off-box), so it is safe to leave enabled on a soak.
+`run soak status` reads it for the live snapshot.
+
+### PG-side sampler line — `pg-<label>.jsonl`
+
+`measure pg` opens a **fresh** `pg` client per sample (a persistent idle client
+would be reaped by `idle_session_timeout`) and appends one line per `--interval-sec`
+(default 30). Sampling errors are recorded on the line and never kill the sampler —
+a PG crash/recovery window is exactly the data worth keeping. Fields:
+
+```
+t              ISO timestamp
+docker         { raw, usedBytes, limitBytes }   # `docker stats` for --container (default constructive-scale-pg); {err} on failure
+backendsByState{ active, idle, "idle in transaction", null, … }  # pg_stat_activity grouped by state
+backendsTotal  total backends on this database
+backendsAllDbs sum(numbackends) across all databases
+pgClassRows    count(*) FROM pg_class   # catalog-size proxy; drives the 21KB/37KB laws
+dbSizeBytes    pg_database_size(current_database())
+err            present only if the whole sample failed
+```
+
+### Collector summary — `measure collector`
+
+`measure collector` samples the server process RSS via `ps -o rss=` every
+`--interval-sec` (default 15) and tails `metrics-<label>.jsonl`. At exit
+(SIGINT/SIGTERM, `--duration-sec`, or the PID disappearing) it writes:
+
+```
+rss.minMb / maxMb / finalMb
+rss.slopeMbPerHour     least-squares slope over the LAST HALF of samples (the leak signal)
+rss.series[]           { tSec, rssMb }
+metrics.evictionsTotal / drainsTotal / buildsTotal   picked from the final metrics line
+metrics.linesSeen, metrics.lastLine
+stopReason, durationSec
+```
+
+The last-half slope is the headline longevity number: a flat/negative
+`slopeMbPerHour` over a multi-hour soak means no leak.
+
+### Workload report — `load harness`
+
+`load harness` streams a rolling progress JSONL line to stdout every `--report-sec`
+and writes the full report to `--out` (`harness-<label>.json`) on completion or
+`SIGTERM` (after a ≤ 15s drain). Each progress line:
+
+```
+t=progress, at, elapsedSec, windowSec,
+sent, completed, ok, err,
+windowRps, cumRps, windowErrRate, inFlight, dropped, rotating,
+latencyWindow { count, min, mean, p50, p95, p99, max },
+sentinelChecks, sentinelOwnSeen, sentinelOk
+```
+
+The **bleed sentinel** periodically (`--sentinel-interval-sec`, default 60) reads
+each tenant and asserts no foreign `CANARY-<dbname>` row is visible. A violation
+flips `sentinelOk=false`, records the offending rows, and **exits 2**. Exit codes:
+`0` ok · `1` fatal · `2` bleed-sentinel violation.
+
+### Merged report — `report merge`
+
+`report merge` aligns the server metrics JSONL, harness progress JSONL, churn /
+soak-ops event lines, and the pg-sampler JSONL into one `report-data.json`
+(a single aligned time series with event markers, the heap slope, and counter
+deltas) and prints a markdown summary table to stdout. `report summarize`
+one-lines each `run ramp` step (crash / errRate / rps / p50-p95-p99 / heapMax /
+evict / builds / connGuard / pgConnMax).
+
+---
+
+## Sizing model (capacity law + constants)
+
+Memory cost is driven by **catalog size** (total relations in the PG database),
+**not** by tenant count. Two constants, measured on the 61k-`pg_class`-row catalog:
+
+- **Node instance heap** `I ≈ 50MB + 21KB × pg_class_rows` — every *resident schema
+  instance* retains this, class-independent (it is the introspection graph), and it
+  is live memory, not GC-able. ~1.3GB at 61k rows.
+- **PG introspection spike** `≈ 37KB × pg_class_rows` **per build** — every schema
+  build spikes a Postgres backend by this much (~2.7GB at 61k rows; OOM > 5.4GB at
+  135k). Backends retain multi-GB relcache and accumulate across the pool; recycle
+  via `idle_session_timeout` or pgbouncer `server_lifetime`.
+
+Tenants that share a blueprint are **free** — zero marginal heap, zero marginal
+builds. So you size in two axes: how many relations live in one PG database (shard
+size) and how many distinct blueprint shapes a node keeps resident (node capacity
+`R`).
+
+**Node capacity** (`report predict`, via `graphile-cache.computeCapacityFromBudget`):
+
+```
+I = per-instance heap        (measure once per catalog size)
+B = base reserve             (server + request working set; default 256MB)
+T = build transient reserve  (one in-flight build;          default 768MB @ 61k rows)
+H = --max-old-space-size
+
+R = clamp( min( ⌊(H − B) / I⌋,  ⌊(H − B − T) / I⌋ + 1 ), 1, 50 )
+```
+
+Validated @61k rows: min viable heap **1536MB** (1 resident; 1152MB aborts
+mid-build with a V8 SIGABRT); 2048MB → R=1; 3584MB → R=2 (api + auth both resident,
+0 evictions). Container RSS ≈ heap × 1.4–1.5 (native/external on top of V8).
+
+**Operating rule:** `R` must cover the node's *actively hit* blueprint set — api and
+auth shapes count **separately**. A tenant fleet on one node needs `R ≥ 2`: at `R=1`
+hourly batch relogins collide with api traffic and failed relogins retry every 30s →
+self-sustaining eviction oscillation; at `R=2` the same workload runs clean.
+
+**Shard-per-PG-database.** Tenants-per-database is the fundamental unit, bounded by
+catalog size on both sides. Instance heap grows with the shard's catalog, so bigger
+shards need disproportionately bigger app nodes — favor **more, smaller shards**. The
+blueprint cache key already scopes by database, so shard-local pooling needs no code
+change. Concretely, ~1000 marketplace-class tenants ≈ 10 shards × ~100 tenants (16GB
+PG nodes), each served by one app node at `R=2` (heap ~6GB, container ~9GB).
+
+---
+
+## Environment knobs
+
+Server behavior is controlled by `GRAPHILE_*` env vars (the harness sets the ones it
+manages; set the rest to tune). Heap is controlled by Node.
+
+| Knob | Effect |
+|---|---|
+| `NODE_OPTIONS=--max-old-space-size=<mb>` | V8 heap budget `H` — the primary capacity lever |
+| `GRAPHILE_BLUEPRINT_POOLING` | `1` = one shared instance per schema-shape (the whole point) |
+| `GRAPHILE_DEBUG_METRICS` | `1` = write the metrics JSONL |
+| `GRAPHILE_DEBUG_METRICS_FILE` | metrics JSONL path |
+| `GRAPHILE_DEBUG_METRICS_INTERVAL_MS` | metrics sample period |
+| `GRAPHILE_METRICS_ENDPOINT` | `1` = expose `GET /metrics` (loopback-guarded) |
+| `GRAPHILE_CACHE_MAX` | hard cap on resident instances (heap-aware; floor 1) |
+| `GRAPHILE_CACHE_INSTANCE_HEAP_BYTES` | measured per-instance heap `I` (set to your catalog's delta + ~10%) |
+| `GRAPHILE_CACHE_BASE_RESERVE_BYTES` | base reserve `B` (default 256MB) |
+| `GRAPHILE_CACHE_BUILD_RESERVE_BYTES` | build transient reserve `T` (default 768MB @ 61k) |
+| `GRAPHILE_CACHE_TTL_MS` | idle resident-instance TTL before drain |
+| `GRAPHILE_CACHE_DRAIN_TIMEOUT_MS` | grace period to drain a to-be-evicted instance |
+| `GRAPHILE_MEMORY_GOVERNOR` | `1` = enable the heap-pressure governor |
+| `GRAPHILE_MEMORY_GOVERNOR_ELEVATED` | proactive-evict threshold (default ~85%) |
+| `GRAPHILE_MEMORY_GOVERNOR_CRITICAL` | refuse-builds threshold (default ~92%; 503 + Retry-After) |
+| `GRAPHILE_BUILD_CONCURRENCY` | BuildSemaphore size (default 1 — serializes node AND PG build spikes) |
+| `GRAPHILE_BUILD_TIMEOUT_MS` | request build-wait bound (503 `BUILD_TIMEOUT`; build finishes in background) |
+| `GRAPHILE_CONNECTION_GUARD` | `0` = disable the connection-class error guard (default on) |
+
+Rule of thumb without measuring: `GRAPHILE_CACHE_INSTANCE_HEAP_BYTES ≈ 50MB + 21KB ×
+pg_class_rows`; measure yours with `perf-harness measure instance-heap`.
+
+---
+
+## Hub safety
+
+`HUB_PORTS = [5432, 3000, 3001, 3002, 9000]` — the ports a local Constructive hub
+(Postgres, the two GraphQL servers, the dashboard, MinIO) listens on. **Every**
+command that dials Postgres or a server port refuses one of those ports unless you
+pass `--allow-hub`, so the harness can never point load at, or spawn a server on top
+of, a live hub. The Postgres port defaults to **5433, never 5432**. Only pass
+`--allow-hub` when you genuinely mean to target the hub.
+
+---
+
+## Credentials
+
+Never hardcoded, never interpolated into shell strings (children are spawned with
+argument arrays only):
+
+- `--email` defaults to `seeder@gmail.com`.
+- `--password` has **no default**. Resolution order: `--password` flag → `PERF_PASSWORD`
+  env. Commands that need auth error out with guidance when it is missing —
+  `export PERF_PASSWORD=…` is the intended path.
+
+---
+
+## Command reference
+
+```
+fleet discover   --like <pat> --out <file> [--pretty] [--pg-*]
+fleet provision  --count <n> --prefix <p> --blueprint <b> [--start-index] [--concurrency] [--validate]
+fleet drift      --groups <n> --per-group <n> --column-drift <n> [--pg-*]
+fleet canary     --fleet <file> [--table categories] [--cleanup] [--pg-*]
+fleet subset     --fleet <file> [--blueprints <n>] [--per-blueprint <n>] [--tenants <n>] [--same-bp-regex] --out <file>
+fleet teardown   --fleet <file> | --only <name> [--keep <n>] [--dry-run] [--pg-*]
+
+load harness     --fleet <file> --port <n> [--rps] [--shape zipf|uniform|burst] [--mix read:..,write:..,meta:..]
+                 [--auth 1] [--sentinel-interval-sec 60] [--relogin-sec 3600] [--duration-sec] --out <file>
+load churn       --fleet <file> [--interval-notify-sec 20] [--provision-every-sec] [--channel schema:update] [--duration-sec]
+
+measure collector    --pid <n> [--metrics-file <f>] [--interval-sec 15] [--duration-sec] --out <file>
+measure pg           [--container constructive-scale-pg] [--interval-sec 30] [--duration-sec] --out <file> [--pg-*]
+measure instance-heap --label <l> --host <api-host> [--port] [--heap-mb] [--cache-max 1] [--settle-sec]
+
+run ramp         --plan <plan.json> [--only step1,step2] --out <results.jsonl>
+run soak start   --fleet <file> --label <l> [--port] [--heap-mb] [--duration-sec] [--out-dir]
+run soak status  --label <l> [--out-dir]
+run soak stop    --label <l> [--out-dir]
+run soak-ops     [--interval-sec 7200] [--duration-sec 86400] [--prefix soak]
+
+report summarize <results.jsonl> [...more]
+report merge     --metrics <m.jsonl> --harness-log <h.jsonl> [--churn-log <c.jsonl>] [--ops-log <o.log>] [--pg <pg.jsonl>] [--out-dir ./perf-out]
+report predict   --instance-heap-bytes <n> [--heap-mb 1536,2048,3584] [--base-reserve-bytes <n>] [--build-reserve-bytes <n>]
+
+regression run       --fleet <file> [--suite quick|standard|deep] [--baseline <name>] [--port] [--heap-mb] [--deep-heap-mb 7168] [--out-dir] [--only <checks>] [--skip <checks>]
+regression baselines
+```
+
+Global: `--help` / `-h` (top-level or per-domain usage) · `--version`.
+Connection flags `--pg-host/--pg-port/--pg-user/--pg-password/--pg-database` override
+`PGHOST/PGPORT/PGUSER/PGPASSWORD/PGDATABASE`, which override
+`localhost/5433/postgres/password/constructive`.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | ok / suite pass |
+| `1` | fatal error / suite fail / usage error |
+| `2` | cross-tenant **bleed** sentinel violation (`load harness`, `regression run`) |
+
+## Testing
+
+`pnpm test` (jest) is pure-unit and needs **no** network, Postgres, or Docker:
+argv parsing + coercions, the hub guardrail, RNG determinism, the zipf/mix samplers,
+histogram percentiles, subset construction, collector math, token-field scoring,
+ramp config merge, summarize/merge on fixtures, the baseline comparator, the deep-suite
+helpers (host-rewrite fleet derivation, partition-creep math, advisory-verdict
+aggregation, and the settings-SQL builder), and the tenant-factory shape fingerprint.
+Anything needing a live server/PG is gated behind `PERF_E2E=1`.
diff --git a/packages/perf-harness/jest.config.js b/packages/perf-harness/jest.config.js
new file mode 100644
index 0000000000..057a9420ed
--- /dev/null
+++ b/packages/perf-harness/jest.config.js
@@ -0,0 +1,18 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        babelConfig: false,
+        tsconfig: 'tsconfig.json',
+      },
+    ],
+  },
+  transformIgnorePatterns: [`/node_modules/*`],
+  testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  modulePathIgnorePatterns: ['dist/*']
+};
diff --git a/packages/perf-harness/package.json b/packages/perf-harness/package.json
new file mode 100644
index 0000000000..d91bc4f2d1
--- /dev/null
+++ b/packages/perf-harness/package.json
@@ -0,0 +1,58 @@
+{
+  "name": "@constructive-io/perf-harness",
+  "version": "0.1.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "Reusable performance / regression harness for the Constructive GraphQL server",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "bin": {
+    "perf-harness": "index.js",
+    "cperf": "index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "dev": "ts-node ./src/index.ts",
+    "lint": "eslint . --fix",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@inquirerer/utils": "^3.3.9",
+    "graphile-cache": "workspace:^",
+    "inquirerer": "^4.9.1",
+    "pg": "^8.21.0"
+  },
+  "devDependencies": {
+    "@inquirerer/test": "^1.4.3",
+    "@types/node": "^22.19.11",
+    "@types/pg": "^8.20.0",
+    "makage": "^0.3.0",
+    "ts-node": "^10.9.2"
+  },
+  "keywords": [
+    "performance",
+    "regression",
+    "harness",
+    "soak",
+    "constructive",
+    "graphile",
+    "postgres"
+  ]
+}
diff --git a/packages/perf-harness/src/commands/fleet.ts b/packages/perf-harness/src/commands/fleet.ts
new file mode 100644
index 0000000000..07715f5467
--- /dev/null
+++ b/packages/perf-harness/src/commands/fleet.ts
@@ -0,0 +1,120 @@
+/**
+ * `fleet` command group — provision / discover / drift / canary / subset /
+ * teardown the perf tenant fleet.
+ *
+ * Each subcommand delegates to a `src/fleet/*` module, except `subset`, whose
+ * pure algorithm lives in `core/fleetfile.buildSubset`; the CLI glue (read
+ * --fleet + --drifted, write --out) is implemented inline here.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { Argv, asBool, asInt, usageExit } from '../core/args';
+import { buildSubset, loadFleet, SubsetOpts } from '../core/fleetfile';
+import * as canary from '../fleet/canary';
+import * as discover from '../fleet/discover';
+import * as drift from '../fleet/drift';
+import * as provision from '../fleet/provision';
+import * as teardown from '../fleet/teardown';
+
+export const domain = 'fleet';
+export const summary = 'discover / provision / drift / canary / subset / teardown the perf tenant fleet';
+
+export interface Subcommand {
+  usage: string;
+  run(argv: Argv): Promise<number>;
+}
+
+const SUBSET_USAGE = `perf-harness fleet subset — derive a ramp-specific fleet manifest from a fleet + drift assignment
+
+Options:
+  --fleet <file>         fleet manifest from \`fleet discover\` (required)
+  --drifted <file>       drift assignment from \`fleet drift\` (optional)
+  --out <file>           write the subset manifest here (required)
+  --blueprints <K>       diversity subset: first K blueprint groups
+  --per-blueprint <N>    tenants per blueprint group (default: 5)
+  --tenants <N>          tenant-count subset: N group-0 tenants (single blueprint)
+  --same-bp-regex <re>   group-0 membership regex (default: ^(factory[0-9]+|marketplace_db_tenant1)$)
+  --help
+`;
+
+async function runSubset(argv: Argv): Promise<number> {
+  if (asBool(argv.help)) return usageExit(SUBSET_USAGE, 0);
+
+  const fleetFile = typeof argv.fleet === 'string' ? argv.fleet : null;
+  const out = typeof argv.out === 'string' ? argv.out : null;
+  if (!fleetFile) {
+    console.error('--fleet is required');
+    return 1;
+  }
+  if (!out) {
+    console.error('--out is required');
+    return 1;
+  }
+
+  try {
+    const fleet = loadFleet(fleetFile).tenants;
+    const drifted =
+      typeof argv.drifted === 'string'
+        ? JSON.parse(fs.readFileSync(argv.drifted, 'utf8'))
+        : { groups: {}, columnDrift: [] };
+    const o: SubsetOpts = {
+      blueprints: asInt(argv.blueprints, 0),
+      perBlueprint: asInt(argv['per-blueprint'], 5),
+      tenants: asInt(argv.tenants, 0),
+      sameBpRegex: typeof argv['same-bp-regex'] === 'string' ? argv['same-bp-regex'] : undefined
+    };
+
+    const { subset, tenants, warnings } = buildSubset(fleet, drifted, o);
+    for (const w of warnings) console.error(w);
+
+    // Preserve the original subset-fleet.mjs manifest shape (adds `derivedFrom`,
+    // which core/fleetfile.buildSubset omits).
+    const manifest = {
+      generatedAt: subset.generatedAt,
+      derivedFrom: fleetFile,
+      subset: subset.subset,
+      count: subset.count,
+      tenants: subset.tenants
+    };
+
+    fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
+    fs.writeFileSync(out, JSON.stringify(manifest) + '\n');
+    console.error(`[subset] ${subset.subset}: ${tenants.length} tenants -> ${out}`);
+    return 0;
+  } catch (err: any) {
+    console.error(String((err && err.message) || err));
+    return 1;
+  }
+}
+
+// Concise one-line synopses for the composed domain-level help listing; each
+// subcommand's own `--help` prints its fuller USAGE (via its `run`).
+export const subcommands: Record<string, Subcommand> = {
+  discover: {
+    usage: "fleet discover [--like '%'] [--out fleet.json] [--pretty] [--pg-* ...]",
+    run: discover.run
+  },
+  provision: {
+    usage:
+      'fleet provision [--count 1] [--prefix factory] [--blueprint marketplace] [--concurrency 1] [--dry-run] [--validate <db>] [--pg-* ...]',
+    run: provision.run
+  },
+  drift: {
+    usage: 'fleet drift [--groups K] [--per-group 4] [--column-drift N] [--out <f>] [--pg-* ...]',
+    run: drift.run
+  },
+  canary: {
+    usage: 'fleet canary --fleet <file> [--table categories] [--cleanup] [--pg-* ...]',
+    run: canary.run
+  },
+  subset: {
+    usage:
+      'fleet subset --fleet <file> --out <file> [--drifted <file>] [--blueprints K --per-blueprint N | --tenants N] [--same-bp-regex <re>]',
+    run: runSubset
+  },
+  teardown: {
+    usage: 'fleet teardown [--prefix factory] [--keep 40] [--only <db>] [--dry-run] [--pg-* ...]',
+    run: teardown.run
+  }
+};
diff --git a/packages/perf-harness/src/commands/load.ts b/packages/perf-harness/src/commands/load.ts
new file mode 100644
index 0000000000..586abcf61d
--- /dev/null
+++ b/packages/perf-harness/src/commands/load.ts
@@ -0,0 +1,31 @@
+/**
+ * `load` domain — workload drivers.
+ *
+ *   perf-harness load harness  paced GraphQL load + bleed sentinel (harness.mjs)
+ *   perf-harness load churn    schema-cache NOTIFY churn        (churn-driver.mjs)
+ *
+ * Each subcommand handles its own `--help` and returns a numeric exit code
+ * (harness: 0 ok / 1 fatal / 2 bleed-sentinel violation; churn: 0 / 1).
+ */
+import { Argv } from '../core/args';
+import { runChurn } from '../load/churn';
+import { runHarness } from '../load/harness';
+
+export const domain = 'load';
+export const summary = 'workload drivers — paced GraphQL load (bleed sentinel) and schema-cache churn';
+
+export interface Subcommand {
+  usage: string;
+  run(argv: Argv): Promise<number>;
+}
+
+export const subcommands: Record<string, Subcommand> = {
+  harness: {
+    usage: 'load harness --fleet <file> [--port 3333 --duration-sec 60 --rps 20 --mix read:.7,write:.25,meta:.05 --shape zipf|uniform|burst --auth 0|1 --out results.json]',
+    run: runHarness
+  },
+  churn: {
+    usage: 'load churn --fleet <file> [--interval-notify-sec 20 --provision-every-sec 0 --duration-sec 3600 --channel schema:update --pg-* ...]',
+    run: runChurn
+  }
+};
diff --git a/packages/perf-harness/src/commands/measure.ts b/packages/perf-harness/src/commands/measure.ts
new file mode 100644
index 0000000000..b3fee471f8
--- /dev/null
+++ b/packages/perf-harness/src/commands/measure.ts
@@ -0,0 +1,34 @@
+/**
+ * `measure` domain — memory/heap measurement primitives.
+ *
+ *   measure collector      RSS sampler + server-metrics tailer (collector.mjs)
+ *   measure pg             PG-side docker + pg_stat_activity sampler (pg-sampler.mjs)
+ *   measure instance-heap  marginal per-class instance heap cost (measure-instance-heap.mjs)
+ */
+import { Argv } from '../core/args';
+import { runCollector } from '../measure/collector';
+import { runInstanceHeap } from '../measure/instanceHeap';
+import { runPgSampler } from '../measure/pgSampler';
+
+export const domain = 'measure';
+export const summary = 'memory/heap measurement: RSS+metrics collector, PG sampler, per-class instance-heap';
+
+export interface Subcommand {
+  usage: string;
+  run(argv: Argv): Promise<number>;
+}
+
+export const subcommands: Record<string, Subcommand> = {
+  collector: {
+    usage: 'measure collector --pid <n> [--metrics-file <f>] [--interval-sec 15] [--duration-sec 0] [--out collector.json]',
+    run: runCollector
+  },
+  pg: {
+    usage: 'measure pg [--out out/pg-soak.jsonl] [--interval-sec 30] [--duration-sec 0] [--container constructive-scale-pg] [--pg-* ...]',
+    run: runPgSampler
+  },
+  'instance-heap': {
+    usage: 'measure instance-heap --host <vhost> [--label <name>] [--port 3344] [--heap-mb 2048] [--cache-max 1] [--settle-sec 70] [--out-dir ./perf-out]',
+    run: runInstanceHeap
+  }
+};
diff --git a/packages/perf-harness/src/commands/regression.ts b/packages/perf-harness/src/commands/regression.ts
new file mode 100644
index 0000000000..8e7b8b1cab
--- /dev/null
+++ b/packages/perf-harness/src/commands/regression.ts
@@ -0,0 +1,44 @@
+/**
+ * `perf-harness regression <sub>` — the one-command regression suite + catalog.
+ *
+ * Registration contract (consumed by src/index.ts): a domain name, a one-line
+ * summary, a `Subcommand` shape, and a `subcommands` map.
+ */
+import { Argv } from '../core/args';
+import { DEFAULT_BASELINE, listBaselines } from '../regression/baselines';
+import { runRegression } from '../regression/suite';
+
+export const domain = 'regression';
+export const summary = 'run the regression suite against a baseline, or list known baselines';
+
+export interface Subcommand {
+  usage: string;
+  run(argv: Argv): Promise<number>;
+}
+
+async function runBaselines(_argv: Argv): Promise<number> {
+  const rows = listBaselines();
+  console.log(`known baselines (default: ${DEFAULT_BASELINE}):`);
+  for (const b of rows) {
+    console.log(
+      `  ${b.name}  (captured ${b.capturedAt})  catalog=${b.catalogPgClassRows} rows  ` +
+        `I=${b.instanceHeapKBPerRow}KB/row  minViable=${b.minViableHeapMB}MB  ` +
+        `thresholds: errRate<=${b.thresholds.maxHealthyErrRate} p99<=${b.thresholds.maxHealthyP99Ms}ms ` +
+        `zmDelta<=${b.thresholds.maxZeroMarginalDeltaMB}MB heapKB/row<=${b.thresholds.maxInstanceHeapKBPerRow} ` +
+        `slope<=${b.thresholds.maxHeapSlopeMBPerHour}MB/h`
+    );
+  }
+  return 0;
+}
+
+export const subcommands: Record<string, Subcommand> = {
+  run: {
+    usage:
+      'regression run --fleet <manifest> [--suite quick|standard|deep] [--baseline <name>] [--port 3345] [--heap-mb 3584] [--deep-heap-mb 7168] [--out-dir ./perf-out] [--drifted <f>] [--same-bp-regex <re>] [--only <scenario,...>] [--skip <scenario,...>] [--server-cmd "..."] [--allow-hub]',
+    run: runRegression
+  },
+  baselines: {
+    usage: 'regression baselines',
+    run: runBaselines
+  }
+};
diff --git a/packages/perf-harness/src/commands/report.ts b/packages/perf-harness/src/commands/report.ts
new file mode 100644
index 0000000000..a49843cd77
--- /dev/null
+++ b/packages/perf-harness/src/commands/report.ts
@@ -0,0 +1,34 @@
+/**
+ * `perf-harness report <sub>` — post-run analysis commands.
+ *
+ * Registration contract (consumed by src/index.ts): a domain name, a one-line
+ * summary, a `Subcommand` shape, and a `subcommands` map.
+ */
+import { Argv } from '../core/args';
+import { runMerge } from '../report/merge';
+import { runPredict } from '../report/predict';
+import { runSummarize } from '../report/summarize';
+
+export const domain = 'report';
+export const summary = 'analyze run artifacts: summarize step results, merge series, predict capacity';
+
+export interface Subcommand {
+  usage: string;
+  run(argv: Argv): Promise<number>;
+}
+
+export const subcommands: Record<string, Subcommand> = {
+  summarize: {
+    usage: 'report summarize <results.jsonl> [more.jsonl ...]',
+    run: runSummarize
+  },
+  merge: {
+    usage:
+      'report merge --metrics <m.jsonl> --harness-log <h.jsonl> [--churn-log <c.jsonl>] [--ops-log <o.log>] [--pg <pg.jsonl>] [--out-dir ./perf-out]',
+    run: runMerge
+  },
+  predict: {
+    usage: 'report predict --instance-heap-bytes <n> [--heap-mb 1536,2048,3584] [--base-reserve-bytes <n>] [--build-reserve-bytes <n>]',
+    run: runPredict
+  }
+};
diff --git a/packages/perf-harness/src/commands/run.ts b/packages/perf-harness/src/commands/run.ts
new file mode 100644
index 0000000000..49b8305a1d
--- /dev/null
+++ b/packages/perf-harness/src/commands/run.ts
@@ -0,0 +1,28 @@
+/**
+ * `run` domain — server lifecycle + ramp / soak orchestration.
+ *
+ * Subcommands:
+ *   run ramp                     V2 limits-discovery executor (fresh server per step)
+ *   run soak <start|status|stop> long-running soak orchestrator
+ *   run soak-ops                 provision/drop cycles during a soak
+ *
+ * `run soak` routes on the next positional (argv._[2]) inside runSoak.
+ */
+import { Argv } from '../core/args';
+import { RAMP_USAGE, runRamp } from '../run/ramp';
+import { runSoak, SOAK_USAGE } from '../run/soak';
+import { runSoakOps, SOAK_OPS_USAGE } from '../run/soakOps';
+
+export const domain = 'run';
+export const summary = 'server lifecycle + ramp / soak orchestration';
+
+export interface Subcommand {
+  usage: string;
+  run(argv: Argv): Promise<number>;
+}
+
+export const subcommands: Record<string, Subcommand> = {
+  ramp: { usage: RAMP_USAGE, run: (argv: Argv) => runRamp(argv) },
+  soak: { usage: SOAK_USAGE, run: (argv: Argv) => runSoak(argv) },
+  'soak-ops': { usage: SOAK_OPS_USAGE, run: (argv: Argv) => runSoakOps(argv) }
+};
diff --git a/packages/perf-harness/src/core/__tests__/args.test.ts b/packages/perf-harness/src/core/__tests__/args.test.ts
new file mode 100644
index 0000000000..5e9bece78b
--- /dev/null
+++ b/packages/perf-harness/src/core/__tests__/args.test.ts
@@ -0,0 +1,65 @@
+import { asBool, asFloat, asInt, parseArgv } from '../args';
+
+describe('parseArgv', () => {
+  test('--flag value form', () => {
+    expect(parseArgv(['--host', 'h'])).toEqual({ _: [], host: 'h' });
+  });
+
+  test('--flag=value form', () => {
+    expect(parseArgv(['--host=h'])).toEqual({ _: [], host: 'h' });
+  });
+
+  test('bare --flag becomes true', () => {
+    expect(parseArgv(['--verbose'])).toEqual({ _: [], verbose: true });
+  });
+
+  test('bare flag immediately before another flag is true', () => {
+    const a = parseArgv(['--dry-run', '--tenants', '5']);
+    expect(a['dry-run']).toBe(true);
+    expect(a.tenants).toBe('5');
+  });
+
+  test('trailing bare flag is true', () => {
+    const a = parseArgv(['--tenants', '5', '--allow-hub']);
+    expect(a.tenants).toBe('5');
+    expect(a['allow-hub']).toBe(true);
+  });
+
+  test('positionals collect into _', () => {
+    const a = parseArgv(['fleet', 'subset', '--tenants', '5']);
+    expect(a._).toEqual(['fleet', 'subset']);
+    expect(a.tenants).toBe('5');
+  });
+
+  test('empty argv yields just _', () => {
+    expect(parseArgv([])).toEqual({ _: [] });
+  });
+});
+
+describe('coercions', () => {
+  test('asBool truthy tokens', () => {
+    for (const v of ['1', 'true', 'TRUE', 'yes', 'on']) expect(asBool(v)).toBe(true);
+  });
+
+  test('asBool falsy tokens + default', () => {
+    for (const v of ['0', 'false', 'no', 'nope', 'off']) expect(asBool(v)).toBe(false);
+    expect(asBool(undefined)).toBe(false);
+    expect(asBool(undefined, true)).toBe(true);
+    expect(asBool(null, true)).toBe(true);
+    expect(asBool(true)).toBe(true);
+    expect(asBool(false)).toBe(false);
+  });
+
+  test('asInt parses / falls back', () => {
+    expect(asInt('42')).toBe(42);
+    expect(asInt('42px')).toBe(42);
+    expect(asInt(undefined, 7)).toBe(7);
+    expect(asInt('notnum', 3)).toBe(3);
+  });
+
+  test('asFloat parses / falls back', () => {
+    expect(asFloat('3.14')).toBeCloseTo(3.14);
+    expect(asFloat(undefined, 1.5)).toBe(1.5);
+    expect(asFloat('nope', 2.5)).toBe(2.5);
+  });
+});
diff --git a/packages/perf-harness/src/core/__tests__/config.test.ts b/packages/perf-harness/src/core/__tests__/config.test.ts
new file mode 100644
index 0000000000..317059e6bc
--- /dev/null
+++ b/packages/perf-harness/src/core/__tests__/config.test.ts
@@ -0,0 +1,83 @@
+import { parseArgv } from '../args';
+import { assertPortAllowed, HUB_PORTS, pgConfigFromArgv, resolveCreds } from '../config';
+
+const ORIGINAL_ENV = process.env;
+beforeEach(() => {
+  process.env = { ...ORIGINAL_ENV };
+});
+afterEach(() => {
+  process.env = ORIGINAL_ENV;
+});
+
+describe('hub guardrail', () => {
+  test('HUB_PORTS is the exact reserved set', () => {
+    expect(HUB_PORTS).toEqual([5432, 3000, 3001, 3002, 9000]);
+  });
+
+  test('reserved hub port 5432 throws and names --allow-hub', () => {
+    expect(() => assertPortAllowed(5432, false)).toThrow(/--allow-hub/);
+  });
+
+  test('every reserved port throws', () => {
+    for (const p of HUB_PORTS) expect(() => assertPortAllowed(p, false)).toThrow();
+  });
+
+  test('isolated port 5433 passes', () => {
+    expect(() => assertPortAllowed(5433, false)).not.toThrow();
+  });
+
+  test('--allow-hub overrides the guardrail', () => {
+    expect(() => assertPortAllowed(5432, true)).not.toThrow();
+  });
+});
+
+describe('pgConfigFromArgv precedence', () => {
+  test('defaults to 5433 (never 5432) / localhost / postgres / constructive', () => {
+    for (const k of ['PGHOST', 'PGPORT', 'PGUSER', 'PGPASSWORD', 'PGDATABASE']) delete process.env[k];
+    const cfg = pgConfigFromArgv(parseArgv([]));
+    expect(cfg).toEqual({
+      host: 'localhost',
+      port: 5433,
+      user: 'postgres',
+      password: 'password',
+      database: 'constructive'
+    });
+  });
+
+  test('flags beat env beat defaults', () => {
+    process.env.PGHOST = 'envhost';
+    process.env.PGPORT = '5999';
+    process.env.PGUSER = 'envuser';
+    const cfg = pgConfigFromArgv(parseArgv(['--pg-host', 'flaghost', '--pg-database', 'mydb']));
+    expect(cfg.host).toBe('flaghost'); // flag wins
+    expect(cfg.port).toBe(5999); // env beats default
+    expect(cfg.user).toBe('envuser'); // env beats default
+    expect(cfg.database).toBe('mydb'); // flag
+    expect(cfg.password).toBe('password'); // default
+  });
+
+  test('rejects hub port 5432 unless --allow-hub', () => {
+    expect(() => pgConfigFromArgv(parseArgv(['--pg-port', '5432']))).toThrow(/--allow-hub/);
+    const cfg = pgConfigFromArgv(parseArgv(['--pg-port', '5432', '--allow-hub']));
+    expect(cfg.port).toBe(5432);
+  });
+});
+
+describe('resolveCreds', () => {
+  test('email defaults to seeder@gmail.com; password never has a literal default', () => {
+    delete process.env.PERF_PASSWORD;
+    expect(resolveCreds(parseArgv([]))).toEqual({ email: 'seeder@gmail.com', password: null });
+  });
+
+  test('password resolution: flag > PERF_PASSWORD env > null', () => {
+    delete process.env.PERF_PASSWORD;
+    expect(resolveCreds(parseArgv(['--password', 'p1'])).password).toBe('p1');
+    process.env.PERF_PASSWORD = 'envpw';
+    expect(resolveCreds(parseArgv([])).password).toBe('envpw');
+    expect(resolveCreds(parseArgv(['--password', 'flagpw'])).password).toBe('flagpw');
+  });
+
+  test('custom email flag is honored', () => {
+    expect(resolveCreds(parseArgv(['--email', 'x@y.com'])).email).toBe('x@y.com');
+  });
+});
diff --git a/packages/perf-harness/src/core/__tests__/fixtures/drifted.json b/packages/perf-harness/src/core/__tests__/fixtures/drifted.json
new file mode 100644
index 0000000000..3503f9827a
--- /dev/null
+++ b/packages/perf-harness/src/core/__tests__/fixtures/drifted.json
@@ -0,0 +1,6 @@
+{
+  "groups": {
+    "1": ["drift_a", "drift_b"]
+  },
+  "columnDrift": ["factory3"]
+}
diff --git a/packages/perf-harness/src/core/__tests__/fixtures/empty-fleet.json b/packages/perf-harness/src/core/__tests__/fixtures/empty-fleet.json
new file mode 100644
index 0000000000..c567a93b2b
--- /dev/null
+++ b/packages/perf-harness/src/core/__tests__/fixtures/empty-fleet.json
@@ -0,0 +1 @@
+{ "tenants": [] }
diff --git a/packages/perf-harness/src/core/__tests__/fixtures/fleet.json b/packages/perf-harness/src/core/__tests__/fixtures/fleet.json
new file mode 100644
index 0000000000..2fa921f90b
--- /dev/null
+++ b/packages/perf-harness/src/core/__tests__/fixtures/fleet.json
@@ -0,0 +1,13 @@
+{
+  "tenants": [
+    { "dbname": "factory1" },
+    { "dbname": "factory2" },
+    { "dbname": "factory3" },
+    { "dbname": "factory4" },
+    { "dbname": "factory5" },
+    { "dbname": "marketplace_db_tenant1" },
+    { "dbname": "tenant2" },
+    { "dbname": "drift_a" },
+    { "dbname": "drift_b" }
+  ]
+}
diff --git a/packages/perf-harness/src/core/__tests__/fleetfile.test.ts b/packages/perf-harness/src/core/__tests__/fleetfile.test.ts
new file mode 100644
index 0000000000..e9e4456af2
--- /dev/null
+++ b/packages/perf-harness/src/core/__tests__/fleetfile.test.ts
@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { buildSubset, canaryName, CANARY_PREFIX, loadFleet, Tenant } from '../fleetfile';
+
+const fixture = (name: string): string => path.join(__dirname, 'fixtures', name);
+const fleet: Tenant[] = loadFleet(fixture('fleet.json')).tenants;
+const drifted = JSON.parse(fs.readFileSync(fixture('drifted.json'), 'utf8'));
+const names = (ts: Tenant[]): string[] => ts.map((t) => t.dbname);
+
+describe('loadFleet', () => {
+  test('reads the tenant array from a {tenants} manifest', () => {
+    const { tenants } = loadFleet(fixture('fleet.json'));
+    expect(tenants.length).toBe(9);
+  });
+
+  test('throws on an empty fleet', () => {
+    expect(() => loadFleet(fixture('empty-fleet.json'))).toThrow(/no tenants/);
+  });
+});
+
+describe('canary naming', () => {
+  test('prefix + dbname', () => {
+    expect(CANARY_PREFIX).toBe('CANARY-');
+    expect(canaryName({ dbname: 'factory7' })).toBe('CANARY-factory7');
+  });
+});
+
+describe('buildSubset — diversity mode', () => {
+  test('first K groups, N per group', () => {
+    const { subset, tenants, warnings } = buildSubset(fleet, drifted, { blueprints: 2, perBlueprint: 2 });
+    expect(names(tenants)).toEqual(['factory1', 'factory2', 'drift_a', 'drift_b']);
+    expect(subset.count).toBe(4);
+    expect(subset.subset).toBe('diversity k=2 per=2');
+    expect(warnings).toEqual([]);
+  });
+
+  test('warns when a group has fewer than perBlueprint tenants', () => {
+    const { tenants, warnings } = buildSubset(fleet, drifted, { blueprints: 2, perBlueprint: 5 });
+    // group0 gives 5 (factory1..5); drift group only has 2
+    expect(names(tenants)).toEqual(['factory1', 'factory2', 'factory3', 'factory4', 'factory5', 'drift_a', 'drift_b']);
+    expect(warnings).toEqual(['warn: group 1 has only 2/5 tenants']);
+  });
+
+  test('throws when asking for more blueprint groups than exist', () => {
+    expect(() => buildSubset(fleet, drifted, { blueprints: 5 })).toThrow('only 2 blueprint groups available, asked for 5');
+  });
+});
+
+describe('buildSubset — tenant-count mode', () => {
+  test('N group-0 tenants (column-drift tenant stays in group 0)', () => {
+    const { subset, tenants, warnings } = buildSubset(fleet, drifted, { tenants: 3 });
+    // factory3 is in columnDrift but keeps its relname set => still group 0
+    expect(names(tenants)).toEqual(['factory1', 'factory2', 'factory3']);
+    expect(subset.subset).toBe('tenant-count n=3 (single blueprint)');
+    expect(subset.count).toBe(3);
+    expect(warnings).toEqual([]);
+  });
+
+  test('warns when fewer undrifted tenants are available than requested', () => {
+    const { subset, tenants, warnings } = buildSubset(fleet, drifted, { tenants: 100 });
+    expect(tenants.length).toBe(6); // factory1..5 + marketplace_db_tenant1
+    expect(subset.subset).toBe('tenant-count n=6 (single blueprint)');
+    expect(warnings).toEqual(['warn: only 6/100 undrifted tenants available']);
+  });
+
+  test('excludes non-matching (divergent) seeder tenants like tenant2', () => {
+    const { tenants } = buildSubset(fleet, drifted, { tenants: 100 });
+    expect(names(tenants)).not.toContain('tenant2');
+    expect(names(tenants)).not.toContain('drift_a');
+  });
+});
+
+describe('buildSubset — mode selection', () => {
+  test('throws when neither mode is selected', () => {
+    expect(() => buildSubset(fleet, drifted, {})).toThrow('one of --blueprints or --tenants is required');
+  });
+
+  test('custom sameBpRegex changes group 0 membership', () => {
+    const { tenants } = buildSubset(fleet, { groups: {} }, { tenants: 100, sameBpRegex: '^factory[0-9]+$' });
+    // marketplace_db_tenant1 no longer matches
+    expect(names(tenants)).toEqual(['factory1', 'factory2', 'factory3', 'factory4', 'factory5']);
+  });
+});
diff --git a/packages/perf-harness/src/core/__tests__/histogram.test.ts b/packages/perf-harness/src/core/__tests__/histogram.test.ts
new file mode 100644
index 0000000000..b9593091b7
--- /dev/null
+++ b/packages/perf-harness/src/core/__tests__/histogram.test.ts
@@ -0,0 +1,55 @@
+import { DEFAULT_BUCKETS, Histogram } from '../histogram';
+
+describe('Histogram', () => {
+  test('empty histogram: zero percentiles and summary', () => {
+    const h = new Histogram();
+    expect(h.percentile(50)).toBe(0);
+    expect(h.summary()).toEqual({
+      count: 0,
+      min: 0,
+      mean: 0,
+      p50: 0,
+      p95: 0,
+      p99: 0,
+      max: 0
+    });
+  });
+
+  test('summary has the exact field set and basic stats', () => {
+    const h = new Histogram();
+    [10, 20, 30].forEach((v) => h.record(v));
+    const s = h.summary();
+    expect(Object.keys(s).sort()).toEqual(['count', 'max', 'mean', 'min', 'p50', 'p95', 'p99'].sort());
+    expect(s.count).toBe(3);
+    expect(s.min).toBe(10);
+    expect(s.max).toBe(30);
+    expect(s.mean).toBe(20);
+  });
+
+  test('percentiles land on bucket boundaries', () => {
+    const h = new Histogram();
+    for (let i = 0; i < 100; i++) h.record(5); // 5 is a bucket edge
+    expect(h.percentile(50)).toBe(5);
+    expect(h.percentile(95)).toBe(5);
+    expect(h.percentile(99)).toBe(5);
+  });
+
+  test('values beyond the top bucket fall into the overflow bucket (rounded max)', () => {
+    const h = new Histogram();
+    h.record(100000); // > 60000, the last configured bucket
+    expect(h.percentile(99)).toBe(100000);
+    expect(h.summary().max).toBe(100000);
+  });
+
+  test('mean is rounded to 2 decimals', () => {
+    const h = new Histogram();
+    [1, 2, 2].forEach((v) => h.record(v)); // 5/3 = 1.666...
+    expect(h.summary().mean).toBe(1.67);
+  });
+
+  test('DEFAULT_BUCKETS is the fibonacci-ish ladder up to 60000', () => {
+    expect(DEFAULT_BUCKETS[0]).toBe(1);
+    expect(DEFAULT_BUCKETS[DEFAULT_BUCKETS.length - 1]).toBe(60000);
+    expect(DEFAULT_BUCKETS.length).toBe(23);
+  });
+});
diff --git a/packages/perf-harness/src/core/__tests__/proc.test.ts b/packages/perf-harness/src/core/__tests__/proc.test.ts
new file mode 100644
index 0000000000..dfab2f2b22
--- /dev/null
+++ b/packages/perf-harness/src/core/__tests__/proc.test.ts
@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { isAlive, readJsonl, readPid, writeDone } from '../proc';
+
+const tmp = (): string => fs.mkdtempSync(path.join(os.tmpdir(), 'perf-proc-'));
+
+describe('readJsonl', () => {
+  test('parses valid lines and skips blank / corrupt ones', () => {
+    const dir = tmp();
+    const file = path.join(dir, 'metrics.jsonl');
+    fs.writeFileSync(
+      file,
+      [
+        JSON.stringify({ a: 1 }),
+        '', // blank
+        '   ', // whitespace only
+        '{ this is not json', // corrupt (e.g. half-flushed final row)
+        JSON.stringify({ b: 2 }),
+        '{"c":3}' // trailing line without newline
+      ].join('\n')
+    );
+    expect(readJsonl(file)).toEqual([{ a: 1 }, { b: 2 }, { c: 3 }]);
+  });
+
+  test('missing file returns []', () => {
+    expect(readJsonl(path.join(tmp(), 'does-not-exist.jsonl'))).toEqual([]);
+  });
+
+  test('empty file returns []', () => {
+    const dir = tmp();
+    const file = path.join(dir, 'empty.jsonl');
+    fs.writeFileSync(file, '');
+    expect(readJsonl(file)).toEqual([]);
+  });
+});
+
+describe('readPid', () => {
+  test('reads a written pid file', () => {
+    const dir = tmp();
+    fs.writeFileSync(path.join(dir, 'server.pid'), '12345\n');
+    expect(readPid(dir, 'server')).toBe(12345);
+  });
+
+  test('returns null when the pid file is absent', () => {
+    expect(readPid(tmp(), 'missing')).toBeNull();
+  });
+
+  test('returns null on garbage content', () => {
+    const dir = tmp();
+    fs.writeFileSync(path.join(dir, 'bad.pid'), 'not-a-pid\n');
+    expect(readPid(dir, 'bad')).toBeNull();
+  });
+});
+
+describe('isAlive', () => {
+  test('the current process is alive', () => {
+    expect(isAlive(process.pid)).toBe(true);
+  });
+
+  test('a pid above the max range is not alive', () => {
+    expect(isAlive(2 ** 30)).toBe(false);
+  });
+
+  test('non-positive pids are not alive', () => {
+    expect(isAlive(0)).toBe(false);
+    expect(isAlive(-1)).toBe(false);
+  });
+});
+
+describe('writeDone', () => {
+  test('writes a .done marker with default timestamp content', () => {
+    const dir = tmp();
+    writeDone(dir, 'soak');
+    const body = fs.readFileSync(path.join(dir, 'soak.done'), 'utf8');
+    expect(body.endsWith('\n')).toBe(true);
+    expect(body.trim().length).toBeGreaterThan(0);
+  });
+
+  test('writes explicit content (newline-terminated)', () => {
+    const dir = tmp();
+    writeDone(dir, 'soak', 'ok');
+    expect(fs.readFileSync(path.join(dir, 'soak.done'), 'utf8')).toBe('ok\n');
+  });
+});
diff --git a/packages/perf-harness/src/core/__tests__/rng.test.ts b/packages/perf-harness/src/core/__tests__/rng.test.ts
new file mode 100644
index 0000000000..64d7122249
--- /dev/null
+++ b/packages/perf-harness/src/core/__tests__/rng.test.ts
@@ -0,0 +1,88 @@
+import { makeMixSampler, makeRng, makeZipfSampler } from '../rng';
+
+describe('makeRng (mulberry32)', () => {
+  // Golden values guard the exact algorithm — a change here means the sampler
+  // sequences are no longer reproducible across harness versions.
+  test('seed 42 produces the known sequence', () => {
+    const r = makeRng(42);
+    expect([r(), r(), r()]).toEqual([
+      0.6011037519201636,
+      0.44829055899754167,
+      0.8524657934904099
+    ]);
+  });
+
+  test('seed 1 produces the known sequence', () => {
+    const r = makeRng(1);
+    expect([r(), r(), r()]).toEqual([
+      0.6270739405881613,
+      0.002735721180215478,
+      0.5274470399599522
+    ]);
+  });
+
+  test('same seed is deterministic; different seeds diverge', () => {
+    const a = makeRng(123);
+    const b = makeRng(123);
+    const c = makeRng(124);
+    const seqA = Array.from({ length: 20 }, () => a());
+    const seqB = Array.from({ length: 20 }, () => b());
+    const seqC = Array.from({ length: 20 }, () => c());
+    expect(seqA).toEqual(seqB);
+    expect(seqA).not.toEqual(seqC);
+  });
+
+  test('all outputs are in [0, 1)', () => {
+    const r = makeRng(9999);
+    for (let i = 0; i < 1000; i++) {
+      const v = r();
+      expect(v).toBeGreaterThanOrEqual(0);
+      expect(v).toBeLessThan(1);
+    }
+  });
+});
+
+describe('makeZipfSampler', () => {
+  test('favours low indices (monotonically decreasing frequency)', () => {
+    const n = 5;
+    const z = makeZipfSampler(n, makeRng(7));
+    const counts = new Array(n).fill(0);
+    for (let i = 0; i < 10000; i++) counts[z()]++;
+    // hot index 0 dominates the cold tail
+    expect(counts[0]).toBeGreaterThan(counts[n - 1] * 3);
+    for (let i = 1; i < n; i++) expect(counts[i - 1]).toBeGreaterThan(counts[i]);
+  });
+
+  test('every sample is a valid in-range index', () => {
+    const n = 8;
+    const z = makeZipfSampler(n, makeRng(3));
+    for (let i = 0; i < 500; i++) {
+      const idx = z();
+      expect(idx).toBeGreaterThanOrEqual(0);
+      expect(idx).toBeLessThan(n);
+    }
+  });
+});
+
+describe('makeMixSampler', () => {
+  test('weights the keys proportionally', () => {
+    const mix = makeMixSampler('read:0.7,write:0.25,meta:0.05', makeRng(11));
+    const tally: Record<string, number> = { read: 0, write: 0, meta: 0 };
+    const N = 20000;
+    for (let i = 0; i < N; i++) tally[mix()]++;
+    expect(tally.read / N).toBeCloseTo(0.7, 1);
+    expect(tally.write / N).toBeCloseTo(0.25, 1);
+    expect(tally.read).toBeGreaterThan(tally.write);
+    expect(tally.write).toBeGreaterThan(tally.meta);
+  });
+
+  test('empty / invalid mix falls back to read:1', () => {
+    const mix = makeMixSampler('', makeRng(1));
+    for (let i = 0; i < 50; i++) expect(mix()).toBe('read');
+  });
+
+  test('trims keys and ignores non-positive weights', () => {
+    const mix = makeMixSampler(' write : 1 , bad:0 , junk', makeRng(5));
+    for (let i = 0; i < 50; i++) expect(mix()).toBe('write');
+  });
+});
diff --git a/packages/perf-harness/src/core/args.ts b/packages/perf-harness/src/core/args.ts
new file mode 100644
index 0000000000..3110e58d24
--- /dev/null
+++ b/packages/perf-harness/src/core/args.ts
@@ -0,0 +1,63 @@
+/**
+ * Minimal, dependency-free argv parsing + coercions.
+ *
+ * Port of `scripts/scale-validate/_lib.mjs` `parseArgs` — but folded into a
+ * single `Argv` shape where positionals land in `_` (the convention the CLI
+ * router and every command reads).
+ *
+ *   --flag value | --flag=value | --flag (boolean true) ; positionals -> _
+ */
+
+export type Argv = Record<string, any> & { _: string[] };
+
+export function parseArgv(raw: string[]): Argv {
+  const args: Argv = { _: [] };
+  for (let i = 0; i < raw.length; i++) {
+    const a = raw[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq !== -1) {
+        args[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const key = a.slice(2);
+        const next = raw[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+          args[key] = true;
+        } else {
+          args[key] = next;
+          i++;
+        }
+      }
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+export function asBool(v: any, dflt = false): boolean {
+  if (v === undefined || v === null) return dflt;
+  if (typeof v === 'boolean') return v;
+  const s = String(v).toLowerCase();
+  return s === '1' || s === 'true' || s === 'yes' || s === 'on';
+}
+
+export function asInt(v: any, dflt?: number): number {
+  const n = Number.parseInt(v, 10);
+  return Number.isFinite(n) ? n : dflt;
+}
+
+export function asFloat(v: any, dflt?: number): number {
+  const n = Number.parseFloat(v);
+  return Number.isFinite(n) ? n : dflt;
+}
+
+/**
+ * Print a usage string (to stderr — stdout is reserved for the machine-readable
+ * JSON/JSONL protocol) and return the intended exit code so callers can do
+ * `return usageExit(USAGE)` / `process.exitCode = usageExit(USAGE, 0)`.
+ */
+export function usageExit(usage: string, code = 1): number {
+  console.error(usage);
+  return code;
+}
diff --git a/packages/perf-harness/src/core/config.ts b/packages/perf-harness/src/core/config.ts
new file mode 100644
index 0000000000..ee10172191
--- /dev/null
+++ b/packages/perf-harness/src/core/config.ts
@@ -0,0 +1,96 @@
+/**
+ * Runtime config resolution + the hub-safety guardrail.
+ *
+ * The harness is designed to run against an ISOLATED rig (a dedicated pgpm
+ * docker container on a non-hub port + a dedicated server port). To make it
+ * impossible to accidentally point the load generators at the shared
+ * constructive-hub, every command that dials Postgres or a server port runs the
+ * port through `assertPortAllowed`. The PG port default is 5433 — NEVER 5432.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { Argv, asBool } from './args';
+
+export interface PgConfig {
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+  database: string;
+}
+
+// Ports the shared constructive-hub binds (PG, public/dashboard/private GraphQL,
+// MinIO). Refuse them unless the operator explicitly passes --allow-hub.
+export const HUB_PORTS: number[] = [5432, 3000, 3001, 3002, 9000];
+
+export function assertPortAllowed(port: number, allowHub: boolean, what = 'port'): void {
+  if (allowHub) return;
+  if (HUB_PORTS.includes(port)) {
+    throw new Error(
+      `refusing to use ${what} ${port}: it is a reserved constructive-hub port ` +
+        `(${HUB_PORTS.join(', ')}). This harness targets an isolated rig; ` +
+        `pass --allow-hub to override (danger: may disrupt the live hub).`
+    );
+  }
+}
+
+// CLI flags win over env, env wins over defaults. We NEVER default to 5432.
+export function pgConfigFromArgv(argv: Argv): PgConfig {
+  const num = (v: any, d: number): number => {
+    const n = Number.parseInt(v, 10);
+    return Number.isFinite(n) ? n : d;
+  };
+  const cfg: PgConfig = {
+    host: argv['pg-host'] || process.env.PGHOST || 'localhost',
+    port: num(argv['pg-port'] ?? process.env.PGPORT, 5433),
+    user: argv['pg-user'] || process.env.PGUSER || 'postgres',
+    password: argv['pg-password'] ?? process.env.PGPASSWORD ?? 'password',
+    database: argv['pg-database'] || process.env.PGDATABASE || 'constructive'
+  };
+  assertPortAllowed(cfg.port, asBool(argv['allow-hub']), 'pg-port');
+  return cfg;
+}
+
+// Walk up from `startDir` (default cwd) to the first pnpm-workspace.yaml.
+export function findRepoRoot(startDir?: string): string {
+  let dir = path.resolve(startDir || process.cwd());
+  for (;;) {
+    if (fs.existsSync(path.join(dir, 'pnpm-workspace.yaml'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    `could not locate repo root: no pnpm-workspace.yaml walking up from ${startDir || process.cwd()}`
+  );
+}
+
+// Output directory for every artifact (metrics/harness/pg/results/logs/pids).
+export function resolveOutDir(argv: Argv): string {
+  const dir = path.resolve(argv['out-dir'] || './perf-out');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+// The command used to boot a server. Default: run the built cnc CLI via node.
+// Override with --server-cmd "node /some/other/entry.js" (whitespace-split).
+export function resolveServerCmd(argv: Argv, repoRoot: string): string[] {
+  const raw = argv['server-cmd'];
+  if (typeof raw === 'string' && raw.trim()) {
+    return raw.trim().split(/\s+/);
+  }
+  return ['node', path.join(repoRoot, 'packages', 'cli', 'dist', 'index.js')];
+}
+
+// Credentials for authenticated load. Email has a seeder default; the password
+// is NEVER given a literal default — flag > PERF_PASSWORD env > null. Commands
+// needing auth must error with guidance when it resolves to null.
+export function resolveCreds(argv: Argv): { email: string; password: string | null } {
+  const emailFlag = typeof argv['email'] === 'string' ? argv['email'].trim() : '';
+  const email = emailFlag || 'seeder@gmail.com';
+  const pwFlag = typeof argv['password'] === 'string' ? argv['password'] : '';
+  const pwEnv = process.env.PERF_PASSWORD || '';
+  const password = pwFlag || pwEnv || null;
+  return { email, password };
+}
diff --git a/packages/perf-harness/src/core/fleetfile.ts b/packages/perf-harness/src/core/fleetfile.ts
new file mode 100644
index 0000000000..b7e0da1e68
--- /dev/null
+++ b/packages/perf-harness/src/core/fleetfile.ts
@@ -0,0 +1,116 @@
+/**
+ * Fleet manifest loading + canary naming + the pure subset algorithm.
+ *
+ * `loadFleet`, `CANARY_PREFIX`, `canaryName` port from
+ * `scripts/scale-validate/_lib.mjs`; `buildSubset` is the pure core of
+ * `scripts/scale-validate/subset-fleet.mjs` (file IO / process.exit stripped —
+ * hard errors throw, soft conditions are collected into `warnings`).
+ */
+import fs from 'node:fs';
+
+export interface Tenant {
+  dbname: string;
+  databaseId?: string;
+  apiHost?: string;
+  authHost?: string;
+  schemas?: string[];
+  appPublicSchema?: string;
+}
+
+export function loadFleet(file: string): { manifest: any; tenants: Tenant[] } {
+  const raw = fs.readFileSync(file, 'utf8');
+  const parsed = JSON.parse(raw);
+  const tenants = Array.isArray(parsed) ? parsed : parsed.tenants;
+  if (!Array.isArray(tenants) || tenants.length === 0) {
+    throw new Error(`fleet file ${file} has no tenants`);
+  }
+  return { manifest: parsed, tenants };
+}
+
+// The token used inside CANARY-<token> rows. MUST match between the canary
+// seeder and the harness sentinel so bleed can be attributed to a foreign
+// tenant. Token == tenant.dbname.
+export const CANARY_PREFIX = 'CANARY-';
+
+export function canaryName(t: Tenant): string {
+  return `${CANARY_PREFIX}${t.dbname}`;
+}
+
+export interface SubsetOpts {
+  blueprints?: number;
+  perBlueprint?: number;
+  tenants?: number;
+  sameBpRegex?: string;
+}
+
+// Blueprint groups: group 0 = the KNOWN-identical blueprint pool (matches
+// sameBpRegex, minus table-drifted tenants; column-drift tenants keep their
+// relname set so they STAY in group 0), groups 1..K = drift-marker groups.
+//
+// Modes:
+//   blueprints=K, perBlueprint=N  -> diversity subset: first K groups, N each.
+//   tenants=N                     -> tenant-count subset: N group-0 tenants.
+export function buildSubset(
+  fleet: Tenant[],
+  drifted: { groups?: Record<string, string[]>; columnDrift?: string[] },
+  o: SubsetOpts
+): { subset: any; tenants: Tenant[]; warnings: string[] } {
+  const warnings: string[] = [];
+  const blueprints = o.blueprints ?? 0;
+  const perBlueprint = o.perBlueprint ?? 5;
+  const tenantCount = o.tenants ?? 0;
+  const sameBpRe = new RegExp(o.sameBpRegex || '^(factory[0-9]+|marketplace_db_tenant1)$');
+
+  const all = fleet;
+  const byName = new Map(all.map((t) => [t.dbname, t]));
+
+  const driftGroups = (drifted && drifted.groups) || {};
+  const driftedNames = new Set<string>();
+  for (const names of Object.values(driftGroups)) names.forEach((n) => driftedNames.add(n));
+
+  const group0 = all
+    .filter((t) => sameBpRe.test(t.dbname) && !driftedNames.has(t.dbname))
+    .map((t) => t.dbname);
+  const groups: string[][] = [group0];
+  for (const g of Object.keys(driftGroups).sort((a, b) => Number(a) - Number(b))) {
+    groups.push(driftGroups[g]);
+  }
+
+  let picked: string[] = [];
+  let label = '';
+  if (blueprints > 0) {
+    if (blueprints > groups.length) {
+      throw new Error(`only ${groups.length} blueprint groups available, asked for ${blueprints}`);
+    }
+    for (let k = 0; k < blueprints; k++) {
+      const take = groups[k].slice(0, perBlueprint);
+      if (take.length < perBlueprint) {
+        warnings.push(`warn: group ${k} has only ${take.length}/${perBlueprint} tenants`);
+      }
+      picked.push(...take);
+    }
+    label = `diversity k=${blueprints} per=${perBlueprint}`;
+  } else if (tenantCount > 0) {
+    picked = group0.slice(0, tenantCount);
+    if (picked.length < tenantCount) {
+      warnings.push(`warn: only ${picked.length}/${tenantCount} undrifted tenants available`);
+    }
+    label = `tenant-count n=${picked.length} (single blueprint)`;
+  } else {
+    throw new Error('one of --blueprints or --tenants is required');
+  }
+
+  const tenants = picked.map((n) => byName.get(n)).filter(Boolean) as Tenant[];
+  const missing = picked.filter((n) => !byName.has(n));
+  if (missing.length) {
+    warnings.push(`warn: ${missing.length} drifted names not in fleet: ${missing.join(',')}`);
+  }
+
+  const subset = {
+    generatedAt: new Date().toISOString(),
+    subset: label,
+    count: tenants.length,
+    tenants
+  };
+  return { subset, tenants, warnings };
+}
diff --git a/packages/perf-harness/src/core/gql.ts b/packages/perf-harness/src/core/gql.ts
new file mode 100644
index 0000000000..fa43482daf
--- /dev/null
+++ b/packages/perf-harness/src/core/gql.ts
@@ -0,0 +1,271 @@
+/**
+ * GraphQL-over-HTTP client + introspection-driven op discovery.
+ * Verbatim ports from `scripts/scale-validate/_lib.mjs`.
+ */
+
+export interface GqlResponse {
+  status: number;
+  ok: boolean;
+  json?: any;
+  text?: string;
+  elapsedMs: number;
+  error?: string;
+}
+
+export interface GqlFetchOpts {
+  host: string;
+  port: number;
+  query: string;
+  variables?: any;
+  token?: string;
+  timeoutMs?: number;
+  gqlPath?: string;
+}
+
+// We put the tenant host in the URL (e.g. api-xxx.localhost) because undici
+// ignores an explicit `host` header. `*.localhost` resolves to loopback, so the
+// connection lands on 127.0.0.1 while the server sees the correct Host header
+// for subdomain routing.
+export async function gqlFetch(opts: GqlFetchOpts): Promise<GqlResponse> {
+  const { host, port, query, variables, token, timeoutMs = 30000, gqlPath = '/graphql' } = opts;
+  const url = `http://${host}:${port}${gqlPath}`;
+  const headers: Record<string, string> = { 'content-type': 'application/json', accept: 'application/json' };
+  if (token) headers.authorization = `Bearer ${token}`;
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  const start = performance.now();
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(variables ? { query, variables } : { query }),
+      signal: ac.signal
+    });
+    const elapsedMs = performance.now() - start;
+    const ct = res.headers.get('content-type') || '';
+    let json: any = null;
+    let text: any = null;
+    if (ct.includes('json')) {
+      json = await res.json().catch((): any => null);
+    } else {
+      text = await res.text().catch((): any => null);
+      // Some error paths return JSON without the header — try to parse.
+      if (text) {
+        try { json = JSON.parse(text); } catch { /* not json */ }
+      }
+    }
+    return { status: res.status, ok: res.ok, json, text, elapsedMs, error: null };
+  } catch (err: any) {
+    const elapsedMs = performance.now() - start;
+    const error = err && err.name === 'AbortError' ? 'timeout' : (err && (err.code || err.message)) || 'network';
+    return { status: 0, ok: false, json: null, text: null, elapsedMs, error };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function isRotating(resp: GqlResponse): boolean {
+  if (resp.status === 503) {
+    const code = resp.json && resp.json.error && resp.json.error.code;
+    return code === 'SERVICE_ROTATING' || true; // any 503 counts as rotating
+  }
+  return false;
+}
+
+export function gqlErrors(resp: GqlResponse): any[] {
+  return (resp.json && Array.isArray(resp.json.errors)) ? resp.json.errors : [];
+}
+
+export function isUnauthenticated(resp: GqlResponse): boolean {
+  const errs = gqlErrors(resp);
+  for (const e of errs) {
+    const code = e && e.extensions && e.extensions.code;
+    if (code === 'UNAUTHENTICATED' || code === 'FORBIDDEN') return true;
+    const msg = (e && e.message) || '';
+    if (/unauthenticated|not authori[sz]ed|permission denied|jwt|login required|invalid token|expired/i.test(msg)) return true;
+  }
+  if (resp.status === 401 || resp.status === 403) return true;
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Introspection helpers (operate on the JSON introspection result)
+// ---------------------------------------------------------------------------
+export const INTROSPECTION_QUERY = `query Introspect {
+  __schema {
+    queryType { name }
+    mutationType { name }
+    types {
+      kind
+      name
+      fields(includeDeprecated: true) { name args { name type { ...T } } type { ...T } }
+      inputFields { name type { ...T } }
+    }
+  }
+}
+fragment T on __Type {
+  kind name
+  ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } } }
+}`;
+
+export function unwrapType(ref: any): any {
+  let t = ref;
+  while (t && t.ofType) t = t.ofType;
+  return t || null;
+}
+
+export function isNonNull(ref: any): boolean {
+  return !!(ref && ref.kind === 'NON_NULL');
+}
+
+export interface TypeIndex {
+  index: Map<string, any>;
+  queryType: string | null;
+  mutationType: string | null;
+}
+
+export function buildTypeIndex(introspect: any): TypeIndex {
+  const index = new Map<string, any>();
+  const schema = introspect && introspect.__schema;
+  if (!schema) return { index, queryType: null, mutationType: null };
+  for (const t of schema.types) index.set(t.name, t);
+  return {
+    index,
+    queryType: schema.queryType && schema.queryType.name,
+    mutationType: schema.mutationType && schema.mutationType.name
+  };
+}
+
+function findConnectionField(index: Map<string, any>, queryTypeName: string, re: RegExp): string | null {
+  const qt = index.get(queryTypeName);
+  if (!qt) return null;
+  const candidates = (qt.fields || []).filter((f: any) => re.test(f.name));
+  for (const f of candidates) {
+    const named = unwrapType(f.type);
+    const nt = named && index.get(named.name);
+    if (nt && (nt.fields || []).some((sf: any) => sf.name === 'nodes')) return f.name;
+  }
+  return candidates[0] ? candidates[0].name : null;
+}
+
+const SCALAR_SAMPLE = (scalar: string, rand: any): any => {
+  switch (scalar) {
+    case 'Int':
+    case 'BigInt':
+      return 0;
+    case 'Float':
+    case 'BigFloat':
+      return 0;
+    case 'Boolean':
+      return true;
+    default:
+      return `load-${rand}`;
+  }
+};
+
+export interface DiscoveredCreate {
+  name: string;
+  inputTypeName: string;
+  innerName: string;
+  requiredScalars: { name: string; scalar: string; kind: string }[];
+  payloadFieldName: string | null;
+  keySelect: string;
+}
+
+export interface DiscoveredDelete {
+  name: string;
+  inputTypeName: string;
+  key: string;
+}
+
+export interface DiscoveredOps {
+  queryType: string | null;
+  mutationType: string | null;
+  read: string | null;
+  meta: boolean;
+  create: DiscoveredCreate | null;
+  del: DiscoveredDelete | null;
+}
+
+// Discover create/delete/read/meta operations from an introspection result.
+export function discoverOps(introspect: any): DiscoveredOps {
+  const { index, queryType, mutationType } = buildTypeIndex(introspect);
+  const out: DiscoveredOps = { queryType, mutationType, read: null, meta: false, create: null, del: null };
+  if (!queryType) return out;
+
+  // read (categories connection)
+  out.read = findConnectionField(index, queryType, /categor/i);
+
+  // meta (_meta { tables { name } })
+  const qt = index.get(queryType);
+  out.meta = !!(qt && (qt.fields || []).some((f: any) => f.name === '_meta'));
+
+  if (!mutationType) return out;
+  const mt = index.get(mutationType);
+
+  // delete mutation (prefer PK id-based over nodeId-based)
+  const delField = (mt.fields || []).find((f: any) => /^delete.*categor/i.test(f.name) && !/nodeid/i.test(f.name))
+    || (mt.fields || []).find((f: any) => /^delete.*categor/i.test(f.name));
+  if (delField) {
+    const inputArg = (delField.args || []).find((a: any) => a.name === 'input');
+    if (inputArg) {
+      const inputType = index.get(unwrapType(inputArg.type).name);
+      const innerFields = (inputType.inputFields || []).map((f: any) => ({ name: f.name, typeName: unwrapType(f.type).name }));
+      const byId = innerFields.find((f: any) => f.name === 'id');
+      const byNodeId = innerFields.find((f: any) => f.name === 'nodeId');
+      const key = byId ? 'id' : (byNodeId ? 'nodeId' : (innerFields[0] && innerFields[0].name));
+      if (key) {
+        out.del = { name: delField.name, inputTypeName: unwrapType(inputArg.type).name, key };
+      }
+    }
+  }
+
+  // create mutation
+  const createField = (mt.fields || []).find((f: any) => /^create.*categor/i.test(f.name));
+  if (createField) {
+    const inputArg = (createField.args || []).find((a: any) => a.name === 'input');
+    if (inputArg) {
+      const inputTypeName = unwrapType(inputArg.type).name;
+      const inputType = index.get(inputTypeName);
+      const innerField = (inputType.inputFields || []).find((f: any) => {
+        const nt = index.get(unwrapType(f.type).name);
+        return nt && nt.kind === 'INPUT_OBJECT';
+      });
+      if (innerField) {
+        const innerType = index.get(unwrapType(innerField.type).name);
+        const requiredScalars = (innerType.inputFields || [])
+          .filter((f: any) => isNonNull(f.type))
+          .map((f: any) => ({ name: f.name, scalar: unwrapType(f.type).name, kind: unwrapType(f.type).kind }))
+          .filter((f: any) => f.kind === 'SCALAR' || f.kind === 'ENUM');
+        const payloadType = index.get(unwrapType(createField.type).name);
+        const payloadField = (payloadType.fields || []).find((f: any) => {
+          const nt = index.get(unwrapType(f.type).name);
+          return nt && nt.kind === 'OBJECT' && /categor/i.test(nt.name) && (nt.fields || []).some((sf: any) => sf.name === 'id');
+        });
+        out.create = {
+          name: createField.name,
+          inputTypeName,
+          innerName: innerField.name,
+          requiredScalars,
+          payloadFieldName: payloadField ? payloadField.name : null,
+          // which key to select in the payload so we can delete afterwards
+          keySelect: out.del ? out.del.key : 'id'
+        };
+      }
+    }
+  }
+  return out;
+}
+
+// Build the record input object for a create write. `nameValue` is forced onto
+// the `name` column; everything else required gets a type-appropriate value.
+export function buildCreateRecord(create: DiscoveredCreate, nameValue: any, rand: any): Record<string, any> {
+  const rec: Record<string, any> = {};
+  for (const f of create.requiredScalars) {
+    if (f.name === 'name') rec[f.name] = nameValue;
+    else if (f.name === 'slug') rec[f.name] = `load-${rand}`;
+    else rec[f.name] = SCALAR_SAMPLE(f.scalar, rand);
+  }
+  if (rec.name === undefined) rec.name = nameValue; // ensure name present even if not flagged required
+  return rec;
+}
diff --git a/packages/perf-harness/src/core/histogram.ts b/packages/perf-harness/src/core/histogram.ts
new file mode 100644
index 0000000000..441a987523
--- /dev/null
+++ b/packages/perf-harness/src/core/histogram.ts
@@ -0,0 +1,74 @@
+/**
+ * Bucketed latency histogram (bounded memory — safe for multi-hour soaks).
+ * Verbatim port from `scripts/scale-validate/_lib.mjs`.
+ */
+
+export const DEFAULT_BUCKETS: number[] = [
+  1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610,
+  1000, 1600, 2600, 4200, 6800, 11000, 18000, 30000, 60000
+];
+
+const round2 = (n: number): number => Math.round(n * 100) / 100;
+
+export interface HistogramSummary {
+  count: number;
+  min: number;
+  mean: number;
+  p50: number;
+  p95: number;
+  p99: number;
+  max: number;
+}
+
+export class Histogram {
+  buckets: number[];
+  counts: number[];
+  count: number;
+  sum: number;
+  min: number;
+  max: number;
+
+  constructor(buckets: number[] = DEFAULT_BUCKETS) {
+    this.buckets = buckets;
+    this.counts = new Array(buckets.length + 1).fill(0);
+    this.count = 0;
+    this.sum = 0;
+    this.min = Infinity;
+    this.max = 0;
+  }
+
+  record(ms: number): void {
+    this.count++;
+    this.sum += ms;
+    if (ms < this.min) this.min = ms;
+    if (ms > this.max) this.max = ms;
+    let i = 0;
+    while (i < this.buckets.length && ms > this.buckets[i]) i++;
+    this.counts[i]++;
+  }
+
+  percentile(p: number): number {
+    if (this.count === 0) return 0;
+    const target = Math.ceil((p / 100) * this.count);
+    let cum = 0;
+    for (let i = 0; i < this.counts.length; i++) {
+      cum += this.counts[i];
+      if (cum >= target) {
+        return i < this.buckets.length ? this.buckets[i] : Math.round(this.max);
+      }
+    }
+    return Math.round(this.max);
+  }
+
+  summary(): HistogramSummary {
+    return {
+      count: this.count,
+      min: this.count ? round2(this.min) : 0,
+      mean: this.count ? round2(this.sum / this.count) : 0,
+      p50: this.percentile(50),
+      p95: this.percentile(95),
+      p99: this.percentile(99),
+      max: round2(this.max)
+    };
+  }
+}
diff --git a/packages/perf-harness/src/core/pgc.ts b/packages/perf-harness/src/core/pgc.ts
new file mode 100644
index 0000000000..ecd5bf3714
--- /dev/null
+++ b/packages/perf-harness/src/core/pgc.ts
@@ -0,0 +1,46 @@
+/**
+ * Postgres client helpers + error classification.
+ *
+ * `pg` is a real dependency of this package now, so `getPg()` is a plain
+ * require — NOT the @dataplan/pg resolution chain the standalone scripts used.
+ * The classification helpers are ported from
+ * `scripts/scale-validate/tenant-factory.mjs`.
+ */
+import { PgConfig } from './config';
+
+export function getPg(): { Client: any; Pool: any } {
+  // Lazy require so importing this module never loads pg until a caller needs a
+  // real connection (keeps pure/unit paths free of the native binding).
+  return require('pg');
+}
+
+export async function withFreshClient<T>(pg: PgConfig, fn: (client: any) => Promise<T>): Promise<T> {
+  const { Client } = getPg();
+  const client = new Client(pg);
+  await client.connect();
+  try {
+    return await fn(client);
+  } finally {
+    try {
+      await client.end();
+    } catch {
+      // a broken connection's end() can reject — never mask the real error
+    }
+  }
+}
+
+// 57P0x/08006/08003/53300 + a message sniff: connection-class failures (e.g. PG
+// crash recovery / server restart). Callers retry these after a long backoff so
+// a run survives a server restart.
+export function isConnLoss(err: any): boolean {
+  const code = err && err.code;
+  if (['57P01', '57P02', '57P03', '08006', '08003', '53300'].includes(code)) return true;
+  const msg = (err && err.message) || '';
+  return /connection terminated|terminating connection|server closed the connection/i.test(msg);
+}
+
+// 40P01/40001: deadlock / serialization failure — retry the transaction.
+export function isRetryableTxn(err: any): boolean {
+  const code = err && err.code;
+  return code === '40P01' || code === '40001';
+}
diff --git a/packages/perf-harness/src/core/proc.ts b/packages/perf-harness/src/core/proc.ts
new file mode 100644
index 0000000000..8ea93f34c3
--- /dev/null
+++ b/packages/perf-harness/src/core/proc.ts
@@ -0,0 +1,163 @@
+/**
+ * Detached-process + artifact-file utilities.
+ *
+ * New in the package port: replaces the ad-hoc nohup/python-setsid launcher and
+ * the inline child-management the shell orchestrators used. A spawned process
+ * outlives the launching CLI (detached + unref), its stdout/stderr go to a log
+ * file, and its pid is recorded so `run soak status/stop` can find it later.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+export interface SpawnDetachedOpts {
+  name: string;
+  cmd: string;
+  args: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  outDir: string;
+}
+
+export function spawnDetached(o: SpawnDetachedOpts): { pid: number; logPath: string; pidPath: string } {
+  fs.mkdirSync(o.outDir, { recursive: true });
+  const logPath = path.join(o.outDir, `${o.name}.log`);
+  const pidPath = path.join(o.outDir, `${o.name}.pid`);
+  // Append so a restart keeps history; both stdout and stderr share the fd.
+  const logFd = fs.openSync(logPath, 'a');
+  try {
+    const child = spawn(o.cmd, o.args, {
+      detached: true,
+      stdio: ['ignore', logFd, logFd],
+      // Merge over the parent env so PATH etc. survive; o.env wins on conflicts.
+      env: o.env ? { ...process.env, ...o.env } : process.env,
+      cwd: o.cwd || process.cwd()
+    });
+    child.unref();
+    const pid = child.pid;
+    fs.writeFileSync(pidPath, `${pid}\n`);
+    return { pid, logPath, pidPath };
+  } finally {
+    // The child holds its own dup of the fd; the parent's copy is done.
+    fs.closeSync(logFd);
+  }
+}
+
+export function isAlive(pid: number): boolean {
+  if (!pid || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err: any) {
+    // EPERM => the process exists but is owned by another user (still alive).
+    return !!(err && err.code === 'EPERM');
+  }
+}
+
+export async function stopPid(pid: number, termTimeoutMs = 15000): Promise<'term' | 'kill' | 'gone'> {
+  if (!isAlive(pid)) return 'gone';
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch {
+    return 'gone';
+  }
+  const deadline = Date.now() + termTimeoutMs;
+  while (Date.now() < deadline) {
+    if (!isAlive(pid)) return 'term';
+    await sleep(200);
+  }
+  if (!isAlive(pid)) return 'term';
+  try {
+    process.kill(pid, 'SIGKILL');
+  } catch {
+    return 'gone';
+  }
+  const killDeadline = Date.now() + 2000;
+  while (Date.now() < killDeadline) {
+    if (!isAlive(pid)) return 'kill';
+    await sleep(100);
+  }
+  return 'kill';
+}
+
+export function readPid(outDir: string, name: string): number | null {
+  const pidPath = path.join(outDir, `${name}.pid`);
+  try {
+    const raw = fs.readFileSync(pidPath, 'utf8').trim();
+    const pid = Number.parseInt(raw, 10);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+// Resolve once either loopback family accepts a connection. macOS frequently
+// binds `localhost` to ::1 only, so we must probe both 127.0.0.1 and ::1.
+export function waitForPort(port: number, timeoutMs: number): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  const tryConnect = (host: string): Promise<boolean> =>
+    new Promise((resolve) => {
+      const sock = net.connect({ host, port });
+      let done = false;
+      const finish = (ok: boolean): void => {
+        if (done) return;
+        done = true;
+        sock.destroy();
+        resolve(ok);
+      };
+      sock.setTimeout(1000);
+      sock.once('connect', () => finish(true));
+      sock.once('timeout', () => finish(false));
+      sock.once('error', () => finish(false));
+    });
+  return new Promise((resolve, reject) => {
+    const attempt = async (): Promise<void> => {
+      if ((await tryConnect('127.0.0.1')) || (await tryConnect('::1'))) {
+        resolve();
+        return;
+      }
+      if (Date.now() >= deadline) {
+        reject(new Error(`timed out waiting for port ${port} after ${timeoutMs}ms`));
+        return;
+      }
+      setTimeout(() => { void attempt(); }, 250);
+    };
+    void attempt();
+  });
+}
+
+// Parse a JSON-lines file, skipping blank/corrupt lines (e.g. a half-flushed
+// final row from a process killed mid-write).
+export function ensureParentDir(file: string): void {
+  fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+}
+
+export function readJsonl(file: string): any[] {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return [];
+  }
+  const out: any[] = [];
+  for (const line of raw.split('\n')) {
+    const s = line.trim();
+    if (!s) continue;
+    try {
+      out.push(JSON.parse(s));
+    } catch {
+      // skip corrupt/partial line
+    }
+  }
+  return out;
+}
+
+export function writeDone(outDir: string, name: string, content?: string): void {
+  fs.mkdirSync(outDir, { recursive: true });
+  const donePath = path.join(outDir, `${name}.done`);
+  const body = content !== undefined ? content : new Date().toISOString();
+  fs.writeFileSync(donePath, body.endsWith('\n') ? body : `${body}\n`);
+}
diff --git a/packages/perf-harness/src/core/rng.ts b/packages/perf-harness/src/core/rng.ts
new file mode 100644
index 0000000000..18eed18263
--- /dev/null
+++ b/packages/perf-harness/src/core/rng.ts
@@ -0,0 +1,71 @@
+/**
+ * Seedable RNG + shape samplers — verbatim ports from
+ * `scripts/scale-validate/_lib.mjs`. Reproducible tenant/shape selection so a
+ * soak or ramp can be replayed byte-for-byte from a seed.
+ */
+
+export type Rng = () => number;
+
+// mulberry32 — small, fast, fully deterministic for a given 32-bit seed.
+export function makeRng(seed: number): Rng {
+  let a = (seed >>> 0) || 0x9e3779b9;
+  return function rng(): number {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+// zipf: weight_i = 1 / (i + 1) over fleet order; returns an index sampler that
+// favours low indices (the "hot" tenants).
+export function makeZipfSampler(n: number, rng: Rng): () => number {
+  const weights: number[] = [];
+  let total = 0;
+  for (let i = 0; i < n; i++) {
+    const w = 1 / (i + 1);
+    weights.push(w);
+    total += w;
+  }
+  const cum: number[] = [];
+  let acc = 0;
+  for (let i = 0; i < n; i++) {
+    acc += weights[i] / total;
+    cum.push(acc);
+  }
+  return () => {
+    const r = rng();
+    for (let i = 0; i < n; i++) if (r <= cum[i]) return i;
+    return n - 1;
+  };
+}
+
+// "read:0.7,write:0.25,meta:0.05" -> weighted key sampler.
+export function makeMixSampler(mixStr: string, rng: Rng): () => string {
+  const entries: [string, number][] = [];
+  let total = 0;
+  for (const part of String(mixStr).split(',')) {
+    const [k, v] = part.split(':');
+    const w = Number.parseFloat(v);
+    if (k && Number.isFinite(w) && w > 0) {
+      entries.push([k.trim(), w]);
+      total += w;
+    }
+  }
+  if (entries.length === 0) {
+    entries.push(['read', 1]);
+    total = 1;
+  }
+  const cum: [string, number][] = [];
+  let acc = 0;
+  for (const [k, w] of entries) {
+    acc += w / total;
+    cum.push([k, acc]);
+  }
+  return () => {
+    const r = rng();
+    for (const [k, c] of cum) if (r <= c) return k;
+    return cum[cum.length - 1][0];
+  };
+}
diff --git a/packages/perf-harness/src/fleet/__tests__/canary.test.ts b/packages/perf-harness/src/fleet/__tests__/canary.test.ts
new file mode 100644
index 0000000000..01a0cdfbce
--- /dev/null
+++ b/packages/perf-harness/src/fleet/__tests__/canary.test.ts
@@ -0,0 +1,44 @@
+import { valueForColumn } from '../canary';
+
+describe('valueForColumn — required-column value synthesis', () => {
+  const name = 'CANARY-factory7';
+  const slug = 'canary-factory7';
+
+  test('the name column always gets the canary name', () => {
+    expect(valueForColumn({ column_name: 'name', data_type: 'text' }, name, slug)).toBe(name);
+    // name wins even when the declared type would otherwise map elsewhere
+    expect(valueForColumn({ column_name: 'name', data_type: 'integer' }, name, slug)).toBe(name);
+  });
+
+  test('the slug column gets the canary slug', () => {
+    expect(valueForColumn({ column_name: 'slug', data_type: 'text' }, name, slug)).toBe(slug);
+  });
+
+  test('text / char / citext columns get the slug', () => {
+    expect(valueForColumn({ column_name: 'title', data_type: 'character varying' }, name, slug)).toBe(slug);
+    expect(valueForColumn({ column_name: 'body', data_type: 'text' }, name, slug)).toBe(slug);
+    expect(valueForColumn({ column_name: 'handle', data_type: 'USER-DEFINED', udt_name: 'citext' }, name, slug)).toBe(
+      slug
+    );
+  });
+
+  test('boolean columns get true', () => {
+    expect(valueForColumn({ column_name: 'is_active', data_type: 'boolean' }, name, slug)).toBe(true);
+  });
+
+  test('numeric columns get 0', () => {
+    for (const data_type of ['integer', 'bigint', 'smallint', 'numeric', 'double precision', 'real']) {
+      expect(valueForColumn({ column_name: 'qty', data_type }, name, slug)).toBe(0);
+    }
+  });
+
+  test('unknown required column types are unsynthesizable (undefined)', () => {
+    expect(valueForColumn({ column_name: 'meta', data_type: 'jsonb' }, name, slug)).toBeUndefined();
+    expect(valueForColumn({ column_name: 'created_at', data_type: 'timestamp with time zone' }, name, slug)).toBeUndefined();
+    expect(valueForColumn({ column_name: 'tags', data_type: 'ARRAY', udt_name: '_text' }, name, slug)).toBeUndefined();
+  });
+
+  test('missing type metadata falls through to undefined (not a crash)', () => {
+    expect(valueForColumn({ column_name: 'mystery' }, name, slug)).toBeUndefined();
+  });
+});
diff --git a/packages/perf-harness/src/fleet/__tests__/provision.test.ts b/packages/perf-harness/src/fleet/__tests__/provision.test.ts
new file mode 100644
index 0000000000..bfe9ac6d35
--- /dev/null
+++ b/packages/perf-harness/src/fleet/__tests__/provision.test.ts
@@ -0,0 +1,93 @@
+import { classifyRetry, computeShape, retryBackoffMs, ShapeRelation, stripSchemaHashPrefix } from '../provision';
+
+describe('stripSchemaHashPrefix', () => {
+  test('strips through the first -<8 hex>- segment', () => {
+    expect(stripSchemaHashPrefix('marketplace-db-tenant1-5e6b13b2-app-public')).toBe('app-public');
+    expect(stripSchemaHashPrefix('factory12-aabbccdd-app-private')).toBe('app-private');
+  });
+
+  test('leaves control-plane schemas (no hash segment) unchanged', () => {
+    expect(stripSchemaHashPrefix('services_public')).toBe('services_public');
+    expect(stripSchemaHashPrefix('public')).toBe('public');
+  });
+});
+
+describe('computeShape — shape fingerprint', () => {
+  const relnames = ['categories', 'order_items', 'orders', 'products', 'reviews'];
+  const rowsFor = (schema: string): ShapeRelation[] => relnames.map((relname) => ({ nspname: schema, relname }));
+
+  test('same relnames, different schema-hash prefixes => same fingerprint', () => {
+    const a = computeShape(rowsFor('factory1-aabbccdd-app-public'));
+    const b = computeShape(rowsFor('factory2-11223344-app-public'));
+    expect(a.fingerprint).toBe(b.fingerprint);
+    expect(a.pairs.length).toBe(5);
+    // pairs are the logical (stripped) schema, not the physical one
+    expect(a.pairs.every(([schema]) => schema === 'app-public')).toBe(true);
+  });
+
+  test('an extra relation changes the fingerprint (table drift)', () => {
+    const base = computeShape(rowsFor('factory1-aabbccdd-app-public'));
+    const drifted = computeShape([
+      ...rowsFor('factory1-aabbccdd-app-public'),
+      { nspname: 'factory1-aabbccdd-app-public', relname: 'drift_marker_g1' }
+    ]);
+    expect(drifted.fingerprint).not.toBe(base.fingerprint);
+  });
+
+  test('deterministic regardless of input row order', () => {
+    const ordered = computeShape(rowsFor('t-aabbccdd-app-public'));
+    const shuffled = computeShape([...rowsFor('t-aabbccdd-app-public')].reverse());
+    expect(shuffled.fingerprint).toBe(ordered.fingerprint);
+  });
+
+  test('an empty relation set is stable and non-empty digest', () => {
+    expect(computeShape([]).fingerprint).toBe(computeShape([]).fingerprint);
+    expect(computeShape([]).pairs).toEqual([]);
+  });
+});
+
+describe('classifyRetry — connection loss vs deadlock vs fatal', () => {
+  test('connection-class codes are retriable and flagged connLost', () => {
+    for (const code of ['57P01', '57P02', '57P03', '08006', '08003', '53300']) {
+      expect(classifyRetry({ code })).toEqual({ connLost: true, retriable: true });
+    }
+  });
+
+  test('deadlock / serialization are retriable but NOT connLost (short backoff)', () => {
+    expect(classifyRetry({ code: '40P01' })).toEqual({ connLost: false, retriable: true });
+    expect(classifyRetry({ code: '40001' })).toEqual({ connLost: false, retriable: true });
+  });
+
+  test('a terminated-connection message with no code is treated as connLost', () => {
+    expect(classifyRetry({ message: 'server closed the connection unexpectedly' })).toEqual({
+      connLost: true,
+      retriable: true
+    });
+    expect(classifyRetry({ message: 'terminating connection due to administrator command' }).connLost).toBe(true);
+  });
+
+  test('an ordinary error (unique_violation) is not retriable', () => {
+    expect(classifyRetry({ code: '23505', message: 'duplicate key value' })).toEqual({
+      connLost: false,
+      retriable: false
+    });
+  });
+});
+
+describe('retryBackoffMs', () => {
+  test('connection loss backs off ~10s * attempt', () => {
+    expect(retryBackoffMs(true, 1, 0)).toBe(10000);
+    expect(retryBackoffMs(true, 2, 0)).toBe(20000);
+    expect(retryBackoffMs(true, 3, 0)).toBe(30000);
+  });
+
+  test('deadlock backs off ~100ms * attempt', () => {
+    expect(retryBackoffMs(false, 1, 0)).toBe(100);
+    expect(retryBackoffMs(false, 3, 0)).toBe(300);
+  });
+
+  test('adds jitter in [0,100)', () => {
+    expect(retryBackoffMs(false, 1, 0.999)).toBe(100 + 99);
+    expect(retryBackoffMs(true, 1, 0.5)).toBe(10000 + 50);
+  });
+});
diff --git a/packages/perf-harness/src/fleet/__tests__/teardown.test.ts b/packages/perf-harness/src/fleet/__tests__/teardown.test.ts
new file mode 100644
index 0000000000..36a309479e
--- /dev/null
+++ b/packages/perf-harness/src/fleet/__tests__/teardown.test.ts
@@ -0,0 +1,27 @@
+import { buildWhere } from '../teardown';
+
+describe('buildWhere — tenant selection SQL', () => {
+  test('--only matches an exact name (single param)', () => {
+    expect(buildWhere({ only: 'factory101', prefix: 'factory', keep: 40 })).toEqual({
+      sql: 'name = $1',
+      params: ['factory101']
+    });
+  });
+
+  test('prefix/keep drops every `<prefix><n>` above --keep', () => {
+    const w = buildWhere({ only: null, prefix: 'factory', keep: 40 });
+    expect(w.sql).toBe(`name ~ ('^' || $1 || '[0-9]+$') AND (regexp_replace(name, '^' || $1, ''))::int > $2`);
+    expect(w.params).toEqual(['factory', 40]);
+  });
+
+  test('--only takes precedence over prefix/keep', () => {
+    const w = buildWhere({ only: 'marketplace_db_tenant1', prefix: 'factory', keep: 40 });
+    expect(w.sql).toBe('name = $1');
+    expect(w.params).toEqual(['marketplace_db_tenant1']);
+  });
+
+  test('a custom prefix/keep is threaded through as params (no interpolation)', () => {
+    const w = buildWhere({ only: undefined, prefix: 'loadtest', keep: 0 });
+    expect(w.params).toEqual(['loadtest', 0]);
+  });
+});
diff --git a/packages/perf-harness/src/fleet/canary.ts b/packages/perf-harness/src/fleet/canary.ts
new file mode 100644
index 0000000000..34dde4978f
--- /dev/null
+++ b/packages/perf-harness/src/fleet/canary.ts
@@ -0,0 +1,170 @@
+/**
+ * fleet canary — seed one CANARY-<dbname> row into each tenant's app-public
+ * categories table (superuser pg client). Idempotent. Port of
+ * `scripts/scale-validate/canary-seed.mjs`.
+ *
+ * The harness bleed-sentinel reads a tenant's categories and FAILS HARD if it
+ * ever sees a CANARY-<other-dbname> row — so these rows must exist for the
+ * sentinel to have anything to detect cross-tenant bleed with.
+ *
+ * NOT NULL columns without a default are discovered via information_schema and
+ * filled (name -> the canary name, slug/other text -> a canary slug).
+ *
+ *   perf-harness fleet canary --fleet fleet.json
+ *   perf-harness fleet canary --fleet fleet.json --cleanup
+ */
+import { Argv, asBool, usageExit } from '../core/args';
+import { pgConfigFromArgv } from '../core/config';
+import { canaryName, loadFleet } from '../core/fleetfile';
+import { withFreshClient } from '../core/pgc';
+
+export const USAGE = `perf-harness fleet canary — insert/remove CANARY-<dbname> rows in each tenant's categories
+
+Options:
+  --fleet <file>   fleet manifest from \`fleet discover\` (required)
+  --table <name>   target table (default: categories)
+  --cleanup        remove the canary rows instead of inserting
+  --pg-* / PG*     connection overrides
+  --allow-hub      permit a constructive-hub port
+  --help
+`;
+
+const REQUIRED_COLS_SQL = `
+SELECT column_name, data_type, udt_name
+FROM information_schema.columns
+WHERE table_schema = $1 AND table_name = $2
+  AND is_nullable = 'NO'
+  AND column_default IS NULL
+ORDER BY ordinal_position;
+`;
+
+const TABLE_EXISTS_SQL = `
+SELECT 1 FROM information_schema.tables
+WHERE table_schema = $1 AND table_name = $2 AND table_type = 'BASE TABLE';
+`;
+
+export function valueForColumn(
+  col: { column_name: string; data_type?: string; udt_name?: string },
+  nameValue: string,
+  slugValue: string
+): any {
+  if (col.column_name === 'name') return nameValue;
+  if (col.column_name === 'slug') return slugValue;
+  const t = (col.data_type || '').toLowerCase();
+  const u = (col.udt_name || '').toLowerCase();
+  if (t.includes('char') || t === 'text' || u === 'citext') return slugValue;
+  if (t.includes('bool')) return true;
+  if (t.includes('int') || t === 'numeric' || t.includes('double') || t.includes('real')) return 0;
+  // Unknown required column type we cannot safely synthesize.
+  return undefined;
+}
+
+export async function run(argv: Argv): Promise<number> {
+  if (asBool(argv.help) || !argv.fleet) {
+    console.error(USAGE);
+    return !argv.fleet && !asBool(argv.help) ? 1 : 0;
+  }
+
+  try {
+    const table = typeof argv.table === 'string' ? argv.table : 'categories';
+    const cleanup = asBool(argv.cleanup);
+    const { tenants } = loadFleet(argv.fleet);
+    const cfg = pgConfigFromArgv(argv);
+
+    const report: any = { table, mode: cleanup ? 'cleanup' : 'seed', results: [] };
+    await withFreshClient(cfg, async (client) => {
+      for (const t of tenants) {
+        const schema = t.appPublicSchema;
+        const entry: any = { dbname: t.dbname, schema, status: 'ok' };
+        if (!schema) {
+          entry.status = 'skipped';
+          entry.reason = 'no app-public schema';
+          report.results.push(entry);
+          continue;
+        }
+        const exists = await client.query(TABLE_EXISTS_SQL, [schema, table]);
+        if (exists.rowCount === 0) {
+          entry.status = 'skipped';
+          entry.reason = `no ${table} table (blank tenant)`;
+          report.results.push(entry);
+          continue;
+        }
+
+        const name = canaryName(t);
+        // canary token == tenant.dbname (see core/fleetfile); slug is a
+        // filesystem-safe rendering of it.
+        const slug = `canary-${t.dbname}`.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+        const qSchema = `"${schema}"`;
+        const qTable = `"${table}"`;
+
+        if (cleanup) {
+          const del = await client.query(`DELETE FROM ${qSchema}.${qTable} WHERE name = $1`, [name]);
+          entry.removed = del.rowCount;
+          report.results.push(entry);
+          continue;
+        }
+
+        // Idempotent: skip if a canary row already exists.
+        const already = await client.query(
+          `SELECT count(*)::int AS n FROM ${qSchema}.${qTable} WHERE name = $1`,
+          [name]
+        );
+        if (already.rows[0].n > 0) {
+          entry.status = 'exists';
+          entry.inserted = 0;
+          report.results.push(entry);
+          continue;
+        }
+
+        const cols = await client.query(REQUIRED_COLS_SQL, [schema, table]);
+        const colNames: string[] = [];
+        const values: any[] = [];
+        const placeholders: string[] = [];
+        let bad: string | null = null;
+        let idx = 1;
+        const seen = new Set<string>();
+        for (const col of cols.rows) {
+          const v = valueForColumn(col, name, slug);
+          if (v === undefined) {
+            bad = col.column_name;
+            break;
+          }
+          colNames.push(`"${col.column_name}"`);
+          values.push(v);
+          placeholders.push(`$${idx++}`);
+          seen.add(col.column_name);
+        }
+        // Ensure `name` is always written even if it was not flagged required.
+        if (!seen.has('name')) {
+          colNames.push('"name"');
+          values.push(name);
+          placeholders.push(`$${idx++}`);
+        }
+        if (bad) {
+          entry.status = 'skipped';
+          entry.reason = `unsupported required column: ${bad}`;
+          report.results.push(entry);
+          continue;
+        }
+        const ins = await client.query(
+          `INSERT INTO ${qSchema}.${qTable} (${colNames.join(', ')}) VALUES (${placeholders.join(', ')})`,
+          values
+        );
+        entry.inserted = ins.rowCount;
+        entry.name = name;
+        report.results.push(entry);
+      }
+    });
+
+    const seeded = report.results.filter((r: any) => r.inserted > 0).length;
+    const existed = report.results.filter((r: any) => r.status === 'exists').length;
+    const removed = report.results.reduce((a: number, r: any) => a + (r.removed || 0), 0);
+    const skipped = report.results.filter((r: any) => r.status === 'skipped').length;
+    report.summary = { seeded, existed, removed, skipped, tenants: tenants.length };
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return 0;
+  } catch (err: any) {
+    process.stderr.write(`[canary-seed] ERROR: ${err && err.stack ? err.stack : err}\n`);
+    return 1;
+  }
+}
diff --git a/packages/perf-harness/src/fleet/discover.ts b/packages/perf-harness/src/fleet/discover.ts
new file mode 100644
index 0000000000..859deb2838
--- /dev/null
+++ b/packages/perf-harness/src/fleet/discover.ts
@@ -0,0 +1,105 @@
+/**
+ * fleet discover — print a JSON fleet manifest describing every tenant
+ * database. Port of `scripts/scale-validate/fleet.mjs`.
+ *
+ * For each tenant database (metaschema_public.database where name like the
+ * --like pattern) it resolves databaseId, the api/auth hosts (from
+ * services_public.domains) and the physical schemas of the `api` API.
+ *
+ *   perf-harness fleet discover > fleet.json
+ *   perf-harness fleet discover --like 'marketplace%' --pretty
+ *   perf-harness fleet discover --pg-port 5433 --out fleet.json
+ */
+import fs from 'node:fs';
+
+import { Argv, asBool, usageExit } from '../core/args';
+import { pgConfigFromArgv } from '../core/config';
+import { withFreshClient } from '../core/pgc';
+import { ensureParentDir } from '../core/proc';
+import { Tenant } from '../core/fleetfile';
+
+export const USAGE = `perf-harness fleet discover — emit JSON fleet manifest from the control-plane DB
+
+Options:
+  --like <pattern>   database name filter (default: '%' — all databases; e.g. 'marketplace%' to narrow)
+  --out <file>       write JSON here instead of stdout
+  --pretty           pretty-print JSON
+  --pg-host/--pg-port/--pg-user/--pg-password/--pg-database  connection overrides
+  --allow-hub        permit a constructive-hub port (default refuses 5432/3000/3001/3002/9000)
+  --help
+`;
+
+const FLEET_SQL = `
+SELECT
+  d.name AS dbname,
+  d.id::text AS database_id,
+  (SELECT dom.subdomain || '.' || dom.domain
+     FROM services_public.domains dom
+     WHERE dom.database_id = d.id AND dom.subdomain LIKE 'api-%'
+     ORDER BY dom.subdomain LIMIT 1) AS api_host,
+  (SELECT dom.subdomain || '.' || dom.domain
+     FROM services_public.domains dom
+     WHERE dom.database_id = d.id AND dom.subdomain LIKE 'auth-%'
+     ORDER BY dom.subdomain LIMIT 1) AS auth_host,
+  COALESCE((
+    SELECT array_agg(s.schema_name ORDER BY s.schema_name)
+      FROM services_public.apis a
+      JOIN services_public.api_schemas aps ON aps.api_id = a.id AND aps.database_id = a.database_id
+      JOIN metaschema_public.schema s ON s.id = aps.schema_id
+     WHERE a.database_id = d.id AND a.name = 'api'
+  ), ARRAY[]::text[]) AS schemas
+FROM metaschema_public.database d
+WHERE d.name LIKE $1
+ORDER BY d.name;
+`;
+
+export async function run(argv: Argv): Promise<number> {
+  if (asBool(argv.help)) return usageExit(USAGE, 0);
+  try {
+    // Default widened from the original fleet.mjs 'marketplace%' to '%': the
+    // canonical validation fleet (committed fleet.json, VALIDATION-REPORT.md)
+    // and the tenants `fleet provision` creates (factory*) are only captured
+    // by a match-all pattern. Pass --like to narrow (e.g. 'marketplace%').
+    const like = typeof argv.like === 'string' ? argv.like : '%';
+    const pretty = asBool(argv.pretty);
+    const cfg = pgConfigFromArgv(argv);
+    const rows = await withFreshClient(cfg, async (client) => {
+      const res = await client.query(FLEET_SQL, [like]);
+      return res.rows;
+    });
+
+    const tenants: Tenant[] = rows.map((r: any) => {
+      const schemas: string[] = r.schemas || [];
+      const appPublicSchema = schemas.find((s) => /-app-public$/.test(s)) || schemas[0] || null;
+      return {
+        dbname: r.dbname,
+        databaseId: r.database_id,
+        apiHost: r.api_host,
+        authHost: r.auth_host,
+        schemas,
+        appPublicSchema
+      };
+    });
+
+    const manifest = {
+      generatedAt: new Date().toISOString(),
+      like,
+      pg: { host: cfg.host, port: cfg.port, database: cfg.database },
+      count: tenants.length,
+      tenants
+    };
+
+    const json = JSON.stringify(manifest, null, pretty ? 2 : 0);
+    if (typeof argv.out === 'string') {
+      ensureParentDir(argv.out);
+      fs.writeFileSync(argv.out, `${json}\n`, 'utf8');
+      process.stderr.write(`[fleet] wrote ${tenants.length} tenants to ${argv.out}\n`);
+    } else {
+      process.stdout.write(`${json}\n`);
+    }
+    return 0;
+  } catch (err: any) {
+    process.stderr.write(`[fleet] ERROR: ${err && err.stack ? err.stack : err}\n`);
+    return 1;
+  }
+}
diff --git a/packages/perf-harness/src/fleet/drift.ts b/packages/perf-harness/src/fleet/drift.ts
new file mode 100644
index 0000000000..189baaa6b5
--- /dev/null
+++ b/packages/perf-harness/src/fleet/drift.ts
@@ -0,0 +1,105 @@
+/**
+ * fleet drift — apply deliberate shape drift to seeded tenants so the fleet
+ * spans multiple blueprints. Port of `scripts/scale-validate/drift-tenants.mjs`
+ * (inline pg defaults/parser replaced with core config + args; --pg-* and --help
+ * added; output written under --out-dir).
+ *
+ * The pooling shape-fingerprint hashes [logical schema, relname] pairs — only
+ * ADDING A RELATION changes a tenant's blueprint.
+ *
+ *   --groups K --per-group N   assign K drift groups; group g (1-based) gets a
+ *                              marker TABLE drift_marker_g<g> in app-public →
+ *                              K distinct blueprints (group 0 = undrifted).
+ *   --column-drift N           additionally give N tenants a benign EXTRA COLUMN
+ *                              on categories (same relname set → SAME blueprint;
+ *                              exercises the documented fingerprint limitation).
+ *
+ * Writes drifted.json describing the assignment. Idempotent (IF NOT EXISTS).
+ *   perf-harness fleet drift --groups 6 --per-group 4 --column-drift 2
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { Argv, asBool, asInt, usageExit } from '../core/args';
+import { PgConfig, pgConfigFromArgv, resolveOutDir } from '../core/config';
+import { withFreshClient } from '../core/pgc';
+
+export const USAGE = `perf-harness fleet drift — apply deliberate shape drift so the fleet spans multiple blueprints
+
+Options:
+  --groups <K>         assign K table-drift groups (drift_marker_g<g> per group)
+  --per-group <N>      tenants per group (default: 4)
+  --column-drift <N>   give N tenants a benign extra column (same blueprint)
+  --out <file>         write assignment JSON here (default: <out-dir>/drifted.json)
+  --out-dir <dir>      artifact directory (default: ./perf-out)
+  --pg-* / PG*         connection overrides
+  --allow-hub          permit a constructive-hub port
+  --help
+`;
+
+// Tenant app-public schemas, oldest first for stable assignment.
+const TENANT_SCHEMAS_SQL = `
+    SELECT db.name AS dbname, s.schema_name
+    FROM metaschema_public.database db
+    JOIN metaschema_public.schema s ON s.database_id = db.id
+    WHERE db.name NOT IN ('constructive') AND s.schema_name LIKE '%-app-public'
+    ORDER BY db.name`;
+
+export async function run(argv: Argv): Promise<number> {
+  if (asBool(argv.help)) return usageExit(USAGE, 0);
+
+  const groups = asInt(argv.groups, 0);
+  const perGroup = asInt(argv['per-group'], 4);
+  const columnDrift = asInt(argv['column-drift'], 0);
+
+  let cfg: PgConfig;
+  try {
+    cfg = pgConfigFromArgv(argv);
+  } catch (err) {
+    console.error(err);
+    return 1;
+  }
+
+  const outFile =
+    typeof argv.out === 'string' ? path.resolve(argv.out) : path.join(resolveOutDir(argv), 'drifted.json');
+
+  try {
+    await withFreshClient(cfg, async (client) => {
+      const { rows } = await client.query(TENANT_SCHEMAS_SQL);
+
+      const assignment: { groups: Record<string, string[]>; columnDrift: string[] } = { groups: {}, columnDrift: [] };
+      let idx = 0;
+
+      for (let g = 1; g <= groups; g++) {
+        assignment.groups[g] = [];
+        for (let n = 0; n < perGroup && idx < rows.length; n++, idx++) {
+          const { dbname, schema_name } = rows[idx];
+          await client.query(
+            `CREATE TABLE IF NOT EXISTS "${schema_name.replace(/"/g, '""')}"."drift_marker_g${g}" (id serial PRIMARY KEY, note text)`
+          );
+          assignment.groups[g].push(dbname);
+          console.error(`table-drift g${g}: ${dbname}`);
+        }
+      }
+
+      for (let n = 0; n < columnDrift && idx < rows.length; n++, idx++) {
+        const { dbname, schema_name } = rows[idx];
+        await client.query(
+          `ALTER TABLE "${schema_name.replace(/"/g, '""')}".categories ADD COLUMN IF NOT EXISTS drift_col_only text`
+        );
+        assignment.columnDrift.push(dbname);
+        console.error(`column-drift (same blueprint, documents fingerprint limit): ${dbname}`);
+      }
+
+      fs.mkdirSync(path.dirname(outFile), { recursive: true });
+      fs.writeFileSync(outFile, JSON.stringify(assignment, null, 2));
+      console.error(
+        `done: ${groups} table-drift groups × ${perGroup}, ${columnDrift} column-drift; assignment → ${outFile}`
+      );
+    });
+    return 0;
+  } catch (err) {
+    console.error(err);
+    return 1;
+  }
+}
diff --git a/packages/perf-harness/src/fleet/provision.ts b/packages/perf-harness/src/fleet/provision.ts
new file mode 100644
index 0000000000..fb3584a578
--- /dev/null
+++ b/packages/perf-harness/src/fleet/provision.ts
@@ -0,0 +1,433 @@
+/**
+ * fleet provision — the fast-path tenant factory. Port of
+ * `scripts/scale-validate/tenant-factory.mjs`.
+ *
+ * Creates blueprint-identical marketplace tenants directly via SQL, reusing the
+ * SAME control-plane procedures the GraphQL seeder ultimately invokes, but
+ * WITHOUT the GraphQL/undici layer (and its 300s HTTP cap). Per tenant, in one
+ * committed transaction:
+ *
+ *   1. metaschema_generators.provision_database(...)   — db + domains + apis +
+ *        site + modules + the app_public/app_private application schemas.
+ *   2. metaschema_private.bootstrap_owner_into_database(...) — copies the owner
+ *        user + primary email + password_hash from the control-plane source
+ *        database so password sign-in works.
+ *   3. INSERT metaschema_modules_public.blueprint (copy of the reference
+ *        definition) + metaschema_modules_public.construct_blueprint(
+ *        blueprint_id, app_public_schema_id) — builds the marketplace tables.
+ *
+ * Session GUC: the module install triggers call
+ * metaschema_private.ensure_super_constructive(), which RAISES unless
+ * `constructive.allow_super_constructive = 'true'`. We set it per-transaction.
+ *
+ *   perf-harness fleet provision --count 5 --prefix factory --blueprint marketplace
+ *   perf-harness fleet provision --validate factory1   # shape check vs reference
+ */
+import { createHash, randomBytes } from 'node:crypto';
+
+import { Argv, asBool, asInt, usageExit } from '../core/args';
+import { PgConfig, pgConfigFromArgv } from '../core/config';
+import { getPg, isConnLoss, isRetryableTxn } from '../core/pgc';
+
+export const USAGE = `perf-harness fleet provision — create blueprint-identical marketplace tenants via SQL
+
+Options:
+  --count <n>          number of tenants to create (default: 1)
+  --prefix <name>      tenant name prefix (default: factory)
+  --blueprint <name>   reference blueprint name (default: marketplace)
+  --reference <db>     reference tenant database (default: marketplace_db_tenant1)
+  --source-db <db>     control-plane source database (default: constructive)
+  --domain <domain>    subdomain suffix (default: localhost)
+  --concurrency <n>    parallel workers (default: 1)
+  --max-retries <n>    retries on connection loss / deadlock (default: 3)
+  --start-index <n>    first tenant index (default: next free after prefix)
+  --dry-run            ROLLBACK each tenant transaction (shape check only)
+  --validate <db>      compare a tenant's api shape-fingerprint to the reference
+  --pg-* / PG*         connection overrides
+  --allow-hub          permit a constructive-hub port
+  --help
+`;
+
+interface ProvisionOpts {
+  count: number;
+  prefix: string;
+  blueprint: string;
+  reference: string;
+  sourceDb: string;
+  domain: string;
+  concurrency: number;
+  maxRetries: number;
+  dryRun: boolean;
+  validate: string | null;
+  startIndex: number | null;
+}
+
+function readOpts(argv: Argv): ProvisionOpts {
+  return {
+    count: asInt(argv.count, 1),
+    prefix: typeof argv.prefix === 'string' ? argv.prefix : 'factory',
+    blueprint: typeof argv.blueprint === 'string' ? argv.blueprint : 'marketplace',
+    reference: typeof argv.reference === 'string' ? argv.reference : 'marketplace_db_tenant1',
+    sourceDb: typeof argv['source-db'] === 'string' ? argv['source-db'] : 'constructive',
+    domain: typeof argv.domain === 'string' ? argv.domain : 'localhost',
+    concurrency: asInt(argv.concurrency, 1),
+    maxRetries: asInt(argv['max-retries'], 3),
+    dryRun: asBool(argv['dry-run']),
+    validate: typeof argv.validate === 'string' ? argv.validate : null,
+    startIndex: argv['start-index'] !== undefined ? asInt(argv['start-index'], null) : null
+  };
+}
+
+const now = (): bigint => process.hrtime.bigint();
+const ms = (t: bigint): string => `${(Number(t) / 1e6).toFixed(0)}ms`;
+
+// ---------------------------------------------------------------------------
+// retry classification (deadlock/serialization vs connection-class failures)
+// ---------------------------------------------------------------------------
+// 40P01/40001: deadlock/serialization -> short backoff. 57P0x/08006/08003/53300
+// + message sniff: connection-class (e.g. PG crash recovery) -> long backoff so
+// the run survives a server restart. Classifiers live in core/pgc.
+export function classifyRetry(err: any): { connLost: boolean; retriable: boolean } {
+  const connLost = isConnLoss(err);
+  return { connLost, retriable: connLost || isRetryableTxn(err) };
+}
+
+export function retryBackoffMs(connLost: boolean, attempt: number, rand: number = Math.random()): number {
+  return (connLost ? 10000 : 100) * attempt + Math.floor(rand * 100);
+}
+
+// ---------------------------------------------------------------------------
+// shape fingerprint (step 3.i): compare the logical [schema, relname] set of a
+// tenant's `api` API to the reference tenant's — same set => same fingerprint =>
+// same bp: key. Mirrors graphql/server/src/middleware/blueprint.ts:
+// stripSchemaHashPrefix + fingerprintFromRelations. The physical-schema hash
+// prefix is stripped in JS (not SQL) so the property is unit-testable.
+// ---------------------------------------------------------------------------
+const SHAPE_SQL = `
+  WITH api_schema AS (
+    SELECT s.schema_name
+      FROM metaschema_public.database d
+      JOIN services_public.apis a ON a.database_id = d.id AND a.name = 'api'
+      JOIN services_public.api_schemas x ON x.api_id = a.id
+      JOIN metaschema_public.schema s ON s.id = x.schema_id
+     WHERE d.name = $1
+  )
+  SELECT n.nspname, c.relname
+    FROM api_schema aps
+    JOIN pg_namespace n ON n.nspname = aps.schema_name
+    JOIN pg_class c ON c.relnamespace = n.oid AND c.relkind IN ('r','v','m','p')
+   ORDER BY 1, 2`;
+
+export interface ShapeRelation {
+  nspname: string;
+  relname: string;
+}
+
+// Strip the tenant hash prefix from a physical schema name (mirror of the
+// server's stripSchemaHashPrefix): `<dashed-dbname>-<8hex>-<logical>` ->
+// `<logical>`; control-plane schemas without the segment are unchanged.
+export function stripSchemaHashPrefix(name: string): string {
+  const match = /-[0-9a-f]{8}-/.exec(name);
+  if (!match) return name;
+  return name.slice(match.index + match[0].length);
+}
+
+// sha256 over the sorted [logicalSchema, relname] pairs (same algorithm as the
+// server's fingerprintFromRelations). Returns the pairs too, for reporting.
+export function computeShape(rows: ShapeRelation[]): { pairs: [string, string][]; fingerprint: string } {
+  const pairs: [string, string][] = rows.map((row) => [stripSchemaHashPrefix(row.nspname), row.relname]);
+  pairs.sort((a, b) => (a[0] !== b[0] ? (a[0] < b[0] ? -1 : 1) : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0));
+  return { pairs, fingerprint: createHash('sha256').update(JSON.stringify(pairs)).digest('hex') };
+}
+
+async function shapeOf(pool: any, dbName: string): Promise<{ pairs: [string, string][]; fingerprint: string }> {
+  const r = await pool.query(SHAPE_SQL, [dbName]);
+  return computeShape(r.rows);
+}
+
+async function validateShape(pool: any, opts: ProvisionOpts): Promise<boolean> {
+  const ref = await shapeOf(pool, opts.reference);
+  const cand = await shapeOf(pool, opts.validate);
+  const same = ref.fingerprint === cand.fingerprint;
+  console.error(`\n=== SHAPE CHECK: "${opts.validate}" vs reference "${opts.reference}" ===`);
+  console.error(`reference api relations (${ref.pairs.length}):`);
+  for (const [s, r] of ref.pairs) console.error(`    ${s}.${r}`);
+  console.error(`candidate api relations (${cand.pairs.length}):`);
+  for (const [s, r] of cand.pairs) console.error(`    ${s}.${r}`);
+  console.error(`reference shapeFingerprint: ${ref.fingerprint}`);
+  console.error(`candidate shapeFingerprint: ${cand.fingerprint}`);
+  console.error(`IDENTICAL SHAPE => same bp: key expected: ${same ? 'YES' : 'NO'}`);
+  return same;
+}
+
+// ---------------------------------------------------------------------------
+// reference loading
+// ---------------------------------------------------------------------------
+async function loadReference(pool: any, opts: ProvisionOpts): Promise<any> {
+  const ref = await pool.query(
+    `SELECT d.id AS db_id, d.owner_id
+       FROM metaschema_public.database d
+      WHERE d.name = $1`,
+    [opts.reference]
+  );
+  if (ref.rows.length === 0) throw new Error(`reference database "${opts.reference}" not found`);
+  const { db_id: refDbId, owner_id: ownerId } = ref.rows[0];
+
+  const prov = await pool.query(
+    `SELECT modules, options, domain
+       FROM metaschema_modules_public.database_provision_module
+      WHERE database_id = $1
+      ORDER BY created_at
+      LIMIT 1`,
+    [refDbId]
+  );
+  if (prov.rows.length === 0)
+    throw new Error(`no database_provision_module row for reference "${opts.reference}"`);
+  const modules = prov.rows[0].modules;
+  const options = prov.rows[0].options;
+
+  const bp = await pool.query(
+    `SELECT name, display_name, definition
+       FROM metaschema_modules_public.blueprint
+      WHERE database_id = $1 AND name = $2`,
+    [refDbId, opts.blueprint]
+  );
+  if (bp.rows.length === 0)
+    throw new Error(`reference blueprint "${opts.blueprint}" not found on "${opts.reference}"`);
+  const blueprint = bp.rows[0];
+
+  const src = await pool.query(`SELECT id FROM metaschema_public.database WHERE name = $1`, [opts.sourceDb]);
+  if (src.rows.length === 0) throw new Error(`source database "${opts.sourceDb}" not found`);
+  const sourceDbId = src.rows[0].id;
+
+  return { refDbId, ownerId, modules, options, blueprint, sourceDbId };
+}
+
+async function nextStartIndex(pool: any, prefix: string): Promise<number> {
+  const r = await pool.query(
+    `SELECT COALESCE(MAX((regexp_replace(name, '^' || $1, ''))::int), 0) AS mx
+       FROM metaschema_public.database
+      WHERE name ~ ('^' || $1 || '[0-9]+$')`,
+    [prefix]
+  );
+  return (r.rows[0].mx || 0) + 1;
+}
+
+// ---------------------------------------------------------------------------
+// per-tenant provisioning (one committed transaction)
+// ---------------------------------------------------------------------------
+async function createTenant(pool: any, ref: any, opts: ProvisionOpts, index: number): Promise<any> {
+  const name = `${opts.prefix}${index}`;
+  const subdomain = `${name}-${randomBytes(4).toString('hex')}`;
+
+  let attempt = 0;
+  for (;;) {
+    attempt++;
+    const client = await pool.connect();
+    const t: any = {};
+    try {
+      await client.query('BEGIN');
+      await client.query('SET LOCAL statement_timeout = 0');
+      await client.query('SET LOCAL idle_in_transaction_session_timeout = 0');
+      await client.query('SET LOCAL lock_timeout = 0');
+      await client.query(`SET LOCAL constructive.allow_super_constructive = 'true'`);
+
+      // Phase 1: provision_database
+      let s = now();
+      const provRes = await client.query(
+        `SELECT metaschema_generators.provision_database($1,$2,$3,$4,$5::jsonb,$6::jsonb) AS db_id`,
+        [name, ref.ownerId, subdomain, opts.domain, JSON.stringify(ref.modules), JSON.stringify(ref.options)]
+      );
+      const dbId = provRes.rows[0].db_id;
+      t.provision = now() - s;
+
+      // Phase 2: bootstrap owner (password sign-in path)
+      s = now();
+      await client.query(`SELECT metaschema_private.bootstrap_owner_into_database($1,$2,$3,false)`, [
+        dbId,
+        ref.sourceDbId,
+        ref.ownerId
+      ]);
+      t.bootstrap = now() - s;
+
+      // Phase 3: blueprint copy + construct
+      s = now();
+      const bpRes = await client.query(
+        `INSERT INTO metaschema_modules_public.blueprint
+           (owner_id, database_id, name, display_name, definition)
+         VALUES ($1,$2,$3,$4,$5::jsonb)
+         RETURNING id`,
+        [ref.ownerId, dbId, ref.blueprint.name, ref.blueprint.display_name, JSON.stringify(ref.blueprint.definition)]
+      );
+      const blueprintId = bpRes.rows[0].id;
+      const schemaRes = await client.query(
+        `SELECT id, schema_name FROM metaschema_public.schema
+          WHERE database_id = $1 AND name = 'app_public'`,
+        [dbId]
+      );
+      if (schemaRes.rows.length === 0) throw new Error('app_public schema not found after provision');
+      const appPublicSchemaId = schemaRes.rows[0].id;
+      const appPublicPhysical = schemaRes.rows[0].schema_name;
+      await client.query(`SELECT metaschema_modules_public.construct_blueprint($1,$2)`, [
+        blueprintId,
+        appPublicSchemaId
+      ]);
+      t.blueprint = now() - s;
+
+      // Phase 4: in-txn verification
+      const verify: any = {};
+      verify.schemaCount = (
+        await client.query(`SELECT count(*)::int AS c FROM metaschema_public.schema WHERE database_id=$1`, [dbId])
+      ).rows[0].c;
+      verify.appTables = (
+        await client.query(
+          `SELECT array_agg(c.relname::text ORDER BY c.relname) AS tables
+             FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace
+            WHERE n.nspname=$1 AND c.relkind='r'`,
+          [appPublicPhysical]
+        )
+      ).rows[0].tables;
+      verify.domains = (
+        await client.query(
+          `SELECT array_agg(d.subdomain || '.' || d.domain ORDER BY d.subdomain) AS hosts
+             FROM services_public.domains d WHERE d.database_id=$1
+              AND (d.subdomain LIKE 'api-%' OR d.subdomain LIKE 'auth-%')`,
+          [dbId]
+        )
+      ).rows[0].hosts;
+
+      if (opts.dryRun) await client.query('ROLLBACK');
+      else await client.query('COMMIT');
+
+      return {
+        ok: true,
+        name,
+        subdomain,
+        dbId,
+        appPublicPhysical,
+        apiHost: `api-${subdomain}.${opts.domain}`,
+        authHost: `auth-${subdomain}.${opts.domain}`,
+        timings: t,
+        verify,
+        attempt,
+        rolledBack: opts.dryRun
+      };
+    } catch (err: any) {
+      try {
+        await client.query('ROLLBACK');
+      } catch {
+        // rollback of an already-broken txn can throw — ignore
+      }
+      const { connLost, retriable } = classifyRetry(err);
+      if (retriable && attempt <= opts.maxRetries) {
+        const backoff = retryBackoffMs(connLost, attempt);
+        console.error(`  [${name}] ${err.code} (attempt ${attempt}) — retrying in ${backoff}ms`);
+        await new Promise((r) => setTimeout(r, backoff));
+        continue;
+      }
+      return { ok: false, name, subdomain, error: err.message, code: err.code, attempt };
+    } finally {
+      client.release();
+    }
+  }
+}
+
+export async function run(argv: Argv): Promise<number> {
+  if (asBool(argv.help)) return usageExit(USAGE, 0);
+  const opts = readOpts(argv);
+
+  let cfg: PgConfig;
+  try {
+    cfg = pgConfigFromArgv(argv);
+  } catch (err) {
+    console.error(err);
+    return 1;
+  }
+
+  const { Pool } = getPg();
+  const pool = new Pool({ ...cfg, max: Math.max(2, opts.concurrency + 1) });
+  // An idle pooled client dying (PG crash/restart) must not take down the run.
+  pool.on('error', (e: any) => console.error(`  [pool] idle client error (continuing): ${e.message}`));
+
+  try {
+    if (opts.validate) {
+      const ok = await validateShape(pool, opts);
+      return ok ? 0 : 1;
+    }
+
+    const ref = await loadReference(pool, opts);
+    const start = opts.startIndex ?? (await nextStartIndex(pool, opts.prefix));
+    const indices = Array.from({ length: opts.count }, (_, k) => start + k);
+
+    console.error(
+      `tenant-factory: creating ${opts.count} tenant(s) prefix=${opts.prefix} indices=${start}..${
+        start + opts.count - 1
+      } blueprint=${opts.blueprint} concurrency=${opts.concurrency}${opts.dryRun ? ' [DRY-RUN]' : ''}`
+    );
+    console.error(`  owner=${ref.ownerId} source-db=${ref.sourceDbId} modules=${ref.modules.length} items`);
+
+    const results: any[] = [];
+    const wallStart = now();
+
+    // simple concurrency pool
+    let cursor = 0;
+    const worker = async (): Promise<void> => {
+      for (;;) {
+        const i = cursor++;
+        if (i >= indices.length) return;
+        const idx = indices[i];
+        const tStart = now();
+        const res = await createTenant(pool, ref, opts, idx);
+        const wall = now() - tStart;
+        res.wall = wall;
+        results.push(res);
+        if (res.ok) {
+          const okTables = Array.isArray(res.verify.appTables) && res.verify.appTables.length === 5;
+          console.error(
+            `  [${res.name}] OK db=${res.dbId} schemas=${res.verify.schemaCount} ` +
+              `appTables=${(res.verify.appTables || []).join(',')} ${okTables ? '✓' : '✗5'} ` +
+              `(prov ${ms(res.timings.provision)} boot ${ms(res.timings.bootstrap)} ` +
+              `bp ${ms(res.timings.blueprint)} wall ${ms(wall)}${
+                res.attempt > 1 ? ` retries=${res.attempt - 1}` : ''
+              })`
+          );
+        } else {
+          console.error(`  [${res.name}] FAILED code=${res.code} ${res.error}`);
+        }
+      }
+    };
+    await Promise.all(Array.from({ length: opts.concurrency }, () => worker()));
+
+    const wall = now() - wallStart;
+    const ok = results.filter((r) => r.ok);
+    const failed = results.filter((r) => !r.ok);
+    const totalSec = Number(wall) / 1e9;
+    const perMin = ok.length > 0 ? (ok.length / totalSec) * 60 : 0;
+
+    console.error(`\n=== SUMMARY ===`);
+    console.error(`created ${ok.length}/${opts.count} tenants in ${totalSec.toFixed(1)}s`);
+    if (ok.length) {
+      const avg = (sel: (r: any) => any): number => ok.reduce((a, r) => a + Number(sel(r)), 0) / ok.length / 1e6;
+      console.error(
+        `  avg per-tenant: provision ${avg((r) => r.timings.provision).toFixed(0)}ms ` +
+          `bootstrap ${avg((r) => r.timings.bootstrap).toFixed(0)}ms ` +
+          `blueprint ${avg((r) => r.timings.blueprint).toFixed(0)}ms ` +
+          `wall ${avg((r) => r.wall).toFixed(0)}ms`
+      );
+      console.error(`  throughput: ${perMin.toFixed(2)} tenants/minute (concurrency=${opts.concurrency})`);
+      console.error(`  api hosts:`);
+      for (const r of ok) console.error(`    ${r.name}: ${r.apiHost}  (auth: ${r.authHost})`);
+    }
+    if (failed.length) {
+      console.error(`  FAILURES:`);
+      for (const r of failed) console.error(`    ${r.name}: [${r.code}] ${r.error}`);
+      return 1;
+    }
+    return 0;
+  } catch (err) {
+    console.error(err);
+    return 1;
+  } finally {
+    await pool.end();
+  }
+}
diff --git a/packages/perf-harness/src/fleet/teardown.ts b/packages/perf-harness/src/fleet/teardown.ts
new file mode 100644
index 0000000000..4a84a556ac
--- /dev/null
+++ b/packages/perf-harness/src/fleet/teardown.ts
@@ -0,0 +1,175 @@
+/**
+ * fleet teardown — tear down factory tenants above --keep (catalog-wall
+ * remediation: the rig's PG cannot introspect a 100+-tenant catalog, so the
+ * fleet is trimmed to a size the VM can serve). Port of
+ * `scripts/scale-validate/drop-tenants.mjs` (inline pg defaults replaced with
+ * core config + args; --pg-* and --help added).
+ *
+ * Per tenant, in one transaction:
+ *   1. capture its physical schema names from metaschema_public.schema
+ *   2. DELETE FROM metaschema_public.database (control-plane FKs CASCADE;
+ *      metaschema delete triggers may drop physical objects — requires the
+ *      constructive.allow_super_constructive GUC)
+ *   3. DROP SCHEMA IF EXISTS ... CASCADE for any physical schema that survived
+ * Then VACUUM ANALYZE the hot catalogs and report the new catalog size.
+ *
+ *   perf-harness fleet teardown --prefix factory --keep 40 [--dry-run] [--only factory101]
+ */
+import { Argv, asBool, asInt, usageExit } from '../core/args';
+import { PgConfig, pgConfigFromArgv } from '../core/config';
+import { getPg } from '../core/pgc';
+
+export const USAGE = `perf-harness fleet teardown — drop factory tenants above --keep and reclaim catalog
+
+Options:
+  --prefix <name>   tenant name prefix (default: factory)
+  --keep <n>        keep tenants with index <= n (default: 40)
+  --only <db>       drop exactly this one tenant instead of prefix/keep
+  --dry-run         ROLLBACK each drop (report only)
+  --pg-* / PG*      connection overrides
+  --allow-hub       permit a constructive-hub port
+  --help
+`;
+
+// Hot catalogs to VACUUM ANALYZE after a drop batch so pg_class introspection
+// stays fast at scale.
+const VACUUM_CATALOGS = ['pg_class', 'pg_attribute', 'pg_proc', 'pg_constraint', 'pg_policy', 'pg_namespace', 'pg_depend', 'pg_type'];
+
+export interface TeardownWhere {
+  sql: string;
+  params: any[];
+}
+
+// --only targets exactly one tenant; otherwise drop every `<prefix><n>` tenant
+// whose numeric index exceeds --keep.
+export function buildWhere(opts: { only?: string | null; prefix: string; keep: number }): TeardownWhere {
+  if (opts.only) {
+    return { sql: `name = $1`, params: [opts.only] };
+  }
+  return {
+    sql: `name ~ ('^' || $1 || '[0-9]+$') AND (regexp_replace(name, '^' || $1, ''))::int > $2`,
+    params: [opts.prefix, opts.keep]
+  };
+}
+
+const qid = (s: string): string => `"${s.replace(/"/g, '""')}"`;
+
+async function dropOne(pool: any, row: any, dry: boolean): Promise<{ ok: boolean; error?: string }> {
+  const client = await pool.connect();
+  const t0 = Date.now();
+  try {
+    await client.query('BEGIN');
+    await client.query('SET LOCAL statement_timeout = 0');
+    await client.query('SET LOCAL lock_timeout = 0');
+    await client.query(`SET LOCAL constructive.allow_super_constructive = 'true'`);
+
+    const schemas = (
+      await client.query(`SELECT schema_name FROM metaschema_public.schema WHERE database_id=$1`, [row.id])
+    ).rows.map((r: any) => r.schema_name);
+
+    await client.query(`DELETE FROM metaschema_public.database WHERE id=$1`, [row.id]);
+
+    let survivors = 0;
+    for (const s of schemas) {
+      const exists = await client.query(`SELECT 1 FROM pg_namespace WHERE nspname=$1`, [s]);
+      if (exists.rows.length) {
+        survivors++;
+        await client.query(`DROP SCHEMA IF EXISTS ${qid(s)} CASCADE`);
+      }
+    }
+
+    // pg_partman registers partitioned tables by NAME in partman.part_config —
+    // not schema-scoped, not FK-cascaded — and schema hashes are deterministic
+    // per dbname, so a leftover row blocks re-provisioning a reused tenant name
+    // (unique_violation on parent_table). Clean them with the schemas.
+    if (schemas.length) {
+      const patterns = schemas.map((s: string) => `${s}.%`);
+      try {
+        await client.query(`DELETE FROM partman.part_config_sub WHERE sub_parent LIKE ANY($1)`, [patterns]);
+      } catch {
+        /* part_config_sub may not exist */
+      }
+      try {
+        const del = await client.query(`DELETE FROM partman.part_config WHERE parent_table LIKE ANY($1)`, [patterns]);
+        if (del.rowCount) console.error(`  [${row.name}] cleaned ${del.rowCount} partman.part_config row(s)`);
+      } catch {
+        /* partman may not be installed */
+      }
+    }
+
+    if (dry) await client.query('ROLLBACK');
+    else await client.query('COMMIT');
+    console.error(
+      `  [${row.name}] dropped (schemas=${schemas.length} survivors-dropped=${survivors}) ${Date.now() - t0}ms${dry ? ' [DRY]' : ''}`
+    );
+    return { ok: true };
+  } catch (e: any) {
+    try {
+      await client.query('ROLLBACK');
+    } catch {
+      // rollback of an already-broken txn can throw — ignore
+    }
+    console.error(`  [${row.name}] FAILED: ${e.code || ''} ${e.message}`);
+    return { ok: false, error: e.message };
+  } finally {
+    client.release();
+  }
+}
+
+export async function run(argv: Argv): Promise<number> {
+  if (asBool(argv.help)) return usageExit(USAGE, 0);
+
+  const prefix = typeof argv.prefix === 'string' ? argv.prefix : 'factory';
+  const keep = asInt(argv.keep, 40);
+  const only = typeof argv.only === 'string' ? argv.only : null;
+  const dry = asBool(argv['dry-run']);
+
+  let cfg: PgConfig;
+  try {
+    cfg = pgConfigFromArgv(argv);
+  } catch (err) {
+    console.error(err);
+    return 1;
+  }
+
+  const { Pool } = getPg();
+  const pool = new Pool({ ...cfg, max: 2 });
+  pool.on('error', (e: any) => console.error(`[pool] idle client error (continuing): ${e.message}`));
+
+  try {
+    const where = buildWhere({ only, prefix, keep });
+    const { rows } = await pool.query(
+      `SELECT id, name FROM metaschema_public.database WHERE ${where.sql}
+     ORDER BY (regexp_replace(name, '[^0-9]', '', 'g'))::int NULLS LAST`,
+      where.params
+    );
+    console.error(`drop-tenants: ${rows.length} tenant(s) to drop${dry ? ' [DRY-RUN]' : ''}`);
+
+    let ok = 0;
+    for (const row of rows) {
+      const r = await dropOne(pool, row, dry);
+      if (r.ok) ok++;
+    }
+    console.error(`dropped ${ok}/${rows.length}`);
+
+    if (!dry && ok > 0) {
+      console.error('VACUUM ANALYZE hot catalogs...');
+      for (const cat of VACUUM_CATALOGS) {
+        await pool.query(`VACUUM ANALYZE ${cat}`);
+      }
+    }
+
+    const stats = await pool.query(`
+    SELECT (SELECT count(*) FROM pg_class) AS classes,
+           (SELECT count(*) FROM pg_attribute) AS attrs,
+           (SELECT count(*) FROM pg_namespace) AS namespaces,
+           (SELECT count(*) FROM metaschema_public.database) AS databases`);
+    console.error(`catalog now: ${JSON.stringify(stats.rows[0])}`);
+    return 0;
+  } catch (err) {
+    console.error(err);
+    return 1;
+  } finally {
+    await pool.end();
+  }
+}
diff --git a/packages/perf-harness/src/index.ts b/packages/perf-harness/src/index.ts
new file mode 100644
index 0000000000..e5b76b7d99
--- /dev/null
+++ b/packages/perf-harness/src/index.ts
@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * perf-harness — Constructive performance / regression CLI.
+ *
+ * Non-interactive, script-friendly router:
+ *   perf-harness <domain> <subcommand> [flags]
+ *
+ * Each `src/commands/<domain>.ts` self-registers via `{ domain, summary,
+ * subcommands }`. This shell is deliberately a hand-rolled router over
+ * `core/args.parseArgv` rather than the `inquirerer` CLI class the sibling
+ * `packages/cli` uses: the domain contract returns numeric exit codes (0/1/2),
+ * routing is 2–3 positionals deep (`run soak start|status|stop`), and the
+ * automation contract forbids interactive prompts — none of which the
+ * prompt-driven `inquirerer` shell accommodates cleanly. See DESIGN.md
+ * "Command registration contract" (a working non-interactive CLI beats
+ * framework conformance).
+ *
+ * stdout is reserved for the machine-readable JSON/JSONL protocol emitted by
+ * subcommands; help/usage (human output) goes to stderr via `usageExit`.
+ */
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+
+import * as fleet from './commands/fleet';
+import * as load from './commands/load';
+import * as measure from './commands/measure';
+import * as regression from './commands/regression';
+import * as report from './commands/report';
+import * as run from './commands/run';
+import { Argv, parseArgv, usageExit } from './core/args';
+
+interface Subcommand {
+  usage: string;
+  run(argv: Argv): Promise<number>;
+}
+
+interface Domain {
+  domain: string;
+  summary: string;
+  subcommands: Record<string, Subcommand>;
+}
+
+// Ordered for help rendering; the registry below is keyed off each `.domain`.
+const DOMAIN_LIST: Domain[] = [fleet, load, measure, run, report, regression];
+
+const domains: Record<string, Domain> = {};
+for (const d of DOMAIN_LIST) domains[d.domain] = d;
+
+function readVersion(): string {
+  // Published layout puts package.json next to index.js (publishConfig.directory
+  // = dist); built/dev layouts put it one level up. Walk up until the first
+  // package.json with a version is found.
+  let dir = __dirname;
+  for (let i = 0; i < 6; i++) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+      if (pkg && typeof pkg.version === 'string') return pkg.version;
+    } catch {
+      // not here — keep walking up
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return '0.0.0';
+}
+
+function topLevelHelp(): string {
+  const w = Math.max(...DOMAIN_LIST.map((d) => d.domain.length));
+  const lines = DOMAIN_LIST.map((d) => `  ${d.domain.padEnd(w)}  ${d.summary}`);
+  return [
+    'perf-harness — Constructive performance / regression harness',
+    '',
+    'Usage: perf-harness <domain> <subcommand> [flags]',
+    '',
+    'Domains:',
+    ...lines,
+    '',
+    "Run 'perf-harness <domain> --help' to list a domain's subcommands.",
+    'Global flags: --help/-h, --version.',
+    'Common flags: --allow-hub, --out-dir <dir>, --pg-host/--pg-port/--pg-user/--pg-password/--pg-database.'
+  ].join('\n');
+}
+
+function domainHelp(d: Domain): string {
+  const usageLines = Object.values(d.subcommands).map((s) => `  ${s.usage}`);
+  return [
+    `perf-harness ${d.domain} — ${d.summary}`,
+    '',
+    `Usage: perf-harness ${d.domain} <subcommand> [flags]`,
+    '',
+    'Subcommands:',
+    ...usageLines
+  ].join('\n');
+}
+
+async function main(): Promise<number> {
+  const raw = process.argv.slice(2);
+  const argv = parseArgv(raw);
+
+  // Detect meta-flags from the RAW argv: parseArgv treats `--flag value` as
+  // key=value, which would otherwise let `--version`/`--help` swallow a
+  // following positional. These flags are always standalone booleans.
+  if (raw.includes('--version')) {
+    console.log(readVersion());
+    return 0;
+  }
+  const wantHelp = raw.includes('--help') || raw.includes('-h');
+
+  const domainName = argv._[0];
+  if (domainName === 'help' && !argv._[1]) return usageExit(topLevelHelp(), 0);
+  if (!domainName) return usageExit(topLevelHelp(), wantHelp ? 0 : 1);
+
+  const domain = domains[domainName];
+  if (!domain) return usageExit(`Unknown domain: ${domainName}\n\n${topLevelHelp()}`, 1);
+
+  const subName = argv._[1];
+  if (subName === 'help') return usageExit(domainHelp(domain), 0);
+  if (!subName) return usageExit(domainHelp(domain), wantHelp ? 0 : 1);
+
+  const sub = domain.subcommands[subName];
+  if (!sub) {
+    if (wantHelp) return usageExit(domainHelp(domain), 0);
+    return usageExit(`Unknown subcommand: ${domainName} ${subName}\n\n${domainHelp(domain)}`, 1);
+  }
+
+  // Pass the full argv through unchanged: subcommands read their own
+  // positionals (e.g. `run soak` dispatches on argv._[2] = start|status|stop)
+  // and handle their own `--help`.
+  const code = await sub.run(argv);
+  return typeof code === 'number' ? code : 0;
+}
+
+main()
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((err) => {
+    console.error(err && err.message ? err.message : String(err));
+    process.exitCode = 1;
+  });
diff --git a/packages/perf-harness/src/load/__tests__/harness.test.ts b/packages/perf-harness/src/load/__tests__/harness.test.ts
new file mode 100644
index 0000000000..41f635b5e2
--- /dev/null
+++ b/packages/perf-harness/src/load/__tests__/harness.test.ts
@@ -0,0 +1,126 @@
+import { DEFAULT_OPS, findTokenSelection, scoreTokenField } from '../harness';
+
+// A minimal introspection type index: Map<typeName, { kind, name, fields }>.
+// `findTokenSelection` follows each field's named type through the index, so
+// every referenced type (scalars included) must be present.
+function buildIndex(types: any[]): Map<string, any> {
+  const index = new Map<string, any>();
+  for (const t of types) index.set(t.name, t);
+  return index;
+}
+
+const STRING = { kind: 'SCALAR', name: 'String' };
+const scalar = (name: string) => ({ name, type: { kind: 'SCALAR', name: 'String' } });
+const object = (name: string, typeName: string) => ({ name, type: { kind: 'OBJECT', name: typeName } });
+
+describe('scoreTokenField', () => {
+  test('accessToken exact match scores highest', () => {
+    expect(scoreTokenField('accessToken')).toBe(4);
+    expect(scoreTokenField('accesstoken')).toBe(4);
+    expect(scoreTokenField('ACCESSTOKEN')).toBe(4);
+  });
+
+  test('contains-accessToken beats plain token beats jwt beats nothing', () => {
+    expect(scoreTokenField('userAccessToken')).toBe(3);
+    expect(scoreTokenField('token')).toBe(2);
+    expect(scoreTokenField('refreshToken')).toBe(2);
+    expect(scoreTokenField('jwt')).toBe(1);
+    expect(scoreTokenField('jwtBlob')).toBe(1);
+    expect(scoreTokenField('id')).toBe(0);
+    expect(scoreTokenField('clientMutationId')).toBe(0);
+  });
+
+  test('strict ordering: accessToken > userAccessToken > token > jwt > other', () => {
+    const s = scoreTokenField;
+    expect(s('accessToken')).toBeGreaterThan(s('userAccessToken'));
+    expect(s('userAccessToken')).toBeGreaterThan(s('token'));
+    expect(s('token')).toBeGreaterThan(s('jwt'));
+    expect(s('jwt')).toBeGreaterThan(s('email'));
+  });
+});
+
+describe('findTokenSelection', () => {
+  test('descends one level into an object field (result { accessToken })', () => {
+    const index = buildIndex([
+      STRING,
+      { kind: 'OBJECT', name: 'SignInResult', fields: [scalar('accessToken')] },
+      { kind: 'OBJECT', name: 'SignInPayload', fields: [scalar('clientMutationId'), object('result', 'SignInResult')] }
+    ]);
+    const sel = findTokenSelection(index, 'SignInPayload');
+    expect(sel).not.toBeNull();
+    expect(sel.selection).toBe('result { accessToken }');
+    expect(sel.path).toEqual(['result', 'accessToken']);
+    expect(sel.score).toBe(4);
+  });
+
+  test('prefers a direct scalar accessToken over a plain token (early return at score>=3)', () => {
+    const index = buildIndex([
+      STRING,
+      { kind: 'OBJECT', name: 'SignInPayloadFlat', fields: [scalar('token'), scalar('accessToken')] }
+    ]);
+    const sel = findTokenSelection(index, 'SignInPayloadFlat');
+    expect(sel.selection).toBe('accessToken');
+    expect(sel.path).toEqual(['accessToken']);
+    expect(sel.score).toBe(4);
+  });
+
+  test('falls back to a nested jwt field when no higher-scoring field exists', () => {
+    const index = buildIndex([
+      STRING,
+      { kind: 'OBJECT', name: 'JwtResult', fields: [scalar('jwt')] },
+      { kind: 'OBJECT', name: 'JwtPayload', fields: [scalar('clientMutationId'), object('result', 'JwtResult')] }
+    ]);
+    const sel = findTokenSelection(index, 'JwtPayload');
+    expect(sel.selection).toBe('result { jwt }');
+    expect(sel.path).toEqual(['result', 'jwt']);
+    expect(sel.score).toBe(1);
+  });
+
+  test('returns null when no token-ish field is present', () => {
+    const index = buildIndex([
+      STRING,
+      { kind: 'OBJECT', name: 'BoringPayload', fields: [scalar('id'), scalar('clientMutationId')] }
+    ]);
+    expect(findTokenSelection(index, 'BoringPayload')).toBeNull();
+  });
+
+  test('returns null when the payload type is not in the index', () => {
+    const index = buildIndex([STRING]);
+    expect(findTokenSelection(index, 'Nonexistent')).toBeNull();
+  });
+});
+
+describe('DEFAULT_OPS', () => {
+  test('has the canonical categories fallback shape', () => {
+    const ops = DEFAULT_OPS();
+    expect(ops.read).toBe('categories');
+    expect(ops.meta).toBe(true);
+    expect(ops.queryType).toBeNull();
+    expect(ops.mutationType).toBeNull();
+    expect(ops.create).toEqual({
+      name: 'createCategory',
+      inputTypeName: 'CreateCategoryInput',
+      innerName: 'category',
+      requiredScalars: [
+        { name: 'name', scalar: 'String', kind: 'SCALAR' },
+        { name: 'slug', scalar: 'String', kind: 'SCALAR' }
+      ],
+      payloadFieldName: 'category',
+      keySelect: 'id'
+    });
+    expect(ops.del).toEqual({ name: 'deleteCategory', inputTypeName: 'DeleteCategoryInput', key: 'id' });
+  });
+
+  test('is a factory — each call returns an independent object the harness can mutate', () => {
+    const a = DEFAULT_OPS();
+    const b = DEFAULT_OPS();
+    expect(a).not.toBe(b);
+    expect(a.create).not.toBe(b.create);
+    // The harness downgrades a tenant by setting ops.read = null after a probe;
+    // that must not bleed into the next fallback.
+    a.read = null;
+    a.create = null;
+    expect(DEFAULT_OPS().read).toBe('categories');
+    expect(DEFAULT_OPS().create).not.toBeNull();
+  });
+});
diff --git a/packages/perf-harness/src/load/churn.ts b/packages/perf-harness/src/load/churn.ts
new file mode 100644
index 0000000000..86bc1683fd
--- /dev/null
+++ b/packages/perf-harness/src/load/churn.ts
@@ -0,0 +1,127 @@
+/**
+ * load/churn — drive schema-cache churn during a soak.
+ *
+ * Every --interval-notify-sec it issues a NOTIFY on channel "schema:update"
+ * (via pg_notify) with a random tenant's databaseId as payload. The server
+ * LISTENs on "schema:update" and flushes that database's cached PostGraphile
+ * instance(s), forcing rebuilds — exercising eviction/drain/build paths.
+ *
+ * A provisioning hook fires every --provision-every-sec but only logs a marker;
+ * actual tenant provisioning is handled separately by the orchestrator.
+ *
+ * Timeline events are emitted as JSON lines to stdout (start | notify |
+ * notify-error | provision-marker | stop).
+ *
+ * Faithful port of `scripts/scale-validate/churn-driver.mjs`. Deviations (all
+ * DESIGN-mandated): a fresh pg Client per NOTIFY comes from `core/pgc`
+ * `withFreshClient`; the PG connection runs through the hub guardrail
+ * (`pgConfigFromArgv`); and the script becomes a `run(argv): Promise<number>`
+ * subcommand — on signal it emits the stop line and returns 0 (natural loop
+ * drain) instead of calling `process.exit(0)`.
+ */
+import { Argv, asBool, asInt } from '../core/args';
+import { pgConfigFromArgv } from '../core/config';
+import { loadFleet } from '../core/fleetfile';
+import { withFreshClient } from '../core/pgc';
+
+const nowIso = (): string => new Date().toISOString();
+
+const HELP = `perf-harness load churn — NOTIFY schema:update churn + provisioning markers
+
+Options:
+  --fleet <file>              fleet manifest (required)
+  --interval-notify-sec <n>   NOTIFY period (default 20; 0 disables)
+  --provision-every-sec <n>   provisioning-marker period (default 0 = off)
+  --duration-sec <n>          run length (default 3600; 0 = until SIGINT)
+  --channel <name>            notify channel (default schema:update)
+  --seed <n>                  RNG seed
+  --pg-* / PG*                connection overrides (pg-port default 5433, never 5432)
+  --allow-hub                 permit a hub PG port (danger)
+  --help
+`;
+
+export async function runChurn(argv: Argv): Promise<number> {
+  if (asBool(argv.help) || !argv.fleet) {
+    process.stderr.write(HELP);
+    return (!argv.fleet && !asBool(argv.help)) ? 1 : 0;
+  }
+
+  try {
+    const intervalNotifySec = asInt(argv['interval-notify-sec'], 20);
+    const provisionEverySec = asInt(argv['provision-every-sec'], 0);
+    const durationSec = asInt(argv['duration-sec'], 3600);
+    const channel = typeof argv.channel === 'string' ? argv.channel : 'schema:update';
+    let seed = asInt(argv.seed, (Date.now() & 0x7fffffff));
+    const { tenants } = loadFleet(argv.fleet);
+    const cfg = pgConfigFromArgv(argv);
+
+    const emit = (obj: any): void => { process.stdout.write(`${JSON.stringify({ at: nowIso(), ...obj })}\n`); };
+    // Same LCG the original used for churn selection — deliberately NOT the core
+    // mulberry32; kept identical so a seeded churn timeline replays byte-for-byte.
+    const rand = (): number => { seed = (seed * 1103515245 + 12345) & 0x7fffffff; return seed / 0x7fffffff; };
+    const pickTenant = () => tenants[Math.floor(rand() * tenants.length)];
+
+    let notifies = 0;
+    let provisions = 0;
+    let failures = 0;
+    const timers: any[] = [];
+
+    emit({ t: 'start', channel, intervalNotifySec, provisionEverySec, durationSec, tenants: tenants.length, pid: process.pid });
+
+    if (intervalNotifySec > 0) {
+      timers.push(setInterval(async () => {
+        const tenant = pickTenant();
+        try {
+          // Fresh connection per query: with long NOTIFY intervals a persistent
+          // client gets reaped by idle_session_timeout (57P05) and its socket
+          // error would kill the driver mid-soak. Hourly connects are free. The
+          // per-client 'error' listener swallows late socket errors on end().
+          await withFreshClient(cfg, (client) => {
+            client.on('error', () => {});
+            return client.query('SELECT pg_notify($1, $2)', [channel, tenant.databaseId]);
+          });
+          notifies++;
+          emit({ t: 'notify', channel, databaseId: tenant.databaseId, dbname: tenant.dbname, seq: notifies });
+        } catch (err: any) {
+          failures++;
+          emit({ t: 'notify-error', databaseId: tenant.databaseId, dbname: tenant.dbname, error: String((err && err.message) || err) });
+        }
+      }, intervalNotifySec * 1000));
+    }
+
+    if (provisionEverySec > 0) {
+      timers.push(setInterval(() => {
+        provisions++;
+        // Provisioning hook — the orchestrator performs the real provision; we
+        // only mark the timeline so churn events can be correlated.
+        emit({ t: 'provision-marker', seq: provisions, note: 'provisioning handled by orchestrator' });
+      }, provisionEverySec * 1000));
+    }
+
+    let resolveDone: (code: number) => void;
+    const done = new Promise<number>((res) => { resolveDone = res; });
+
+    let stopped = false;
+    const stop = (reason: string): void => {
+      if (stopped) return;
+      stopped = true;
+      for (const t of timers) clearInterval(t);
+      emit({ t: 'stop', reason, notifies, provisions, failures });
+      // per-query connections — nothing persistent to close
+    };
+
+    let stopTimer: any = null;
+    if (durationSec > 0) stopTimer = setTimeout(() => { stop('duration'); resolveDone(0); }, durationSec * 1000);
+    const onSig = (): void => { if (stopTimer) clearTimeout(stopTimer); stop('signal'); resolveDone(0); };
+    process.on('SIGINT', onSig);
+    process.on('SIGTERM', onSig);
+
+    const code = await done;
+    process.removeListener('SIGINT', onSig);
+    process.removeListener('SIGTERM', onSig);
+    return code;
+  } catch (err: any) {
+    process.stderr.write(`[churn] FATAL: ${err && err.stack ? err.stack : err}\n`);
+    return 1;
+  }
+}
diff --git a/packages/perf-harness/src/load/harness.ts b/packages/perf-harness/src/load/harness.ts
new file mode 100644
index 0000000000..b819fa9447
--- /dev/null
+++ b/packages/perf-harness/src/load/harness.ts
@@ -0,0 +1,784 @@
+/**
+ * load/harness — workload driver for the scale-validation soak/ramp.
+ *
+ * Generates a token-bucket-paced request stream (open-loop) at a target RPS
+ * across the tenant fleet, with a read/write/meta class mix, tenant-selection
+ * shapes (zipf/uniform/burst), per-tenant auth, a cross-tenant bleed sentinel,
+ * latency histograms, rolling per-interval stdout summaries, and a final JSON
+ * report.
+ *
+ * Faithful port of `scripts/scale-validate/harness.mjs`: every flag, default,
+ * output field, protocol line, and exit code is preserved. Deviations (all
+ * mandated by DESIGN.md) are: creds resolve via `resolveCreds` with NO literal
+ * password default; the server `--port` runs through the hub guardrail; and the
+ * script becomes a `run(argv): Promise<number>` subcommand that returns exit
+ * codes (0 ok / 1 fatal / 2 bleed-sentinel violation) instead of mutating
+ * `process.exitCode` and calling `process.exit`.
+ *
+ * NO server/package code is imported — this only speaks GraphQL over HTTP.
+ */
+import fs from 'node:fs';
+
+import { Argv, asBool, asFloat, asInt } from '../core/args';
+import { assertPortAllowed, resolveCreds } from '../core/config';
+import { CANARY_PREFIX, canaryName, loadFleet, Tenant } from '../core/fleetfile';
+import {
+  buildCreateRecord, buildTypeIndex, DiscoveredOps, discoverOps, gqlErrors, gqlFetch, GqlResponse,
+  INTROSPECTION_QUERY, isRotating, isUnauthenticated, unwrapType
+} from '../core/gql';
+import { Histogram } from '../core/histogram';
+import { ensureParentDir } from '../core/proc';
+import { makeMixSampler, makeRng, makeZipfSampler } from '../core/rng';
+
+// Tiny helpers that lived inline in `_lib.mjs` and are not part of the core
+// signature surface — kept local to the load domain.
+const nowIso = (): string => new Date().toISOString();
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+const round2 = (n: number): number => Math.round(n * 100) / 100;
+
+const HELP = `perf-harness load harness — workload driver (soaks + ramps) against the running cnc server
+
+Required:
+  --fleet <file>              fleet manifest from \`fleet discover\`
+Common:
+  --port <n>                  server port (default 3333)
+  --duration-sec <n>          run length (default 60)
+  --rps <n>                   target requests/sec (default 20)
+  --mix read:.7,write:.25,meta:.05   class mix (default that)
+  --shape zipf|uniform|burst  tenant selection (default zipf)
+  --auth 0|1                  authenticate reads/writes (default 1)
+  --sentinel-interval-sec <n> bleed sentinel period (default 60)
+  --out <file>                final JSON report (default results.json)
+Tuning:
+  --report-sec <n>            rolling summary interval (default 60)
+  --burst-window-sec <n>      burst shape focus window (default 30)
+  --relogin-sec <n>           token refresh period (default 3600)
+  --timeout-ms <n>            per-request timeout (default 30000)
+  --max-inflight <n>          concurrency cap (default max(64, rps*2))
+  --rotate-backoff-ms <n>     503 retry backoff (default 250)
+  --email <addr>              seeder email (default seeder@gmail.com)
+  --password <pw>             seeder password (or PERF_PASSWORD env; required when --auth 1)
+  --seed <n>                  RNG seed for reproducible selection
+  --allow-hub                 permit a hub port for --port (danger)
+  --quiet                     suppress per-minute lines (still written to --out)
+  --help
+
+Leaked LOAD- rows (only on delete failure) are reported as write.leaked; clean
+with: DELETE FROM "<schema>".categories WHERE name LIKE 'LOAD-%';
+`;
+
+// ---------------------------------------------------------------------------
+// Auth token-field scoring (pure — exported for unit tests)
+// ---------------------------------------------------------------------------
+export function scoreTokenField(name: string): number {
+  if (/^accesstoken$/i.test(name)) return 4;
+  if (/accesstoken/i.test(name)) return 3;
+  if (/token/i.test(name)) return 2;
+  if (/jwt/i.test(name)) return 1;
+  return 0;
+}
+
+export interface TokenSelection {
+  selection: string;
+  path: string[];
+  score: number;
+}
+
+// Given a built type index and a payload type name, find the best token field to
+// select out of a signIn mutation payload. Prefers a direct scalar
+// `accessToken` (score >= 3); otherwise descends one level into object fields
+// (e.g. `result { accessToken }`).
+export function findTokenSelection(index: Map<string, any>, payloadTypeName: string): TokenSelection | null {
+  const pt = index.get(payloadTypeName);
+  if (!pt) return null;
+  let best: TokenSelection | null = null;
+  const consider = (selection: string, path: string[], score: number): void => {
+    if (score > 0 && (!best || score > best.score)) best = { selection, path, score };
+  };
+  for (const f of (pt.fields || [])) {
+    const nt = index.get(unwrapType(f.type).name);
+    if (nt && nt.kind === 'SCALAR') consider(f.name, [f.name], scoreTokenField(f.name));
+  }
+  if (best && best.score >= 3) return best;
+  for (const f of (pt.fields || [])) {
+    const nt = index.get(unwrapType(f.type).name);
+    if (nt && nt.kind === 'OBJECT') {
+      for (const sf of (nt.fields || [])) {
+        const st = index.get(unwrapType(sf.type).name);
+        if (st && st.kind === 'SCALAR') consider(`${f.name} { ${sf.name} }`, [f.name, sf.name], scoreTokenField(sf.name));
+      }
+    }
+  }
+  return best;
+}
+
+// ---------------------------------------------------------------------------
+// Startup capability fallback (pure — exported for unit tests)
+// ---------------------------------------------------------------------------
+// Used when a tenant's introspection fails: assume the canonical `categories`
+// shape so the tenant still exercises its PostGraphile instance. `queryType`/
+// `mutationType` are null because there is no schema to derive them from.
+export const DEFAULT_OPS = (): DiscoveredOps => ({
+  queryType: null,
+  mutationType: null,
+  read: 'categories',
+  meta: true,
+  create: {
+    name: 'createCategory',
+    inputTypeName: 'CreateCategoryInput',
+    innerName: 'category',
+    requiredScalars: [
+      { name: 'name', scalar: 'String', kind: 'SCALAR' },
+      { name: 'slug', scalar: 'String', kind: 'SCALAR' }
+    ],
+    payloadFieldName: 'category',
+    keySelect: 'id'
+  },
+  del: { name: 'deleteCategory', inputTypeName: 'DeleteCategoryInput', key: 'id' }
+});
+
+const isValidationAbsent = (resp: GqlResponse): boolean =>
+  gqlErrors(resp).some((e) =>
+    /cannot query field|unknown field|unknown argument|unknown type|does not exist on type|not defined|no field/i.test((e && e.message) || '')
+  );
+
+const getByPath = (obj: any, path: string[]): any => {
+  let cur = obj;
+  for (const k of path) { if (cur == null) return null; cur = cur[k]; }
+  return cur == null ? null : cur;
+};
+
+interface RuntimeTenant {
+  tenant: Tenant;
+  ops: DiscoveredOps;
+  token: string | null;
+  tokenAt: number;
+  reloginInFlight: boolean;
+  authError: string | null;
+  introspectError: string | null;
+  leakedKeys: any[];
+}
+
+interface AuthShape {
+  field: string;
+  query: string;
+  path: string[];
+  selection: string;
+}
+
+// ---------------------------------------------------------------------------
+// Subcommand entry point
+// ---------------------------------------------------------------------------
+export async function runHarness(argv: Argv): Promise<number> {
+  if (asBool(argv.help) || !argv.fleet) {
+    process.stderr.write(HELP);
+    return (!argv.fleet && !asBool(argv.help)) ? 1 : 0;
+  }
+
+  // -------------------------------------------------------------------------
+  // Config
+  // -------------------------------------------------------------------------
+  const PORT = asInt(argv.port, 3333);
+  assertPortAllowed(PORT, asBool(argv['allow-hub']), 'port');
+  const DURATION_SEC = asInt(argv['duration-sec'], 60);
+  const RPS = Math.max(asFloat(argv.rps, 20), 0.1);
+  const MIX = typeof argv.mix === 'string' ? argv.mix : 'read:0.7,write:0.25,meta:0.05';
+  const SHAPE = ['zipf', 'uniform', 'burst'].includes(argv.shape) ? argv.shape : 'zipf';
+  const AUTH = asBool(argv.auth, true);
+  const SENTINEL_SEC = asInt(argv['sentinel-interval-sec'], 60);
+  const OUT = typeof argv.out === 'string' ? argv.out : 'results.json';
+  const REPORT_SEC = asInt(argv['report-sec'], 60);
+  const BURST_WINDOW_SEC = asInt(argv['burst-window-sec'], 30);
+  const RELOGIN_SEC = asInt(argv['relogin-sec'], 3600);
+  const TIMEOUT_MS = asInt(argv['timeout-ms'], 30000);
+  const MAX_INFLIGHT = asInt(argv['max-inflight'], Math.max(64, Math.ceil(RPS * 2)));
+  const ROTATE_BACKOFF_MS = asInt(argv['rotate-backoff-ms'], 250);
+  const SEED = asInt(argv.seed, (Date.now() & 0x7fffffff));
+  const QUIET = asBool(argv.quiet);
+
+  // Credentials: NO literal password default (DESIGN creds rule). Resolve via
+  // flag > PERF_PASSWORD and fail with guidance when auth is on but absent.
+  const { email: EMAIL, password: PASSWORD } = resolveCreds(argv);
+  if (AUTH && !PASSWORD) {
+    process.stderr.write(
+      '[harness] --auth 1 but no password provided. Pass --password <pw> or set PERF_PASSWORD ' +
+        '(or run with --auth 0 to skip authentication).\n'
+    );
+    return 1;
+  }
+
+  const rng = makeRng(SEED);
+  const { tenants } = loadFleet(argv.fleet);
+
+  // -------------------------------------------------------------------------
+  // Metrics
+  // -------------------------------------------------------------------------
+  const M: any = {
+    startedAt: nowIso(),
+    config: {
+      port: PORT, durationSec: DURATION_SEC, rps: RPS, mix: MIX, shape: SHAPE, auth: AUTH,
+      sentinelIntervalSec: SENTINEL_SEC, reportSec: REPORT_SEC, burstWindowSec: BURST_WINDOW_SEC,
+      reloginSec: RELOGIN_SEC, timeoutMs: TIMEOUT_MS, maxInflight: MAX_INFLIGHT, seed: SEED,
+      fleetCount: tenants.length
+    },
+    totals: { sent: 0, completed: 0, ok: 0, err: 0, requests: 0, dropped: 0, rotating: 0, rotatingRetried: 0, timeouts: 0, network: 0 },
+    http: {},
+    netErrors: {},
+    gqlByCode: {},
+    gqlByMsg: {},
+    gqlMsgOverflow: 0,
+    classes: {
+      read: { sent: 0, ok: 0, err: 0, unavailable: 0, hist: new Histogram() },
+      write: { sent: 0, ok: 0, err: 0, unavailable: 0, fallbackRead: 0, created: 0, deleted: 0, leaked: 0, createErr: 0, deleteErr: 0, hist: new Histogram() },
+      meta: { sent: 0, ok: 0, err: 0, unavailable: 0, hist: new Histogram() }
+    },
+    overallHist: new Histogram(),
+    perTenant: {},
+    auth: { enabled: AUTH, shape: null, logins: 0, loginFailures: 0, relogins: 0, unauth: 0 },
+    sentinel: { checks: 0, tenantsChecked: 0, ownCanarySeen: 0, inconclusive: 0, violations: [], ok: true },
+    progress: []
+  };
+  for (const t of tenants) M.perTenant[t.dbname] = { sent: 0, ok: 0, err: 0 };
+
+  let windowHist = new Histogram();
+  const startMs = Date.now();
+  let pacingStartMs = 0;
+  let inFlight = 0;
+  let stopping = false;
+  let stopReason: string | null = null;
+  let exitCode = 0;
+
+  // -------------------------------------------------------------------------
+  // Runtime tenant state
+  // -------------------------------------------------------------------------
+  const runtime: RuntimeTenant[] = tenants.map((tenant): RuntimeTenant => ({
+    tenant,
+    ops: { queryType: null, mutationType: null, read: null, meta: false, create: null, del: null },
+    token: null,
+    tokenAt: 0,
+    reloginInFlight: false,
+    authError: null,
+    introspectError: null,
+    leakedKeys: []
+  }));
+
+  let writeCounter = 0;
+  const randId = (): string => `${(SEED & 0xffff).toString(36)}-${(writeCounter++).toString(36)}-${Math.floor(rng() * 1e9).toString(36)}`;
+  const log = (...a: any[]): void => { if (!QUIET) process.stderr.write(`${a.join(' ')}\n`); };
+  const emit = (obj: any): void => { process.stdout.write(`${JSON.stringify(obj)}\n`); };
+
+  // -------------------------------------------------------------------------
+  // HTTP request with retry-once on 503 SERVICE_ROTATING
+  // -------------------------------------------------------------------------
+  async function apiRequest(s: RuntimeTenant, opts: { query: string; variables?: any; token?: string }): Promise<GqlResponse> {
+    let resp = await gqlFetch({ host: s.tenant.apiHost, port: PORT, query: opts.query, variables: opts.variables, token: opts.token, timeoutMs: TIMEOUT_MS });
+    if (isRotating(resp)) {
+      M.totals.rotating++;
+      await sleep(ROTATE_BACKOFF_MS);
+      resp = await gqlFetch({ host: s.tenant.apiHost, port: PORT, query: opts.query, variables: opts.variables, token: opts.token, timeoutMs: TIMEOUT_MS });
+      M.totals.rotatingRetried++;
+    }
+    return resp;
+  }
+
+  function trackHttp(resp: GqlResponse, cls: string): void {
+    M.totals.requests++;
+    M.overallHist.record(resp.elapsedMs);
+    windowHist.record(resp.elapsedMs);
+    M.classes[cls].hist.record(resp.elapsedMs);
+    const key = String(resp.status);
+    M.http[key] = (M.http[key] || 0) + 1;
+    if (resp.error === 'timeout') M.totals.timeouts++;
+    else if (resp.error) { M.totals.network++; M.netErrors[resp.error] = (M.netErrors[resp.error] || 0) + 1; }
+    for (const e of gqlErrors(resp)) {
+      const code = (e.extensions && e.extensions.code) || 'GRAPHQL_ERROR';
+      M.gqlByCode[code] = (M.gqlByCode[code] || 0) + 1;
+      const msg = String((e && e.message) || '').slice(0, 200);
+      // Cap distinct-message cardinality so a 24h soak with id-bearing messages
+      // cannot grow this map without bound.
+      if (M.gqlByMsg[msg] !== undefined || Object.keys(M.gqlByMsg).length < 1000) {
+        M.gqlByMsg[msg] = (M.gqlByMsg[msg] || 0) + 1;
+      } else {
+        M.gqlMsgOverflow++;
+      }
+    }
+  }
+
+  function bumpTenant(s: RuntimeTenant, kind: string): void { const p = M.perTenant[s.tenant.dbname]; if (p) p[kind]++; }
+
+  function maybeRelogin(s: RuntimeTenant, resp: GqlResponse): void {
+    if (!AUTH) return;
+    if (isUnauthenticated(resp)) { M.auth.unauth++; scheduleRelogin(s); }
+  }
+
+  // -------------------------------------------------------------------------
+  // Op executors — each returns { ok } or { skip:true }; runOp folds into totals.
+  // -------------------------------------------------------------------------
+  async function execRead(s: RuntimeTenant): Promise<any> {
+    const r = M.classes.read;
+    r.sent++;
+    const resp = await apiRequest(s, { query: `{ ${s.ops.read} { totalCount nodes { name } } }`, token: s.token });
+    trackHttp(resp, 'read');
+    maybeRelogin(s, resp);
+    const ok = resp.ok && gqlErrors(resp).length === 0 && !resp.error;
+    if (ok) r.ok++; else r.err++;
+    bumpTenant(s, ok ? 'ok' : 'err');
+    return { ok };
+  }
+
+  async function execMeta(s: RuntimeTenant): Promise<any> {
+    const m = M.classes.meta;
+    m.sent++;
+    const resp = await apiRequest(s, { query: '{ _meta { tables { name } } }' });
+    trackHttp(resp, 'meta');
+    const ok = resp.ok && gqlErrors(resp).length === 0 && !resp.error;
+    if (ok) m.ok++; else m.err++;
+    bumpTenant(s, ok ? 'ok' : 'err');
+    return { ok };
+  }
+
+  function createQuery(c: any): string {
+    return `mutation Create($input: ${c.inputTypeName}!) { ${c.name}(input: $input) { ${c.payloadFieldName} { ${c.keySelect} } } }`;
+  }
+  function deleteQuery(d: any): string {
+    return `mutation Del($input: ${d.inputTypeName}!) { ${d.name}(input: $input) { clientMutationId } }`;
+  }
+
+  async function execWrite(s: RuntimeTenant): Promise<any> {
+    const w = M.classes.write;
+    w.sent++;
+    const rand = randId();
+    const record = buildCreateRecord(s.ops.create, `LOAD-${rand}`, rand);
+    const cResp = await apiRequest(s, {
+      query: createQuery(s.ops.create),
+      variables: { input: { [s.ops.create.innerName]: record } },
+      token: s.token
+    });
+    trackHttp(cResp, 'write');
+    maybeRelogin(s, cResp);
+    const cOk = cResp.ok && gqlErrors(cResp).length === 0 && !cResp.error;
+    if (!cOk) { w.createErr++; w.err++; bumpTenant(s, 'err'); return { ok: false }; }
+    w.created++;
+    const payload = cResp.json && cResp.json.data && cResp.json.data[s.ops.create.name];
+    const rec = payload && payload[s.ops.create.payloadFieldName];
+    const keyVal = rec && rec[s.ops.create.keySelect];
+    if (keyVal == null) { w.err++; w.leaked++; bumpTenant(s, 'err'); return { ok: false }; }
+    const dResp = await apiRequest(s, {
+      query: deleteQuery(s.ops.del),
+      variables: { input: { [s.ops.del.key]: keyVal } },
+      token: s.token
+    });
+    trackHttp(dResp, 'write');
+    maybeRelogin(s, dResp);
+    const dOk = dResp.ok && gqlErrors(dResp).length === 0 && !dResp.error;
+    if (dOk) { w.deleted++; w.ok++; bumpTenant(s, 'ok'); return { ok: true }; }
+    w.deleteErr++; w.leaked++; w.err++;
+    if (s.leakedKeys.length < 200) s.leakedKeys.push(keyVal);
+    bumpTenant(s, 'err');
+    return { ok: false };
+  }
+
+  // Substitution keeps a tenant's PostGraphile instance under load even when a
+  // class is unavailable for it (e.g. the blank tenant with no categories table).
+  function canWrite(s: RuntimeTenant): boolean { return !!(s.ops.create && s.ops.del && s.ops.create.payloadFieldName); }
+
+  async function opRead(s: RuntimeTenant): Promise<any> {
+    if (s.ops.read) return execRead(s);
+    M.classes.read.unavailable++;
+    if (s.ops.meta) return execMeta(s);
+    return { skip: true };
+  }
+  async function opMeta(s: RuntimeTenant): Promise<any> {
+    if (s.ops.meta) return execMeta(s);
+    M.classes.meta.unavailable++;
+    if (s.ops.read) return execRead(s);
+    return { skip: true };
+  }
+  async function opWrite(s: RuntimeTenant): Promise<any> {
+    if (canWrite(s)) return execWrite(s);
+    M.classes.write.unavailable++;
+    if (s.ops.read) { M.classes.write.fallbackRead++; return execRead(s); }
+    if (s.ops.meta) { M.classes.write.fallbackRead++; return execMeta(s); }
+    return { skip: true };
+  }
+
+  async function runOp(cls: string, s: RuntimeTenant): Promise<void> {
+    M.perTenant[s.tenant.dbname].sent++;
+    let res;
+    if (cls === 'read') res = await opRead(s);
+    else if (cls === 'write') res = await opWrite(s);
+    else res = await opMeta(s);
+    if (res && res.skip) return;
+    if (res && res.ok) M.totals.ok++; else M.totals.err++;
+  }
+
+  // -------------------------------------------------------------------------
+  // Auth
+  // -------------------------------------------------------------------------
+  async function resolveAuthShape(): Promise<AuthShape> {
+    for (const s of runtime) {
+      if (!s.tenant.authHost) continue;
+      const resp = await gqlFetch({ host: s.tenant.authHost, port: PORT, query: INTROSPECTION_QUERY, timeoutMs: TIMEOUT_MS });
+      const data = resp.json && resp.json.data;
+      if (!data || !data.__schema) continue;
+      const { index, mutationType } = buildTypeIndex(data);
+      if (!mutationType) continue;
+      const mt = index.get(mutationType);
+      const field = (mt.fields || []).find((f: any) => /^signin$/i.test(f.name)) || (mt.fields || []).find((f: any) => /signin/i.test(f.name));
+      if (!field) continue;
+      const tokenSel = findTokenSelection(index, unwrapType(field.type).name);
+      if (!tokenSel) continue;
+      const query = `mutation SignIn($email: String!, $password: String!) { ${field.name}(input: { email: $email, password: $password }) { ${tokenSel.selection} } }`;
+      return { field: field.name, query, path: [field.name, ...tokenSel.path], selection: tokenSel.selection };
+    }
+    // Fallback: documented shape.
+    return {
+      field: 'signIn',
+      query: 'mutation SignIn($email: String!, $password: String!) { signIn(input: { email: $email, password: $password }) { result { accessToken } } }',
+      path: ['signIn', 'result', 'accessToken'],
+      selection: 'result { accessToken }'
+    };
+  }
+
+  let authShape: AuthShape | null = null;
+  async function loginTenant(s: RuntimeTenant, initial: boolean): Promise<boolean> {
+    if (!authShape || !s.tenant.authHost) return false;
+    const resp = await gqlFetch({ host: s.tenant.authHost, port: PORT, query: authShape.query, variables: { email: EMAIL, password: PASSWORD }, timeoutMs: TIMEOUT_MS });
+    const errs = gqlErrors(resp);
+    if (!resp.ok || errs.length || resp.error) {
+      M.auth.loginFailures++;
+      s.authError = (errs[0] && errs[0].message) || resp.error || `http ${resp.status}`;
+      return false;
+    }
+    const tok = getByPath(resp.json && resp.json.data, authShape.path);
+    if (!tok || typeof tok !== 'string') { M.auth.loginFailures++; s.authError = 'no token in signIn response'; return false; }
+    s.token = tok;
+    s.tokenAt = Date.now();
+    s.authError = null;
+    if (initial) M.auth.logins++; else M.auth.relogins++;
+    return true;
+  }
+
+  function scheduleRelogin(s: RuntimeTenant): void {
+    if (s.reloginInFlight) return;
+    s.reloginInFlight = true;
+    loginTenant(s, false).catch(() => {}).finally(() => { s.reloginInFlight = false; });
+  }
+
+  // -------------------------------------------------------------------------
+  // Startup capability discovery (introspection + probe verification)
+  // -------------------------------------------------------------------------
+  async function resolveTenantOps(s: RuntimeTenant): Promise<void> {
+    const resp = await apiRequest(s, { query: INTROSPECTION_QUERY });
+    const data = resp.json && resp.json.data;
+    if (data && data.__schema) {
+      s.ops = discoverOps(data);
+    } else {
+      s.introspectError = (gqlErrors(resp)[0] && gqlErrors(resp)[0].message) || resp.error || `http ${resp.status}`;
+      s.ops = DEFAULT_OPS();
+    }
+    // Probe read presence (schema-level) with token so RLS doesn't mask absence.
+    if (s.ops.read) {
+      const pr = await apiRequest(s, { query: `{ ${s.ops.read} { totalCount } }`, token: s.token });
+      if (isValidationAbsent(pr)) s.ops.read = null;
+    }
+    if (s.ops.meta) {
+      const pm = await apiRequest(s, { query: '{ _meta { tables { name } } }' });
+      if (isValidationAbsent(pm)) s.ops.meta = false;
+    }
+    // Probe write: attempt a real create+delete once; downgrade only on schema absence.
+    if (canWrite(s)) {
+      const rand = `probe-${randId()}`;
+      const record = buildCreateRecord(s.ops.create, `LOAD-${rand}`, rand);
+      const cr = await apiRequest(s, { query: createQuery(s.ops.create), variables: { input: { [s.ops.create.innerName]: record } }, token: s.token });
+      if (isValidationAbsent(cr)) {
+        s.ops.create = null;
+        s.ops.del = null;
+      } else {
+        const payload = cr.json && cr.json.data && cr.json.data[s.ops.create.name];
+        const rec = payload && payload[s.ops.create.payloadFieldName];
+        const keyVal = rec && rec[s.ops.create.keySelect];
+        if (keyVal != null) {
+          await apiRequest(s, { query: deleteQuery(s.ops.del), variables: { input: { [s.ops.del.key]: keyVal } }, token: s.token });
+        }
+      }
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Bleed sentinel
+  // -------------------------------------------------------------------------
+  function pickTwo<T>(arr: T[]): T[] {
+    if (arr.length <= 1) return arr.slice();
+    const i = Math.floor(rng() * arr.length);
+    let j = Math.floor(rng() * arr.length);
+    if (j === i) j = (j + 1) % arr.length;
+    return [arr[i], arr[j]];
+  }
+
+  async function runSentinel(): Promise<void> {
+    if (stopping) return;
+    M.sentinel.checks++;
+    const eligible = runtime.filter((s) => s.ops.read && (!AUTH || s.token));
+    if (eligible.length === 0) { M.sentinel.inconclusive++; return; }
+    const picks = pickTwo(eligible);
+    for (const s of picks) {
+      M.sentinel.tenantsChecked++;
+      const resp = await apiRequest(s, { query: `{ ${s.ops.read} { nodes { name } } }`, token: s.token });
+      if (!resp.ok || gqlErrors(resp).length || resp.error) { M.sentinel.inconclusive++; continue; }
+      const nodes = (((resp.json || {}).data || {})[s.ops.read] || {}).nodes || [];
+      const own = canaryName(s.tenant);
+      let sawOwn = false;
+      for (const node of nodes) {
+        const nm = node && node.name;
+        if (typeof nm !== 'string') continue;
+        if (nm === own) { sawOwn = true; continue; }
+        if (nm.startsWith(CANARY_PREFIX)) {
+          M.sentinel.ok = false;
+          M.sentinel.violations.push({
+            at: nowIso(),
+            readTenant: s.tenant.dbname,
+            readHost: s.tenant.apiHost,
+            foreignCanary: nm,
+            sampleNames: nodes.map((n: any) => n && n.name).filter(Boolean).slice(0, 50)
+          });
+        }
+      }
+      if (sawOwn) M.sentinel.ownCanarySeen++;
+    }
+    if (!M.sentinel.ok) {
+      exitCode = 2;
+      finish('sentinel-violation');
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Pacer (token bucket) + worker pool
+  // -------------------------------------------------------------------------
+  const zipfSampler = SHAPE === 'zipf' ? makeZipfSampler(runtime.length, rng) : null;
+  let burstIndex = Math.floor(rng() * runtime.length);
+  let burstUntil = Date.now() + BURST_WINDOW_SEC * 1000;
+
+  function pickTenant(): RuntimeTenant {
+    if (SHAPE === 'uniform') return runtime[Math.floor(rng() * runtime.length)];
+    if (SHAPE === 'burst') {
+      if (Date.now() >= burstUntil) {
+        burstIndex = Math.floor(rng() * runtime.length);
+        burstUntil = Date.now() + BURST_WINDOW_SEC * 1000;
+      }
+      return runtime[burstIndex];
+    }
+    return runtime[zipfSampler()];
+  }
+
+  const mixSampler = makeMixSampler(MIX, rng);
+
+  let tokens = 0;
+  const capacity = Math.max(RPS, 1);
+  const tickMs = 20;
+  const refillPerTick = RPS * (tickMs / 1000);
+
+  function launchOne(): void {
+    inFlight++;
+    M.totals.sent++;
+    const s = pickTenant();
+    const cls = mixSampler();
+    runOp(cls, s).catch(() => {}).finally(() => {
+      inFlight--;
+      M.totals.completed++;
+      pump();
+    });
+  }
+
+  function pump(): void {
+    while (!stopping && tokens >= 1 && inFlight < MAX_INFLIGHT) {
+      tokens -= 1;
+      launchOne();
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Rolling per-interval reporter
+  // -------------------------------------------------------------------------
+  let snap = { t: startMs, completed: 0, ok: 0, err: 0 };
+  function report(kind: string): void {
+    const nowT = Date.now();
+    const elapsedSec = (nowT - startMs) / 1000;
+    const winSec = Math.max((nowT - snap.t) / 1000, 0.001);
+    const dc = M.totals.completed - snap.completed;
+    const der = M.totals.err - snap.err;
+    const line = {
+      t: kind,
+      at: nowIso(),
+      elapsedSec: round2(elapsedSec),
+      windowSec: round2(winSec),
+      sent: M.totals.sent,
+      completed: M.totals.completed,
+      ok: M.totals.ok,
+      err: M.totals.err,
+      windowRps: round2(dc / winSec),
+      cumRps: round2(M.totals.completed / Math.max(elapsedSec, 0.001)),
+      windowErrRate: dc ? round2(der / dc) : 0,
+      inFlight,
+      dropped: Math.round(M.totals.dropped),
+      rotating: M.totals.rotating,
+      latencyWindow: windowHist.summary(),
+      sentinelChecks: M.sentinel.checks,
+      sentinelOwnSeen: M.sentinel.ownCanarySeen,
+      sentinelOk: M.sentinel.ok
+    };
+    emit(line);
+    M.progress.push(line);
+    snap = { t: nowT, completed: M.totals.completed, ok: M.totals.ok, err: M.totals.err };
+    windowHist = new Histogram();
+  }
+
+  // -------------------------------------------------------------------------
+  // Lifecycle
+  // -------------------------------------------------------------------------
+  let timers: any[] = [];
+  let durationTimer: any = null;
+  let donePromiseResolve: (value?: void | PromiseLike<void>) => void;
+  const donePromise = new Promise<void>((res) => { donePromiseResolve = res; });
+
+  function finish(reason: string): void {
+    if (stopping) return;
+    stopping = true;
+    stopReason = reason;
+    for (const t of timers) clearInterval(t);
+    timers = [];
+    if (durationTimer) { clearTimeout(durationTimer); durationTimer = null; }
+    donePromiseResolve();
+  }
+
+  async function drain(): Promise<void> {
+    const deadline = Date.now() + 15000;
+    while (inFlight > 0 && Date.now() < deadline) await sleep(50);
+  }
+
+  function finalize(): any {
+    const endMs = Date.now();
+    const wallSec = (endMs - startMs) / 1000;
+    const loadSec = (endMs - (pacingStartMs || startMs)) / 1000;
+    const topN = (obj: any, n = 20): any[] => Object.entries(obj).sort((a: any, b: any) => b[1] - a[1]).slice(0, n).map(([k, v]) => ({ key: k, count: v }));
+    const classSummary = (c: any): any => {
+      const base = { sent: c.sent, ok: c.ok, err: c.err, unavailable: c.unavailable, latency: c.hist.summary() };
+      if (c === M.classes.write) {
+        return { ...base, created: c.created, deleted: c.deleted, leaked: c.leaked, createErr: c.createErr, deleteErr: c.deleteErr, fallbackRead: c.fallbackRead };
+      }
+      return base;
+    };
+    const out = {
+      startedAt: M.startedAt,
+      endedAt: nowIso(),
+      wallSec: round2(wallSec),
+      loadSec: round2(loadSec),
+      stopReason,
+      config: M.config,
+      fleet: { count: tenants.length, file: argv.fleet },
+      capabilities: runtime.map((s) => ({
+        dbname: s.tenant.dbname,
+        apiHost: s.tenant.apiHost,
+        read: !!s.ops.read,
+        write: canWrite(s),
+        meta: !!s.ops.meta,
+        authed: !!s.token,
+        authError: s.authError,
+        introspectError: s.introspectError,
+        leakedKeys: s.leakedKeys.length
+      })),
+      totals: {
+        ...M.totals,
+        dropped: Math.round(M.totals.dropped),
+        achievedRps: round2(M.totals.completed / Math.max(loadSec, 0.001)),
+        errRate: M.totals.completed ? round2(M.totals.err / M.totals.completed) : 0
+      },
+      latencyOverall: M.overallHist.summary(),
+      byClass: { read: classSummary(M.classes.read), write: classSummary(M.classes.write), meta: classSummary(M.classes.meta) },
+      http: M.http,
+      netErrors: M.netErrors,
+      gqlErrorsByCode: M.gqlByCode,
+      gqlErrorsTop: topN(M.gqlByMsg),
+      gqlErrorsMsgOverflow: M.gqlMsgOverflow,
+      perTenant: M.perTenant,
+      auth: M.auth,
+      sentinel: M.sentinel,
+      progress: M.progress,
+      verdict: {
+        pass: M.sentinel.ok,
+        bleedViolations: M.sentinel.violations.length,
+        note: M.sentinel.ok ? 'no cross-tenant bleed detected' : 'BLEED SENTINEL VIOLATION'
+      }
+    };
+    ensureParentDir(OUT);
+    fs.writeFileSync(OUT, `${JSON.stringify(out, null, 2)}\n`);
+    return out;
+  }
+
+  // -------------------------------------------------------------------------
+  // Main
+  // -------------------------------------------------------------------------
+  const onSig = (): void => finish('signal');
+  const cleanup = (): void => {
+    for (const t of timers) clearInterval(t);
+    timers = [];
+    if (durationTimer) { clearTimeout(durationTimer); durationTimer = null; }
+    process.removeListener('SIGINT', onSig);
+    process.removeListener('SIGTERM', onSig);
+  };
+
+  try {
+    log(`[harness] seed=${SEED} shape=${SHAPE} rps=${RPS} dur=${DURATION_SEC}s mix=${MIX} auth=${AUTH} tenants=${tenants.length} -> ${OUT}`);
+
+    if (AUTH) {
+      authShape = await resolveAuthShape();
+      M.auth.shape = authShape.selection;
+      log(`[harness] auth shape: ${authShape.field} { ${authShape.selection} }`);
+      await Promise.all(runtime.map((s) => loginTenant(s, true)));
+      log(`[harness] logins ok=${M.auth.logins} failed=${M.auth.loginFailures}`);
+    }
+
+    await Promise.all(runtime.map((s) => resolveTenantOps(s).catch((e) => { s.introspectError = String((e && e.message) || e); })));
+    const caps = runtime.map((s) => `${s.tenant.dbname.replace('marketplace_db_', '')}[r=${s.ops.read ? 1 : 0}w=${canWrite(s) ? 1 : 0}m=${s.ops.meta ? 1 : 0}${s.token ? 'a' : ''}]`);
+    log(`[harness] capabilities: ${caps.join(' ')}`);
+
+    // Timers
+    pacingStartMs = Date.now();
+    snap = { t: pacingStartMs, completed: 0, ok: 0, err: 0 };
+    timers.push(setInterval(() => {
+      if (stopping) return;
+      tokens += refillPerTick;
+      if (tokens > capacity) { M.totals.dropped += (tokens - capacity); tokens = capacity; }
+      pump();
+    }, tickMs));
+    timers.push(setInterval(() => report('progress'), REPORT_SEC * 1000));
+    timers.push(setInterval(() => { runSentinel().catch(() => {}); }, SENTINEL_SEC * 1000));
+    timers.push(setInterval(() => {
+      if (!AUTH) return;
+      const cutoff = Date.now() - RELOGIN_SEC * 1000;
+      for (const s of runtime) if (s.token && s.tokenAt < cutoff) scheduleRelogin(s);
+    }, 30000));
+
+    durationTimer = setTimeout(() => finish('duration'), DURATION_SEC * 1000);
+    process.on('SIGINT', onSig);
+    process.on('SIGTERM', onSig);
+
+    await donePromise;
+    await drain();
+    const out = finalize();
+
+    const c = out.byClass;
+    log(`[harness] DONE reason=${stopReason} wall=${out.wallSec}s load=${out.loadSec}s completed=${out.totals.completed} ok=${out.totals.ok} err=${out.totals.err} achievedRps=${out.totals.achievedRps} p50=${out.latencyOverall.p50} p95=${out.latencyOverall.p95} p99=${out.latencyOverall.p99}`);
+    log(`[harness] read ${c.read.ok}/${c.read.err} write ${c.write.ok}/${c.write.err}(created=${c.write.created} leaked=${c.write.leaked}) meta ${c.meta.ok}/${c.meta.err} | sentinel checks=${M.sentinel.checks} ownSeen=${M.sentinel.ownCanarySeen} violations=${M.sentinel.violations.length}`);
+    log(`[harness] wrote ${OUT}`);
+    if (!M.sentinel.ok) log('[harness] *** BLEED SENTINEL VIOLATION — exit 2 ***');
+
+    cleanup();
+    return exitCode;
+  } catch (err: any) {
+    process.stderr.write(`[harness] FATAL: ${err && err.stack ? err.stack : err}\n`);
+    try { finalize(); } catch { /* best effort */ }
+    cleanup();
+    return exitCode || 1;
+  }
+}
diff --git a/packages/perf-harness/src/measure/__tests__/collector.test.ts b/packages/perf-harness/src/measure/__tests__/collector.test.ts
new file mode 100644
index 0000000000..ba3819bd1a
--- /dev/null
+++ b/packages/perf-harness/src/measure/__tests__/collector.test.ts
@@ -0,0 +1,115 @@
+import { flattenNumeric, linregSlope, pickCounter } from '../collector';
+
+describe('linregSlope', () => {
+  test('perfect line through the origin recovers the slope', () => {
+    expect(linregSlope([[0, 0], [1, 2], [2, 4], [3, 6]])).toBeCloseTo(2, 10);
+  });
+
+  test('fractional slope', () => {
+    expect(linregSlope([[0, 1], [2, 2]])).toBeCloseTo(0.5, 10);
+  });
+
+  test('flat series has zero slope', () => {
+    expect(linregSlope([[0, 5], [1, 5], [2, 5]])).toBe(0);
+  });
+
+  test('fewer than two points returns 0', () => {
+    expect(linregSlope([])).toBe(0);
+    expect(linregSlope([[3, 3]])).toBe(0);
+  });
+
+  test('degenerate x (zero denominator) returns 0', () => {
+    expect(linregSlope([[5, 1], [5, 9]])).toBe(0);
+  });
+
+  test('last-half behavior: slope tracks only the recent (second-half) trend', () => {
+    // First half flat at 500, second half rising +10 MB/sec. finalize() regresses
+    // over samples.slice(floor(len/2)) — the last half — so the reported slope is
+    // the recent trend, not the whole-run average.
+    const samples = [
+      { tSec: 0, rssMb: 500 },
+      { tSec: 1, rssMb: 500 },
+      { tSec: 2, rssMb: 500 },
+      { tSec: 3, rssMb: 500 },
+      { tSec: 4, rssMb: 500 },
+      { tSec: 5, rssMb: 510 },
+      { tSec: 6, rssMb: 520 },
+      { tSec: 7, rssMb: 530 }
+    ];
+    const full = linregSlope(samples.map((s) => [s.tSec, s.rssMb]));
+    const lastHalf = samples.slice(Math.floor(samples.length / 2));
+    const halfSlope = linregSlope(lastHalf.map((s) => [s.tSec, s.rssMb]));
+
+    expect(halfSlope).toBeCloseTo(10, 10); // MB/sec over the last half only
+    expect(full).toBeGreaterThan(0);
+    expect(full).toBeLessThan(halfSlope); // whole-run average is diluted by the flat first half
+
+    // and the MB/hour conversion finalize() applies
+    const slopeMbPerHour = Math.round(halfSlope * 3600 * 100) / 100;
+    expect(slopeMbPerHour).toBe(36000);
+  });
+});
+
+// A representative server metrics line (schema owned by the server
+// instrumentation; the tailer must stay schema-tolerant).
+const METRICS_LINE = {
+  ts: '2026-07-03T00:00:00.000Z',
+  heapUsed: 123456789,
+  rss: 234567890,
+  cache: { size: 2, max: 64 },
+  counters: {
+    evictions: { total: 12, lru: 8, ttl: 4 },
+    drains: 3,
+    builds: 7,
+    connGuard: { blocked: 0 }
+  }
+};
+
+describe('flattenNumeric', () => {
+  const flat = flattenNumeric(METRICS_LINE);
+  const byPath = Object.fromEntries(flat.map((f) => [f.path, f.value]));
+
+  test('flattens nested numeric leaves with dotted paths', () => {
+    expect(byPath['heapUsed']).toBe(123456789);
+    expect(byPath['rss']).toBe(234567890);
+    expect(byPath['cache.size']).toBe(2);
+    expect(byPath['cache.max']).toBe(64);
+    expect(byPath['counters.evictions.total']).toBe(12);
+    expect(byPath['counters.evictions.lru']).toBe(8);
+    expect(byPath['counters.builds']).toBe(7);
+    expect(byPath['counters.connGuard.blocked']).toBe(0);
+  });
+
+  test('excludes non-numeric fields', () => {
+    expect(byPath['ts']).toBeUndefined();
+    expect(flat.every((f) => typeof f.value === 'number')).toBe(true);
+  });
+});
+
+describe('pickCounter', () => {
+  const flat = flattenNumeric(METRICS_LINE);
+
+  test('prefers an explicit total over sibling numeric fields', () => {
+    const evict = pickCounter(flat, 'evict');
+    expect(evict.value).toBe(12);
+    expect(evict.path).toBe('counters.evictions.total');
+    expect(evict.candidates).toHaveLength(3); // total + lru + ttl
+  });
+
+  test('picks a lone scalar counter', () => {
+    const build = pickCounter(flat, 'build');
+    expect(build.value).toBe(7);
+    expect(build.path).toBe('counters.builds');
+
+    const drain = pickCounter(flat, 'drain');
+    expect(drain.value).toBe(3);
+    expect(drain.path).toBe('counters.drains');
+  });
+
+  test('no match yields a null pick with no candidates', () => {
+    const none = pickCounter(flat, 'zzz-nope');
+    expect(none.value).toBeNull();
+    expect(none.path).toBeNull();
+    expect(none.candidates).toEqual([]);
+  });
+});
diff --git a/packages/perf-harness/src/measure/__tests__/pgSampler.test.ts b/packages/perf-harness/src/measure/__tests__/pgSampler.test.ts
new file mode 100644
index 0000000000..0a8eb16015
--- /dev/null
+++ b/packages/perf-harness/src/measure/__tests__/pgSampler.test.ts
@@ -0,0 +1,35 @@
+import { toBytes } from '../pgSampler';
+
+describe('toBytes (docker MemUsage unit parser)', () => {
+  test('bytes', () => {
+    expect(toBytes('512B')).toBe(512);
+  });
+
+  test('KiB', () => {
+    expect(toBytes('2KiB')).toBe(2048);
+  });
+
+  test('MiB', () => {
+    expect(toBytes('1.5MiB')).toBe(1572864); // 1.5 * 1024^2
+  });
+
+  test('GiB', () => {
+    expect(toBytes('4GiB')).toBe(4294967296); // 4 * 1024^3
+    expect(toBytes('1.234GiB')).toBe(Math.round(1.234 * 1024 ** 3));
+  });
+
+  test('tolerates whitespace between value and unit', () => {
+    expect(toBytes('1.234 GiB')).toBe(Math.round(1.234 * 1024 ** 3));
+  });
+
+  test('parses each side of a docker "used / limit" string', () => {
+    const [used, limit] = '1.234GiB / 4GiB'.split('/').map((s) => toBytes(s));
+    expect(used).toBe(Math.round(1.234 * 1024 ** 3));
+    expect(limit).toBe(4294967296);
+  });
+
+  test('unknown / unparseable input returns null', () => {
+    expect(toBytes('nonsense')).toBeNull();
+    expect(toBytes('')).toBeNull();
+  });
+});
diff --git a/packages/perf-harness/src/measure/collector.ts b/packages/perf-harness/src/measure/collector.ts
new file mode 100644
index 0000000000..99e800cbcb
--- /dev/null
+++ b/packages/perf-harness/src/measure/collector.ts
@@ -0,0 +1,266 @@
+/**
+ * collector — RSS sampler + server metrics tailer.
+ *
+ * Port of `scripts/scale-validate/collector.mjs`. Samples the server process RSS
+ * (`ps -o rss=`) every --interval-sec and tails the server's metrics JSONL. At
+ * exit it computes:
+ *   - RSS min / max / final (MB)
+ *   - linear-regression slope (MB/hour) over the LAST HALF of the RSS samples
+ *   - eviction / drain / build totals parsed from the LAST metrics line
+ * and writes a summary JSON to --out.
+ *
+ * The metrics JSONL schema is owned by the server instrumentation; this tailer
+ * is intentionally schema-tolerant: it flattens the last JSON object and picks
+ * the best numeric field per counter family (evict / drain / build).
+ *
+ * Exit is triggered by SIGINT/SIGTERM, by --duration-sec, or when the monitored
+ * PID disappears. The JSONL protocol lines are written to stdout (machine
+ * readable); the summary file goes to --out.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+
+import { Argv, asInt, usageExit } from '../core/args';
+import { ensureParentDir } from '../core/proc';
+
+// Tiny helpers the standalone script imported from _lib.mjs; core does not
+// re-export them (histogram folded round2 in privately), so inline them here
+// exactly as the original defined them.
+const nowIso = (): string => new Date().toISOString();
+const round2 = (n: number): number => Math.round(n * 100) / 100;
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+const HELP = `measure collector — sample RSS + tail metrics.jsonl, summarize at exit
+
+Options:
+  --pid <n>            server process id to sample (required)
+  --metrics-file <f>   server metrics.jsonl to tail (optional)
+  --interval-sec <n>   sample period (default 15)
+  --duration-sec <n>   run length (default 0 = until SIGINT or pid exit)
+  --out <file>         summary JSON (default collector.json)
+  --help
+`;
+
+export interface FlatNumeric {
+  path: string;
+  value: number;
+}
+
+export interface CounterCandidate {
+  path: string;
+  value: number;
+}
+
+export interface CounterPick {
+  value: number | null;
+  path: string | null;
+  candidates: CounterCandidate[];
+}
+
+function sampleRssMb(pid: number): number | null {
+  const res = spawnSync('ps', ['-o', 'rss=', '-p', String(pid)], { encoding: 'utf8' });
+  if (res.status !== 0) return null;
+  const kb = Number.parseInt((res.stdout || '').trim(), 10);
+  if (!Number.isFinite(kb)) return null;
+  return round2(kb / 1024);
+}
+
+// Least-squares slope of y over x. Returns slope in y-units per x-unit.
+export function linregSlope(points: number[][]): number {
+  const n = points.length;
+  if (n < 2) return 0;
+  let sx = 0;
+  let sy = 0;
+  let sxx = 0;
+  let sxy = 0;
+  for (const [x, y] of points) {
+    sx += x;
+    sy += y;
+    sxx += x * x;
+    sxy += x * y;
+  }
+  const denom = n * sxx - sx * sx;
+  if (denom === 0) return 0;
+  return (n * sxy - sx * sy) / denom;
+}
+
+// Flatten nested object into [{ path, value }] for numeric leaves only.
+export function flattenNumeric(obj: any, prefix = '', out: FlatNumeric[] = []): FlatNumeric[] {
+  if (obj == null || typeof obj !== 'object') return out;
+  for (const [k, v] of Object.entries(obj)) {
+    const path = prefix ? `${prefix}.${k}` : k;
+    if (typeof v === 'number' && Number.isFinite(v)) out.push({ path, value: v });
+    else if (v && typeof v === 'object') flattenNumeric(v, path, out);
+  }
+  return out;
+}
+
+// Pick the best-matching numeric field for a counter family.
+export function pickCounter(flat: FlatNumeric[], family: string): CounterPick {
+  const re = new RegExp(family, 'i');
+  const candidates = flat.filter((f) => re.test(f.path));
+  if (candidates.length === 0) return { value: null, path: null, candidates: [] };
+  // Prefer explicit totals/counts, then longer (more specific) paths.
+  const score = (p: string): number => (/(total|count|sum|cumulative|s$)/i.test(p) ? 2 : 0) + p.length / 1000;
+  candidates.sort((a, b) => score(b.path) - score(a.path));
+  return {
+    value: candidates[0].value,
+    path: candidates[0].path,
+    candidates: candidates.map((c) => ({ path: c.path, value: c.value }))
+  };
+}
+
+export async function runCollector(argv: Argv): Promise<number> {
+  if (argv.help) return usageExit(HELP, 0);
+  if (argv.pid === undefined) return usageExit(HELP, 1);
+
+  const pid = asInt(argv.pid, 0);
+  const metricsFile = typeof argv['metrics-file'] === 'string' ? argv['metrics-file'] : null;
+  const intervalSec = asInt(argv['interval-sec'], 15);
+  const durationSec = asInt(argv['duration-sec'], 0);
+  const out = typeof argv.out === 'string' ? argv.out : 'collector.json';
+
+  const startMs = Date.now();
+  const samples: { tSec: number; rssMb: number }[] = [];
+  let lastMetricsObj: any = null;
+  let metricsLinesSeen = 0;
+  let metricsOffset = 0;
+  let stopping = false;
+  let stopReason: string | null = null;
+
+  const readMetricsTail = (): void => {
+    if (!metricsFile) return;
+    let stat;
+    try {
+      stat = fs.statSync(metricsFile);
+    } catch {
+      return;
+    }
+    if (stat.size < metricsOffset) metricsOffset = 0; // rotated/truncated
+    if (stat.size === metricsOffset) return;
+    let chunk = '';
+    try {
+      const fd = fs.openSync(metricsFile, 'r');
+      const len = stat.size - metricsOffset;
+      const buf = Buffer.alloc(len);
+      fs.readSync(fd, buf, 0, len, metricsOffset);
+      fs.closeSync(fd);
+      chunk = buf.toString('utf8');
+      metricsOffset = stat.size;
+    } catch {
+      return;
+    }
+    for (const line of chunk.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      metricsLinesSeen++;
+      try {
+        lastMetricsObj = JSON.parse(trimmed);
+      } catch {
+        /* partial/non-json line — ignore */
+      }
+    }
+  };
+
+  const emit = (obj: any): void => {
+    process.stdout.write(`${JSON.stringify({ at: nowIso(), ...obj })}\n`);
+  };
+  emit({ t: 'start', pid, metricsFile, intervalSec, durationSec });
+
+  const finalize = (): any => {
+    const rssValues = samples.map((s) => s.rssMb);
+    const rssMin = rssValues.length ? Math.min(...rssValues) : null;
+    const rssMax = rssValues.length ? Math.max(...rssValues) : null;
+    const rssFinal = rssValues.length ? rssValues[rssValues.length - 1] : null;
+    // slope over the last half of samples
+    const half = samples.slice(Math.floor(samples.length / 2));
+    const slopeMbPerSec = linregSlope(half.map((s) => [s.tSec, s.rssMb]));
+    const slopeMbPerHour = round2(slopeMbPerSec * 3600);
+
+    const flat = lastMetricsObj ? flattenNumeric(lastMetricsObj) : [];
+    const evictions = pickCounter(flat, 'evict');
+    const drains = pickCounter(flat, 'drain');
+    const builds = pickCounter(flat, 'build');
+
+    const summary = {
+      generatedAt: nowIso(),
+      pid,
+      stopReason,
+      durationSec: round2((Date.now() - startMs) / 1000),
+      intervalSec,
+      rss: {
+        samples: samples.length,
+        minMb: rssMin,
+        maxMb: rssMax,
+        finalMb: rssFinal,
+        slopeMbPerHour,
+        slopeBasis: `last ${half.length} of ${samples.length} samples`,
+        series: samples
+      },
+      metrics: {
+        file: metricsFile,
+        linesSeen: metricsLinesSeen,
+        evictionsTotal: evictions.value,
+        evictionsField: evictions.path,
+        drainsTotal: drains.value,
+        drainsField: drains.path,
+        buildsTotal: builds.value,
+        buildsField: builds.path,
+        candidates: { evict: evictions.candidates, drain: drains.candidates, build: builds.candidates },
+        lastLine: lastMetricsObj
+      }
+    };
+    ensureParentDir(out);
+    fs.writeFileSync(out, `${JSON.stringify(summary, null, 2)}\n`);
+    emit({
+      t: 'summary',
+      rssMinMb: rssMin,
+      rssMaxMb: rssMax,
+      rssFinalMb: rssFinal,
+      slopeMbPerHour,
+      evictionsTotal: evictions.value,
+      drainsTotal: drains.value,
+      buildsTotal: builds.value,
+      out
+    });
+    return summary;
+  };
+
+  const onSig = (): void => {
+    stopping = true;
+    stopReason = stopReason || 'signal';
+  };
+  process.on('SIGINT', onSig);
+  process.on('SIGTERM', onSig);
+
+  try {
+    // Prime the metrics offset so we start reading from current EOF-ish but
+    // still capture the last line: read everything once so lastMetricsObj is
+    // populated.
+    readMetricsTail();
+
+    while (!stopping) {
+      const rssMb = sampleRssMb(pid);
+      if (rssMb == null) {
+        stopReason = 'pid-exited';
+        break;
+      }
+      samples.push({ tSec: round2((Date.now() - startMs) / 1000), rssMb });
+      readMetricsTail();
+      emit({ t: 'sample', tSec: round2((Date.now() - startMs) / 1000), rssMb, metricsLines: metricsLinesSeen });
+      if (durationSec > 0 && (Date.now() - startMs) / 1000 >= durationSec) {
+        stopReason = 'duration';
+        break;
+      }
+      // sleep in small slices so SIGINT is responsive
+      const until = Date.now() + intervalSec * 1000;
+      while (!stopping && Date.now() < until) await sleep(200);
+    }
+    readMetricsTail();
+    finalize();
+    return 0;
+  } catch (err: any) {
+    process.stderr.write(`[collector] FATAL: ${err && err.stack ? err.stack : err}\n`);
+    return 1;
+  }
+}
diff --git a/packages/perf-harness/src/measure/instanceHeap.ts b/packages/perf-harness/src/measure/instanceHeap.ts
new file mode 100644
index 0000000000..d611439102
--- /dev/null
+++ b/packages/perf-harness/src/measure/instanceHeap.ts
@@ -0,0 +1,206 @@
+/**
+ * instanceHeap — per-class instance heap cost (V2 sizing input).
+ *
+ * Port of `scripts/scale-validate/measure-instance-heap.mjs`. Boots a FRESH
+ * server (own child process, own metrics file) via run/server.ts `spawnServer`
+ * with the blueprint cache capped at 1, waits for the metrics sampler baseline,
+ * cold-builds exactly ONE instance class by hitting a single virtual host, lets
+ * the heap settle, and records the delta. Because the server is fresh and only
+ * one host is ever hit, the delta IS the marginal cost of the first resident
+ * instance of that class (instance + its share of lazily initialized caches).
+ *
+ * Env: PGHOST/PGPORT/PGUSER/PGPASSWORD/PGDATABASE (or --pg-* flags; PG port
+ * defaults to 5433, never 5432). The server port + PG port both run through the
+ * hub-safety guardrail.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { Argv, asBool, asInt, usageExit } from '../core/args';
+import {
+  assertPortAllowed,
+  findRepoRoot,
+  PgConfig,
+  pgConfigFromArgv,
+  resolveOutDir,
+  resolveServerCmd
+} from '../core/config';
+import { ensureParentDir, readJsonl } from '../core/proc';
+import { spawnServer, SpawnedServer } from '../run/server';
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+const MB = (b: number): number => Math.round((b / 1024 / 1024) * 10) / 10;
+
+const USAGE = `measure instance-heap — marginal per-class heap cost on a fresh cap=1 server
+
+Options:
+  --label <name>       label for artifacts + result row (default unlabeled)
+  --host <vhost>       virtual host to cold-build (required, e.g. api-xxx.localhost)
+  --port <n>           server port (default 3344)
+  --heap-mb <n>        --max-old-space-size for the child (default 2048)
+  --cache-max <n>      GRAPHILE_CACHE_MAX for the child (default 1)
+  --settle-sec <n>     settle window after the cold build (default 70)
+  --out <file>         result JSONL (default <out-dir>/instance-heap-results.jsonl)
+  --out-dir <dir>      artifact directory (default ./perf-out)
+  --server-cmd <cmd>   override the server launch command (whitespace-split)
+  --pg-host/--pg-port/--pg-user/--pg-password/--pg-database   connection overrides
+  --allow-hub          permit a reserved constructive-hub port (danger)
+  --help
+`;
+
+// Probe a virtual host with a `{ __typename }` query. Kept local (not gqlFetch)
+// so the recorded { status, ms, body } shape matches the original exactly.
+async function probeTypename(
+  host: string,
+  port: number,
+  timeoutMs: number
+): Promise<{ status: number; ms: number; body: string }> {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  const start = performance.now();
+  try {
+    const res = await fetch(`http://${host}:${port}/graphql`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify({ query: 'query { __typename }' }),
+      signal: ac.signal
+    });
+    const body = await res.text();
+    return { status: res.status, ms: Math.round(performance.now() - start), body: body.slice(0, 200) };
+  } catch (e) {
+    return { status: 0, ms: Math.round(performance.now() - start), body: String(e).slice(0, 200) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function runInstanceHeap(argv: Argv): Promise<number> {
+  if (argv.help) return usageExit(USAGE, 0);
+
+  const label = typeof argv.label === 'string' ? argv.label : 'unlabeled';
+  const host = typeof argv.host === 'string' ? argv.host : null;
+  const port = asInt(argv.port, 3344);
+  const heapMb = asInt(argv['heap-mb'], 2048);
+  // Keep the raw string for the result field (original stored the string '1');
+  // pass a number to spawnServer.
+  const cacheMaxRaw = typeof argv['cache-max'] === 'string' ? argv['cache-max'] : '1';
+  const cacheMax = asInt(cacheMaxRaw, 1);
+  const settleSec = asInt(argv['settle-sec'], 70);
+  if (!host) return usageExit('--host is required', 1);
+
+  const allowHub = asBool(argv['allow-hub']);
+  let pg: PgConfig;
+  try {
+    pg = pgConfigFromArgv(argv); // hub guardrail on the PG port
+    assertPortAllowed(port, allowHub, 'server-port'); // hub guardrail on the server port
+  } catch (e: any) {
+    console.error(`[${label}] ${e && e.message ? e.message : e}`);
+    return 1;
+  }
+
+  const outDir = resolveOutDir(argv);
+  const repoRoot = findRepoRoot();
+  const serverCmd = resolveServerCmd(argv, repoRoot);
+  const serverName = `cap1-${label}`;
+  const metricsFile = path.join(outDir, `metrics-${serverName}.jsonl`);
+  const out = typeof argv.out === 'string' ? argv.out : path.join(outDir, 'instance-heap-results.jsonl');
+  if (fs.existsSync(metricsFile)) fs.rmSync(metricsFile);
+
+  const readMetrics = (): any[] => readJsonl(metricsFile);
+
+  console.error(`[${label}] starting server port=${port} heap=${heapMb}MB cacheMax=${cacheMaxRaw} host=${host}`);
+  const result: any = { label, host, heapMb, cacheMax: cacheMaxRaw, ok: false };
+  let server: SpawnedServer | null = null;
+  try {
+    server = await spawnServer({
+      name: serverName,
+      port,
+      heapMb,
+      metricsFile,
+      pg,
+      repoRoot,
+      outDir,
+      serverCmd,
+      cacheMax,
+      allowHub
+    });
+    console.error(`[${label}] listening; waiting for baseline metrics...`);
+
+    // Baseline: at least 2 sampler lines (~20s) so init transients are past.
+    let m: any[] = [];
+    const baseDeadline = Date.now() + 90000;
+    while (Date.now() < baseDeadline) {
+      m = readMetrics();
+      if (m.length >= 2) break;
+      await sleep(2000);
+    }
+    if (m.length < 2) throw new Error(`no metrics baseline (${m.length} lines): sampler not writing?`);
+    const baseline = m[m.length - 1];
+    const baselineCount = m.length;
+    result.baseline = { heapUsedMB: MB(baseline.heapUsed), rssMB: MB(baseline.rss) };
+    console.error(`[${label}] baseline heapUsed=${result.baseline.heapUsedMB}MB rss=${result.baseline.rssMB}MB`);
+
+    // Cold build: first request to this host builds the instance.
+    const cold = await probeTypename(host, port, 420000);
+    result.cold = cold;
+    console.error(`[${label}] cold request: status=${cold.status} ${cold.ms}ms ${cold.body}`);
+    if (cold.status !== 200) throw new Error(`cold request failed: ${cold.status} ${cold.body}`);
+
+    // Settle and sample.
+    const targetLines = baselineCount + Math.ceil(settleSec / 10);
+    const settleDeadline = Date.now() + settleSec * 1000 + 60000;
+    while (Date.now() < settleDeadline) {
+      m = readMetrics();
+      if (m.length >= targetLines) break;
+      await sleep(5000);
+    }
+    const post = m.slice(baselineCount);
+    if (post.length === 0) throw new Error('no post-build metrics samples');
+    const last = post[post.length - 1];
+    const heaps = post.map((x: any) => x.heapUsed);
+    const rsss = post.map((x: any) => x.rss);
+    result.postBuild = {
+      samples: post.length,
+      heapUsedLastMB: MB(last.heapUsed),
+      heapUsedMinMB: MB(Math.min(...heaps)),
+      heapUsedMaxMB: MB(Math.max(...heaps)),
+      rssLastMB: MB(last.rss),
+      rssMaxMB: MB(Math.max(...rsss)),
+      cache: last.cache,
+      counters: last.counters
+    };
+    result.deltaHeapMB = Math.round((result.postBuild.heapUsedLastMB - result.baseline.heapUsedMB) * 10) / 10;
+    result.deltaRssMB = Math.round((result.postBuild.rssLastMB - result.baseline.rssMB) * 10) / 10;
+
+    // Warm request: instance resident, should be fast.
+    const warm = await probeTypename(host, port, 30000);
+    result.warm = { status: warm.status, ms: warm.ms };
+    result.ok = warm.status === 200;
+    console.error(
+      `[${label}] deltaHeap=${result.deltaHeapMB}MB deltaRss=${result.deltaRssMB}MB ` +
+        `(post last=${result.postBuild.heapUsedLastMB}MB min=${result.postBuild.heapUsedMinMB}MB ` +
+        `max=${result.postBuild.heapUsedMaxMB}MB) warm=${warm.ms}ms`
+    );
+  } catch (e: any) {
+    // A startup (port-wait) timeout throws before `server` is assigned, but
+    // spawnServer attaches the started child to err.server so we can still tail
+    // its log and stop it in the finally.
+    if (!server && e && e.server) server = e.server;
+    result.error = String(e && e.message ? e.message : e);
+    result.serverLogTail = server ? server.logTail(1500) : '';
+    console.error(`[${label}] FAILED: ${result.error}`);
+  } finally {
+    if (server) {
+      try {
+        await server.stop();
+      } catch {
+        /* already gone */
+      }
+    }
+  }
+
+  ensureParentDir(out);
+  fs.appendFileSync(out, JSON.stringify(result) + '\n');
+  console.error(`[${label}] result appended to ${out}`);
+  return result.ok ? 0 : 1;
+}
diff --git a/packages/perf-harness/src/measure/pgSampler.ts b/packages/perf-harness/src/measure/pgSampler.ts
new file mode 100644
index 0000000000..1b6a0b826c
--- /dev/null
+++ b/packages/perf-harness/src/measure/pgSampler.ts
@@ -0,0 +1,146 @@
+/**
+ * pgSampler — PG-side time series for perf runs.
+ *
+ * Port of `scripts/scale-validate/pg-sampler.mjs`. The node side is covered by
+ * the server's GRAPHILE_DEBUG_METRICS JSONL; this captures the Postgres half.
+ *
+ * Every --interval-sec appends one JSONL line to --out with:
+ *   - docker container memory (usage/limit bytes) for --container
+ *   - pg_stat_activity backend counts by state (+ total)
+ *   - pg_class row count (catalog size proxy) and current database size
+ *
+ * Connection: standard PG* env vars (or --pg-* flags via pgConfigFromArgv, which
+ * also runs the hub-port guardrail). A FRESH client per sample (the rig runs
+ * idle_session_timeout=120s; a persistent idle client would be reaped mid-run).
+ * Sampling errors are recorded on the line ({err}) and never kill the sampler —
+ * a PG crash/recovery window is exactly the data we want to keep collecting
+ * through.
+ *
+ * Exit: --duration-sec elapsed, or SIGINT/SIGTERM (JSONL is append-per-line,
+ * nothing to flush).
+ */
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { Argv, asInt, usageExit } from '../core/args';
+import { PgConfig, pgConfigFromArgv } from '../core/config';
+import { withFreshClient } from '../core/pgc';
+
+const nowIso = (): string => new Date().toISOString();
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+const USAGE = `measure pg — docker + pg_stat_activity/pg_class/db-size sampler
+
+Options:
+  --out <file>         JSONL output (default out/pg-soak.jsonl)
+  --interval-sec <n>   sample period (default 30)
+  --duration-sec <n>   run length (default 0 = until SIGINT/SIGTERM)
+  --container <name>   docker container to stat (default constructive-scale-pg)
+  --pg-host/--pg-port/--pg-user/--pg-password/--pg-database   connection overrides
+                       (PG* env otherwise; PG port defaults to 5433, never 5432)
+  --allow-hub          permit a reserved constructive-hub port (danger)
+  --help
+`;
+
+// Parse a docker `MemUsage` value like "1.234GiB" into bytes. Exported for unit
+// tests. Returns null when the input does not match a known unit.
+export function toBytes(s: string): number | null {
+  const mm = /([\d.]+)\s*(B|KiB|MiB|GiB)/.exec(s);
+  if (!mm) return null;
+  const mult: Record<string, number> = { B: 1, KiB: 1024, MiB: 1024 ** 2, GiB: 1024 ** 3 };
+  return Math.round(parseFloat(mm[1]) * mult[mm[2]]);
+}
+
+function dockerMem(name: string): Promise<any> {
+  return new Promise((resolve) => {
+    execFile(
+      'docker',
+      ['stats', '--no-stream', '--format', '{{.MemUsage}}', name],
+      { timeout: 10000 },
+      (err, stdout) => {
+        if (err) return resolve({ err: String(err.message || err).slice(0, 200) });
+        // e.g. "1.234GiB / 4GiB"
+        const m = String(stdout).trim();
+        const [used, limit] = m.split('/').map((s) => toBytes(s));
+        resolve({ raw: m, usedBytes: used, limitBytes: limit });
+      }
+    );
+  });
+}
+
+async function pgSample(pg: PgConfig): Promise<any> {
+  return withFreshClient(pg, async (client) => {
+    // sequential on purpose: pg queues concurrent query() on one client (deprecated)
+    const act = await client.query("SELECT COALESCE(state, 'null') AS state, count(*)::int AS n FROM pg_stat_activity GROUP BY 1");
+    const cls = await client.query('SELECT count(*)::int AS n FROM pg_class');
+    const size = await client.query('SELECT pg_database_size(current_database())::bigint AS b, (SELECT sum(numbackends)::int FROM pg_stat_database) AS backends');
+    const byState: Record<string, number> = {};
+    let total = 0;
+    for (const r of act.rows) {
+      byState[r.state] = r.n;
+      total += r.n;
+    }
+    return {
+      backendsByState: byState,
+      backendsTotal: total,
+      backendsAllDbs: size.rows[0].backends,
+      pgClassRows: cls.rows[0].n,
+      dbSizeBytes: Number(size.rows[0].b)
+    };
+  });
+}
+
+export async function runPgSampler(argv: Argv): Promise<number> {
+  if (argv.help) return usageExit(USAGE, 0);
+
+  const outFile = typeof argv.out === 'string' ? argv.out : 'out/pg-soak.jsonl';
+  const intervalSec = asInt(argv['interval-sec'], 30);
+  const durationSec = asInt(argv['duration-sec'], 0);
+  const container = typeof argv.container === 'string' ? argv.container : 'constructive-scale-pg';
+
+  let pg: PgConfig;
+  try {
+    pg = pgConfigFromArgv(argv);
+  } catch (e: any) {
+    console.error(`[pg-sampler] ${e && e.message ? e.message : e}`);
+    return 1;
+  }
+
+  fs.mkdirSync(path.dirname(outFile), { recursive: true });
+
+  let stopping = false;
+  const onSig = (): void => {
+    stopping = true;
+  };
+  process.on('SIGINT', onSig);
+  process.on('SIGTERM', onSig);
+
+  const startMs = Date.now();
+  console.error(
+    `[pg-sampler] out=${outFile} interval=${intervalSec}s duration=${durationSec || 'until-signal'}s ` +
+      `container=${container} pg=${pg.host}:${pg.port}/${pg.database}`
+  );
+
+  for (;;) {
+    if (stopping) break;
+    if (durationSec && (Date.now() - startMs) / 1000 >= durationSec) break;
+    const line: any = { t: nowIso() };
+    try {
+      line.docker = await dockerMem(container);
+    } catch (e: any) {
+      line.docker = { err: String(e.message || e).slice(0, 200) };
+    }
+    try {
+      Object.assign(line, await pgSample(pg));
+    } catch (e: any) {
+      line.err = String(e.message || e).slice(0, 200);
+    }
+    fs.appendFileSync(outFile, `${JSON.stringify(line)}\n`);
+    // sleep in small slices so signals stay responsive
+    const until = Date.now() + intervalSec * 1000;
+    while (Date.now() < until && !stopping) await sleep(500);
+  }
+  console.error('[pg-sampler] done');
+  return 0;
+}
diff --git a/packages/perf-harness/src/regression/__tests__/baselines.test.ts b/packages/perf-harness/src/regression/__tests__/baselines.test.ts
new file mode 100644
index 0000000000..f9f0a59396
--- /dev/null
+++ b/packages/perf-harness/src/regression/__tests__/baselines.test.ts
@@ -0,0 +1,45 @@
+import { BASELINES, DEFAULT_BASELINE, getBaseline, listBaselines } from '../baselines';
+
+describe('baselines catalog', () => {
+  test('DEFAULT_BASELINE is the 2026-07 catalog entry', () => {
+    expect(DEFAULT_BASELINE).toBe('catalog61k-2026-07');
+    expect(BASELINES[DEFAULT_BASELINE]).toBeDefined();
+    expect(listBaselines().length).toBeGreaterThanOrEqual(1);
+  });
+
+  test('catalog61k-2026-07 has the exact measured constants + thresholds', () => {
+    const b = getBaseline('catalog61k-2026-07');
+    expect(b.catalogPgClassRows).toBe(61238);
+    expect(b.instanceHeapKBPerRow).toBe(21);
+    expect(b.pgIntrospectionSpikeKBPerRow).toBe(37);
+    expect(b.minViableHeapMB).toBe(1536);
+    expect(b.baseReserveMB).toBe(256);
+    expect(b.buildReserveMB).toBe(768);
+    expect(b.zeroMarginal.tenants).toEqual([10, 20, 32]);
+    expect(b.zeroMarginal.heapMaxMB).toEqual([1460.1, 1459.6, 1464.1]);
+    expect(b.healthy).toEqual({ rps: 188, p99Ms: 21, errRate: 0 });
+    expect(b.capacityByHeapMB['2048']).toBe(1);
+    expect(b.capacityByHeapMB['3584']).toBe(2);
+    expect(b.thresholds).toEqual({
+      maxInstanceHeapKBPerRow: 28,
+      maxZeroMarginalDeltaMB: 100,
+      maxHealthyErrRate: 0.005,
+      maxHealthyP99Ms: 150,
+      maxHeapSlopeMBPerHour: 5
+    });
+  });
+
+  test('catalog61k-2026-07 carries the deep-tier thresholds + constants', () => {
+    const b = getBaseline('catalog61k-2026-07');
+    expect(b.deepThresholds).toEqual({
+      multiApiHeapTolerance: 0.2,
+      settingsSplitExpectedInstances: 2,
+      partitionCreepMaxRowsPerTenantMonth: 200
+    });
+    expect(b.deepConstants).toEqual({ apiSurfacesRoutable: 8 });
+  });
+
+  test('getBaseline throws on an unknown name', () => {
+    expect(() => getBaseline('does-not-exist')).toThrow(/unknown baseline/);
+  });
+});
diff --git a/packages/perf-harness/src/regression/__tests__/compare.test.ts b/packages/perf-harness/src/regression/__tests__/compare.test.ts
new file mode 100644
index 0000000000..c576064cd1
--- /dev/null
+++ b/packages/perf-harness/src/regression/__tests__/compare.test.ts
@@ -0,0 +1,105 @@
+import { getBaseline } from '../baselines';
+import { CheckResult, compareToBaseline, MeasuredRegression, verdictFromChecks } from '../compare';
+
+const bl = getBaseline('catalog61k-2026-07');
+const find = (checks: CheckResult[], name: string): CheckResult => checks.find((c) => c.name === name);
+const cmp = (m: MeasuredRegression): CheckResult[] => compareToBaseline(m, bl);
+
+describe('compareToBaseline boundaries', () => {
+  test('instance-heap passes at the threshold and fails just above', () => {
+    expect(find(cmp({ instanceHeapKBPerRow: 28 }), 'instance-heap').pass).toBe(true);
+    expect(find(cmp({ instanceHeapKBPerRow: 28.1 }), 'instance-heap').pass).toBe(false);
+  });
+
+  test('healthy errRate passes at 0.005 and fails at 0.006', () => {
+    expect(find(cmp({ healthy: { errRate: 0.005 } }), 'healthy-single-bp:errRate').pass).toBe(true);
+    expect(find(cmp({ healthy: { errRate: 0.006 } }), 'healthy-single-bp:errRate').pass).toBe(false);
+  });
+
+  test('healthy p99 passes at 150ms and fails at 151ms', () => {
+    expect(find(cmp({ healthy: { p99Ms: 150 } }), 'healthy-single-bp:p99').pass).toBe(true);
+    expect(find(cmp({ healthy: { p99Ms: 151 } }), 'healthy-single-bp:p99').pass).toBe(false);
+  });
+
+  test('zero-marginal passes at 100MB delta and fails at 101MB', () => {
+    expect(find(cmp({ zeroMarginalDeltaMB: 100 }), 'zero-marginal-tenants').pass).toBe(true);
+    expect(find(cmp({ zeroMarginalDeltaMB: 101 }), 'zero-marginal-tenants').pass).toBe(false);
+  });
+
+  test('thrash-not-crash passes when the server survives and fails on crash', () => {
+    expect(find(cmp({ thrashCrashed: false }), 'thrash-not-crash').pass).toBe(true);
+    expect(find(cmp({ thrashCrashed: true }), 'thrash-not-crash').pass).toBe(false);
+  });
+
+  test('heap-slope passes at threshold and fails above', () => {
+    expect(find(cmp({ heapSlopeMBPerHour: 5 }), 'heap-slope').pass).toBe(true);
+    expect(find(cmp({ heapSlopeMBPerHour: 6 }), 'heap-slope').pass).toBe(false);
+  });
+
+  test('only measurements that were taken produce checks', () => {
+    expect(cmp({}).length).toBe(0);
+    const partial = cmp({ healthy: { errRate: 0 } });
+    expect(partial.map((c) => c.name)).toEqual(['healthy-single-bp:errRate']);
+  });
+});
+
+describe('verdictFromChecks', () => {
+  test('all-pass is exit 0', () => {
+    const checks = cmp({ healthy: { errRate: 0, p99Ms: 21 }, zeroMarginalDeltaMB: 4, bleedViolations: 0 });
+    expect(verdictFromChecks(checks)).toMatchObject({ pass: true, bleed: false, exitCode: 0 });
+  });
+
+  test('a non-bleed failure is exit 1', () => {
+    const checks = cmp({ healthy: { errRate: 0.9 }, bleedViolations: 0 });
+    const v = verdictFromChecks(checks);
+    expect(v.pass).toBe(false);
+    expect(v.bleed).toBe(false);
+    expect(v.exitCode).toBe(1);
+    expect(v.failed).toContain('healthy-single-bp:errRate');
+  });
+
+  test('any bleed violation forces exit 2 even if everything else passes', () => {
+    const clean = cmp({ bleedViolations: 0 });
+    expect(find(clean, 'bleed').pass).toBe(true);
+    expect(verdictFromChecks(clean).exitCode).toBe(0);
+
+    const bled = cmp({ healthy: { errRate: 0, p99Ms: 21 }, bleedViolations: 2 });
+    expect(find(bled, 'bleed').pass).toBe(false);
+    const v = verdictFromChecks(bled);
+    expect(v.bleed).toBe(true);
+    expect(v.exitCode).toBe(2);
+  });
+});
+
+// Advisory checks (the deep-tier scenario probes) are reported but must NEVER
+// contribute to the verdict / exit code.
+describe('verdictFromChecks — advisory checks', () => {
+  const adv = (name: string, pass: boolean): CheckResult => ({ name, pass, value: null, threshold: null, note: '', advisory: true });
+  const grade = (name: string, pass: boolean): CheckResult => ({ name, pass, value: null, threshold: null, note: '' });
+
+  test('a failing advisory check does not flip a passing suite', () => {
+    const v = verdictFromChecks([grade('multi-api-residency', true), adv('partition-creep', false), adv('settings-variant-split', false)]);
+    expect(v.pass).toBe(true);
+    expect(v.exitCode).toBe(0);
+    expect(v.failed).toEqual([]);
+  });
+
+  test('an advisory check named bleed cannot force exit 2', () => {
+    const v = verdictFromChecks([grade('healthy-single-bp:errRate', true), adv('bleed', false)]);
+    expect(v.bleed).toBe(false);
+    expect(v.exitCode).toBe(0);
+  });
+
+  test('a failing GRADEABLE check still fails while advisory noise is ignored', () => {
+    const v = verdictFromChecks([grade('multi-api-residency', false), adv('partition-creep', false)]);
+    expect(v.exitCode).toBe(1);
+    expect(v.failed).toEqual(['multi-api-residency']);
+    expect(v.failed).not.toContain('partition-creep');
+  });
+
+  test('a GRADEABLE bleed still forces exit 2 alongside advisory checks', () => {
+    const v = verdictFromChecks([grade('bleed', false), adv('realtime-dedicated-cost', true)]);
+    expect(v.bleed).toBe(true);
+    expect(v.exitCode).toBe(2);
+  });
+});
diff --git a/packages/perf-harness/src/regression/__tests__/scenarios.test.ts b/packages/perf-harness/src/regression/__tests__/scenarios.test.ts
new file mode 100644
index 0000000000..5003ef5310
--- /dev/null
+++ b/packages/perf-harness/src/regression/__tests__/scenarios.test.ts
@@ -0,0 +1,200 @@
+import { Tenant } from '../../core/fleetfile';
+import { verdictFromChecks } from '../compare';
+import {
+  buildResidencyAbortCheck,
+  buildTeardownLeftoverWarning,
+  computeCreepProjection,
+  DEEP_SCENARIOS,
+  deriveSurfaceFleets,
+  parsePartitionIntervalSeconds,
+  rewriteHostPrefix,
+  scenarioEnabled,
+  SECONDS_PER_MONTH
+} from '../scenarios';
+
+// ---------------------------------------------------------------------------
+// fleet host-rewrite derivation
+// ---------------------------------------------------------------------------
+describe('rewriteHostPrefix', () => {
+  test('rewrites the leading api- label to another surface', () => {
+    expect(rewriteHostPrefix('api-factory2-fab4d29f.localhost', 'api', 'admin')).toBe('admin-factory2-fab4d29f.localhost');
+    expect(rewriteHostPrefix('api-factory2-fab4d29f.localhost', 'api', 'usage')).toBe('usage-factory2-fab4d29f.localhost');
+  });
+
+  test('returns null when the from-prefix does not match', () => {
+    expect(rewriteHostPrefix('auth-factory2-fab4d29f.localhost', 'api', 'admin')).toBeNull();
+    expect(rewriteHostPrefix('', 'api', 'admin')).toBeNull();
+    expect(rewriteHostPrefix(undefined as any, 'api', 'admin')).toBeNull();
+  });
+
+  test('only the FIRST label is rewritten (later api- substrings untouched)', () => {
+    expect(rewriteHostPrefix('api-api-x.localhost', 'api', 'admin')).toBe('admin-api-x.localhost');
+  });
+});
+
+describe('deriveSurfaceFleets', () => {
+  const tenants: Tenant[] = [
+    { dbname: 'factory2', apiHost: 'api-factory2-aaaa1111.localhost', authHost: 'auth-factory2-aaaa1111.localhost' },
+    { dbname: 'factory3', apiHost: 'api-factory3-bbbb2222.localhost', authHost: 'auth-factory3-bbbb2222.localhost' }
+  ];
+
+  test('api surface keeps hosts; admin/usage rewrite the label; authHost preserved', () => {
+    const { fleets, warnings } = deriveSurfaceFleets(tenants, ['api', 'admin', 'usage']);
+    expect(warnings).toEqual([]);
+    const api = fleets.find((f) => f.surface === 'api');
+    const admin = fleets.find((f) => f.surface === 'admin');
+    const usage = fleets.find((f) => f.surface === 'usage');
+    expect(api.tenants.map((t) => t.apiHost)).toEqual(['api-factory2-aaaa1111.localhost', 'api-factory3-bbbb2222.localhost']);
+    expect(admin.tenants.map((t) => t.apiHost)).toEqual(['admin-factory2-aaaa1111.localhost', 'admin-factory3-bbbb2222.localhost']);
+    expect(usage.tenants.map((t) => t.apiHost)).toEqual(['usage-factory2-aaaa1111.localhost', 'usage-factory3-bbbb2222.localhost']);
+    // authHost is untouched on every derived surface (login always uses auth).
+    expect(admin.tenants[0].authHost).toBe('auth-factory2-aaaa1111.localhost');
+  });
+
+  test('tenants without apiHost, or with a non-api host, are dropped with a warning', () => {
+    const mixed: Tenant[] = [
+      { dbname: 'ok', apiHost: 'api-ok-1234abcd.localhost' },
+      { dbname: 'nohost' },
+      { dbname: 'weird', apiHost: 'gateway.example.com' }
+    ];
+    const { fleets, warnings } = deriveSurfaceFleets(mixed, ['admin']);
+    expect(fleets[0].tenants.map((t) => t.dbname)).toEqual(['ok']);
+    expect(warnings.some((w) => w.includes('nohost'))).toBe(true);
+    expect(warnings.some((w) => w.includes('weird'))).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// creep math
+// ---------------------------------------------------------------------------
+describe('parsePartitionIntervalSeconds', () => {
+  test('common partman intervals', () => {
+    expect(parsePartitionIntervalSeconds('1 day')).toBe(86400);
+    expect(parsePartitionIntervalSeconds('7 days')).toBe(604800);
+    expect(parsePartitionIntervalSeconds('1 week')).toBe(604800);
+    expect(parsePartitionIntervalSeconds('1 hour')).toBe(3600);
+    expect(parsePartitionIntervalSeconds('1 mon')).toBe(SECONDS_PER_MONTH);
+    expect(parsePartitionIntervalSeconds('1 month')).toBe(SECONDS_PER_MONTH);
+  });
+
+  test('clock and mixed forms', () => {
+    expect(parsePartitionIntervalSeconds('01:00:00')).toBe(3600);
+    expect(parsePartitionIntervalSeconds('00:15:00')).toBe(900);
+    expect(parsePartitionIntervalSeconds('1 day 06:00:00')).toBe(86400 + 6 * 3600);
+  });
+
+  test('unparseable / id-based intervals return null', () => {
+    expect(parsePartitionIntervalSeconds('10000')).toBeNull();
+    expect(parsePartitionIntervalSeconds('')).toBeNull();
+    expect(parsePartitionIntervalSeconds(null as any)).toBeNull();
+  });
+});
+
+describe('computeCreepProjection', () => {
+  test('monthly interval → exactly 1 partition/parent/month', () => {
+    const p = computeCreepProjection({
+      rowsPerPartition: 10,
+      partitionedParents: 4,
+      partitionIntervalSeconds: SECONDS_PER_MONTH,
+      instanceHeapKBPerRow: 21
+    });
+    expect(p.intervalsPerMonth).toBe(1);
+    expect(p.partitionsPerMonth).toBe(4);
+    expect(p.rowsPerTenantPerMonth).toBe(40);
+    // 40 rows * 21KB / 1024 = 0.82 MB
+    expect(p.heapCreepMBPerMonthPerTenant).toBeCloseTo(0.82, 2);
+  });
+
+  test('daily interval scales by ~30.44 intervals/month', () => {
+    const p = computeCreepProjection({
+      rowsPerPartition: 5,
+      partitionedParents: 1,
+      partitionIntervalSeconds: 86400,
+      instanceHeapKBPerRow: 21
+    });
+    expect(p.intervalsPerMonth).toBeCloseTo(30.44, 1);
+    expect(p.rowsPerTenantPerMonth).toBeCloseTo(152.19, 1);
+  });
+
+  test('zero / negative inputs never divide-by-zero or go negative', () => {
+    const p = computeCreepProjection({ rowsPerPartition: -5, partitionedParents: -1, partitionIntervalSeconds: 0, instanceHeapKBPerRow: 21 });
+    expect(p.intervalsPerMonth).toBe(0);
+    expect(p.rowsPerTenantPerMonth).toBe(0);
+    expect(p.heapCreepMBPerMonthPerTenant).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// scenario filter
+// ---------------------------------------------------------------------------
+describe('scenarioEnabled', () => {
+  test('all enabled by default', () => {
+    for (const s of DEEP_SCENARIOS) expect(scenarioEnabled(s)).toBe(true);
+  });
+
+  test('--only restricts to the named set', () => {
+    expect(scenarioEnabled('partition-creep', ['partition-creep'])).toBe(true);
+    expect(scenarioEnabled('multi-api-residency', ['partition-creep'])).toBe(false);
+  });
+
+  test('--skip removes, and wins over --only', () => {
+    expect(scenarioEnabled('partition-creep', null, ['partition-creep'])).toBe(false);
+    expect(scenarioEnabled('partition-creep', ['partition-creep'], ['partition-creep'])).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// teardown-leftover warning (settings-variant-split / realtime-dedicated-cost)
+// ---------------------------------------------------------------------------
+describe('buildTeardownLeftoverWarning', () => {
+  test('surfaces a warning naming the scenario and the leftover row count', () => {
+    const w = buildTeardownLeftoverWarning('settings-variant-split', 2);
+    expect(w).not.toBeNull();
+    expect(w).toContain('settings-variant-split');
+    expect(w).toMatch(/left 2 database_settings row/);
+  });
+
+  test('no warning when the teardown restored cleanly (0 rows)', () => {
+    expect(buildTeardownLeftoverWarning('settings-variant-split', 0)).toBeNull();
+  });
+
+  test('no warning when the leftover count is unknown (null — the teardown error already warned)', () => {
+    expect(buildTeardownLeftoverWarning('realtime-dedicated-cost', null)).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// residency fail-closed check (multi-api-residency abort) — the gradeable deep
+// check must not be able to silently PASS when the scenario aborts early
+// ---------------------------------------------------------------------------
+describe('buildResidencyAbortCheck', () => {
+  test('is a FAILING, non-advisory gradeable check that explains the abort', () => {
+    const c = buildResidencyAbortCheck('no baseline metrics sample');
+    expect(c.name).toBe('multi-api-residency');
+    expect(c.pass).toBe(false);
+    expect(c.advisory).toBeUndefined();
+    expect(c.note).toContain('no baseline metrics sample');
+  });
+
+  test('GATES the verdict — an aborted residency scenario cannot silently PASS', () => {
+    const verdict = verdictFromChecks([buildResidencyAbortCheck('boom')]);
+    expect(verdict.pass).toBe(false);
+    expect(verdict.exitCode).toBe(1);
+    expect(verdict.failed).toContain('multi-api-residency');
+  });
+
+  test('advisory-only failures still PASS (the fail-open bug); adding the abort check FAILS (the fix)', () => {
+    const advisoryFailure = {
+      name: 'multi-api-heap-plateau',
+      advisory: true,
+      pass: false,
+      value: 1,
+      threshold: 0,
+      note: 'x'
+    };
+    // Fail-open shape: no gradeable check present → suite still PASSES.
+    expect(verdictFromChecks([advisoryFailure]).pass).toBe(true);
+    // Fail-closed shape: the abort check gates it to FAIL.
+    expect(verdictFromChecks([advisoryFailure, buildResidencyAbortCheck('boom')]).pass).toBe(false);
+  });
+});
diff --git a/packages/perf-harness/src/regression/__tests__/sql.test.ts b/packages/perf-harness/src/regression/__tests__/sql.test.ts
new file mode 100644
index 0000000000..05b689c6e8
--- /dev/null
+++ b/packages/perf-harness/src/regression/__tests__/sql.test.ts
@@ -0,0 +1,136 @@
+import {
+  buildCreateProbePartition,
+  buildDropProbePartition,
+  buildPartConfigLikePatterns,
+  buildSettingsInsert,
+  escapeLikeLiteral,
+  PART_CONFIG_FOR_TENANT_SQL,
+  qid,
+  SCHEMA_UPDATE_CHANNEL,
+  SETTINGS_DELETE_SQL,
+  SETTINGS_FLAGS,
+  splitParentTable
+} from '../sql';
+
+// ---------------------------------------------------------------------------
+// settings-SQL builder — emits exactly the intended INSERT / DELETE
+// ---------------------------------------------------------------------------
+describe('buildSettingsInsert', () => {
+  test('single flag → parameterized one-row INSERT ($1 = database_id, $2 = flag)', () => {
+    expect(buildSettingsInsert(['enable_aggregates'])).toBe(
+      'INSERT INTO services_public.database_settings (database_id, enable_aggregates) VALUES ($1, $2)'
+    );
+  });
+
+  test('multiple flags keep order and placeholder numbering', () => {
+    expect(buildSettingsInsert(['enable_aggregates', 'enable_realtime'])).toBe(
+      'INSERT INTO services_public.database_settings (database_id, enable_aggregates, enable_realtime) VALUES ($1, $2, $3)'
+    );
+  });
+
+  test('rejects an unknown column (allowlist guard) and an empty list', () => {
+    expect(() => buildSettingsInsert(['drop_table' as any])).toThrow(/unknown settings flag/);
+    expect(() => buildSettingsInsert([])).toThrow(/at least one flag/);
+  });
+
+  test('the allowlist is the 12 known feature flags', () => {
+    expect(SETTINGS_FLAGS).toHaveLength(12);
+    expect(SETTINGS_FLAGS).toContain('enable_realtime');
+    expect(SETTINGS_FLAGS).toContain('enable_aggregates');
+  });
+});
+
+describe('settings DELETE + notify channel', () => {
+  test('DELETE targets exactly the seeded database_id set', () => {
+    expect(SETTINGS_DELETE_SQL).toBe(
+      'DELETE FROM services_public.database_settings WHERE database_id = ANY($1::uuid[])'
+    );
+  });
+
+  test('schema:update channel is the server LISTEN channel', () => {
+    expect(SCHEMA_UPDATE_CHANNEL).toBe('schema:update');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// probe-partition DDL builders (reversible pair) + identifier escaping
+// ---------------------------------------------------------------------------
+describe('probe partition DDL', () => {
+  test('CREATE quotes identifiers and inlines validated ISO bounds', () => {
+    const sql = buildCreateProbePartition('factory2-aaaa1111-app-private', 'events', 'events__perfcreep_probe', '2099-01-01 00:00:00+00', '2099-01-08 00:00:00+00');
+    expect(sql).toBe(
+      'CREATE TABLE "factory2-aaaa1111-app-private"."events__perfcreep_probe" ' +
+        'PARTITION OF "factory2-aaaa1111-app-private"."events" ' +
+        "FOR VALUES FROM ('2099-01-01 00:00:00+00') TO ('2099-01-08 00:00:00+00')"
+    );
+  });
+
+  test('DROP is the exact inverse', () => {
+    expect(buildDropProbePartition('s', 'events__perfcreep_probe')).toBe('DROP TABLE IF EXISTS "s"."events__perfcreep_probe"');
+  });
+
+  test('rejects a non-ISO bound (guards the only interpolated literal)', () => {
+    expect(() => buildCreateProbePartition('s', 'p', 'c', "2099'); DROP TABLE x;--", '2099-01-08')).toThrow(/ISO timestamp/);
+  });
+
+  test('qid escapes embedded double-quotes', () => {
+    expect(qid('a"b')).toBe('"a""b"');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parent_table splitting (physical schemas have dashes, never dots)
+// ---------------------------------------------------------------------------
+describe('splitParentTable', () => {
+  test('splits on the last dot', () => {
+    expect(splitParentTable('factory2-aaaa1111-app-private.events')).toEqual({
+      schema: 'factory2-aaaa1111-app-private',
+      table: 'events'
+    });
+  });
+
+  test('returns null when there is no usable dot', () => {
+    expect(splitParentTable('events')).toBeNull();
+    expect(splitParentTable('.events')).toBeNull();
+    expect(splitParentTable('schema.')).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// partman LIKE-pattern building — escape LIKE metacharacters so a schema's
+// underscore/percent cannot over-match a DIFFERENT tenant's parents
+// ---------------------------------------------------------------------------
+describe('escapeLikeLiteral', () => {
+  test('escapes the three LIKE metacharacters (backslash, %, _)', () => {
+    expect(escapeLikeLiteral('foo_bar')).toBe('foo\\_bar');
+    expect(escapeLikeLiteral('a%b')).toBe('a\\%b');
+    expect(escapeLikeLiteral('a\\b')).toBe('a\\\\b');
+  });
+
+  test('leaves dashes and dots untouched (not LIKE metacharacters)', () => {
+    expect(escapeLikeLiteral('factory2-aaaa1111-app-private')).toBe('factory2-aaaa1111-app-private');
+    expect(escapeLikeLiteral('a.b')).toBe('a.b');
+  });
+});
+
+describe('buildPartConfigLikePatterns', () => {
+  test('appends the intended .% table wildcard to each schema', () => {
+    expect(buildPartConfigLikePatterns(['factory2-aaaa1111-app-private'])).toEqual([
+      'factory2-aaaa1111-app-private.%'
+    ]);
+  });
+
+  test('an underscore in a schema is escaped so it cannot match a foreign tenant', () => {
+    // Unescaped, 'foo_bar.%' would ALSO match 'fooXbar.<table>' (a cross-tenant
+    // over-match); escaped, only the literal 'foo_bar.<table>' can match.
+    expect(buildPartConfigLikePatterns(['foo_bar'])).toEqual(['foo\\_bar.%']);
+  });
+
+  test('preserves order and escapes each schema independently', () => {
+    expect(buildPartConfigLikePatterns(['a_b', 'c-d', 'e%f'])).toEqual(['a\\_b.%', 'c-d.%', 'e\\%f.%']);
+  });
+
+  test('the query it feeds still matches with LIKE ANY over $1', () => {
+    expect(PART_CONFIG_FOR_TENANT_SQL).toContain('parent_table LIKE ANY($1)');
+  });
+});
diff --git a/packages/perf-harness/src/regression/baselines.ts b/packages/perf-harness/src/regression/baselines.ts
new file mode 100644
index 0000000000..2851eabf7c
--- /dev/null
+++ b/packages/perf-harness/src/regression/baselines.ts
@@ -0,0 +1,94 @@
+/**
+ * Known-good performance baselines.
+ *
+ * Each baseline captures the measured constants + pass/fail thresholds for one
+ * catalog size, so `regression run` can assert a fresh measurement has not
+ * regressed against it. The seed entry `catalog61k-2026-07` is the 2026-07
+ * blueprint-pooling validation program (see scripts/scale-validate/V2-RESULTS.md
+ * and SIZING.md); the numbers below are transcribed from those documents.
+ */
+
+export interface Baseline {
+  name: string;
+  capturedAt: string;
+  catalogPgClassRows: number;
+  instanceHeapKBPerRow: number;
+  pgIntrospectionSpikeKBPerRow: number;
+  minViableHeapMB: number;
+  baseReserveMB: number;
+  buildReserveMB: number;
+  zeroMarginal: { tenants: number[]; heapMaxMB: number[] };
+  healthy: { rps: number; p99Ms: number; errRate: number };
+  capacityByHeapMB: Record<string, number>;
+  thresholds: {
+    maxInstanceHeapKBPerRow: number;
+    maxZeroMarginalDeltaMB: number;
+    maxHealthyErrRate: number;
+    maxHealthyP99Ms: number;
+    maxHeapSlopeMBPerHour: number;
+  };
+  // Thresholds + constants used ONLY by the `deep`-tier scenario checks
+  // (src/regression/scenarios.ts). Kept separate from `thresholds` so the
+  // quick/standard comparator surface is unchanged.
+  deepThresholds: {
+    // multi-api-residency: allowed |measured - (base + R*I)| / (base + R*I).
+    multiApiHeapTolerance: number;
+    // settings-variant-split: distinct pooled instances expected for one
+    // relation shape when a settings flag differs (control g=[] vs variant g=[…]).
+    settingsSplitExpectedInstances: number;
+    // partition-creep advisory ceiling: projected new catalog rows / tenant / month.
+    partitionCreepMaxRowsPerTenantMonth: number;
+  };
+  deepConstants: {
+    // Number of routable API surfaces per tenant (admin/agent/api/auth/compute/
+    // config/objects/usage — notifications is unrouted). Informational.
+    apiSurfacesRoutable: number;
+  };
+}
+
+export const catalog61k_2026_07: Baseline = {
+  name: 'catalog61k-2026-07',
+  capturedAt: '2026-07-03',
+  catalogPgClassRows: 61238,
+  instanceHeapKBPerRow: 21,
+  pgIntrospectionSpikeKBPerRow: 37,
+  minViableHeapMB: 1536,
+  baseReserveMB: 256,
+  buildReserveMB: 768,
+  zeroMarginal: { tenants: [10, 20, 32], heapMaxMB: [1460.1, 1459.6, 1464.1] },
+  healthy: { rps: 188, p99Ms: 21, errRate: 0 },
+  capacityByHeapMB: { '2048': 1, '3584': 2 },
+  thresholds: {
+    maxInstanceHeapKBPerRow: 28,
+    maxZeroMarginalDeltaMB: 100,
+    maxHealthyErrRate: 0.005,
+    maxHealthyP99Ms: 150,
+    maxHeapSlopeMBPerHour: 5
+  },
+  deepThresholds: {
+    multiApiHeapTolerance: 0.2,
+    settingsSplitExpectedInstances: 2,
+    partitionCreepMaxRowsPerTenantMonth: 200
+  },
+  deepConstants: {
+    apiSurfacesRoutable: 8
+  }
+};
+
+export const BASELINES: Record<string, Baseline> = {
+  [catalog61k_2026_07.name]: catalog61k_2026_07
+};
+
+export const DEFAULT_BASELINE = catalog61k_2026_07.name;
+
+export function getBaseline(name: string): Baseline {
+  const bl = BASELINES[name];
+  if (!bl) {
+    throw new Error(`unknown baseline '${name}'. known: ${Object.keys(BASELINES).join(', ')}`);
+  }
+  return bl;
+}
+
+export function listBaselines(): Baseline[] {
+  return Object.values(BASELINES);
+}
diff --git a/packages/perf-harness/src/regression/compare.ts b/packages/perf-harness/src/regression/compare.ts
new file mode 100644
index 0000000000..eac786eb10
--- /dev/null
+++ b/packages/perf-harness/src/regression/compare.ts
@@ -0,0 +1,143 @@
+/**
+ * Pure regression comparator.
+ *
+ * `compareToBaseline` maps a set of fresh measurements against a `Baseline`'s
+ * thresholds and returns one `CheckResult` per assertion it can evaluate (a
+ * measurement that was not taken produces no check). `verdictFromChecks`
+ * collapses the checks into the suite's tri-state exit code: a failed `bleed`
+ * check is exit 2 (cross-tenant data bleed — the one violation that is never
+ * "just slow"), any other failure is exit 1, all-pass is exit 0.
+ *
+ * ADVISORY checks (the `deep`-tier scenario probes in ./scenarios.ts set
+ * `advisory: true`) are reported like any other check but are IGNORED by
+ * `verdictFromChecks` — an advisory failure never flips `pass`, `bleed`, or the
+ * exit code. They exist to surface findings (per-instance heap cost, partition
+ * creep projection, realtime dedicated-instance behaviour) without turning an
+ * informational regression into a gate failure.
+ *
+ * No IO, no process — this is the unit-tested heart of `regression run`.
+ */
+import { Baseline } from './baselines';
+
+export interface CheckResult {
+  name: string;
+  pass: boolean;
+  value: number | boolean | null;
+  threshold: number | boolean | null;
+  note: string;
+  // When true this check is informational: it is printed + recorded but never
+  // contributes to the suite verdict / exit code (see verdictFromChecks).
+  advisory?: boolean;
+}
+
+export interface MeasuredRegression {
+  instanceHeapKBPerRow?: number;
+  healthy?: { errRate?: number; p99Ms?: number };
+  zeroMarginalDeltaMB?: number;
+  thrashCrashed?: boolean;
+  bleedViolations?: number;
+  heapSlopeMBPerHour?: number;
+}
+
+const has = (v: any): boolean => v !== undefined && v !== null;
+
+export function compareToBaseline(measured: MeasuredRegression, baseline: Baseline): CheckResult[] {
+  const t = baseline.thresholds;
+  const checks: CheckResult[] = [];
+
+  if (has(measured.instanceHeapKBPerRow)) {
+    const value = measured.instanceHeapKBPerRow;
+    checks.push({
+      name: 'instance-heap',
+      value,
+      threshold: t.maxInstanceHeapKBPerRow,
+      pass: value <= t.maxInstanceHeapKBPerRow,
+      note: `KB retained heap per pg_class row (baseline ${baseline.instanceHeapKBPerRow})`
+    });
+  }
+
+  if (measured.healthy && has(measured.healthy.errRate)) {
+    const value = measured.healthy.errRate;
+    checks.push({
+      name: 'healthy-single-bp:errRate',
+      value,
+      threshold: t.maxHealthyErrRate,
+      pass: value <= t.maxHealthyErrRate,
+      note: 'error rate on a single-blueprint subset at capacity'
+    });
+  }
+  if (measured.healthy && has(measured.healthy.p99Ms)) {
+    const value = measured.healthy.p99Ms;
+    checks.push({
+      name: 'healthy-single-bp:p99',
+      value,
+      threshold: t.maxHealthyP99Ms,
+      pass: value <= t.maxHealthyP99Ms,
+      note: 'p99 latency (ms) on a single-blueprint subset at capacity'
+    });
+  }
+
+  if (has(measured.zeroMarginalDeltaMB)) {
+    const value = measured.zeroMarginalDeltaMB;
+    checks.push({
+      name: 'zero-marginal-tenants',
+      value,
+      threshold: t.maxZeroMarginalDeltaMB,
+      pass: value <= t.maxZeroMarginalDeltaMB,
+      note: 'heapMax delta (MB) between low and high tenant-count steps (same blueprint)'
+    });
+  }
+
+  if (has(measured.thrashCrashed)) {
+    checks.push({
+      name: 'thrash-not-crash',
+      value: measured.thrashCrashed,
+      threshold: false,
+      pass: measured.thrashCrashed === false,
+      note: 'server must SURVIVE over-capacity diversity; degraded latency/errors are expected, not failures'
+    });
+  }
+
+  if (has(measured.heapSlopeMBPerHour)) {
+    const value = measured.heapSlopeMBPerHour;
+    checks.push({
+      name: 'heap-slope',
+      value,
+      threshold: t.maxHeapSlopeMBPerHour,
+      pass: value <= t.maxHeapSlopeMBPerHour,
+      note: 'last-half heap growth (MB/hour) — the soak leak signal'
+    });
+  }
+
+  // Bleed is evaluated last and is the exit-2 trigger. Always emit it when a
+  // measurement exists (0 violations is the healthy, common case).
+  if (has(measured.bleedViolations)) {
+    const value = measured.bleedViolations;
+    checks.push({
+      name: 'bleed',
+      value,
+      threshold: 0,
+      pass: value === 0,
+      note: 'cross-tenant sentinel violations across all steps (must be zero)'
+    });
+  }
+
+  return checks;
+}
+
+export interface Verdict {
+  pass: boolean;
+  bleed: boolean;
+  exitCode: 0 | 1 | 2;
+  failed: string[];
+}
+
+export function verdictFromChecks(checks: CheckResult[]): Verdict {
+  // Advisory checks are informational only — they never gate the verdict.
+  const graded = checks.filter((c) => !c.advisory);
+  const failed = graded.filter((c) => !c.pass).map((c) => c.name);
+  const bleed = graded.some((c) => c.name === 'bleed' && !c.pass);
+  const pass = failed.length === 0;
+  const exitCode: 0 | 1 | 2 = bleed ? 2 : pass ? 0 : 1;
+  return { pass, bleed, exitCode, failed };
+}
diff --git a/packages/perf-harness/src/regression/scenarios.ts b/packages/perf-harness/src/regression/scenarios.ts
new file mode 100644
index 0000000000..1234694796
--- /dev/null
+++ b/packages/perf-harness/src/regression/scenarios.ts
@@ -0,0 +1,1209 @@
+/**
+ * Deep-tier scenario checks — the four multi-surface / settings / realtime /
+ * partition probes that run ONLY under `regression run --suite deep`.
+ *
+ * Each scenario is:
+ *   - individually skippable (`--only` / `--skip`, via scenarioEnabled)
+ *   - self-contained: it boots its OWN fresh server(s) via run/server.spawnServer
+ *     and drives light traffic itself via core/gql.gqlFetch (per RECON finding 3);
+ *     no ramp/harness child is required
+ *   - reversible: every mutating SQL statement is paired with its exact inverse
+ *     in a `finally`, and settings mutations refuse to run (skip) if the target
+ *     rows already exist, so the rig is left EXACTLY as found
+ *   - guardrailed: every PG + server port flows through the existing
+ *     assertPortAllowed guardrail (spawnServer + pgConfigFromArgv already do this;
+ *     the ctx handed in is already validated by the suite)
+ *
+ * Only `multi-api-residency` is a GRADEABLE check (the deterministic pooling
+ * residency invariant). Everything else is ADVISORY: reported, never gating.
+ *
+ * The PURE helpers (rewriteHostPrefix / deriveSurfaceFleets / computeCreepProjection
+ * / parsePartitionIntervalSeconds / scenarioEnabled / buildTeardownLeftoverWarning
+ * / buildResidencyAbortCheck) are exported for unit tests and touch no PG or network.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { assertPortAllowed, PgConfig } from '../core/config';
+import { buildSubset, Tenant } from '../core/fleetfile';
+import { gqlFetch, GqlResponse } from '../core/gql';
+import { withFreshClient } from '../core/pgc';
+import { ensureParentDir, readJsonl } from '../core/proc';
+import { spawnServer, SpawnedServer } from '../run/server';
+import { Baseline } from './baselines';
+import { CheckResult } from './compare';
+import {
+  buildCreateProbePartition,
+  buildDropProbePartition,
+  buildPartConfigLikePatterns,
+  buildSettingsInsert,
+  DATABASE_ID_BY_NAME_SQL,
+  IS_PARTITIONED_PARENT_SQL,
+  PART_CONFIG_FOR_TENANT_SQL,
+  PG_CLASS_COUNT_SQL,
+  SCHEMA_UPDATE_CHANNEL,
+  SCHEMA_UPDATE_NOTIFY_SQL,
+  SETTINGS_DELETE_SQL,
+  SETTINGS_EXISTING_SQL,
+  SettingsFlag,
+  splitParentTable,
+  TENANT_SCHEMAS_SQL
+} from './sql';
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+const round1 = (n: number): number => Math.round(n * 10) / 10;
+const round2 = (n: number): number => Math.round(n * 100) / 100;
+const round4 = (n: number): number => Math.round(n * 10000) / 10000;
+const MB = (bytes: number): number => round1(bytes / 1024 / 1024);
+
+// ===========================================================================
+// Registry + filter (pure)
+// ===========================================================================
+
+export const DEEP_SCENARIOS = [
+  'multi-api-residency',
+  'settings-variant-split',
+  'realtime-dedicated-cost',
+  'partition-creep'
+] as const;
+
+export type DeepScenarioName = (typeof DEEP_SCENARIOS)[number];
+
+// `--only a,b` restricts to that set; `--skip a,b` removes from the set; skip
+// wins over only. Empty/absent `only` means "all not skipped".
+export function scenarioEnabled(name: string, only?: string[] | null, skip?: string[] | null): boolean {
+  if (skip && skip.includes(name)) return false;
+  if (only && only.length > 0) return only.includes(name);
+  return true;
+}
+
+// ===========================================================================
+// Host-rewrite derivation (pure)
+// ===========================================================================
+
+// Rewrite the leading `<from>-` label of a virtual host to `<to>-`. The rig's
+// tenant hosts are `api-<tenant>-<hex8>.<domain>`; the admin/usage/… surfaces
+// share the tenant+hex+domain and differ only in this first label. Returns null
+// when `host` does not start with `<from>-`.
+export function rewriteHostPrefix(host: string, fromPrefix: string, toPrefix: string): string | null {
+  if (!host || typeof host !== 'string') return null;
+  const from = `${fromPrefix}-`;
+  if (!host.startsWith(from)) return null;
+  return `${toPrefix}-${host.slice(from.length)}`;
+}
+
+export interface SurfaceFleet {
+  surface: string;
+  tenants: Tenant[]; // each tenant's apiHost rewritten to this surface's host
+}
+
+// Derive a per-surface fleet by rewriting each tenant's apiHost. `surfaces`
+// entries other than 'api' rewrite the `api-` label to `<surface>-`; 'api'
+// keeps the host as-is. authHost is preserved unchanged (login always uses the
+// auth surface). Tenants without an apiHost, or whose apiHost cannot be
+// rewritten, are dropped from that surface's fleet (with a warning).
+export function deriveSurfaceFleets(
+  tenants: Tenant[],
+  surfaces: string[]
+): { fleets: SurfaceFleet[]; warnings: string[] } {
+  const warnings: string[] = [];
+  const fleets: SurfaceFleet[] = [];
+  for (const surface of surfaces) {
+    const out: Tenant[] = [];
+    for (const t of tenants) {
+      if (!t.apiHost) {
+        warnings.push(`${t.dbname}: no apiHost; dropped from ${surface} surface`);
+        continue;
+      }
+      const host = surface === 'api' ? t.apiHost : rewriteHostPrefix(t.apiHost, 'api', surface);
+      if (!host) {
+        warnings.push(`${t.dbname}: apiHost '${t.apiHost}' has no 'api-' label; dropped from ${surface} surface`);
+        continue;
+      }
+      out.push({ ...t, apiHost: host });
+    }
+    fleets.push({ surface, tenants: out });
+  }
+  return { fleets, warnings };
+}
+
+// ===========================================================================
+// Partition-creep math (pure)
+// ===========================================================================
+
+// Average calendar month (30.4375 d) — matches the 'month' unit weight in
+// parsePartitionIntervalSeconds so a monthly interval yields exactly 1/month.
+export const SECONDS_PER_MONTH = 30.4375 * 24 * 3600;
+
+const INTERVAL_UNIT_SECONDS: Record<string, number> = {
+  sec: 1, secs: 1, second: 1, seconds: 1,
+  min: 60, mins: 60, minute: 60, minutes: 60,
+  hour: 3600, hours: 3600, hr: 3600, hrs: 3600,
+  day: 86400, days: 86400,
+  week: 604800, weeks: 604800,
+  mon: SECONDS_PER_MONTH, mons: SECONDS_PER_MONTH, month: SECONDS_PER_MONTH, months: SECONDS_PER_MONTH,
+  year: 365.25 * 24 * 3600, years: 365.25 * 24 * 3600
+};
+
+// Parse a Postgres/partman interval string ('1 day', '7 days', '1 mon',
+// '01:00:00', '1 day 06:00:00') into seconds. Returns null when nothing
+// recognizable is found (e.g. an id-based partition interval like '10000').
+export function parsePartitionIntervalSeconds(interval: string): number | null {
+  if (!interval || typeof interval !== 'string') return null;
+  const s = interval.trim().toLowerCase();
+  if (!s) return null;
+
+  // Pure clock form HH:MM:SS.
+  const pureClock = /^(\d+):(\d{2}):(\d{2})$/.exec(s);
+  if (pureClock) return Number(pureClock[1]) * 3600 + Number(pureClock[2]) * 60 + Number(pureClock[3]);
+
+  let total = 0;
+  let matched = false;
+  const re = /(\d+(?:\.\d+)?)\s*([a-z]+)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(s)) !== null) {
+    const weight = INTERVAL_UNIT_SECONDS[m[2]];
+    if (weight === undefined) continue;
+    total += Number(m[1]) * weight;
+    matched = true;
+  }
+  // Trailing clock component in a mixed interval, e.g. '1 day 06:00:00'.
+  const trailingClock = /(?:^|\s)(\d+):(\d{2}):(\d{2})(?:\s|$)/.exec(s);
+  if (trailingClock && matched) {
+    total += Number(trailingClock[1]) * 3600 + Number(trailingClock[2]) * 60 + Number(trailingClock[3]);
+  }
+  return matched ? total : null;
+}
+
+export interface CreepInputs {
+  rowsPerPartition: number;
+  partitionedParents: number;
+  partitionIntervalSeconds: number;
+  instanceHeapKBPerRow: number;
+}
+
+export interface CreepProjection {
+  intervalsPerMonth: number;
+  partitionsPerMonth: number;
+  rowsPerTenantPerMonth: number;
+  heapCreepMBPerMonthPerTenant: number;
+}
+
+// Project monthly catalog + heap creep for ONE tenant from a measured
+// rows-per-partition, the count of partitioned parents, and the (uniform)
+// partition interval. heap uses the sizing constant KB/pg_class-row.
+export function computeCreepProjection(inp: CreepInputs): CreepProjection {
+  const s = inp.partitionIntervalSeconds;
+  const intervalsPerMonth = s > 0 ? SECONDS_PER_MONTH / s : 0;
+  const parents = Math.max(0, inp.partitionedParents);
+  const rowsPer = Math.max(0, inp.rowsPerPartition);
+  const kbPerRow = Math.max(0, inp.instanceHeapKBPerRow);
+  const partitionsPerMonth = parents * intervalsPerMonth;
+  const rowsPerTenantPerMonth = partitionsPerMonth * rowsPer;
+  const heapCreepMBPerMonthPerTenant = (rowsPerTenantPerMonth * kbPerRow) / 1024;
+  return {
+    intervalsPerMonth: round2(intervalsPerMonth),
+    partitionsPerMonth: round2(partitionsPerMonth),
+    rowsPerTenantPerMonth: round2(rowsPerTenantPerMonth),
+    heapCreepMBPerMonthPerTenant: round2(heapCreepMBPerMonthPerTenant)
+  };
+}
+
+// ===========================================================================
+// Scenario context + result
+// ===========================================================================
+
+export interface ScenarioContext {
+  suite: string;
+  pg: PgConfig;
+  port: number;
+  deepHeapMb: number; // --deep-heap-mb (multi-api residency server)
+  heapMb: number; // regression --heap-mb (the capacity-2 thrash sub-check)
+  outDir: string;
+  repoRoot: string;
+  serverCmd: string[];
+  allowHub: boolean;
+  catalogRows: number;
+  baseline: Baseline;
+  fleet: Tenant[];
+  drifted: any;
+  sameBpRegex?: string;
+  only?: string[] | null;
+  skip?: string[] | null;
+  creds: { email: string; password: string | null };
+}
+
+export interface ScenarioResult {
+  name: string;
+  ran: boolean;
+  skipped?: string;
+  checks: CheckResult[];
+  data?: any;
+  warnings?: string[];
+  error?: string;
+}
+
+const skippedResult = (name: string, reason: string): ScenarioResult => ({
+  name,
+  ran: false,
+  skipped: reason,
+  checks: []
+});
+
+// ===========================================================================
+// Server + metrics helpers (internal)
+// ===========================================================================
+
+interface BootedServer {
+  server: SpawnedServer;
+  metricsFile: string;
+}
+
+async function bootFreshServer(
+  ctx: ScenarioContext,
+  tag: string,
+  heapMb: number,
+  opts?: { metricsEndpoint?: boolean }
+): Promise<BootedServer> {
+  assertPortAllowed(ctx.port, ctx.allowHub, 'server-port');
+  const metricsFile = path.join(ctx.outDir, `deep-metrics-${tag}.jsonl`);
+  if (fs.existsSync(metricsFile)) fs.rmSync(metricsFile);
+  // Size the LRU cache from the MEASURED per-instance heap (catalog pg_class
+  // rows x baseline KB/row), NOT graphile-cache's 512MB default. Without this
+  // the server derives GRAPHILE_CACHE_MAX for ~0.5GB instances (6 @3584MB,
+  // 13 @7168MB) while each real instance retains ~1.3GB here — it would admit
+  // far more instances than the heap can hold, defeat ensureCacheHeadroom's
+  // evict-before-build guard, and risk a genuine OOM/SIGABRT. At the measured
+  // size the cap matches the baseline capacity model (e.g. 2 @3584MB), so the
+  // thrash sub-check's "cap < surfaces" premise and the residency hot-set-fits
+  // premise both actually hold.
+  const instanceHeapBytes = Math.max(1, Math.round(ctx.catalogRows * ctx.baseline.instanceHeapKBPerRow * 1024));
+  const server = await spawnServer({
+    name: `deep-${tag}`,
+    port: ctx.port,
+    heapMb,
+    metricsFile,
+    pg: ctx.pg,
+    repoRoot: ctx.repoRoot,
+    outDir: ctx.outDir,
+    serverCmd: ctx.serverCmd,
+    instanceHeapBytes,
+    metricsEndpoint: opts?.metricsEndpoint === true,
+    detached: false,
+    allowHub: ctx.allowHub
+  });
+  return { server, metricsFile };
+}
+
+async function stopServer(server: SpawnedServer | null): Promise<void> {
+  if (!server) return;
+  try {
+    await server.stop();
+  } catch {
+    /* already gone */
+  }
+  // Let the OS release the listen socket before the next scenario re-binds it.
+  await sleep(2000);
+}
+
+const latestMetrics = (metricsFile: string): any | null => {
+  const rows = readJsonl(metricsFile);
+  return rows.length ? rows[rows.length - 1] : null;
+};
+
+const cacheSizeOf = (s: any): number => (s && s.cache && typeof s.cache.size === 'number' ? s.cache.size : 0);
+const cacheKeysOf = (s: any): number => (s && s.cache && typeof s.cache.keys === 'number' ? s.cache.keys : 0);
+const buildsOf = (s: any): number => (s && s.counters && typeof s.counters.builds === 'number' ? s.counters.builds : 0);
+const heapUsedMBOf = (s: any): number => (s && typeof s.heapUsed === 'number' ? MB(s.heapUsed) : 0);
+const lruEvictionsOf = (s: any): number => (s && s.counters && s.counters.evictions ? s.counters.evictions.lru || 0 : 0);
+const evictionsTotalOf = (s: any): number => {
+  const e = s && s.counters && s.counters.evictions;
+  return e ? (e.lru || 0) + (e.ttl || 0) + (e.manual || 0) + (e.governor || 0) : 0;
+};
+
+// Wait until the metrics sampler has written at least one line (~10s cadence).
+async function waitForBaselineSample(metricsFile: string, timeoutMs = 90000): Promise<any | null> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const s = latestMetrics(metricsFile);
+    if (s) return s;
+    await sleep(2000);
+  }
+  return latestMetrics(metricsFile);
+}
+
+// Wait for a metrics sample strictly NEWER than `afterTs` (the sampler writes a
+// fresh line ~every 10s). Used to snapshot counters AFTER an action completes so
+// a stale line can't misattribute the action's builds/evictions to a later
+// window. Falls back to the latest sample on timeout.
+async function waitForSampleAfter(metricsFile: string, afterTs: string | undefined, timeoutMs = 15000): Promise<any | null> {
+  const deadline = Date.now() + timeoutMs;
+  let last = latestMetrics(metricsFile);
+  while (Date.now() < deadline) {
+    last = latestMetrics(metricsFile);
+    if (last && (!afterTs || last.ts !== afterTs)) return last;
+    await sleep(1000);
+  }
+  return last;
+}
+
+const COLD_TIMEOUT_MS = 300000;
+const WARM_TIMEOUT_MS = 15000;
+
+// A `{ __typename }` probe — builds the tenant's PostGraphile instance on first
+// hit (no auth, universally valid; see RECON finding 4). Retries transient 503
+// SERVICE_ROTATING while the instance builds.
+async function coldProbe(host: string, port: number, retries = 8): Promise<GqlResponse> {
+  let r: GqlResponse = { status: 0, ok: false, elapsedMs: 0, error: 'not-attempted' };
+  for (let i = 0; i <= retries; i++) {
+    r = await gqlFetch({ host, port, query: '{ __typename }', timeoutMs: COLD_TIMEOUT_MS });
+    if (r.status !== 503) return r;
+    await sleep(1500);
+  }
+  return r;
+}
+
+const warmProbe = (host: string, port: number): Promise<GqlResponse> =>
+  gqlFetch({ host, port, query: '{ __typename }', timeoutMs: WARM_TIMEOUT_MS });
+
+const answered = (r: GqlResponse): boolean =>
+  r.status === 200 && !r.error && !(r.json && Array.isArray(r.json.errors) && r.json.errors.length > 0);
+
+// Pick up to N group-0 (single-blueprint) tenants that carry the fields a
+// scenario needs. buildSubset is the same pure selector the standard checks use.
+function pickGroup0(ctx: ScenarioContext, n: number): Tenant[] {
+  try {
+    return buildSubset(ctx.fleet, ctx.drifted || {}, { tenants: n, sameBpRegex: ctx.sameBpRegex }).tenants;
+  } catch {
+    return [];
+  }
+}
+
+// Resolve a tenant's control-plane database id (uuid) — from the manifest when
+// present, else by name from metaschema_public.database.
+async function resolveDatabaseId(client: any, t: Tenant): Promise<string | null> {
+  if (t.databaseId) return String(t.databaseId);
+  const r = await client.query(DATABASE_ID_BY_NAME_SQL, [t.dbname]);
+  return r.rows[0] ? String(r.rows[0].id) : null;
+}
+
+// Resolve db ids for the target tenants and REFUSE to proceed (throw 'SKIP: …')
+// if any already carry a settings row — this phase performs NO mutation, so a
+// skip here leaves the rig exactly as found.
+async function resolveAndPrecheck(ctx: ScenarioContext, tenants: Tenant[]): Promise<string[]> {
+  return withFreshClient(ctx.pg, async (client): Promise<string[]> => {
+    const ids: string[] = [];
+    for (const t of tenants) {
+      const id = await resolveDatabaseId(client, t);
+      if (!id) throw new Error(`could not resolve database id for ${t.dbname}`);
+      ids.push(id);
+    }
+    const existing = await client.query(SETTINGS_EXISTING_SQL, [ids]);
+    if (existing.rows.length > 0) {
+      throw new Error(
+        `SKIP: ${existing.rows.length} target tenant(s) already carry a database_settings row; ` +
+          'refusing to mutate (would break exact-restore teardown)'
+      );
+    }
+    return ids;
+  });
+}
+
+// INSERT one settings row per id (all requested flags set true), pushing each
+// committed id into `inserted` so teardown deletes PRECISELY what landed — even
+// if a later INSERT throws mid-way.
+async function seedSettings(ctx: ScenarioContext, ids: string[], flags: SettingsFlag[], inserted: string[]): Promise<void> {
+  const insertSql = buildSettingsInsert(flags);
+  const values = flags.map(() => true);
+  await withFreshClient(ctx.pg, async (client): Promise<void> => {
+    for (const id of ids) {
+      await client.query(insertSql, [id, ...values]);
+      inserted.push(id);
+    }
+  });
+}
+
+// DELETE exactly the seeded rows + a best-effort schema:update NOTIFY, then
+// report how many survived. Never throws (teardown failures become warnings);
+// an empty id list is a no-op.
+async function teardownSettings(
+  ctx: ScenarioContext,
+  ids: string[]
+): Promise<{ rowsRemaining: number | null; error: string | null }> {
+  if (!ids.length) return { rowsRemaining: 0, error: null };
+  try {
+    return await withFreshClient(ctx.pg, async (client): Promise<{ rowsRemaining: number; error: null }> => {
+      await client.query(SETTINGS_DELETE_SQL, [ids]);
+      for (const id of ids) {
+        await client.query(SCHEMA_UPDATE_NOTIFY_SQL, [SCHEMA_UPDATE_CHANNEL, id]).catch(() => {});
+      }
+      const left = await client.query(SETTINGS_EXISTING_SQL, [ids]);
+      return { rowsRemaining: left.rows.length, error: null };
+    });
+  } catch (e: any) {
+    return { rowsRemaining: null, error: String(e && e.message ? e.message : e) };
+  }
+}
+
+// Surface a non-exact teardown into the suite warnings: when a scenario's
+// teardown left settings rows behind (rowsRemaining > 0) the rig is no longer
+// exactly as found, and that must be VISIBLE in the verdict output — not merely
+// recorded in `data`. Returns the warning string, or null when nothing leaked
+// (0 rows) or the leftover count is unknown (null — the teardown itself already
+// pushed its own error warning). Pure (no PG/IO); exported for unit tests.
+export function buildTeardownLeftoverWarning(scenario: string, rowsRemaining: number | null): string | null {
+  if (typeof rowsRemaining === 'number' && rowsRemaining > 0) {
+    return `${scenario} TEARDOWN left ${rowsRemaining} database_settings row(s) behind (manual cleanup may be needed)`;
+  }
+  return null;
+}
+
+// ===========================================================================
+// 1) multi-api-residency  (GRADEABLE residency + ADVISORY heap / thrash)
+// ===========================================================================
+
+const SURFACES = ['api', 'admin', 'usage'] as const; // + auth via authHost
+
+// Fail-CLOSED CheckResult for the residency invariant when the scenario aborts
+// before it can be measured. NON-advisory (no `advisory` flag) so it GATES the
+// verdict — the whole point is that the suite must not silently PASS when the
+// one gradeable deep check never ran. Pure; exported for unit tests.
+export function buildResidencyAbortCheck(errorMessage: string): CheckResult {
+  return {
+    name: 'multi-api-residency',
+    pass: false,
+    value: null,
+    threshold: 0,
+    note: `residency invariant NOT established — scenario aborted before measurement: ${errorMessage}`
+  };
+}
+
+export async function runMultiApiResidency(ctx: ScenarioContext): Promise<ScenarioResult> {
+  const name = 'multi-api-residency';
+  const warnings: string[] = [];
+
+  const tenants = pickGroup0(ctx, 10).filter((t) => t.apiHost);
+  if (tenants.length === 0) return skippedResult(name, 'no group-0 tenants with an apiHost');
+
+  // Derive api/admin/usage surface fleets by host-rewrite; auth uses authHost.
+  const { fleets, warnings: dw } = deriveSurfaceFleets(tenants, SURFACES as unknown as string[]);
+  warnings.push(...dw);
+  const surfaceTargets: { surface: string; hosts: string[] }[] = [];
+  for (const f of fleets) {
+    const hosts = f.tenants.map((t) => t.apiHost).filter(Boolean) as string[];
+    if (hosts.length) surfaceTargets.push({ surface: f.surface, hosts });
+  }
+  const authHosts = tenants.map((t) => t.authHost).filter(Boolean) as string[];
+  if (authHosts.length) surfaceTargets.push({ surface: 'auth', hosts: authHosts });
+
+  const R = surfaceTargets.length;
+  if (R < 2) return skippedResult(name, `only ${R} routable surface(s) derivable; need >= 2`);
+
+  const data: any = {
+    surfaces: surfaceTargets.map((s) => s.surface),
+    tenantCount: tenants.length,
+    expectedResidency: R
+  };
+
+  // -- primary server at --deep-heap-mb (capacity should be >= R) -----------
+  let booted: BootedServer | null = null;
+  const checks: CheckResult[] = [];
+  try {
+    booted = await bootFreshServer(ctx, 'multiapi', ctx.deepHeapMb);
+    const base = await waitForBaselineSample(booted.metricsFile);
+    if (!base) throw new Error('no baseline metrics sample from the deep-heap server');
+    const baseHeapMB = heapUsedMBOf(base);
+    data.deepHeapMb = ctx.deepHeapMb;
+    data.baseHeapMB = baseHeapMB;
+
+    // Cold-build every surface across every tenant. NOTE: on THIS rig each
+    // (surface, tenant) is its OWN blueprint instance — computeBlueprintKey folds
+    // the per-tenant dbname into the key (middleware/blueprint.ts) and every
+    // tenant here has a distinct dbname, so tenants do NOT collapse to one
+    // instance per surface. This sweep is advisory reachability; the gradeable
+    // invariant below is pool REUSE of the held-hot set, not cross-tenant collapse.
+    const coldOk: Record<string, number> = {};
+    for (const st of surfaceTargets) {
+      coldOk[st.surface] = 0;
+      for (const host of st.hosts) {
+        const r = await coldProbe(host, ctx.port);
+        if (answered(r)) coldOk[st.surface]++;
+      }
+    }
+    data.coldOk = coldOk;
+
+    // Optional faithful "auth via login" — best effort, records nothing gating.
+    if (ctx.creds.password && authHosts.length) {
+      const login = await attemptSignIn(authHosts[0], ctx.port, ctx.creds);
+      data.authLogin = login;
+    }
+
+    // -- prime, then hold ONE host per surface HOT for ~120s -----------------
+    // Gradeable invariant: pool REUSE. Once the R hot instances are resident,
+    // re-serving them must trigger ZERO rebuilds (the pool returns the CACHED
+    // instance, not a fresh build per request) and ZERO LRU evictions (the hot
+    // set fits — which is why the server is sized from the measured per-instance
+    // heap; see bootFreshServer). A pooling regression — unstable keys, or a
+    // collapse that mints a per-request instance — surfaces here as the builds
+    // counter CLIMBING during the hold. cache.size >= R alone can't detect that
+    // (>= R instances already exist from the cold sweep). The cold sweep above
+    // may have LRU-evicted the hot hosts, so PRIME them, then measure the
+    // builds/eviction DELTA across the steady hold.
+    const holdHosts = surfaceTargets.map((st) => ({ surface: st.surface, host: st.hosts[0] }));
+    for (const h of holdHosts) await coldProbe(h.host, ctx.port);
+    // Snapshot counters from a sample taken AFTER the prime builds land, so their
+    // builds are not counted against the steady hold below.
+    const primed = await waitForSampleAfter(booted.metricsFile, latestMetrics(booted.metricsFile)?.ts);
+    const buildsAtHoldStart = buildsOf(primed);
+    const lruAtStart = lruEvictionsOf(primed);
+    let maxCacheSize = cacheSizeOf(primed);
+    let maxHeapMB = Math.max(baseHeapMB, heapUsedMBOf(primed));
+    const surfacesAnswered = new Set<string>();
+    const holdMs = 120000;
+    const holdDeadline = Date.now() + holdMs;
+    while (Date.now() < holdDeadline) {
+      for (const h of holdHosts) {
+        const r = await warmProbe(h.host, ctx.port);
+        if (answered(r)) surfacesAnswered.add(h.surface);
+      }
+      const s = latestMetrics(booted.metricsFile);
+      if (s) {
+        maxCacheSize = Math.max(maxCacheSize, cacheSizeOf(s));
+        maxHeapMB = Math.max(maxHeapMB, heapUsedMBOf(s));
+      }
+      await sleep(1500);
+    }
+    const lastSample = latestMetrics(booted.metricsFile);
+    const buildsDuringHold = Math.max(0, buildsOf(lastSample) - buildsAtHoldStart);
+    const lruDuringHold = Math.max(0, lruEvictionsOf(lastSample) - lruAtStart);
+    const cacheSizeReached = Math.max(maxCacheSize, cacheSizeOf(lastSample));
+    const buildsTotal = buildsOf(lastSample);
+
+    data.residency = {
+      perTenantKeys: true, // dbname is folded into the bp key on this rig — no cross-tenant collapse
+      cacheSizeReached,
+      cacheKeysLast: cacheKeysOf(lastSample),
+      buildsTotal,
+      buildsDuringHold,
+      lruEvictionsDuringHold: lruDuringHold,
+      surfacesAnswered: [...surfacesAnswered],
+      maxHeapMB
+    };
+
+    // Deterministic given a correctly heap-sized cache: steady-state re-serving
+    // of the R hot surfaces rebuilds nothing and evicts nothing, and every
+    // surface keeps answering.
+    const residencyOk =
+      buildsDuringHold === 0 && lruDuringHold === 0 && surfacesAnswered.size === R && cacheSizeReached >= R;
+    checks.push({
+      name: 'multi-api-residency',
+      pass: residencyOk,
+      value: buildsDuringHold,
+      threshold: 0,
+      note:
+        `${R} surfaces (${surfaceTargets.map((s) => s.surface).join('/')}) held hot ~120s ` +
+        `(per-tenant dbname keys — no cross-tenant collapse on this rig): rebuilds during hold ` +
+        `${buildsDuringHold} (must be 0 — pool reuse), LRU evictions ${lruDuringHold} (must be 0 — hot ` +
+        `set resident), surfaces answering ${surfacesAnswered.size}/${R}, cache.size ${cacheSizeReached}`
+    });
+
+    // -- ADVISORY: heap plateau consistent with base + R*I (±tolerance) ------
+    const perInstanceMB = (ctx.baseline.instanceHeapKBPerRow * ctx.catalogRows) / 1024;
+    const expectedPlateauMB = baseHeapMB + R * perInstanceMB;
+    const deltaRatio = expectedPlateauMB > 0 ? Math.abs(maxHeapMB - expectedPlateauMB) / expectedPlateauMB : 1;
+    const tol = ctx.baseline.deepThresholds.multiApiHeapTolerance;
+    const measuredPerInstanceMB = R > 0 ? (maxHeapMB - baseHeapMB) / R : 0;
+    data.heapPlateau = {
+      perInstanceExpectedMB: round1(perInstanceMB),
+      expectedPlateauMB: round1(expectedPlateauMB),
+      measuredMaxHeapMB: round1(maxHeapMB),
+      measuredPerInstanceMB: round1(measuredPerInstanceMB),
+      deltaRatio: round4(deltaRatio),
+      tolerance: tol
+    };
+    checks.push({
+      name: 'multi-api-heap-plateau',
+      advisory: true,
+      pass: deltaRatio <= tol,
+      value: round1(maxHeapMB),
+      threshold: round1(expectedPlateauMB),
+      note:
+        `heapUsed plateau ${round1(maxHeapMB)}MB vs base+${R}*I=${round1(expectedPlateauMB)}MB ` +
+        `(±${tol}; measured ~${round1(measuredPerInstanceMB)}MB/instance)`
+    });
+  } catch (e: any) {
+    if (!booted && e && e.server) booted = { server: e.server, metricsFile: '' };
+    const msg = String(e && e.message ? e.message : e);
+    warnings.push(`multi-api-residency primary phase error: ${msg}`);
+    data.error = msg;
+    // Fail CLOSED: residency is the one GRADEABLE deep check. If we aborted
+    // before recording it, the suite would otherwise PASS with the invariant
+    // never tested (advisory checks don't gate). Push a FAILING gradeable result
+    // — unless the residency check already landed — so the verdict reflects that
+    // the invariant could not be established.
+    if (!checks.some((c) => c.name === name)) {
+      checks.push(buildResidencyAbortCheck(msg));
+    }
+  } finally {
+    await stopServer(booted ? booted.server : null);
+  }
+
+  // -- ADVISORY sub-check: same 4 surfaces at heap 3584 (capacity ~2) must ---
+  // -- churn (LRU evictions) WITHOUT the process dying. ----------------------
+  try {
+    const thrash = await runMultiApiThrash(ctx, surfaceTargets);
+    data.thrash = thrash.data;
+    checks.push(thrash.check);
+    warnings.push(...thrash.warnings);
+  } catch (e: any) {
+    warnings.push(`multi-api thrash sub-check error: ${e && e.message ? e.message : e}`);
+  }
+
+  return { name, ran: true, checks, data, warnings };
+}
+
+async function runMultiApiThrash(
+  ctx: ScenarioContext,
+  surfaceTargets: { surface: string; hosts: string[] }[]
+): Promise<{ check: CheckResult; data: any; warnings: string[] }> {
+  const warnings: string[] = [];
+  let booted: BootedServer | null = null;
+  let crashed = false;
+  let evictions = 0;
+  let evictionsStart = 0;
+  try {
+    booted = await bootFreshServer(ctx, 'multiapi-thrash', ctx.heapMb);
+    await waitForBaselineSample(booted.metricsFile);
+    evictionsStart = evictionsTotalOf(latestMetrics(booted.metricsFile));
+    // A few rounds cycling all surfaces forces the sub-capacity cache to evict.
+    for (let round = 0; round < 3; round++) {
+      for (const st of surfaceTargets) {
+        const r = await coldProbe(st.hosts[0], ctx.port, 4);
+        if (r.status === 0 && r.error) warnings.push(`thrash: ${st.surface} network error ${r.error}`);
+      }
+      if (booted.server.exited()) {
+        crashed = true;
+        break;
+      }
+    }
+    await sleep(3000);
+    const last = latestMetrics(booted.metricsFile);
+    evictions = Math.max(0, evictionsTotalOf(last) - evictionsStart);
+    crashed = crashed || booted.server.exited();
+  } catch (e: any) {
+    if (!booted && e && e.server) booted = { server: e.server, metricsFile: '' };
+    crashed = booted ? booted.server.exited() : true;
+    warnings.push(`thrash boot/drive error: ${e && e.message ? e.message : e}`);
+  } finally {
+    await stopServer(booted ? booted.server : null);
+  }
+  const data = { heapMb: ctx.heapMb, evictionsObserved: evictions, serverCrashed: crashed };
+  return {
+    check: {
+      name: 'multi-api-thrash-3584',
+      advisory: true,
+      pass: !crashed && evictions > 0,
+      value: evictions,
+      threshold: 0,
+      note:
+        `at heap ${ctx.heapMb}MB the heap-sized cache cap (~2 for the measured ~1.3GB instances) is below ` +
+        `the ${surfaceTargets.length} cycled surfaces; expect eviction churn without death: ` +
+        `evictions=${evictions}, crashed=${crashed}`
+    },
+    data,
+    warnings
+  };
+}
+
+// Best-effort signIn against an auth host (records outcome, never gates).
+async function attemptSignIn(
+  authHost: string,
+  port: number,
+  creds: { email: string; password: string | null }
+): Promise<any> {
+  if (!creds.password) return { attempted: false, reason: 'no password' };
+  const query =
+    'mutation SignIn($email: String!, $password: String!) ' +
+    '{ signIn(input: { email: $email, password: $password }) { result { accessToken } } }';
+  const r = await gqlFetch({
+    host: authHost,
+    port,
+    query,
+    variables: { email: creds.email, password: creds.password },
+    timeoutMs: WARM_TIMEOUT_MS
+  });
+  return { attempted: true, status: r.status, ok: answered(r) };
+}
+
+// Read the server's LIVE graphileCache key list from the loopback-only
+// /debug/memory endpoint (enabled with metricsEndpoint:true). getCacheStats()
+// keys the cache by the pool DECISION key, so a pooled tenant appears as its
+// `bp:` blueprint key — letting us observe the key itself, not just a count.
+// Returns null when the endpoint is unavailable/unreachable.
+async function fetchGraphileCacheKeys(port: number): Promise<string[] | null> {
+  for (const host of ['127.0.0.1', '[::1]']) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), 3000);
+    try {
+      const res = await fetch(`http://${host}:${port}/debug/memory`, { signal: ac.signal });
+      if (!res.ok) continue;
+      const j: any = await res.json();
+      const keys = j && j.graphileCache && Array.isArray(j.graphileCache.keys) ? j.graphileCache.keys : null;
+      if (keys) return keys.filter((k: any) => typeof k === 'string');
+    } catch {
+      /* try the next loopback family */
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  return null;
+}
+
+const bpKeys = (keys: string[] | null): string[] => (keys || []).filter((k) => k.startsWith('bp:'));
+
+// Boot a fresh (metrics-endpoint) server, cold-build ONE tenant's api surface,
+// and return the NEW `bp:` cache key it produced. The before/after key-set diff
+// isolates THIS tenant's key from anything the server built at startup. The
+// server is always stopped before returning.
+async function bootAndCaptureTenantKey(
+  ctx: ScenarioContext,
+  tag: string,
+  tenant: Tenant
+): Promise<{ key: string | null; warning?: string }> {
+  let booted: BootedServer | null = null;
+  try {
+    booted = await bootFreshServer(ctx, tag, ctx.heapMb, { metricsEndpoint: true });
+    await waitForBaselineSample(booted.metricsFile);
+    const before = bpKeys(await fetchGraphileCacheKeys(ctx.port));
+    const r = await coldProbe(tenant.apiHost, ctx.port);
+    if (!answered(r)) return { key: null, warning: `${tag}: tenant ${tenant.dbname} did not answer (status ${r.status})` };
+    await sleep(2000);
+    const after = bpKeys(await fetchGraphileCacheKeys(ctx.port));
+    const added = after.filter((k) => !before.includes(k));
+    if (added.length === 1) return { key: added[0] };
+    if (added.length === 0) {
+      return {
+        key: null,
+        warning: `${tag}: no new bp: key after building ${tenant.dbname} (before=${before.length} after=${after.length}; endpoint or pooling unavailable?)`
+      };
+    }
+    return { key: added.sort()[0], warning: `${tag}: ${added.length} new bp: keys building one tenant; took the first` };
+  } catch (e: any) {
+    // A boot that started the child but timed out on the port attaches it here;
+    // salvage the handle so the finally can stop it instead of leaking it.
+    if (!booted && e && e.server) booted = { server: e.server, metricsFile: '' };
+    throw e;
+  } finally {
+    await stopServer(booted ? booted.server : null);
+  }
+}
+
+// ===========================================================================
+// 2) settings-variant-split  (ADVISORY)
+// ===========================================================================
+
+export async function runSettingsVariantSplit(ctx: ScenarioContext): Promise<ScenarioResult> {
+  const name = 'settings-variant-split';
+  const warnings: string[] = [];
+  const flags: SettingsFlag[] = ['enable_aggregates'];
+
+  // Compare ONE tenant's blueprint key across two fresh-server boots — a CONTROL
+  // boot with no settings row (g=[]) and a VARIANT boot with the flag seeded
+  // (g=[…]). The physical dbname is folded into the key on this per-database rig,
+  // so counting instances across DIFFERENT tenants proves nothing (each tenant
+  // already has its own dbname → its own bp: key regardless of settings). Holding
+  // the SAME tenant constant makes the settings flag the ONLY thing that can move
+  // the key — which is exactly the contract this probe is meant to verify.
+  const pool = pickGroup0(ctx, 6).filter((t) => t.apiHost);
+  if (pool.length < 1) return skippedResult(name, `need >= 1 group-0 tenant with apiHost, have ${pool.length}`);
+  const tenant = pool[0];
+
+  const data: any = {
+    tenant: tenant.dbname,
+    flags,
+    expectedInstances: ctx.baseline.deepThresholds.settingsSplitExpectedInstances,
+    method: 'same-tenant two-boot blueprint-key comparison (dbname held constant to isolate the flag)',
+    note:
+      'Each boot is a NEW process with a FRESH databaseSettingsLoader, so boot 1 ' +
+      'loads g=[] and boot 2 loads g=[…] deterministically — no dependence on the ' +
+      '5-min loader TTL or a schema:update flush (RECON finding b).'
+  };
+
+  // Resolve the db id + refuse to mutate a tenant that already has a settings row
+  // (NO mutation in this phase — a skip here leaves the rig untouched).
+  let tenantIds: string[] = [];
+  try {
+    tenantIds = await resolveAndPrecheck(ctx, [tenant]);
+  } catch (e: any) {
+    const msg = e && e.message ? e.message : String(e);
+    if (msg.startsWith('SKIP:')) return skippedResult(name, msg.slice(5).trim());
+    return { name, ran: false, checks: [], error: msg, warnings };
+  }
+
+  // `insertedIds` tracks exactly what we commit, so teardown deletes precisely
+  // that row even if the variant boot throws mid-way.
+  const insertedIds: string[] = [];
+  const checks: CheckResult[] = [];
+  try {
+    // -- boot 1: CONTROL (no settings row) → capture the tenant's bp: key -----
+    const control = await bootAndCaptureTenantKey(ctx, 'settings-control', tenant);
+    if (control.warning) warnings.push(control.warning);
+    data.controlKey = control.key;
+
+    // -- seed the flag, then boot 2: VARIANT → capture the bp: key again ------
+    await seedSettings(ctx, tenantIds, flags, insertedIds);
+    data.seededDatabaseIds = insertedIds;
+    const variant = await bootAndCaptureTenantKey(ctx, 'settings-variant', tenant);
+    if (variant.warning) warnings.push(variant.warning);
+    data.variantKey = variant.key;
+
+    const bothCaptured = !!control.key && !!variant.key;
+    const distinctKeys = new Set([control.key, variant.key].filter(Boolean)).size;
+    const flagChangedKey = bothCaptured && control.key !== variant.key;
+    const expected = ctx.baseline.deepThresholds.settingsSplitExpectedInstances; // 2 distinct keys
+    data.distinctInstances = distinctKeys;
+    data.flagChangedKey = flagChangedKey;
+
+    checks.push({
+      name: 'settings-variant-split',
+      advisory: true,
+      pass: bothCaptured && distinctKeys >= expected,
+      value: distinctKeys,
+      threshold: expected,
+      note: bothCaptured
+        ? `tenant ${tenant.dbname} yielded ${distinctKeys} distinct blueprint key(s) across ` +
+          `control(g=[]) vs variant(g=[${flags.join(',')}]) boots (expected ${expected}); the flag ` +
+          `${flagChangedKey ? 'CHANGED' : 'did NOT change'} the key`
+        : `could not capture both blueprint keys (control=${control.key ? 'ok' : 'missing'}, ` +
+          `variant=${variant.key ? 'ok' : 'missing'}); see warnings`
+    });
+  } catch (e: any) {
+    warnings.push(`settings-variant-split drive error: ${e && e.message ? e.message : e}`);
+    data.error = String(e && e.message ? e.message : e);
+  } finally {
+    // TEARDOWN: delete exactly the row we inserted + best-effort flush NOTIFY.
+    // Restores the rig to zero settings rows (its measured ground truth).
+    const td = await teardownSettings(ctx, insertedIds);
+    data.teardownRowsRemaining = td.rowsRemaining;
+    if (td.error) warnings.push(`settings-variant-split TEARDOWN failed (manual cleanup may be needed): ${td.error}`);
+    const leftover = buildTeardownLeftoverWarning(name, td.rowsRemaining);
+    if (leftover) warnings.push(leftover);
+  }
+
+  return { name, ran: true, checks, data, warnings };
+}
+
+// ===========================================================================
+// 3) realtime-dedicated-cost  (ADVISORY)
+// ===========================================================================
+
+export async function runRealtimeDedicatedCost(ctx: ScenarioContext): Promise<ScenarioResult> {
+  const name = 'realtime-dedicated-cost';
+  const warnings: string[] = [];
+  const flags: SettingsFlag[] = ['enable_realtime'];
+
+  const pool = pickGroup0(ctx, 6).filter((t) => t.apiHost);
+  if (pool.length < 3) return skippedResult(name, `need >= 3 group-0 tenants with apiHost, have ${pool.length}`);
+  const realtime = pool[0];
+  const controls = pool.slice(1, 3);
+
+  const data: any = {
+    realtimeTenant: realtime.dbname,
+    controlTenants: controls.map((t) => t.dbname),
+    flags,
+    note:
+      'RECON finding c: enable_realtime=true force-UNPOOLS the tenant (dedicated ' +
+      'per-tenant instance) and, absent realtime_public infra, adds a background ' +
+      '5s error-poll — it degrades, it does not crash.'
+  };
+
+  // No-mutation resolve + pre-check (skip cleanly if a row already exists).
+  let realtimeIds: string[] = [];
+  try {
+    realtimeIds = await resolveAndPrecheck(ctx, [realtime]);
+  } catch (e: any) {
+    const msg = e && e.message ? e.message : String(e);
+    if (msg.startsWith('SKIP:')) return skippedResult(name, msg.slice(5).trim());
+    return { name, ran: false, checks: [], error: msg, warnings };
+  }
+
+  const insertedIds: string[] = [];
+  const checks: CheckResult[] = [];
+  let booted: BootedServer | null = null;
+  try {
+    await seedSettings(ctx, realtimeIds, flags, insertedIds);
+    data.seededDatabaseIds = insertedIds;
+
+    booted = await bootFreshServer(ctx, 'realtime', ctx.heapMb);
+    const base = await waitForBaselineSample(booted.metricsFile);
+    const baseHeapMB = heapUsedMBOf(base);
+
+    // 1) control A → the shared pooled control instance (baseline).
+    const cA = await coldProbe(controls[0].apiHost, ctx.port);
+    await sleep(4000);
+    const afterControl = latestMetrics(booted.metricsFile);
+    const cacheAfterControl = cacheSizeOf(afterControl);
+    const heapAfterControlMB = heapUsedMBOf(afterControl);
+
+    // 2) realtime tenant → its own (dedicated / unpooled) instance.
+    const rt = await coldProbe(realtime.apiHost, ctx.port);
+    await sleep(6000);
+    const afterRealtime = latestMetrics(booted.metricsFile);
+    const cacheAfterRealtime = cacheSizeOf(afterRealtime);
+    const heapAfterRealtimeMB = heapUsedMBOf(afterRealtime);
+
+    // 3) control B → must NOT add an instance (controls stay pooled together).
+    const cB = await coldProbe(controls[1].apiHost, ctx.port);
+    await sleep(4000);
+    const afterControlB = latestMetrics(booted.metricsFile);
+    const cacheAfterControlB = cacheSizeOf(afterControlB);
+
+    const realtimeServed = answered(rt);
+    const dedicatedInstance = cacheAfterRealtime > cacheAfterControl; // gained its own
+    const controlsStayPooled = cacheAfterControlB <= cacheAfterRealtime; // B added none
+    const realtimeInstanceHeapMB = round1(heapAfterRealtimeMB - heapAfterControlMB);
+
+    const logTail = booted.server.logTail(4000) || '';
+    const realtimePollNoticed = /realtime_public|realtime|touch_listener|drain_changes/i.test(logTail);
+
+    data.measurements = {
+      baseHeapMB,
+      cacheAfterControl,
+      cacheAfterRealtime,
+      cacheAfterControlB,
+      heapAfterControlMB: round1(heapAfterControlMB),
+      heapAfterRealtimeMB: round1(heapAfterRealtimeMB),
+      realtimeInstanceHeapMB,
+      realtimeServed,
+      dedicatedInstance,
+      controlsStayPooled,
+      realtimeLogSignalsSeen: realtimePollNoticed,
+      controlAStatus: cA.status,
+      realtimeStatus: rt.status,
+      controlBStatus: cB.status
+    };
+
+    if (!realtimeServed) {
+      // Capture the exact failure mode — valuable data, not a suite failure.
+      data.failureMode = {
+        status: rt.status,
+        error: rt.error || null,
+        body: (rt.text || (rt.json ? JSON.stringify(rt.json).slice(0, 400) : '')) || '',
+        serverExited: booted.server.exited(),
+        serverExit: booted.server.exitInfo(),
+        logTail: booted.server.logTail(2000)
+      };
+    }
+
+    checks.push({
+      name: 'realtime-dedicated-cost',
+      advisory: true,
+      pass: realtimeServed && dedicatedInstance && controlsStayPooled,
+      value: realtimeInstanceHeapMB,
+      threshold: null,
+      note: realtimeServed
+        ? `realtime tenant served on a dedicated instance (~${realtimeInstanceHeapMB}MB); ` +
+          `controls stayed pooled (${cacheAfterControlB} instance(s))`
+        : `realtime tenant did NOT serve (status ${rt.status}) — failure mode captured`
+    });
+  } catch (e: any) {
+    if (!booted && e && e.server) booted = { server: e.server, metricsFile: '' };
+    warnings.push(`realtime-dedicated-cost drive error: ${e && e.message ? e.message : e}`);
+    data.error = String(e && e.message ? e.message : e);
+    checks.push({
+      name: 'realtime-dedicated-cost',
+      advisory: true,
+      pass: false,
+      value: null,
+      threshold: null,
+      note: `error while measuring realtime tenant: ${data.error}`
+    });
+  } finally {
+    await stopServer(booted ? booted.server : null);
+    const td = await teardownSettings(ctx, insertedIds);
+    data.teardownRowsRemaining = td.rowsRemaining;
+    if (td.error) warnings.push(`realtime-dedicated-cost TEARDOWN failed (manual cleanup may be needed): ${td.error}`);
+    const leftover = buildTeardownLeftoverWarning(name, td.rowsRemaining);
+    if (leftover) warnings.push(leftover);
+  }
+
+  return { name, ran: true, checks, data, warnings };
+}
+
+// ===========================================================================
+// 4) partition-creep  (ADVISORY, pure SQL — no server)
+// ===========================================================================
+
+// Far-future, interval-agnostic window for the throwaway probe partition. No
+// premade partition covers 2099, so the CREATE cannot collide; it is DROPped
+// immediately regardless.
+const PROBE_LO = '2099-01-01 00:00:00+00';
+const PROBE_HI = '2099-01-08 00:00:00+00';
+const PROBE_SUFFIX = '__perfcreep_probe';
+
+export async function runPartitionCreep(ctx: ScenarioContext): Promise<ScenarioResult> {
+  const name = 'partition-creep';
+  const warnings: string[] = [];
+
+  const tenants = pickGroup0(ctx, 3);
+  const tenant = tenants.find((t) => t.databaseId) || tenants[0];
+  if (!tenant) return skippedResult(name, 'no group-0 tenant available');
+
+  const data: any = { tenant: tenant.dbname };
+  const checks: CheckResult[] = [];
+
+  try {
+    await withFreshClient(ctx.pg, async (client): Promise<void> => {
+      const dbId = await resolveDatabaseId(client, tenant);
+      if (!dbId) {
+        warnings.push(`could not resolve database id for ${tenant.dbname}`);
+        return;
+      }
+
+      const schemaRows = await client.query(TENANT_SCHEMAS_SQL, [dbId]);
+      const schemas = schemaRows.rows.map((r: any) => r.schema_name);
+      if (schemas.length === 0) {
+        data.skipped = 'no physical schemas for tenant';
+        return;
+      }
+      const patterns = buildPartConfigLikePatterns(schemas);
+      const partRows = (await client.query(PART_CONFIG_FOR_TENANT_SQL, [patterns])).rows as any[];
+      if (partRows.length === 0) {
+        data.skipped = 'no partman.part_config rows for this tenant (not partitioned / partman absent)';
+        return;
+      }
+
+      // Record every partitioned parent + its interval/premake.
+      const parents = partRows.map((r) => {
+        const intervalSeconds = parsePartitionIntervalSeconds(r.partition_interval);
+        return {
+          parentTable: r.parent_table,
+          partitionInterval: r.partition_interval,
+          intervalSeconds,
+          premake: r.premake
+        };
+      });
+      data.parents = parents;
+      data.partitionedParents = parents.length;
+
+      // Prefer an events parent (RECON: events/billing/limits/user_auth are
+      // partitioned); fall back to the first parent with a parseable interval.
+      const eventsParent =
+        parents.find((p) => /events/i.test(p.parentTable) && p.intervalSeconds) ||
+        parents.find((p) => p.intervalSeconds);
+      if (!eventsParent) {
+        data.skipped = 'no parent with a parseable time interval; cannot measure/project';
+        return;
+      }
+      data.measuredParent = eventsParent.parentTable;
+      const split = splitParentTable(eventsParent.parentTable);
+      if (!split) {
+        data.skipped = `could not split parent_table '${eventsParent.parentTable}'`;
+        return;
+      }
+
+      const isNative = await client.query(IS_PARTITIONED_PARENT_SQL, [split.schema, split.table]);
+      if (isNative.rows.length === 0) {
+        data.skipped = `parent ${eventsParent.parentTable} is not a native partitioned table (relkind<>'p')`;
+        return;
+      }
+
+      // -- measure: create ONE probe partition, diff pg_class, drop, verify ---
+      const child = `${split.table}${PROBE_SUFFIX}`;
+      // Clear any probe child left by a crashed prior run so the baseline is clean.
+      await client.query(buildDropProbePartition(split.schema, child)).catch(() => {});
+      const before = (await client.query(PG_CLASS_COUNT_SQL)).rows[0].n as number;
+      let rowsPerPartition = 0;
+      let restored = before;
+      let created = false;
+      try {
+        await client.query(buildCreateProbePartition(split.schema, split.table, child, PROBE_LO, PROBE_HI));
+        created = true;
+        const after = (await client.query(PG_CLASS_COUNT_SQL)).rows[0].n as number;
+        rowsPerPartition = after - before;
+      } catch (e: any) {
+        warnings.push(`probe partition CREATE failed (measurement skipped): ${e && e.message ? e.message : e}`);
+        data.createError = String(e && e.message ? e.message : e);
+      } finally {
+        if (created) {
+          try {
+            await client.query(buildDropProbePartition(split.schema, child));
+          } catch (e: any) {
+            warnings.push(`probe partition DROP failed — MANUAL CLEANUP NEEDED for ${split.schema}.${child}: ${e && e.message ? e.message : e}`);
+          }
+          restored = (await client.query(PG_CLASS_COUNT_SQL)).rows[0].n as number;
+        }
+      }
+      data.pgClass = { before, restored, rowsPerPartition, restoredToZero: restored === before };
+      if (created && restored !== before) {
+        warnings.push(`partition-creep: pg_class did not return to ${before} (now ${restored}) — investigate leftover objects`);
+      }
+
+      // -- project monthly creep (advisory) -----------------------------------
+      const projection = computeCreepProjection({
+        rowsPerPartition,
+        partitionedParents: parents.length,
+        partitionIntervalSeconds: eventsParent.intervalSeconds as number,
+        instanceHeapKBPerRow: ctx.baseline.instanceHeapKBPerRow
+      });
+      data.projection = projection;
+      data.intervalSecondsUsed = eventsParent.intervalSeconds;
+
+      const ceiling = ctx.baseline.deepThresholds.partitionCreepMaxRowsPerTenantMonth;
+      const measured = rowsPerPartition > 0;
+      checks.push({
+        name: 'partition-creep',
+        advisory: true,
+        pass: measured ? projection.rowsPerTenantPerMonth <= ceiling : true,
+        value: projection.rowsPerTenantPerMonth,
+        threshold: ceiling,
+        note: measured
+          ? `${rowsPerPartition} pg_class rows/partition × ${parents.length} parents → ` +
+            `~${projection.rowsPerTenantPerMonth} rows/tenant/month ` +
+            `(~${projection.heapCreepMBPerMonthPerTenant}MB/tenant/month @ ${ctx.baseline.instanceHeapKBPerRow}KB/row)`
+          : 'measurement skipped (see createError); projection uses rowsPerPartition=0'
+      });
+    });
+  } catch (e: any) {
+    warnings.push(`partition-creep error: ${e && e.message ? e.message : e}`);
+    data.error = String(e && e.message ? e.message : e);
+  }
+
+  if (checks.length === 0 && data.skipped) return skippedResult(name, data.skipped);
+  return { name, ran: true, checks, data, warnings };
+}
+
+// ===========================================================================
+// Orchestrator
+// ===========================================================================
+
+const RUNNERS: Record<DeepScenarioName, (ctx: ScenarioContext) => Promise<ScenarioResult>> = {
+  'multi-api-residency': runMultiApiResidency,
+  'settings-variant-split': runSettingsVariantSplit,
+  'realtime-dedicated-cost': runRealtimeDedicatedCost,
+  'partition-creep': runPartitionCreep
+};
+
+// Run each enabled deep scenario in isolation. A thrown scenario is contained
+// (recorded as an errored result) so one failure never aborts the others — and
+// every scenario has already restored the rig in its own finally.
+export async function runDeepScenarios(ctx: ScenarioContext): Promise<ScenarioResult[]> {
+  const results: ScenarioResult[] = [];
+  for (const scenarioName of DEEP_SCENARIOS) {
+    if (!scenarioEnabled(scenarioName, ctx.only, ctx.skip)) {
+      results.push(skippedResult(scenarioName, 'disabled via --only/--skip'));
+      continue;
+    }
+    try {
+      results.push(await RUNNERS[scenarioName](ctx));
+    } catch (e: any) {
+      results.push({
+        name: scenarioName,
+        ran: false,
+        checks: [],
+        error: `unhandled: ${e && e.message ? e.message : e}`
+      });
+    }
+  }
+  return results;
+}
diff --git a/packages/perf-harness/src/regression/sql.ts b/packages/perf-harness/src/regression/sql.ts
new file mode 100644
index 0000000000..efa5730763
--- /dev/null
+++ b/packages/perf-harness/src/regression/sql.ts
@@ -0,0 +1,191 @@
+/**
+ * SQL builders + constants for the `deep`-tier scenario checks
+ * (src/regression/scenarios.ts).
+ *
+ * Every mutating statement here is PARAMETERIZED and paired with an exact
+ * inverse so a scenario can restore the rig to precisely the state it found:
+ *   - settings INSERT  <-> settings DELETE (by the same database_id set)
+ *   - probe partition CREATE <-> DROP (by the same child name)
+ *
+ * Identifiers that reach a DDL string (schema / table / child names come from
+ * the catalog, never from user argv) are double-quote escaped via `qid`; all
+ * values flow as bind parameters. The flag-column allowlist (`SETTINGS_FLAGS`)
+ * guards the ONE place a column name is interpolated (the settings INSERT).
+ *
+ * No IO here — these are pure string/param builders, unit-tested without PG.
+ */
+
+// LISTEN/NOTIFY channel the server subscribes to for cache invalidation
+// (graphql/server/src/server.ts LISTEN "schema:update"; payload = databaseId).
+export const SCHEMA_UPDATE_CHANNEL = 'schema:update';
+
+// The 12 feature-flag columns on services_public.database_settings (and the
+// matching per-API override columns on services_public.api_settings). Mirrors
+// the loader mapping in packages/express-context/src/loaders/database-settings.ts.
+export const SETTINGS_FLAGS = [
+  'enable_aggregates',
+  'enable_postgis',
+  'enable_search',
+  'enable_direct_uploads',
+  'enable_presigned_uploads',
+  'enable_many_to_many',
+  'enable_connection_filter',
+  'enable_ltree',
+  'enable_llm',
+  'enable_realtime',
+  'enable_bulk',
+  'enable_i18n'
+] as const;
+
+export type SettingsFlag = (typeof SETTINGS_FLAGS)[number];
+
+// Double-quote-escape a SQL identifier (schema / table / child name from the
+// catalog). Mirrors fleet/teardown.ts `qid`.
+export const qid = (s: string): string => `"${String(s).replace(/"/g, '""')}"`;
+
+// ---------------------------------------------------------------------------
+// services_public.database_settings — variant seeding (checks 2 + 3)
+// ---------------------------------------------------------------------------
+
+// Are any of these database_ids ALREADY carrying a settings row? A scenario
+// refuses to mutate (skips) when true, so teardown can never delete a row it
+// did not create — the rig is left exactly as found.
+export const SETTINGS_EXISTING_SQL =
+  'SELECT database_id::text AS database_id FROM services_public.database_settings WHERE database_id = ANY($1::uuid[])';
+
+/**
+ * Parameterized single-row INSERT into services_public.database_settings.
+ * `$1` = database_id; one bind param per requested flag follows, in the order
+ * of `flagColumns`. Columns NOT listed keep their table defaults (postgis/
+ * search/uploads/m2m/connection_filter/ltree ON; aggregates/llm/realtime/bulk/
+ * i18n OFF), matching the rig's implicit per-tenant configuration.
+ *
+ * Throws on an unknown flag column (allowlist guard against injection).
+ */
+export function buildSettingsInsert(flagColumns: SettingsFlag[]): string {
+  if (!flagColumns.length) throw new Error('buildSettingsInsert: at least one flag column required');
+  for (const c of flagColumns) {
+    if (!(SETTINGS_FLAGS as readonly string[]).includes(c)) {
+      throw new Error(`buildSettingsInsert: unknown settings flag column '${c}'`);
+    }
+  }
+  const cols = flagColumns.join(', ');
+  const placeholders = flagColumns.map((_c, i) => `$${i + 2}`).join(', ');
+  return `INSERT INTO services_public.database_settings (database_id, ${cols}) VALUES ($1, ${placeholders})`;
+}
+
+// Exact inverse of the INSERT: remove the rows for precisely the seeded ids.
+export const SETTINGS_DELETE_SQL =
+  'DELETE FROM services_public.database_settings WHERE database_id = ANY($1::uuid[])';
+
+// Notify the server to flush its per-database pooling decisions. NOTE (recon b):
+// this clears the pooling-decision memo + bp: instances but NOT the 5-minute
+// databaseSettingsLoader TTL cache, so a settings change only takes effect
+// deterministically on a FRESH server (which every scenario boots) — the NOTIFY
+// is fired on teardown as a best-effort courtesy to any long-lived listener.
+export const SCHEMA_UPDATE_NOTIFY_SQL = 'SELECT pg_notify($1, $2)';
+
+// ---------------------------------------------------------------------------
+// databaseId + schema resolution
+// ---------------------------------------------------------------------------
+
+// Resolve a tenant's control-plane database id from its name (when the fleet
+// manifest lacks databaseId).
+export const DATABASE_ID_BY_NAME_SQL =
+  'SELECT id::text AS id FROM metaschema_public.database WHERE name = $1';
+
+// Every physical schema of a tenant database (used to scope the partman scan).
+export const TENANT_SCHEMAS_SQL =
+  'SELECT schema_name FROM metaschema_public.schema WHERE database_id = $1 ORDER BY schema_name';
+
+// ---------------------------------------------------------------------------
+// partman.part_config — partition-creep measurement (check 4)
+// ---------------------------------------------------------------------------
+
+// Time-partitioned parents belonging to a tenant's schema set. `$1` is an array
+// of `'<schema>.%'` LIKE patterns built by buildPartConfigLikePatterns, which
+// escapes the LIKE metacharacters in the schema names (so an underscore in a
+// schema cannot act as a single-char wildcard and pull in a DIFFERENT tenant's
+// parents). Matching relies on LIKE's default backslash escape — an explicit
+// ESCAPE clause is not permitted with the `LIKE ANY` quantified form.
+// partition_interval is returned as text and parsed in JS
+// (parsePartitionIntervalSeconds) so a non-time interval simply fails to parse
+// and that parent is skipped, rather than throwing here.
+export const PART_CONFIG_FOR_TENANT_SQL = `
+  SELECT parent_table,
+         partition_interval::text AS partition_interval,
+         premake
+    FROM partman.part_config
+   WHERE parent_table LIKE ANY($1)
+   ORDER BY parent_table`;
+
+// Escape the three LIKE metacharacters (backslash, %, _) in a literal so it
+// matches only itself. PostgreSQL's LIKE treats backslash as its default escape
+// character, so an escaped literal needs no explicit ESCAPE clause.
+export const escapeLikeLiteral = (s: string): string => String(s).replace(/([\\%_])/g, '\\$1');
+
+// Build the `'<schema>.%'` patterns for PART_CONFIG_FOR_TENANT_SQL's `LIKE ANY`.
+// Physical schema names here carry dashes and MAY carry underscores; left
+// unescaped, an underscore is a LIKE single-character wildcard, so a schema
+// 'foo_bar' would yield 'foo_bar.%' and also match a DIFFERENT tenant's
+// 'fooXbar.<table>' parent (a cross-tenant over-match). Escaping the
+// metacharacters pins the schema to itself; the trailing '.%' stays the one
+// intended wildcard (the table component), and the '.' is a literal that anchors
+// the schema/table boundary exactly.
+export function buildPartConfigLikePatterns(schemas: string[]): string[] {
+  return schemas.map((s) => `${escapeLikeLiteral(s)}.%`);
+}
+
+// Confirm a parent is a native partitioned table (relkind 'p') before we add a
+// child to it. `$1` = schema, `$2` = table.
+export const IS_PARTITIONED_PARENT_SQL = `
+  SELECT 1
+    FROM pg_class c
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+   WHERE n.nspname = $1 AND c.relname = $2 AND c.relkind = 'p'
+   LIMIT 1`;
+
+// pg_class row count — the catalog-size proxy the whole sizing model rides on.
+export const PG_CLASS_COUNT_SQL = 'SELECT count(*)::int AS n FROM pg_class';
+
+/**
+ * CREATE one throwaway future partition of a native partitioned parent. Because
+ * PARTITION OF auto-creates the child's indexes (from the parent's partitioned
+ * indexes) and a toast table, the pg_class delta around this statement is the
+ * TRUE marginal per-partition footprint (table + indexes + toast + toast index).
+ * `lo`/`hi` are far-future ISO timestamps (validated by the caller against
+ * ISO_TS_RE) chosen to never overlap a premade partition, so the CREATE cannot
+ * collide; the child is DROPped in teardown regardless.
+ */
+export function buildCreateProbePartition(
+  schema: string,
+  parent: string,
+  child: string,
+  lo: string,
+  hi: string
+): string {
+  if (!ISO_TS_RE.test(lo) || !ISO_TS_RE.test(hi)) {
+    throw new Error(`buildCreateProbePartition: bound is not an ISO timestamp: ${lo} / ${hi}`);
+  }
+  return (
+    `CREATE TABLE ${qid(schema)}.${qid(child)} PARTITION OF ${qid(schema)}.${qid(parent)} ` +
+    `FOR VALUES FROM ('${lo}') TO ('${hi}')`
+  );
+}
+
+// Exact inverse of the probe CREATE.
+export function buildDropProbePartition(schema: string, child: string): string {
+  return `DROP TABLE IF EXISTS ${qid(schema)}.${qid(child)}`;
+}
+
+// Strict ISO-8601 timestamp (date, or date + time + optional zone). Guards the
+// only literal values interpolated into the probe-partition DDL.
+export const ISO_TS_RE = /^\d{4}-\d{2}-\d{2}([ T]\d{2}:\d{2}:\d{2}(\.\d+)?([+-]\d{2}(:?\d{2})?|Z)?)?$/;
+
+// Split a `schema.table` parent_table into its parts on the LAST dot (physical
+// schema names contain dashes but never dots, so the last dot is the separator).
+export function splitParentTable(parentTable: string): { schema: string; table: string } | null {
+  const i = parentTable.lastIndexOf('.');
+  if (i <= 0 || i >= parentTable.length - 1) return null;
+  return { schema: parentTable.slice(0, i), table: parentTable.slice(i + 1) };
+}
diff --git a/packages/perf-harness/src/regression/suite.ts b/packages/perf-harness/src/regression/suite.ts
new file mode 100644
index 0000000000..5126461bc7
--- /dev/null
+++ b/packages/perf-harness/src/regression/suite.ts
@@ -0,0 +1,410 @@
+/**
+ * regression run — the one-command regression suite.
+ *
+ * Re-runs the load-bearing checks from the 2026-07 validation program against a
+ * fresh build and asserts they have not regressed past the chosen baseline's
+ * thresholds. The heavy lifting (booting servers, driving load) is delegated to
+ * OTHER `perf-harness` subcommands spawned as child processes — this file only
+ * orchestrates:
+ *
+ *   preflight -> (standard) measure instance-heap -> run ramp <generated plan>
+ *             -> aggregate step records -> compare to baseline -> verdict
+ *
+ * Suites:
+ *   quick     healthy-single-bp, zero-marginal-tenants, bleed
+ *   standard  + instance-heap, thrash-not-crash
+ *   deep      + the four scenario probes (multi-api-residency [gradeable],
+ *             settings-variant-split, realtime-dedicated-cost, partition-creep
+ *             [advisory]) — see ./scenarios.ts. Advisory checks report pass/fail
+ *             but never flip the verdict or exit code.
+ *
+ * Exit: 0 pass / 1 fail / 2 bleed (a cross-tenant sentinel violation anywhere).
+ *
+ * NOTE: this path needs a live PG rig + a built server; it is exercised behind
+ * PERF_E2E=1, not by the default `jest` run. The child CLI is invoked as
+ * `node <this-cli-entry> ...`, so it assumes the built dist entry (the gate that
+ * runs regression uses the compiled package).
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+
+import { Argv, asBool, asInt } from '../core/args';
+import { assertPortAllowed, findRepoRoot, pgConfigFromArgv, resolveCreds, resolveOutDir, resolveServerCmd } from '../core/config';
+import { buildSubset, loadFleet, Tenant } from '../core/fleetfile';
+import { withFreshClient } from '../core/pgc';
+import { ensureParentDir, readJsonl } from '../core/proc';
+import { DEFAULT_BASELINE, getBaseline } from './baselines';
+import { compareToBaseline, MeasuredRegression, verdictFromChecks } from './compare';
+import { runDeepScenarios, ScenarioContext, ScenarioResult } from './scenarios';
+
+const USAGE = `perf-harness regression run --fleet <manifest> [--suite quick|standard|deep] \\
+  [--baseline ${DEFAULT_BASELINE}] [--port 3345] [--heap-mb 3584] [--deep-heap-mb 7168] \\
+  [--out-dir ./perf-out] [--drifted <drifted.json>] [--same-bp-regex <re>] \\
+  [--only <scenario,...>] [--skip <scenario,...>] [--server-cmd "node ..."] [--allow-hub]
+
+Re-run the regression suite against a fresh build and compare to a baseline.
+The deep tier adds four scenario probes (--only/--skip filter them by name:
+multi-api-residency, settings-variant-split, realtime-dedicated-cost,
+partition-creep); only multi-api-residency can fail the suite, the rest are
+advisory. Exit 0 pass / 1 fail / 2 bleed.`;
+
+const err = (msg: string): void => console.error(`[regression] ${msg}`);
+
+// True if something is already accepting connections on the port (either
+// loopback family). Used to refuse a run when the target port is occupied.
+function isPortBusy(port: number, timeoutMs = 800): Promise<boolean> {
+  const probe = (host: string): Promise<boolean> =>
+    new Promise((resolve) => {
+      const sock = net.connect({ host, port });
+      let done = false;
+      const finish = (busy: boolean): void => {
+        if (done) return;
+        done = true;
+        sock.destroy();
+        resolve(busy);
+      };
+      sock.setTimeout(timeoutMs);
+      sock.once('connect', () => finish(true));
+      sock.once('timeout', () => finish(false));
+      sock.once('error', () => finish(false));
+    });
+  return Promise.all([probe('127.0.0.1'), probe('::1')]).then((r) => r[0] || r[1]);
+}
+
+interface ChildResult {
+  status: number | null;
+  signal: string | null;
+  stdout: string;
+  stderr: string;
+}
+
+// Invoke THIS CLI (built dist entry) as a child, tee-ing its output to a log
+// file under out-dir. PG credentials go via env (never argv — no `ps` leak).
+function spawnCli(cliEntry: string, cliArgs: string[], env: Record<string, string>, logFile: string): ChildResult {
+  const res = spawnSync(process.execPath, [cliEntry, ...cliArgs], {
+    env: { ...process.env, ...env },
+    encoding: 'utf8',
+    timeout: 45 * 60 * 1000,
+    maxBuffer: 64 * 1024 * 1024
+  });
+  const body = `$ ${cliArgs.join(' ')}\n${res.stdout || ''}${res.stderr || ''}\n`;
+  try {
+    ensureParentDir(logFile);
+    fs.appendFileSync(logFile, body);
+  } catch {
+    /* log best-effort */
+  }
+  return { status: res.status, signal: res.signal, stdout: res.stdout || '', stderr: res.stderr || '' };
+}
+
+function writeFleetFile(dir: string, name: string, subset: any): string {
+  const file = path.join(dir, `regression-fleet-${name}.json`);
+  ensureParentDir(file);
+  fs.writeFileSync(file, JSON.stringify(subset, null, 2) + '\n');
+  return file;
+}
+
+export async function runRegression(argv: Argv): Promise<number> {
+  const fleetFile = typeof argv.fleet === 'string' ? argv.fleet : null;
+  if (!fleetFile) {
+    console.error(USAGE);
+    return 1;
+  }
+  const suite = ['standard', 'deep'].includes(argv.suite) ? argv.suite : 'quick';
+  const baselineName = typeof argv.baseline === 'string' ? argv.baseline : DEFAULT_BASELINE;
+  const port = asInt(argv.port, 3345);
+  const heapMb = asInt(argv['heap-mb'], 3584);
+  const deepHeapMb = asInt(argv['deep-heap-mb'], 7168);
+  const allowHub = asBool(argv['allow-hub']);
+  // Scenario filters (deep tier). Comma lists, same shape as `run ramp --only`.
+  const parseList = (v: any): string[] => (typeof v === 'string' ? v.split(',').map((s) => s.trim()).filter(Boolean) : []);
+  const onlyScenarios = parseList(argv.only);
+  const skipScenarios = parseList(argv.skip);
+
+  let baseline;
+  try {
+    baseline = getBaseline(baselineName);
+  } catch (e: any) {
+    err(e.message);
+    return 1;
+  }
+
+  // --- preflight ------------------------------------------------------------
+  try {
+    assertPortAllowed(port, allowHub, 'server-port');
+  } catch (e: any) {
+    err(e.message);
+    return 1;
+  }
+
+  const repoRoot = findRepoRoot();
+  const outDir = resolveOutDir(argv);
+  const pg = pgConfigFromArgv(argv); // also asserts pg-port hub safety
+  const serverCmd = resolveServerCmd(argv, repoRoot);
+  const cliEntry = process.argv[1];
+  const logFile = path.join(outDir, 'regression.log');
+  const warnings: string[] = [];
+
+  // server dist must exist (unless a custom --server-cmd points elsewhere).
+  const jsEntry = serverCmd.find((a) => a.endsWith('.js'));
+  if (jsEntry && !fs.existsSync(jsEntry)) {
+    err(`server entry not found: ${jsEntry} (build it, or pass --server-cmd). ` + `default is <repo>/packages/cli/dist/index.js`);
+    return 1;
+  }
+
+  // port must be free.
+  if (await isPortBusy(port)) {
+    err(`port ${port} is already in use; pick a free --port or stop the listener`);
+    return 1;
+  }
+
+  // PG reachable + catalog size.
+  let catalogRows: number;
+  try {
+    catalogRows = await withFreshClient(pg, async (c) => {
+      const r = await c.query('SELECT count(*)::int AS n FROM pg_class');
+      return r.rows[0].n as number;
+    });
+  } catch (e: any) {
+    err(`PG not reachable at ${pg.host}:${pg.port}/${pg.database}: ${e.message || e}`);
+    return 1;
+  }
+  err(`preflight ok: catalog=${catalogRows} pg_class rows, port ${port} free, baseline ${baselineName}, suite ${suite}`);
+
+  // --- build subsets + ramp plan -------------------------------------------
+  let fleet: Tenant[];
+  try {
+    fleet = loadFleet(fleetFile).tenants;
+  } catch (e: any) {
+    err(`bad fleet ${fleetFile}: ${e.message || e}`);
+    return 1;
+  }
+  const drifted = typeof argv.drifted === 'string' && fs.existsSync(argv.drifted) ? JSON.parse(fs.readFileSync(argv.drifted, 'utf8')) : {};
+  const sameBpRegex = typeof argv['same-bp-regex'] === 'string' ? argv['same-bp-regex'] : undefined;
+
+  // group-0 size (single known-identical blueprint pool).
+  let maxAvail = 0;
+  try {
+    maxAvail = buildSubset(fleet, drifted, { tenants: 1_000_000, sameBpRegex }).tenants.length;
+  } catch (e: any) {
+    err(`could not derive single-blueprint pool from fleet: ${e.message || e}`);
+    return 1;
+  }
+  if (maxAvail === 0) {
+    err('no single-blueprint tenants matched (check --same-bp-regex); cannot run healthy/zero-marginal checks');
+    return 1;
+  }
+  const lowN = Math.min(10, maxAvail);
+
+  const mix = 'read:0.7,write:0.25,meta:0.05';
+  const steps: any[] = [];
+
+  // healthy-single-bp doubles as the zero-marginal LOW step.
+  const healthySub = buildSubset(fleet, drifted, { tenants: lowN, sameBpRegex });
+  warnings.push(...healthySub.warnings);
+  const healthyFleet = writeFleetFile(outDir, 'healthy', healthySub.subset);
+  steps.push({ name: 'healthy-single-bp', fleet: healthyFleet, shape: 'uniform', rps: 25, durationSec: 120 });
+
+  // zero-marginal HIGH step (only if it adds tenants over the low step).
+  let haveZmHigh = false;
+  if (maxAvail > lowN) {
+    const zmHighSub = buildSubset(fleet, drifted, { tenants: maxAvail, sameBpRegex });
+    warnings.push(...zmHighSub.warnings);
+    const zmHighFleet = writeFleetFile(outDir, 'zm-high', zmHighSub.subset);
+    steps.push({ name: 'zm-high', fleet: zmHighFleet, shape: 'zipf', rps: 25, durationSec: 120 });
+    haveZmHigh = true;
+  } else {
+    warnings.push(`zero-marginal: only ${maxAvail} single-blueprint tenants; high step == low step (delta forced 0)`);
+  }
+
+  // thrash-not-crash (standard + deep) needs multiple distinct blueprint shapes.
+  let haveThrash = false;
+  if (suite !== 'quick') {
+    try {
+      const thrashSub = buildSubset(fleet, drifted, { blueprints: 3, perBlueprint: 2, sameBpRegex });
+      warnings.push(...thrashSub.warnings);
+      const thrashFleet = writeFleetFile(outDir, 'thrash', thrashSub.subset);
+      steps.push({ name: 'thrash-not-crash', fleet: thrashFleet, shape: 'uniform', rps: 25, durationSec: 120 });
+      haveThrash = true;
+    } catch (e: any) {
+      warnings.push(`thrash-not-crash skipped: ${e.message || e} (needs --drifted with >=1 drift group)`);
+    }
+  }
+
+  const plan = {
+    port,
+    defaults: { heapMb, rps: 25, durationSec: 120, shape: 'uniform', auth: 1, mix },
+    steps
+  };
+  const planFile = path.join(outDir, 'regression-plan.json');
+  ensureParentDir(planFile);
+  fs.writeFileSync(planFile, JSON.stringify(plan, null, 2) + '\n');
+
+  // Common PG env for children (creds via env, not argv).
+  const childEnv: Record<string, string> = {
+    PGHOST: pg.host,
+    PGPORT: String(pg.port),
+    PGUSER: pg.user,
+    PGPASSWORD: pg.password,
+    PGDATABASE: pg.database
+  };
+  const passthrough: string[] = [];
+  if (allowHub) passthrough.push('--allow-hub');
+  if (typeof argv['server-cmd'] === 'string') passthrough.push('--server-cmd', argv['server-cmd']);
+
+  const measured: MeasuredRegression = {};
+
+  // --- (standard + deep) measure instance-heap -----------------------------
+  if (suite !== 'quick') {
+    const hostTenant = fleet.find((t) => t.apiHost);
+    const host = hostTenant ? hostTenant.apiHost : null;
+    if (!host) {
+      warnings.push('instance-heap skipped: no tenant with an apiHost in the fleet');
+    } else {
+      const ihOut = path.join(outDir, 'regression-instance-heap.jsonl');
+      if (fs.existsSync(ihOut)) fs.rmSync(ihOut);
+      err(`measuring instance heap on ${host} (heap ${heapMb}MB, port ${port})...`);
+      spawnCli(
+        cliEntry,
+        ['measure', 'instance-heap', '--label', 'regression-api', '--host', host, '--port', String(port), '--heap-mb', String(heapMb), '--out', ihOut, ...passthrough],
+        childEnv,
+        logFile
+      );
+      const ihRows = readJsonl(ihOut);
+      const ih = ihRows[ihRows.length - 1];
+      if (ih && typeof ih.deltaHeapMB === 'number') {
+        measured.instanceHeapKBPerRow = Math.round(((ih.deltaHeapMB * 1024) / catalogRows) * 100) / 100;
+      } else {
+        warnings.push('instance-heap produced no usable delta (see regression.log)');
+      }
+    }
+  }
+
+  // --- run ramp (all workload steps) ---------------------------------------
+  const rampOut = path.join(outDir, 'regression-ramp-results.jsonl');
+  if (fs.existsSync(rampOut)) fs.rmSync(rampOut);
+  err(`running ${steps.length} ramp step(s): ${steps.map((s) => s.name).join(', ')}...`);
+  const ramp = spawnCli(cliEntry, ['run', 'ramp', '--plan', planFile, '--out', rampOut, '--out-dir', outDir, ...passthrough], childEnv, logFile);
+  if (ramp.status !== 0) {
+    warnings.push(`run ramp exited ${ramp.status ?? `signal ${ramp.signal}`} (steps may be partial; see regression.log)`);
+  }
+
+  const rampRows = readJsonl(rampOut);
+  const byName = new Map<string, any>();
+  for (const rec of rampRows) if (rec && rec.name) byName.set(rec.name, rec);
+
+  // healthy-single-bp: errRate + p99.
+  const healthyRec = byName.get('healthy-single-bp');
+  if (healthyRec) {
+    const s = healthyRec.summary || {};
+    measured.healthy = {
+      errRate: s.errRate,
+      p99Ms: s.latency?.p99
+    };
+  } else {
+    warnings.push('healthy-single-bp: no ramp record produced');
+  }
+
+  // zero-marginal: heapMax(low) from healthy step, heapMax(high) from zm-high.
+  const lowHeap = healthyRec?.metrics?.heapUsedMaxMB;
+  const highHeap = haveZmHigh ? byName.get('zm-high')?.metrics?.heapUsedMaxMB : lowHeap;
+  if (typeof lowHeap === 'number' && typeof highHeap === 'number') {
+    measured.zeroMarginalDeltaMB = Math.round(Math.abs(highHeap - lowHeap) * 10) / 10;
+  } else {
+    warnings.push('zero-marginal: missing heapUsedMaxMB in one of the steps');
+  }
+
+  // thrash-not-crash: server must survive.
+  if (haveThrash) {
+    const thrashRec = byName.get('thrash-not-crash');
+    if (thrashRec) {
+      measured.thrashCrashed = thrashRec.serverCrashed === true;
+    } else {
+      warnings.push('thrash-not-crash: no ramp record produced');
+    }
+  }
+
+  // bleed: sentinel violations across ALL steps (+ any harness exit 2).
+  let bleed = 0;
+  for (const rec of rampRows) {
+    bleed += rec?.summary?.verdict?.bleedViolations ?? 0;
+    if (rec?.harnessExit === 2 && (rec?.summary?.verdict?.bleedViolations ?? 0) === 0) bleed += 1;
+  }
+  measured.bleedViolations = bleed;
+
+  // --- compare + verdict ----------------------------------------------------
+  const checks = compareToBaseline(measured, baseline);
+
+  // --- (deep) scenario probes ----------------------------------------------
+  // Each scenario boots its OWN fresh server(s) on the same guardrailed port
+  // (sequential, after the ramp child has released it), drives light traffic
+  // itself, and restores the rig in its own finally. Their checks are merged in
+  // BEFORE the verdict; advisory checks never flip it (see compare.ts).
+  let scenarioResults: ScenarioResult[] = [];
+  if (suite === 'deep') {
+    const ctx: ScenarioContext = {
+      suite,
+      pg,
+      port,
+      deepHeapMb,
+      heapMb,
+      outDir,
+      repoRoot,
+      serverCmd,
+      allowHub,
+      catalogRows,
+      baseline,
+      fleet,
+      drifted,
+      sameBpRegex,
+      only: onlyScenarios,
+      skip: skipScenarios,
+      creds: resolveCreds(argv)
+    };
+    err(`running deep scenarios: ${['multi-api-residency', 'settings-variant-split', 'realtime-dedicated-cost', 'partition-creep'].join(', ')}...`);
+    scenarioResults = await runDeepScenarios(ctx);
+    for (const sr of scenarioResults) {
+      checks.push(...sr.checks);
+      if (sr.warnings && sr.warnings.length) warnings.push(...sr.warnings.map((w) => `[${sr.name}] ${w}`));
+      if (sr.skipped) warnings.push(`scenario ${sr.name} skipped: ${sr.skipped}`);
+      if (sr.error) warnings.push(`scenario ${sr.name} error: ${sr.error}`);
+    }
+  }
+
+  const verdict = verdictFromChecks(checks);
+
+  const results = {
+    generatedAt: new Date().toISOString(),
+    baseline: baselineName,
+    suite,
+    port,
+    heapMb,
+    deepHeapMb,
+    catalogPgClassRows: catalogRows,
+    fleet: fleetFile,
+    measured,
+    checks,
+    scenarios: scenarioResults,
+    verdict,
+    warnings,
+    artifacts: { plan: planFile, rampResults: rampOut, log: logFile }
+  };
+  const resultsFile = path.join(outDir, 'regression-results.json');
+  ensureParentDir(resultsFile);
+  fs.writeFileSync(resultsFile, JSON.stringify(results, null, 2) + '\n');
+  err(`wrote ${resultsFile}`);
+
+  // Human verdict table (stdout). Advisory checks are tagged so it is obvious
+  // they do NOT contribute to the verdict.
+  console.log(`\n== regression ${baselineName} (${suite}) — catalog ${catalogRows} rows`);
+  for (const c of checks) {
+    const mark = c.advisory ? (c.pass ? 'ADVISORY ok' : 'ADVISORY x') : c.pass ? 'PASS' : 'FAIL';
+    console.log(`  [${mark}] ${c.name}: value=${c.value} threshold=${c.threshold}  — ${c.note}`);
+  }
+  for (const w of warnings) console.log(`  (warn) ${w}`);
+  console.log(`  verdict: ${verdict.pass ? 'PASS' : verdict.bleed ? 'BLEED' : 'FAIL'} (exit ${verdict.exitCode})`);
+
+  return verdict.exitCode;
+}
diff --git a/packages/perf-harness/src/report/__tests__/merge.test.ts b/packages/perf-harness/src/report/__tests__/merge.test.ts
new file mode 100644
index 0000000000..5a99daae66
--- /dev/null
+++ b/packages/perf-harness/src/report/__tests__/merge.test.ts
@@ -0,0 +1,164 @@
+import { mergeReport, MergeSources, parseOpsLine, renderMarkdown } from '../merge';
+
+const T0 = Date.parse('2026-07-03T00:00:00.000Z');
+const iso = (offsetSec: number): string => new Date(T0 + offsetSec * 1000).toISOString();
+const MB = 1048576;
+
+function counters(builds: number, lru: number, governor: number, absorbedExceptions: number, buildRefusals: number): any {
+  return {
+    evictions: { lru, ttl: 0, manual: 0, governor },
+    disposals: 0,
+    drainTimeouts: 0,
+    buildRefusals,
+    builds,
+    poolingAttaches: 0,
+    poolingBuilds: 0,
+    buildWaitTimeouts: 0,
+    buildQueueDepth: 0,
+    connGuard: { absorbedExceptions, absorbedRejections: 0 }
+  };
+}
+
+function sources(): MergeSources {
+  const metrics = [
+    { ts: iso(0), rss: 150 * MB, heapUsed: 60 * MB, cache: { size: 0, keys: 0 }, counters: counters(0, 0, 0, 0, 0), gc: {} },
+    { ts: iso(10), rss: 160 * MB, heapUsed: 70 * MB, cache: { size: 1, keys: 1 }, counters: counters(1, 1, 0, 0, 0), gc: {} },
+    { ts: iso(20), rss: 170 * MB, heapUsed: 80 * MB, cache: { size: 1, keys: 1 }, counters: counters(2, 2, 1, 3, 1), gc: {} },
+    { ts: iso(30), rss: 180 * MB, heapUsed: 90 * MB, cache: { size: 1, keys: 1 }, counters: counters(3, 2, 1, 5, 1), gc: {} }
+  ];
+  const harness = [
+    { hello: 'banner-non-progress-line' }, // must be filtered out
+    { t: 'progress', at: iso(5), elapsedSec: 5, windowErrRate: 0, latencyWindow: { p50: 13, p95: 21, p99: 21 }, sent: 50, completed: 50, ok: 50, err: 0 },
+    { t: 'progress', at: iso(15), elapsedSec: 15, windowErrRate: 0.01, latencyWindow: { p50: 14, p95: 22, p99: 30 }, sent: 150, completed: 150, ok: 148, err: 2 },
+    { t: 'progress', at: iso(28), elapsedSec: 28, windowErrRate: 0, latencyWindow: { p50: 13, p95: 21, p99: 25 }, sent: 280, completed: 280, ok: 278, err: 2 }
+  ];
+  const churn = [
+    { t: 'start', at: iso(1), channel: 'schema:update', tenants: 5 },
+    { t: 'notify', at: iso(12), dbname: 'factory1', databaseId: 'db-1', seq: 1 },
+    { t: 'stop', at: iso(30), reason: 'signal', notifies: 1, provisions: 0 }
+  ];
+  const ops = [
+    `[soak-ops] ${iso(2)} start: interval=7200s duration=86400s prefix=soak`,
+    `[soak-ops] ${iso(18)} cycle=1 provision status=0 created=soak5 :: some tail`,
+    `[soak-ops] ${iso(29)} cycle=1 drop soak4 status=0`
+  ];
+  const pg = [
+    { t: iso(8), docker: { usedBytes: 800 * MB, limitBytes: 4000 * MB }, backendsTotal: 12 },
+    { t: iso(22), docker: { usedBytes: 900 * MB, limitBytes: 4000 * MB }, backendsTotal: 15 }
+  ];
+  return { metrics, harness, churn, ops, pg };
+}
+
+describe('mergeReport', () => {
+  test('series arrays are all aligned to the metrics clock length', () => {
+    const rd = mergeReport(sources());
+    const s = rd.series;
+    expect(s.t).toHaveLength(4);
+    expect(s.heapUsedMB).toHaveLength(4);
+    expect(s.rssMB).toHaveLength(4);
+    expect(s.cacheSize).toHaveLength(4);
+    expect(s.windowErrRate).toHaveLength(4);
+    expect(s.p99).toHaveLength(4);
+    expect(s.pgContainerMB).toHaveLength(4);
+    expect(s.pgBackends).toHaveLength(4);
+    expect(s.t).toEqual([0, 10, 20, 30]);
+    expect(s.heapUsedMB).toEqual([60, 70, 80, 90]);
+  });
+
+  test('nearest-sample alignment pulls harness + pg values onto metrics ticks', () => {
+    const s = mergeReport(sources()).series;
+    // p99: metric@20 -> progress@15 (=30), metric@30 -> progress@28 (=25)
+    expect(s.p99[2]).toBe(30);
+    expect(s.p99[3]).toBe(25);
+    expect(s.windowErrRate[2]).toBe(0.01);
+    // pg: metric@20 -> pg@22 (900MB / 15), metric@0 -> pg@8 (800MB / 12)
+    expect(s.pgContainerMB[0]).toBe(800);
+    expect(s.pgContainerMB[3]).toBe(900);
+    expect(s.pgBackends[3]).toBe(15);
+  });
+
+  test('extracts churn + ops events sorted by time', () => {
+    const rd = mergeReport(sources());
+    expect(rd.events).toHaveLength(6); // 3 churn + 3 ops
+    const types = rd.events.map((e) => e.type);
+    expect(types).toContain('churn:start');
+    expect(types).toContain('churn:notify');
+    expect(types).toContain('churn:stop');
+    expect(types).toContain('ops:start');
+    expect(types).toContain('ops:provision');
+    expect(types).toContain('ops:drop');
+    // sorted ascending by `at`
+    const ats = rd.events.map((e) => Date.parse(e.at));
+    expect(ats).toEqual([...ats].sort((a, b) => a - b));
+    const notify = rd.events.find((e) => e.type === 'churn:notify');
+    expect(notify.detail).toContain('factory1');
+    const provision = rd.events.find((e) => e.type === 'ops:provision');
+    expect(provision.detail).toContain('cycle=1 provision');
+    // the `:: tail` suffix is trimmed off
+    expect(provision.detail).not.toContain('some tail');
+  });
+
+  test('computes counter first/last/delta', () => {
+    const rd = mergeReport(sources());
+    expect(rd.counters.delta.builds).toBe(3);
+    expect(rd.counters.delta.evictions.lru).toBe(2);
+    expect(rd.counters.delta.evictions.governor).toBe(1);
+    expect(rd.counters.delta.connGuard.absorbedExceptions).toBe(5);
+    expect(rd.counters.delta.buildRefusals).toBe(1);
+    expect(rd.counters.first.builds).toBe(0);
+    expect(rd.counters.last.builds).toBe(3);
+  });
+
+  test('heap slope is positive for a rising heap', () => {
+    const rd = mergeReport(sources());
+    // 60 -> 90 MB over 30s == 1 MB/s == 3600 MB/h
+    expect(rd.slopes.heapMBPerHourFull).toBeGreaterThan(0);
+    expect(rd.slopes.heapMBPerHourLastHalf).toBeGreaterThan(0);
+    expect(Math.round(rd.slopes.heapMBPerHourFull)).toBe(3600);
+  });
+
+  test('meta aggregates requests, latency, heap and pg maxima', () => {
+    const rd = mergeReport(sources());
+    expect(rd.meta.requests.sent).toBe(280);
+    expect(rd.meta.requests.completed).toBe(280);
+    expect(rd.meta.requests.err).toBe(2);
+    expect(rd.meta.latency.p99).toBe(30); // worst window p99
+    expect(rd.meta.latency.p50).toBe(13); // median of window p50s [13,14,13]
+    expect(rd.meta.heap.startMB).toBe(60);
+    expect(rd.meta.heap.maxMB).toBe(90);
+    expect(rd.meta.heap.finalMB).toBe(90);
+    expect(rd.meta.pgContainerMaxMB).toBe(900);
+    expect(rd.meta.counts.events).toBe(6);
+  });
+
+  test('renderMarkdown produces a table with the key rows', () => {
+    const md = renderMarkdown(mergeReport(sources()));
+    expect(md).toContain('| metric | value |');
+    expect(md).toContain('duration');
+    expect(md).toContain('| builds Δ | 3 |');
+    expect(md).toContain('| conn-guard absorbed Δ | 5 |');
+    expect(md).toContain('| pg container max | 900 MB |');
+  });
+
+  test('tolerates empty inputs without throwing', () => {
+    const rd = mergeReport({ metrics: [], harness: [] });
+    expect(rd.series.t).toHaveLength(0);
+    expect(rd.events).toHaveLength(0);
+    expect(rd.counters.delta).toBeNull();
+    expect(rd.slopes.heapMBPerHourFull).toBe(0);
+  });
+});
+
+describe('parseOpsLine', () => {
+  test('parses a provision cycle line', () => {
+    const ev = parseOpsLine('[soak-ops] 2026-07-03T00:00:18.000Z cycle=1 provision status=0 created=soak5 :: tail');
+    expect(ev.type).toBe('ops:provision');
+    expect(ev.at).toBe('2026-07-03T00:00:18.000Z');
+    expect(ev.detail).toBe('cycle=1 provision status=0 created=soak5');
+  });
+
+  test('returns null for a non-soak-ops line', () => {
+    expect(parseOpsLine('[harness] seed=42 shape=zipf')).toBeNull();
+    expect(parseOpsLine('')).toBeNull();
+  });
+});
diff --git a/packages/perf-harness/src/report/__tests__/summarize.test.ts b/packages/perf-harness/src/report/__tests__/summarize.test.ts
new file mode 100644
index 0000000000..1f5a062e76
--- /dev/null
+++ b/packages/perf-harness/src/report/__tests__/summarize.test.ts
@@ -0,0 +1,98 @@
+import { formatStepRecord } from '../summarize';
+
+describe('formatStepRecord', () => {
+  const healthy: any = {
+    name: 'rps-200',
+    serverCrashed: null,
+    error: null,
+    summary: {
+      achievedRps: 188.4,
+      completed: 79128,
+      errRate: 0,
+      latency: { count: 82000, min: 3, mean: 12, p50: 13, p95: 21, p99: 21, max: 67 },
+      http: { '200': 82000 },
+      sentinelOk: true,
+      verdict: { pass: true, bleedViolations: 0 }
+    },
+    metrics: {
+      samples: 99,
+      rssMaxMB: 2201.3,
+      heapUsedMaxMB: 1588.2,
+      heapUsedLastMB: 1500,
+      buildQueueDepthMax: 0,
+      lastCache: { size: 1, keys: 1 },
+      lastCounters: {
+        evictions: { lru: 1, ttl: 0, manual: 0, governor: 0 },
+        disposals: 0,
+        drainTimeouts: 0,
+        buildRefusals: 0,
+        builds: 2,
+        connGuard: { absorbedExceptions: 0, absorbedRejections: 0 }
+      }
+    },
+    pgBackends: { max: 5, samples: 99, err: null },
+    wallSec: 510
+  };
+
+  test('formats a healthy step with every field present', () => {
+    const line = formatStepRecord(healthy);
+    // first pipe-segment is the step name
+    expect(line.split(' | ')[0]).toBe('rps-200');
+    expect(line).toContain('crashed=false');
+    expect(line).toContain('err=-');
+    expect(line).toContain('errRate=0');
+    expect(line).toContain('rps=188.4');
+    expect(line).toContain('p50/p95/p99=13/21/21');
+    expect(line).toContain('http={"200":82000}');
+    expect(line).toContain('sentinelOk=true');
+    expect(line).toContain('heapMax=1588.2MB');
+    expect(line).toContain('rssMax=2201.3MB');
+    expect(line).toContain('queueMax=0');
+    expect(line).toContain('evict={"lru":1,"ttl":0,"manual":0,"governor":0}');
+    expect(line).toContain('builds=2');
+    expect(line).toContain('connGuard={"absorbedExceptions":0,"absorbedRejections":0}');
+    expect(line).toContain('pgConnMax=5');
+    expect(line).toContain('wall=510s');
+    // no cold-burst blob for a normal step
+    expect(line).not.toContain('cold=');
+  });
+
+  test('renders a crashed step with the serialized exit', () => {
+    const crashed: any = {
+      name: 'div-k1',
+      serverCrashed: true,
+      serverExit: { code: null, signal: 'SIGABRT' },
+      error: null,
+      wallSec: 40
+    };
+    const line = formatStepRecord(crashed);
+    expect(line).toContain('crashed={"code":null,"signal":"SIGABRT"}');
+    expect(line).toContain('wall=40s');
+    // absent summary/metrics fields are simply omitted
+    expect(line).not.toContain('errRate=');
+    expect(line).not.toContain('heapMax=');
+  });
+
+  test('emits the cold-burst summary blob when coldBurst is present', () => {
+    const cold: any = {
+      name: 'cold-burst',
+      serverCrashed: null,
+      error: null,
+      coldBurst: { wave1: [], wave2: [] },
+      summary: { coldOk: 0, cold503: 0, coldErr: 5, coldMsMax: 6841, warmMsMax: 58 },
+      wallSec: 120
+    };
+    const line = formatStepRecord(cold);
+    expect(line).toContain('cold=');
+    expect(line).toContain('"coldErr":5');
+    expect(line).toContain('wall=120s');
+  });
+
+  test('shows reconnects on pgBackends only when non-zero', () => {
+    const withReconn = formatStepRecord({ name: 'x', pgBackends: { max: 7, reconnects: 3 }, wallSec: 1 });
+    expect(withReconn).toContain('pgConnMax=7 reconn=3');
+    const noReconn = formatStepRecord({ name: 'x', pgBackends: { max: 7, reconnects: 0 }, wallSec: 1 });
+    expect(noReconn).toContain('pgConnMax=7');
+    expect(noReconn).not.toContain('reconn=');
+  });
+});
diff --git a/packages/perf-harness/src/report/merge.ts b/packages/perf-harness/src/report/merge.ts
new file mode 100644
index 0000000000..dcdd079fbf
--- /dev/null
+++ b/packages/perf-harness/src/report/merge.ts
@@ -0,0 +1,387 @@
+/**
+ * report merge — fuse the artifacts of one perf run into a single report.
+ *
+ * A soak (or ramp) leaves four independent time series behind, each on its own
+ * clock and cadence:
+ *   --metrics     server GRAPHILE_DEBUG_METRICS JSONL (rss/heap/cache/counters/gc)
+ *   --harness-log harness stdout JSONL (t:"progress" windows: rps/errRate/latency)
+ *   --churn-log   churn-driver stdout JSONL (start/notify/provision-marker/stop)
+ *   --ops-log     soak-ops stdout TEXT ([soak-ops] <iso> cycle=N provision|drop ...)
+ *   --pg          pg-sampler JSONL (docker mem + pg_stat_activity backends)
+ *
+ * `merge` aligns them onto the server-metrics clock (nearest-sample hold),
+ * extracts churn/ops timeline events, computes counter first/last/delta and the
+ * heap-growth slope (full run + last half), and writes `report-data.json`. A
+ * compact markdown summary table is printed to stdout for eyeballing.
+ *
+ * The alignment + aggregation live in the pure `mergeReport(sources)` so tests
+ * can drive it from small in-memory fixtures.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { Argv } from '../core/args';
+import { resolveOutDir } from '../core/config';
+import { ensureParentDir, readJsonl } from '../core/proc';
+import { linregSlope } from '../measure/collector';
+
+const USAGE = `perf-harness report merge --metrics <metrics.jsonl> --harness-log <harness.jsonl> \\
+  [--churn-log <churn.jsonl>] [--ops-log <soak-ops.log>] [--pg <pg.jsonl>] [--out-dir ./perf-out]
+
+Fuse server metrics + harness progress + churn/ops events + pg-sampler into
+report-data.json (aligned series, events, counter deltas, heap slope) and print
+a markdown summary.`;
+
+const MB = (b: number): number => Math.round((b / 1048576) * 10) / 10;
+const r2 = (x: number): number => Math.round(x * 100) / 100;
+const nowIso = (): string => new Date().toISOString();
+const ms = (iso: string): number => Date.parse(iso);
+
+export interface MergeSources {
+  metrics: any[];
+  harness: any[]; // raw harness stdout objects; progress lines are filtered here
+  churn?: any[];
+  ops?: string[]; // raw text lines from the soak-ops stdout log
+  pg?: any[];
+  sourcePaths?: Record<string, string | null>;
+}
+
+export interface ReportEvent {
+  at: string;
+  type: string;
+  detail: string;
+}
+
+export interface ReportData {
+  meta: any;
+  series: {
+    t: number[];
+    heapUsedMB: number[];
+    rssMB: number[];
+    cacheSize: number[];
+    windowErrRate: number[];
+    p99: number[];
+    pgContainerMB: number[];
+    pgBackends: number[];
+  };
+  events: ReportEvent[];
+  counters: { first: any; last: any; delta: any };
+  slopes: { heapMBPerHourFull: number; heapMBPerHourLastHalf: number };
+}
+
+// ---------------------------------------------------------------------------
+// event extraction
+// ---------------------------------------------------------------------------
+
+function churnEvents(churn: any[]): ReportEvent[] {
+  const out: ReportEvent[] = [];
+  for (const e of churn || []) {
+    if (!e || !e.at) continue;
+    switch (e.t) {
+      case 'start':
+        out.push({ at: e.at, type: 'churn:start', detail: `channel=${e.channel} tenants=${e.tenants}` });
+        break;
+      case 'notify':
+        out.push({ at: e.at, type: 'churn:notify', detail: `db=${e.dbname ?? e.databaseId} seq=${e.seq}` });
+        break;
+      case 'notify-error':
+        out.push({ at: e.at, type: 'churn:notify-error', detail: `db=${e.dbname ?? e.databaseId} ${e.error || ''}`.trim() });
+        break;
+      case 'provision-marker':
+        out.push({ at: e.at, type: 'churn:provision-marker', detail: `seq=${e.seq}` });
+        break;
+      case 'stop':
+        out.push({ at: e.at, type: 'churn:stop', detail: `reason=${e.reason} notifies=${e.notifies} provisions=${e.provisions}` });
+        break;
+      default:
+        break;
+    }
+  }
+  return out;
+}
+
+// soak-ops lines are plain text: `[soak-ops] <iso> <body>`. Parse leniently.
+export function parseOpsLine(line: string): ReportEvent | null {
+  const m = /^\[soak-ops\]\s+(\S+)\s+(.+)$/.exec(line.trim());
+  if (!m) return null;
+  const at = m[1];
+  const body = m[2].trim();
+  let type = 'ops:other';
+  if (/^start\b/.test(body)) type = 'ops:start';
+  else if (/^cycle=\d+\s+provision\b/.test(body)) type = 'ops:provision';
+  else if (/^cycle=\d+\s+drop\b/.test(body)) type = 'ops:drop';
+  else if (/^final cleanup\b/.test(body)) type = 'ops:cleanup';
+  else if (/^done\b/.test(body)) type = 'ops:done';
+  // Trim the noisy `:: <tail>` suffix and cap length.
+  const detail = body.split(' :: ')[0].slice(0, 200);
+  return { at, type, detail };
+}
+
+function opsEvents(ops: string[]): ReportEvent[] {
+  const out: ReportEvent[] = [];
+  for (const line of ops || []) {
+    if (!line || !line.trim()) continue;
+    const ev = parseOpsLine(line);
+    if (ev) out.push(ev);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// nearest-sample alignment (sample-and-hold onto the metrics clock)
+// ---------------------------------------------------------------------------
+
+// Index of the source sample whose time is closest to target `t`.
+function nearestIndex(sortedTimes: number[], t: number): number {
+  const n = sortedTimes.length;
+  if (n === 0) return -1;
+  let lo = 0;
+  let hi = n - 1;
+  if (t <= sortedTimes[0]) return 0;
+  if (t >= sortedTimes[n - 1]) return n - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    if (sortedTimes[mid] === t) return mid;
+    if (sortedTimes[mid] < t) lo = mid + 1;
+    else hi = mid - 1;
+  }
+  // lo is the first index with time > t; hi = lo - 1.
+  const after = lo;
+  const before = hi;
+  return t - sortedTimes[before] <= sortedTimes[after] - t ? before : after;
+}
+
+// ---------------------------------------------------------------------------
+// counter deltas (recursive numeric diff)
+// ---------------------------------------------------------------------------
+
+export function numericDelta(a: any, b: any): any {
+  if (typeof b === 'number') return typeof a === 'number' ? b - a : b;
+  if (b && typeof b === 'object') {
+    const out: any = {};
+    const keys = new Set<string>([...Object.keys(a || {}), ...Object.keys(b)]);
+    for (const k of keys) out[k] = numericDelta((a || {})[k], b[k]);
+    return out;
+  }
+  return b;
+}
+
+// ---------------------------------------------------------------------------
+// main merge
+// ---------------------------------------------------------------------------
+
+export function mergeReport(sources: MergeSources): ReportData {
+  const metrics = (sources.metrics || []).filter((x) => x && x.ts).slice().sort((a, b) => ms(a.ts) - ms(b.ts));
+  const progress = (sources.harness || []).filter((x) => x && x.t === 'progress' && x.at).slice().sort((a, b) => ms(a.at) - ms(b.at));
+  const pg = (sources.pg || []).filter((x) => x && x.t).slice().sort((a, b) => ms(a.t) - ms(b.t));
+
+  const events = [...churnEvents(sources.churn || []), ...opsEvents(sources.ops || [])].sort(
+    (a, b) => ms(a.at) - ms(b.at)
+  );
+
+  const progressTimes = progress.map((p) => ms(p.at));
+  const pgTimes = pg.map((p) => ms(p.t));
+
+  const series = {
+    t: [] as number[],
+    heapUsedMB: [] as number[],
+    rssMB: [] as number[],
+    cacheSize: [] as number[],
+    windowErrRate: [] as number[],
+    p99: [] as number[],
+    pgContainerMB: [] as number[],
+    pgBackends: [] as number[]
+  };
+
+  const t0 = metrics.length ? ms(metrics[0].ts) : (progressTimes[0] ?? pgTimes[0] ?? Date.now());
+
+  for (const mline of metrics) {
+    const t = ms(mline.ts);
+    series.t.push(r2((t - t0) / 1000));
+    series.heapUsedMB.push(MB(mline.heapUsed));
+    series.rssMB.push(MB(mline.rss));
+    series.cacheSize.push(mline.cache?.size ?? null);
+
+    const pi = nearestIndex(progressTimes, t);
+    if (pi >= 0) {
+      series.windowErrRate.push(progress[pi].windowErrRate ?? null);
+      series.p99.push(progress[pi].latencyWindow?.p99 ?? null);
+    } else {
+      series.windowErrRate.push(null);
+      series.p99.push(null);
+    }
+
+    const gi = nearestIndex(pgTimes, t);
+    if (gi >= 0) {
+      const used = pg[gi].docker?.usedBytes;
+      series.pgContainerMB.push(typeof used === 'number' ? MB(used) : null);
+      series.pgBackends.push(pg[gi].backendsTotal ?? null);
+    } else {
+      series.pgContainerMB.push(null);
+      series.pgBackends.push(null);
+    }
+  }
+
+  // Counter first/last/delta.
+  const firstCounters = metrics.length ? metrics[0].counters ?? null : null;
+  const lastCounters = metrics.length ? metrics[metrics.length - 1].counters ?? null : null;
+  const delta = firstCounters && lastCounters ? numericDelta(firstCounters, lastCounters) : null;
+
+  // Heap-growth slope (MB/hour) over the full run and the last half.
+  const heapPoints: [number, number][] = metrics.map((m) => [(ms(m.ts) - t0) / 1000, MB(m.heapUsed)]);
+  const half = heapPoints.slice(Math.floor(heapPoints.length / 2));
+  const slopes = {
+    heapMBPerHourFull: r2(linregSlope(heapPoints) * 3600),
+    heapMBPerHourLastHalf: r2(linregSlope(half) * 3600)
+  };
+
+  // Requests + errRate from the final progress window (sent/completed/ok/err
+  // are cumulative in a progress line; windowRps/windowErrRate are per-window).
+  const lastProg = progress.length ? progress[progress.length - 1] : null;
+  const requests = lastProg
+    ? {
+        sent: lastProg.sent ?? null,
+        completed: lastProg.completed ?? null,
+        ok: lastProg.ok ?? null,
+        err: lastProg.err ?? null,
+        errRate: lastProg.completed ? r2((lastProg.err || 0) / lastProg.completed) : 0
+      }
+    : { sent: null, completed: null, ok: null, err: null, errRate: null };
+
+  // Aggregate latency: typical median (median of window p50s) + worst tail
+  // (max window p99). Windowed data has no raw samples for a true overall pctl.
+  const p50s = progress.map((p) => p.latencyWindow?.p50).filter((v) => typeof v === 'number');
+  const p99s = progress.map((p) => p.latencyWindow?.p99).filter((v) => typeof v === 'number');
+  const median = (arr: number[]): number => {
+    if (!arr.length) return null;
+    const s = arr.slice().sort((a, b) => a - b);
+    const mid = Math.floor(s.length / 2);
+    return s.length % 2 ? s[mid] : r2((s[mid - 1] + s[mid]) / 2);
+  };
+  const latency = { p50: median(p50s), p99: p99s.length ? Math.max(...p99s) : null };
+
+  const startedAt = metrics.length ? metrics[0].ts : lastProg ? progress[0].at : null;
+  const endedAt = metrics.length ? metrics[metrics.length - 1].ts : lastProg ? lastProg.at : null;
+  const durationSec = lastProg?.elapsedSec ?? (metrics.length ? r2((ms(endedAt) - t0) / 1000) : null);
+
+  const heapMBs = series.heapUsedMB;
+  const heap = {
+    startMB: heapMBs.length ? heapMBs[0] : null,
+    maxMB: heapMBs.length ? Math.max(...heapMBs) : null,
+    finalMB: heapMBs.length ? heapMBs[heapMBs.length - 1] : null
+  };
+
+  const pgContainerMaxMB = series.pgContainerMB.filter((v) => typeof v === 'number').length
+    ? Math.max(...(series.pgContainerMB.filter((v) => typeof v === 'number') as number[]))
+    : null;
+
+  const meta = {
+    generatedAt: nowIso(),
+    sources: sources.sourcePaths || {},
+    counts: {
+      metricsSamples: metrics.length,
+      harnessProgress: progress.length,
+      churnEvents: (sources.churn || []).length,
+      opsLines: (sources.ops || []).length,
+      pgSamples: pg.length,
+      events: events.length
+    },
+    startedAt,
+    endedAt,
+    durationSec,
+    requests,
+    latency,
+    heap,
+    pgContainerMaxMB
+  };
+
+  return { meta, series, events, counters: { first: firstCounters, last: lastCounters, delta }, slopes };
+}
+
+// ---------------------------------------------------------------------------
+// markdown summary
+// ---------------------------------------------------------------------------
+
+export function renderMarkdown(rd: ReportData): string {
+  const m = rd.meta;
+  const d = rd.counters.delta || {};
+  const ev = d.evictions || {};
+  const evictionsDelta = (ev.lru || 0) + (ev.ttl || 0) + (ev.manual || 0) + (ev.governor || 0);
+  const governorDelta = ev.governor || 0;
+  const buildsDelta = d.builds || 0;
+  const refusalsDelta = d.buildRefusals || 0;
+  const guardDelta = (d.connGuard?.absorbedExceptions || 0) + (d.connGuard?.absorbedRejections || 0);
+  const req = m.requests || {};
+  const heap = m.heap || {};
+  const lat = m.latency || {};
+
+  const rows: [string, string][] = [
+    ['duration', m.durationSec != null ? `${m.durationSec}s` : '-'],
+    ['requests', req.sent != null ? `${req.sent} sent / ${req.completed} done (ok ${req.ok} / err ${req.err})` : '-'],
+    ['errRate', req.errRate != null ? String(req.errRate) : '-'],
+    ['latency p50 / p99', `${lat.p50 ?? '-'} / ${lat.p99 ?? '-'} ms`],
+    ['heap start / max / final', `${heap.startMB ?? '-'} / ${heap.maxMB ?? '-'} / ${heap.finalMB ?? '-'} MB`],
+    ['heap slope full / lastHalf', `${rd.slopes.heapMBPerHourFull} / ${rd.slopes.heapMBPerHourLastHalf} MB/h`],
+    ['evictions Δ', String(evictionsDelta)],
+    ['builds Δ', String(buildsDelta)],
+    ['governor evictions Δ', String(governorDelta)],
+    ['conn-guard absorbed Δ', String(guardDelta)],
+    ['build refusals Δ', String(refusalsDelta)],
+    ['pg container max', m.pgContainerMaxMB != null ? `${m.pgContainerMaxMB} MB` : '-'],
+    ['events', String((rd.events || []).length)]
+  ];
+
+  const lines = ['| metric | value |', '| --- | --- |'];
+  for (const [k, v] of rows) lines.push(`| ${k} | ${v} |`);
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+export async function runMerge(argv: Argv): Promise<number> {
+  const metricsFile = typeof argv.metrics === 'string' ? argv.metrics : null;
+  const harnessFile = typeof argv['harness-log'] === 'string' ? argv['harness-log'] : null;
+  if (!metricsFile || !harnessFile) {
+    console.error(USAGE);
+    return 1;
+  }
+  const churnFile = typeof argv['churn-log'] === 'string' ? argv['churn-log'] : null;
+  const opsFile = typeof argv['ops-log'] === 'string' ? argv['ops-log'] : null;
+  const pgFile = typeof argv.pg === 'string' ? argv.pg : null;
+  const outDir = resolveOutDir(argv);
+
+  const sources: MergeSources = {
+    metrics: readJsonl(metricsFile),
+    harness: readJsonl(harnessFile),
+    churn: churnFile ? readJsonl(churnFile) : [],
+    ops: opsFile ? readTextLines(opsFile) : [],
+    pg: pgFile ? readJsonl(pgFile) : [],
+    sourcePaths: {
+      metrics: metricsFile,
+      harnessLog: harnessFile,
+      churnLog: churnFile,
+      opsLog: opsFile,
+      pg: pgFile
+    }
+  };
+
+  const rd = mergeReport(sources);
+  const outFile = path.join(outDir, 'report-data.json');
+  ensureParentDir(outFile);
+  fs.writeFileSync(outFile, JSON.stringify(rd, null, 2) + '\n');
+
+  // Machine artifact path to stderr; the human summary table to stdout.
+  console.error(`[merge] wrote ${outFile}`);
+  console.log(renderMarkdown(rd));
+  return 0;
+}
+
+function readTextLines(file: string): string[] {
+  try {
+    return fs.readFileSync(file, 'utf8').split('\n');
+  } catch {
+    return [];
+  }
+}
diff --git a/packages/perf-harness/src/report/predict.ts b/packages/perf-harness/src/report/predict.ts
new file mode 100644
index 0000000000..374d4d4a83
--- /dev/null
+++ b/packages/perf-harness/src/report/predict.ts
@@ -0,0 +1,99 @@
+/**
+ * report predict — capacity / sizing table.
+ *
+ * Given a per-instance retained-heap estimate (bytes) and a list of heap sizes
+ * (`--max-old-space-size` MB values), print how many PostGraphile instances a
+ * node of each size can safely keep resident (capacity R), using the SAME
+ * two-constraint budget math the server ships with — `computeCapacityFromBudget`
+ * from `graphile-cache`.
+ *
+ * `graphile-cache` is a workspace dependency, but importing it at module top
+ * level drags the whole PostGraphile build chain into every `perf-harness`
+ * start. It is therefore `require`d LAZILY inside `runPredict`, typed against a
+ * minimal local declaration rather than the real module.
+ */
+import { Argv, asInt } from '../core/args';
+
+// Server defaults (graphile-cache DEFAULT_BASE_RESERVE_BYTES / _BUILD_RESERVE_BYTES).
+const DEFAULT_BASE_RESERVE_BYTES = 256 * 1024 * 1024;
+const DEFAULT_BUILD_RESERVE_BYTES = 768 * 1024 * 1024;
+const MB = 1024 * 1024;
+
+const USAGE = `perf-harness report predict --instance-heap-bytes <n> [--heap-mb 1536,2048,3584] \\
+  [--base-reserve-bytes <n>] [--build-reserve-bytes <n>]
+
+Print a heapMB -> capacity(R) sizing table using the server's two-constraint
+budget model (graphile-cache computeCapacityFromBudget).`;
+
+// Minimal local shape of the lazily-required dependency (see file header).
+interface GraphileCacheModule {
+  computeCapacityFromBudget(
+    heapLimit: number,
+    perInstance: number,
+    baseReserve?: number,
+    buildReserve?: number
+  ): number;
+}
+
+export interface SizingRow {
+  heapMB: number;
+  heapBytes: number;
+  capacity: number;
+}
+
+// Pure table builder — `compute` is injected so this is testable without the
+// heavy workspace dependency.
+export function buildSizingTable(
+  heapMbList: number[],
+  instanceHeapBytes: number,
+  baseReserve: number,
+  buildReserve: number,
+  compute: GraphileCacheModule['computeCapacityFromBudget']
+): SizingRow[] {
+  return heapMbList.map((heapMB) => {
+    const heapBytes = heapMB * MB;
+    return { heapMB, heapBytes, capacity: compute(heapBytes, instanceHeapBytes, baseReserve, buildReserve) };
+  });
+}
+
+export async function runPredict(argv: Argv): Promise<number> {
+  const instanceHeapBytes = asInt(argv['instance-heap-bytes'], undefined);
+  if (!instanceHeapBytes || instanceHeapBytes <= 0) {
+    console.error('report predict: --instance-heap-bytes <n> is required (measured per-instance retained heap)');
+    console.error(USAGE);
+    return 1;
+  }
+  const heapMbRaw = typeof argv['heap-mb'] === 'string' ? argv['heap-mb'] : String(argv['heap-mb'] ?? '');
+  const heapMbList = heapMbRaw
+    .split(',')
+    .map((s) => Number.parseInt(s.trim(), 10))
+    .filter((n) => Number.isFinite(n) && n > 0);
+  if (heapMbList.length === 0) {
+    heapMbList.push(1536, 2048, 2560, 3072, 3584, 4096);
+  }
+  const baseReserve = asInt(argv['base-reserve-bytes'], DEFAULT_BASE_RESERVE_BYTES);
+  const buildReserve = asInt(argv['build-reserve-bytes'], DEFAULT_BUILD_RESERVE_BYTES);
+
+  // Lazy — top-level import is FORBIDDEN (drags PostGraphile into CLI start).
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const gc = require('graphile-cache') as GraphileCacheModule;
+
+  const rows = buildSizingTable(heapMbList, instanceHeapBytes, baseReserve, buildReserve, gc.computeCapacityFromBudget);
+
+  console.log(
+    `# capacity sizing  (I=${(instanceHeapBytes / MB).toFixed(0)}MB/instance, ` +
+      `base=${(baseReserve / MB).toFixed(0)}MB, build=${(buildReserve / MB).toFixed(0)}MB)`
+  );
+  console.log('| heapMB | capacity R |');
+  console.log('| --- | --- |');
+  for (const row of rows) {
+    console.log(`| ${row.heapMB} | ${row.capacity} |`);
+  }
+  console.log(
+    '\nNote: heapMB is the --max-old-space-size value. V8 reports a heap_size_limit ' +
+      'slightly ABOVE it (~3-5%, e.g. 3584 -> ~3777MB), so the server may compute a ' +
+      'marginally more generous capacity at exact boundaries; this table is the ' +
+      'conservative floor.'
+  );
+  return 0;
+}
diff --git a/packages/perf-harness/src/report/summarize.ts b/packages/perf-harness/src/report/summarize.ts
new file mode 100644
index 0000000000..5f99b69c86
--- /dev/null
+++ b/packages/perf-harness/src/report/summarize.ts
@@ -0,0 +1,83 @@
+/**
+ * report summarize — one line per ramp step record.
+ *
+ * Port of `scripts/scale-validate/summarize-results.mjs`. Reads one or more
+ * `*-results.jsonl` files (each line is a `run ramp` step record) and prints a
+ * compact single-line digest per step: crash state, error rate, achieved rps,
+ * latency percentiles, HTTP code histogram, bleed-sentinel status, heap/rss
+ * maxima, build-queue depth, eviction/build counters, connection-guard counts,
+ * peak PG backends, and wall time.
+ *
+ * `formatStepRecord` is exported so a fixture test can assert the exact field
+ * formatting without touching the filesystem.
+ */
+import fs from 'node:fs';
+
+import { Argv } from '../core/args';
+
+const USAGE = `perf-harness report summarize <results.jsonl> [more.jsonl ...]
+
+Summarize run-ramp step-result JSONL files (one digest line per step).`;
+
+// Format a single step record into the pipe-joined digest line (no indent —
+// callers add their own). Verbatim field set + ordering from the original.
+export function formatStepRecord(r: any): string {
+  const s = r.summary || {};
+  const lat = s.latency || {};
+  const m = r.metrics || {};
+  const c = m.lastCounters || {};
+  return [
+    r.name,
+    `crashed=${r.serverCrashed ? JSON.stringify(r.serverExit) : false}`,
+    `err=${r.error || '-'}`,
+    s.errRate !== undefined ? `errRate=${s.errRate}` : null,
+    s.achievedRps !== undefined ? `rps=${s.achievedRps}` : null,
+    lat.p50 !== undefined ? `p50/p95/p99=${lat.p50}/${lat.p95}/${lat.p99}` : null,
+    s.http ? `http=${JSON.stringify(s.http)}` : null,
+    s.sentinelOk !== undefined ? `sentinelOk=${s.sentinelOk}` : null,
+    r.coldBurst ? `cold=${JSON.stringify(s)}` : null,
+    m.heapUsedMaxMB !== undefined ? `heapMax=${m.heapUsedMaxMB}MB` : null,
+    m.rssMaxMB !== undefined ? `rssMax=${m.rssMaxMB}MB` : null,
+    m.buildQueueDepthMax !== undefined ? `queueMax=${m.buildQueueDepthMax}` : null,
+    c.evictions ? `evict=${JSON.stringify(c.evictions)}` : null,
+    c.builds !== undefined ? `builds=${c.builds}` : null,
+    c.connGuard ? `connGuard=${JSON.stringify(c.connGuard)}` : null,
+    r.pgBackends
+      ? `pgConnMax=${r.pgBackends.max}${r.pgBackends.reconnects ? ` reconn=${r.pgBackends.reconnects}` : ''}`
+      : null,
+    `wall=${r.wallSec}s`
+  ]
+    .filter(Boolean)
+    .join(' | ');
+}
+
+export async function runSummarize(argv: Argv): Promise<number> {
+  // Positionals are the result files. Depending on how the top-level router
+  // populates `_`, the leading routing tokens may or may not have been sliced
+  // off — drop them defensively so `report summarize a.jsonl` works either way
+  // (a real results-file path is never literally 'report'/'summarize').
+  const files = (argv._ || []).slice();
+  while (files.length && (files[0] === 'report' || files[0] === 'summarize')) files.shift();
+  if (files.length === 0) {
+    console.error(USAGE);
+    return 1;
+  }
+  for (const file of files) {
+    if (!fs.existsSync(file)) {
+      console.log(`-- ${file}: missing`);
+      continue;
+    }
+    console.log(`== ${file}`);
+    const lines = fs.readFileSync(file, 'utf8').trim().split('\n').filter(Boolean);
+    for (const line of lines) {
+      let r: any;
+      try {
+        r = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      console.log('  ' + formatStepRecord(r));
+    }
+  }
+  return 0;
+}
diff --git a/packages/perf-harness/src/run/__tests__/ramp.test.ts b/packages/perf-harness/src/run/__tests__/ramp.test.ts
new file mode 100644
index 0000000000..5f26f371a9
--- /dev/null
+++ b/packages/perf-harness/src/run/__tests__/ramp.test.ts
@@ -0,0 +1,48 @@
+import { mergeStepConfig } from '../ramp';
+
+describe('mergeStepConfig', () => {
+  test('step fields override plan defaults; unspecified defaults survive', () => {
+    const defaults = {
+      heapMb: 2048,
+      rps: 10,
+      durationSec: 420,
+      shape: 'uniform',
+      auth: 1,
+      mix: 'read:0.7,write:0.25,meta:0.05'
+    };
+    const step = { name: 'div-k3', fleet: 'out/fleet-k3.json', rps: 25 };
+    const cfg = mergeStepConfig(defaults, step);
+
+    expect(cfg.rps).toBe(25); // step wins
+    expect(cfg.heapMb).toBe(2048); // default survives
+    expect(cfg.shape).toBe('uniform');
+    expect(cfg.mix).toBe('read:0.7,write:0.25,meta:0.05');
+    expect(cfg.name).toBe('div-k3'); // step-only field present
+    expect(cfg.fleet).toBe('out/fleet-k3.json');
+  });
+
+  test('does not mutate defaults or step', () => {
+    const defaults = { heapMb: 2048, rps: 10 };
+    const step = { name: 'x', rps: 25 };
+    mergeStepConfig(defaults, step);
+    expect(defaults).toEqual({ heapMb: 2048, rps: 10 });
+    expect(step).toEqual({ name: 'x', rps: 25 });
+  });
+
+  test('coldBurst flag and heapMb override flow through', () => {
+    const cfg = mergeStepConfig({ heapMb: 2048, rps: 10 }, { name: 'cb', fleet: 'f.json', coldBurst: true, heapMb: 896 });
+    expect(cfg.coldBurst).toBe(true);
+    expect(cfg.heapMb).toBe(896); // step overrides
+    expect(cfg.rps).toBe(10); // default survives
+  });
+
+  test('an empty step yields the defaults verbatim (plus its name)', () => {
+    const defaults = { heapMb: 2048, rps: 10, shape: 'zipf' };
+    expect(mergeStepConfig(defaults, { name: 'only-name' })).toEqual({ heapMb: 2048, rps: 10, shape: 'zipf', name: 'only-name' });
+  });
+
+  test('nested serverEnv from the step replaces (does not deep-merge) the default', () => {
+    const cfg = mergeStepConfig({ serverEnv: { A: '1' } }, { name: 's', serverEnv: { B: '2' } });
+    expect(cfg.serverEnv).toEqual({ B: '2' }); // shallow spread — step wins wholesale
+  });
+});
diff --git a/packages/perf-harness/src/run/__tests__/soak.test.ts b/packages/perf-harness/src/run/__tests__/soak.test.ts
new file mode 100644
index 0000000000..b8362d4884
--- /dev/null
+++ b/packages/perf-harness/src/run/__tests__/soak.test.ts
@@ -0,0 +1,20 @@
+import { SOAK_STOP_ORDER } from '../soak';
+
+describe('SOAK_STOP_ORDER', () => {
+  test('is the exact ordered fan-out from the DESIGN contract', () => {
+    expect(SOAK_STOP_ORDER).toEqual(['harness', 'collector', 'churn', 'soak-ops', 'pg-sampler', 'server']);
+  });
+
+  test('the harness is stopped first (so it flushes its final report before the server dies)', () => {
+    expect(SOAK_STOP_ORDER[0]).toBe('harness');
+  });
+
+  test('the server is stopped last (load components flush against a live server)', () => {
+    expect(SOAK_STOP_ORDER[SOAK_STOP_ORDER.length - 1]).toBe('server');
+  });
+
+  test('covers every soak component exactly once', () => {
+    expect([...SOAK_STOP_ORDER].sort()).toEqual(['churn', 'collector', 'harness', 'pg-sampler', 'server', 'soak-ops']);
+    expect(new Set(SOAK_STOP_ORDER).size).toBe(SOAK_STOP_ORDER.length);
+  });
+});
diff --git a/packages/perf-harness/src/run/__tests__/soakOps.test.ts b/packages/perf-harness/src/run/__tests__/soakOps.test.ts
new file mode 100644
index 0000000000..a1a779856c
--- /dev/null
+++ b/packages/perf-harness/src/run/__tests__/soakOps.test.ts
@@ -0,0 +1,55 @@
+import { computeCycleTiming, recoverCreatedName } from '../soakOps';
+
+describe('computeCycleTiming', () => {
+  test('waits the remaining interval when a cycle finishes early', () => {
+    const now = 1_000_000;
+    const t = computeCycleTiming({ intervalSec: 7200, elapsedMs: 5000, now, deadline: now + 100_000_000 });
+    expect(t.waitMs).toBe(7200 * 1000 - 5000);
+    expect(t.stop).toBe(false);
+  });
+
+  test('never waits a negative amount when a cycle overran the interval', () => {
+    const now = 1_000_000;
+    const t = computeCycleTiming({ intervalSec: 60, elapsedMs: 95_000, now, deadline: now + 10_000_000 });
+    expect(t.waitMs).toBe(0);
+    expect(t.stop).toBe(false);
+  });
+
+  test('signals stop when the wait would reach or cross the deadline', () => {
+    const now = 1_000_000;
+    // Only 1s left, but a full interval wait is required -> stop.
+    const t = computeCycleTiming({ intervalSec: 7200, elapsedMs: 0, now, deadline: now + 1000 });
+    expect(t.stop).toBe(true);
+  });
+
+  test('stop is inclusive at the deadline boundary (>=)', () => {
+    const now = 1_000_000;
+    const waitMs = 7200 * 1000;
+    // now + waitMs === deadline exactly -> the original breaks (>=).
+    expect(computeCycleTiming({ intervalSec: 7200, elapsedMs: 0, now, deadline: now + waitMs }).stop).toBe(true);
+    // one ms of slack -> keep going.
+    expect(computeCycleTiming({ intervalSec: 7200, elapsedMs: 0, now, deadline: now + waitMs + 1 }).stop).toBe(false);
+  });
+});
+
+describe('recoverCreatedName', () => {
+  test('recovers a name from the "[name] OK db=" marker', () => {
+    expect(recoverCreatedName('noise\n[soak7] OK db=marketplace_db_soak7 host=api-...\n', 'soak')).toBe('soak7');
+  });
+
+  test('prefixes a bare index from the "indices=N.." marker', () => {
+    expect(recoverCreatedName('provisioning indices=7.. and more', 'soak')).toBe('soak7');
+  });
+
+  test('a name already carrying the prefix is used as-is', () => {
+    expect(recoverCreatedName('[soak12] OK db=x', 'soak')).toBe('soak12');
+  });
+
+  test('prefers the "[name] OK db=" marker over the indices marker', () => {
+    expect(recoverCreatedName('indices=3.. then [soak9] OK db=y', 'soak')).toBe('soak9');
+  });
+
+  test('returns null when no marker is present', () => {
+    expect(recoverCreatedName('nothing useful here', 'soak')).toBeNull();
+  });
+});
diff --git a/packages/perf-harness/src/run/ramp.ts b/packages/perf-harness/src/run/ramp.ts
new file mode 100644
index 0000000000..1f2f6191d6
--- /dev/null
+++ b/packages/perf-harness/src/run/ramp.ts
@@ -0,0 +1,376 @@
+/**
+ * `run ramp` — V2 limits-discovery executor (port of v2-ramps.mjs).
+ *
+ * Runs a plan of ramp steps. Each step gets a FRESH server (clean cache, fresh
+ * cumulative counters, own metrics file), then either:
+ *   - drives the workload harness (`load harness`, spawned as a child of THIS
+ *     CLI) against a fleet manifest, or
+ *   - fires a cold-burst: one concurrent first-hit per tenant in the manifest
+ *     (use a 1-tenant-per-blueprint subset so every request is a cold build),
+ *     then a second warm wave.
+ *
+ * Per step it records: harness latency/error summary, metrics-file maxima
+ * (rss/heapUsed/buildQueueDepth), final cache+build counters, max PG backend
+ * count during the run, and whether the server crashed. A heap OOM is a
+ * legitimate FINDING, not a script failure — the step is recorded and the plan
+ * continues.
+ *
+ * Plan file:
+ *   { "port": 3345,
+ *     "defaults": { "heapMb": 2048, "rps": 10, "durationSec": 420,
+ *                   "shape": "uniform", "auth": 1, "mix": "read:0.7,write:0.25,meta:0.05" },
+ *     "steps": [ { "name": "div-k3", "fleet": "out/fleet-k3.json" },
+ *                { "name": "cold-burst", "fleet": "out/fleet-burst.json", "coldBurst": true } ] }
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { Argv, asBool, asInt } from '../core/args';
+import { assertPortAllowed, findRepoRoot, PgConfig, pgConfigFromArgv, resolveOutDir, resolveServerCmd } from '../core/config';
+import { loadFleet, Tenant } from '../core/fleetfile';
+import { getPg } from '../core/pgc';
+import { ensureParentDir, readJsonl } from '../core/proc';
+import { spawnServer, SpawnedServer } from './server';
+
+export const RAMP_USAGE = `perf-harness run ramp — V2 limits-discovery executor (fresh server per step)
+
+Required:
+  --plan <file>               ramp plan JSON ({ port?, defaults, steps[] })
+Common:
+  --port <n>                  server port (overrides plan.port; default plan.port || 3345)
+  --out <file>                results JSONL (default <out-dir>/<label>-results.jsonl)
+  --label <name>              results-file label (default: plan basename)
+  --only step1,step2          run only the named steps
+  --out-dir <dir>             artifact dir (default ./perf-out)
+  --server-cmd "<cmd>"        server launch command (default: node <repo>/packages/cli/dist/index.js)
+  --pg-* / PG*                Postgres connection overrides (default :5433 constructive)
+  --allow-hub                 permit reserved hub ports (danger)
+  --help
+
+Auth for harness steps uses PERF_PASSWORD from the environment (never argv).
+Each step's cfg = { ...plan.defaults, ...step }.`;
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+const MB = (b: number): number => Math.round((b / 1024 / 1024) * 10) / 10;
+
+// ---------------------------------------------------------------------------
+// Plan shape
+// ---------------------------------------------------------------------------
+export interface RampDefaults {
+  heapMb?: number;
+  rps?: number;
+  durationSec?: number;
+  shape?: string;
+  auth?: number;
+  mix?: string;
+  cacheMax?: number;
+  instanceHeapBytes?: number;
+  sentinelSec?: number;
+  seed?: number;
+  coldTimeoutMs?: number;
+  serverEnv?: Record<string, string>;
+  [k: string]: any;
+}
+
+export interface RampStep {
+  name: string;
+  fleet?: string;
+  coldBurst?: boolean;
+  [k: string]: any;
+}
+
+export interface RampPlan {
+  port?: number;
+  defaults: RampDefaults;
+  steps: RampStep[];
+}
+
+// The per-step config: plan defaults overlaid by the step's own fields. Exported
+// for tests. Pure — never mutates its inputs.
+export function mergeStepConfig(defaults: RampDefaults, step: RampStep): RampDefaults & RampStep {
+  return { ...defaults, ...step };
+}
+
+// ---------------------------------------------------------------------------
+// PG backend sampling (server pools + LISTEN connections)
+// ---------------------------------------------------------------------------
+interface PgBackendSampler {
+  max: number;
+  last: number;
+  samples: number;
+  stop: boolean;
+  err: string | null;
+  reconnects: number;
+}
+
+function startPgBackendSampler(pg: PgConfig): PgBackendSampler {
+  const { Client } = getPg();
+  const state: PgBackendSampler = { max: 0, last: 0, samples: 0, stop: false, err: null, reconnects: 0 };
+  void (async () => {
+    // PG may crash-recover mid-step (introspection OOM inside its cgroup) —
+    // swallow client errors and reconnect rather than killing the executor.
+    while (!state.stop) {
+      let client: any;
+      try {
+        client = new Client(pg);
+        client.on('error', () => {});
+        await client.connect();
+        while (!state.stop) {
+          const r = await client.query(
+            `SELECT count(*)::int AS c FROM pg_stat_activity
+              WHERE datname = current_database() AND pid <> pg_backend_pid()`
+          );
+          state.last = r.rows[0].c;
+          state.max = Math.max(state.max, state.last);
+          state.samples++;
+          await sleep(5000);
+        }
+      } catch (e: any) {
+        state.err = String(e && e.message ? e.message : e);
+        state.reconnects++;
+      } finally {
+        try {
+          await client?.end();
+        } catch {
+          /* recovery window */
+        }
+      }
+      if (!state.stop) await sleep(5000);
+    }
+  })();
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// Workloads
+// ---------------------------------------------------------------------------
+// Invoke the harness as a child of THIS CLI (`perf-harness load harness ...`),
+// mirroring the original's per-step process isolation. Credentials flow via the
+// inherited environment (PERF_PASSWORD) — never on argv.
+function runHarnessChild(flags: string[]): Promise<{ code: number | null; tail: string }> {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [process.argv[1], 'load', 'harness', ...flags], {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    let tail = '';
+    child.stdout.on('data', (d) => {
+      process.stdout.write(d);
+      tail = (tail + d).slice(-4000);
+    });
+    child.stderr.on('data', (d) => {
+      process.stderr.write(d);
+      tail = (tail + d).slice(-4000);
+    });
+    child.on('exit', (code) => resolve({ code, tail }));
+    child.on('error', (err) => resolve({ code: 1, tail: `${tail}\n[spawn error] ${err && err.message ? err.message : err}` }));
+  });
+}
+
+interface ColdHit {
+  dbname: string;
+  status: number;
+  ms: number;
+  err?: string;
+}
+
+async function coldBurst(fleetPath: string, port: number, coldTimeoutMs: number): Promise<{ wave1: ColdHit[]; wave2: ColdHit[] }> {
+  const { tenants } = loadFleet(fleetPath);
+  const one = async (t: Tenant): Promise<ColdHit> => {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), coldTimeoutMs);
+    const start = performance.now();
+    try {
+      const res = await fetch(`http://${t.apiHost}:${port}/graphql`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ query: 'query { __typename }' }),
+        signal: ac.signal
+      });
+      await res.text();
+      return { dbname: t.dbname, status: res.status, ms: Math.round(performance.now() - start) };
+    } catch (e) {
+      return { dbname: t.dbname, status: 0, ms: Math.round(performance.now() - start), err: String(e).slice(0, 120) };
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  console.log(`[cold-burst] firing ${tenants.length} concurrent first-hits...`);
+  const wave1 = await Promise.all(tenants.map(one));
+  const wave2 = await Promise.all(tenants.map(one)); // warm check
+  return { wave1, wave2 };
+}
+
+// Resolve a plan's `step.fleet` (relative to cwd first, then the plan dir).
+function resolveFleetPath(planDir: string, fleet: string): string {
+  if (path.isAbsolute(fleet)) return fleet;
+  const relCwd = path.resolve(process.cwd(), fleet);
+  if (fs.existsSync(relCwd)) return relCwd;
+  const relPlan = path.resolve(planDir, fleet);
+  if (fs.existsSync(relPlan)) return relPlan;
+  return relCwd; // loadFleet will throw a clear ENOENT
+}
+
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+export async function runRamp(argv: Argv): Promise<number> {
+  if (asBool(argv.help)) {
+    console.log(RAMP_USAGE);
+    return 0;
+  }
+  const planArg = typeof argv.plan === 'string' ? argv.plan : '';
+  const planPath = planArg ? path.resolve(process.cwd(), planArg) : '';
+  if (!planPath || !fs.existsSync(planPath)) {
+    console.error('run ramp: --plan <file> is required');
+    return 1;
+  }
+  const plan: RampPlan = JSON.parse(fs.readFileSync(planPath, 'utf8'));
+  const planDir = path.dirname(planPath);
+
+  const allowHub = asBool(argv['allow-hub']);
+  const port = asInt(argv.port, plan.port || 3345);
+  assertPortAllowed(port, allowHub, 'server-port');
+
+  const pg = pgConfigFromArgv(argv);
+  const outDir = resolveOutDir(argv);
+  const repoRoot = findRepoRoot();
+  const serverCmd = resolveServerCmd(argv, repoRoot);
+
+  const label = typeof argv.label === 'string' && argv.label ? argv.label : path.basename(planPath).replace(/\.json$/i, '');
+  const outFile = typeof argv.out === 'string' && argv.out ? path.resolve(process.cwd(), argv.out) : path.join(outDir, `${label}-results.jsonl`);
+
+  const only = (typeof argv.only === 'string' ? argv.only : '').split(',').filter(Boolean);
+  const steps = (plan.steps || []).filter((s) => only.length === 0 || only.includes(s.name));
+
+  console.log(`[ramp] plan=${path.basename(planPath)} steps=${steps.map((s) => s.name).join(',')} port=${port} -> ${outFile}`);
+
+  for (const step of steps) {
+    const cfg = mergeStepConfig(plan.defaults || {}, step);
+    const name = `${step.name}-h${cfg.heapMb}`;
+    const metricsFile = path.join(outDir, `metrics-${name}.jsonl`);
+    const harnessOut = path.join(outDir, `harness-${name}.json`);
+    if (fs.existsSync(metricsFile)) fs.rmSync(metricsFile);
+
+    console.log(
+      `\n===== STEP ${name}: heap=${cfg.heapMb}MB fleet=${step.fleet} ` +
+        `${step.coldBurst ? 'COLD-BURST' : `rps=${cfg.rps} dur=${cfg.durationSec}s shape=${cfg.shape}`} =====`
+    );
+
+    const record: any = {
+      name: step.name,
+      heapMb: cfg.heapMb,
+      fleet: step.fleet,
+      config: cfg,
+      startedAt: new Date().toISOString()
+    };
+    const pgSampler = startPgBackendSampler(pg);
+    const t0 = Date.now();
+    let server: SpawnedServer | null = null;
+    try {
+      server = await spawnServer({
+        name: `server-${name}`,
+        port,
+        heapMb: cfg.heapMb,
+        metricsFile,
+        pg,
+        repoRoot,
+        outDir,
+        serverCmd,
+        cacheMax: cfg.cacheMax,
+        instanceHeapBytes: cfg.instanceHeapBytes,
+        extraEnv: cfg.serverEnv,
+        detached: false,
+        allowHub
+      });
+
+      // metrics baseline so the sampler is known-alive before load
+      const bDeadline = Date.now() + 60000;
+      while (readJsonl(metricsFile).length < 1 && Date.now() < bDeadline) await sleep(2000);
+
+      if (step.coldBurst) {
+        const fleetPath = resolveFleetPath(planDir, step.fleet);
+        record.coldBurst = await coldBurst(fleetPath, port, cfg.coldTimeoutMs ?? 420000);
+        const w1: ColdHit[] = record.coldBurst.wave1;
+        record.summary = {
+          coldOk: w1.filter((r) => r.status === 200).length,
+          cold503: w1.filter((r) => r.status === 503).length,
+          coldErr: w1.filter((r) => r.status !== 200 && r.status !== 503).length,
+          coldMsMax: Math.max(...w1.map((r) => r.ms)),
+          warmMsMax: Math.max(...record.coldBurst.wave2.map((r: ColdHit) => r.ms))
+        };
+        await sleep(15000); // let the sampler catch the post-burst state
+      } else {
+        const fleetPath = resolveFleetPath(planDir, step.fleet);
+        const flags = [
+          '--fleet', fleetPath,
+          '--port', String(port),
+          '--duration-sec', String(cfg.durationSec),
+          '--rps', String(cfg.rps),
+          '--mix', String(cfg.mix),
+          '--shape', String(cfg.shape),
+          '--auth', String(cfg.auth),
+          '--sentinel-interval-sec', String(cfg.sentinelSec ?? 60),
+          '--seed', String(cfg.seed ?? 42),
+          '--out', harnessOut
+        ];
+        const h = await runHarnessChild(flags);
+        record.harnessExit = h.code; // 2 = bleed sentinel violation
+        if (fs.existsSync(harnessOut)) {
+          const rep = JSON.parse(fs.readFileSync(harnessOut, 'utf8'));
+          record.summary = {
+            achievedRps: rep.totals?.achievedRps,
+            completed: rep.totals?.completed,
+            errRate: rep.totals?.errRate,
+            latency: rep.latencyOverall,
+            readLatency: rep.byClass?.read?.latency,
+            http: rep.http,
+            netErrors: rep.netErrors,
+            sentinelOk: rep.sentinel?.ok,
+            verdict: rep.verdict
+          };
+        } else {
+          record.error = `harness produced no report (exit ${h.code})`;
+          record.harnessTail = h.tail;
+        }
+      }
+    } catch (e: any) {
+      if (e && e.server) server = e.server as SpawnedServer; // startup crash — recover the handle
+      record.error = record.error || String(e && e.message ? e.message : e);
+    } finally {
+      pgSampler.stop = true;
+      const crashed = server ? server.exited() : true;
+      const m = readJsonl(metricsFile);
+      if (m.length) {
+        const last = m[m.length - 1];
+        record.metrics = {
+          samples: m.length,
+          rssMaxMB: MB(Math.max(...m.map((x) => x.rss))),
+          heapUsedMaxMB: MB(Math.max(...m.map((x) => x.heapUsed))),
+          heapUsedLastMB: MB(last.heapUsed),
+          buildQueueDepthMax: Math.max(...m.map((x) => x.counters?.buildQueueDepth ?? 0)),
+          lastCache: last.cache,
+          lastCounters: last.counters
+        };
+      }
+      if (server) await server.stop();
+      if (crashed) {
+        const info = server ? server.exitInfo() : { code: null, signal: null };
+        record.serverCrashed = true;
+        record.serverExit = { code: info.code, signal: info.signal };
+        record.serverLogTail = server ? server.logTail(2500) : '';
+        console.error(`[ramp] SERVER CRASHED during ${name}: code=${info.code} signal=${info.signal}`);
+      }
+      record.pgBackends = { max: pgSampler.max, samples: pgSampler.samples, err: pgSampler.err };
+      record.wallSec = Math.round((Date.now() - t0) / 1000);
+      record.endedAt = new Date().toISOString();
+      ensureParentDir(outFile);
+      fs.appendFileSync(outFile, JSON.stringify(record) + '\n');
+      console.log(`[ramp] step ${name} done in ${record.wallSec}s -> ${outFile}`);
+    }
+  }
+  console.log(`\n[ramp] all steps complete -> ${outFile}`);
+  return 0;
+}
diff --git a/packages/perf-harness/src/run/server.ts b/packages/perf-harness/src/run/server.ts
new file mode 100644
index 0000000000..03c0ce9d49
--- /dev/null
+++ b/packages/perf-harness/src/run/server.ts
@@ -0,0 +1,200 @@
+/**
+ * Server child management — shared by `run ramp`, `run soak`, and
+ * `measure instance-heap`.
+ *
+ * Boots the built cnc server with the validated soak recipe env (heap cap,
+ * blueprint pooling, metrics JSONL + optional /metrics endpoint, optional
+ * instance-heap estimate) and the fixed server flags, then waits for the port
+ * to accept a loopback connection before resolving.
+ *
+ * Two modes:
+ *   - managed (default): the child stays a direct child of this process. The
+ *     returned handle exposes live crash introspection (exited/exitInfo/logTail)
+ *     and a `stop()` that does SIGTERM -> 15s -> SIGKILL. This is what `run ramp`
+ *     uses so an 896MB-heap OOM mid-step is a recorded FINDING, not an abort.
+ *   - detached (`detached: true`): the child outlives this CLI (core/proc
+ *     spawnDetached — own process group, log file, pid file). This is what
+ *     `run soak start` uses.
+ *
+ * Return shape is a structural superset of the DESIGN `{ pid, stop }` contract.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { assertPortAllowed, PgConfig } from '../core/config';
+import { isAlive, spawnDetached, stopPid, waitForPort } from '../core/proc';
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+export interface ServerSpawnOpts {
+  name: string;
+  port: number;
+  heapMb: number;
+  metricsFile: string;
+  pg: PgConfig;
+  repoRoot: string;
+  outDir: string;
+  serverCmd?: string[];
+  cacheMax?: number;
+  instanceHeapBytes?: number;
+  metricsEndpoint?: boolean;
+  extraEnv?: Record<string, string>;
+  detached?: boolean;
+  allowHub?: boolean;
+}
+
+export interface SpawnedServer {
+  pid: number;
+  stop: () => Promise<void>;
+  // Live crash introspection (used by ramp's crash-tolerated-and-recorded path).
+  exited: () => boolean;
+  exitInfo: () => { code: number | null; signal: string | null };
+  logTail: (maxChars?: number) => string;
+  // Set only in detached mode.
+  logPath: string | null;
+  pidPath: string | null;
+}
+
+// Build the child env from the validated soak recipe. extraEnv is applied
+// BEFORE PG* (matching v2-ramps startServer ordering) so PgConfig is always the
+// single source of truth for the DB connection — extraEnv can tune GRAPHILE_*
+// but must never redirect the server to a different database.
+function buildServerEnv(o: ServerSpawnOpts): Record<string, string> {
+  const env: Record<string, string> = {
+    NODE_ENV: 'production',
+    NODE_OPTIONS: `--max-old-space-size=${o.heapMb}`,
+    GRAPHILE_DEBUG_METRICS: '1',
+    GRAPHILE_DEBUG_METRICS_FILE: o.metricsFile,
+    GRAPHILE_BLUEPRINT_POOLING: '1'
+  };
+  if (o.metricsEndpoint) env.GRAPHILE_METRICS_ENDPOINT = '1';
+  if (o.cacheMax) env.GRAPHILE_CACHE_MAX = String(o.cacheMax);
+  if (o.instanceHeapBytes) env.GRAPHILE_CACHE_INSTANCE_HEAP_BYTES = String(o.instanceHeapBytes);
+  if (o.extraEnv) Object.assign(env, o.extraEnv);
+  env.PGHOST = o.pg.host;
+  env.PGPORT = String(o.pg.port);
+  env.PGUSER = o.pg.user;
+  env.PGPASSWORD = o.pg.password;
+  env.PGDATABASE = o.pg.database;
+  return env;
+}
+
+function resolveServerArgv(o: ServerSpawnOpts): { cmd: string; args: string[] } {
+  const serverCmd = o.serverCmd && o.serverCmd.length
+    ? o.serverCmd
+    : ['node', path.join(o.repoRoot, 'packages', 'cli', 'dist', 'index.js')];
+  const cmd = serverCmd[0];
+  const baseArgs = serverCmd.slice(1);
+  const serverArgs = ['server', '--port', String(o.port), '--origin', '*', '--simpleInflection', '--postgis', '--servicesApi'];
+  return { cmd, args: [...baseArgs, ...serverArgs] };
+}
+
+export async function spawnServer(o: ServerSpawnOpts): Promise<SpawnedServer> {
+  // Guardrail: refuse to bind a reserved hub port unless explicitly allowed.
+  assertPortAllowed(o.port, !!o.allowHub, 'server-port');
+
+  const { cmd, args } = resolveServerArgv(o);
+  const overrides = buildServerEnv(o);
+
+  if (o.detached) {
+    const { pid, logPath, pidPath } = spawnDetached({
+      name: o.name,
+      cmd,
+      args,
+      env: overrides,
+      cwd: o.repoRoot,
+      outDir: o.outDir
+    });
+    const handle: SpawnedServer = {
+      pid,
+      stop: async (): Promise<void> => {
+        await stopPid(pid, 15000);
+      },
+      exited: () => !isAlive(pid),
+      exitInfo: () => ({ code: null, signal: null }),
+      logTail: (maxChars = 8000) => {
+        try {
+          return fs.readFileSync(logPath, 'utf8').slice(-maxChars);
+        } catch {
+          return '';
+        }
+      },
+      logPath,
+      pidPath
+    };
+    try {
+      await waitForPort(o.port, 120000);
+    } catch (err: any) {
+      // Hand the started child back so the caller can record/stop it.
+      if (err) err.server = handle;
+      throw err;
+    }
+    return handle;
+  }
+
+  // Managed mode: keep the child handle so the caller can observe a crash.
+  const state: { log: string; exited: boolean; exitCode: number | null; exitSignal: string | null } = {
+    log: '',
+    exited: false,
+    exitCode: null,
+    exitSignal: null
+  };
+  const child = spawn(cmd, args, {
+    cwd: o.repoRoot,
+    env: { ...process.env, ...overrides },
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  const append = (d: any): void => {
+    state.log = (state.log + d).slice(-8000);
+  };
+  if (child.stdout) child.stdout.on('data', append);
+  if (child.stderr) child.stderr.on('data', append);
+  child.on('exit', (code, signal) => {
+    state.exited = true;
+    state.exitCode = code;
+    state.exitSignal = signal;
+  });
+  child.on('error', (err) => {
+    state.exited = true;
+    state.exitCode = state.exitCode == null ? 1 : state.exitCode;
+    append(`\n[spawn error] ${err && err.message ? err.message : err}`);
+  });
+
+  const stop = async (): Promise<void> => {
+    if (state.exited) return;
+    try {
+      child.kill('SIGTERM');
+    } catch {
+      return;
+    }
+    const deadline = Date.now() + 15000;
+    while (!state.exited && Date.now() < deadline) await sleep(300);
+    if (!state.exited) {
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        return;
+      }
+      const killDeadline = Date.now() + 2000;
+      while (!state.exited && Date.now() < killDeadline) await sleep(100);
+    }
+  };
+
+  const handle: SpawnedServer = {
+    pid: child.pid as number,
+    stop,
+    exited: () => state.exited,
+    exitInfo: () => ({ code: state.exitCode, signal: state.exitSignal }),
+    logTail: (maxChars = 8000) => state.log.slice(-maxChars),
+    logPath: null,
+    pidPath: null
+  };
+  try {
+    await waitForPort(o.port, 120000);
+  } catch (err: any) {
+    if (err) err.server = handle;
+    throw err;
+  }
+  return handle;
+}
diff --git a/packages/perf-harness/src/run/soak.ts b/packages/perf-harness/src/run/soak.ts
new file mode 100644
index 0000000000..47eccd2758
--- /dev/null
+++ b/packages/perf-harness/src/run/soak.ts
@@ -0,0 +1,363 @@
+/**
+ * `run soak start|status|stop` — the soak orchestrator.
+ *
+ * NEW in the package port: replaces the hand-written out/run-soak-*.sh scripts.
+ * A soak is six long-lived components launched detached (own process group, log
+ * file, pid file) under --out-dir, tagged by --label:
+ *
+ *   server      cnc server: heap 3584, blueprint pooling, instance-heap
+ *               estimate, /metrics endpoint, metrics JSONL
+ *   harness     `load harness`  rps 30, zipf, authenticated, canary sentinel 60s
+ *   churn       `load churn`    schema:update NOTIFY every 3600s
+ *   soak-ops    `run soak-ops`  provision/drop cycle every 7200s
+ *   collector   `measure collector`  RSS + metrics tail on the server pid
+ *   pg-sampler  `measure pg`    docker + pg_stat_activity every 30s
+ *
+ * Recipe distilled from run-soak-server.sh / run-soak-load.sh / run-pg-sampler.sh.
+ * Credentials reach the harness child via the PERF_PASSWORD env var, never argv.
+ *
+ *   start   boots the server (waits for the port), then the load stack; prints a
+ *           JSON summary of pids + artifact paths.
+ *   status  pid liveness + last harness progress line + a /metrics snapshot
+ *           (loopback only, if the port answers).
+ *   stop    SIGTERM fan-out IN ORDER harness -> collector -> churn -> soak-ops ->
+ *           pg-sampler -> server (each waited on), then writes <label>.done.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { Argv, asBool, asInt, usageExit } from '../core/args';
+import { assertPortAllowed, findRepoRoot, pgConfigFromArgv, resolveCreds, resolveOutDir, resolveServerCmd } from '../core/config';
+import { isAlive, readJsonl, readPid, spawnDetached, stopPid, writeDone } from '../core/proc';
+import { spawnServer, SpawnedServer } from './server';
+
+export const SOAK_USAGE = `perf-harness run soak <start|status|stop> — long-running soak orchestrator
+
+Common:
+  --label <name>              soak label / file prefix (default soak)
+  --out-dir <dir>             artifact dir (default ./perf-out)
+
+start:
+  --fleet <file>              fleet manifest (required)
+  --duration-sec <n>          soak length (default 86400)
+  --heap-mb <n>               server heap cap MB (default 3584)
+  --port <n>                  server port (default 3333)
+  --instance-heap-bytes <n>   GRAPHILE_CACHE_INSTANCE_HEAP_BYTES (default 1450000000)
+  --rps <n>                   harness target rps (default 30)
+  --container <name>          docker container for pg-sampler (default constructive-scale-pg)
+  --server-cmd "<cmd>"        server launch command
+  --pg-* / PG*                Postgres connection overrides (default :5433 constructive)
+  --email <addr>              seeder email (default seeder@gmail.com)
+  --password <pw>             seeder password (or PERF_PASSWORD env; required for auth)
+  --allow-hub                 permit reserved hub ports (danger)
+
+status | stop:
+  (uses --label / --out-dir to locate the running soak)`;
+
+// Component keys. Pid/log files are <label>-<key>.{pid,log} under --out-dir.
+const COMPONENTS = ['server', 'harness', 'churn', 'soak-ops', 'collector', 'pg-sampler'] as const;
+type ComponentKey = (typeof COMPONENTS)[number];
+
+// SIGTERM fan-out order: load components flush FIRST, the server dies LAST.
+export const SOAK_STOP_ORDER: ComponentKey[] = ['harness', 'collector', 'churn', 'soak-ops', 'pg-sampler', 'server'];
+
+// Per-component SIGTERM grace before SIGKILL. soak-ops gets a generous window so
+// an in-flight cycle child + the final drop can finish cleanly.
+const STOP_TERM_TIMEOUT_MS: Record<ComponentKey, number> = {
+  harness: 30000,
+  collector: 15000,
+  churn: 15000,
+  'soak-ops': 1200000,
+  'pg-sampler': 15000,
+  server: 30000
+};
+
+const err = (...a: any[]): void => {
+  process.stderr.write(`${a.join(' ')}\n`);
+};
+const out = (obj: any): void => {
+  process.stdout.write(`${JSON.stringify(obj)}\n`);
+};
+const compName = (label: string, key: ComponentKey): string => `${label}-${key}`;
+
+// ---------------------------------------------------------------------------
+export async function runSoak(argv: Argv): Promise<number> {
+  if (asBool(argv.help)) {
+    console.log(SOAK_USAGE);
+    return 0;
+  }
+  // Locate the action among the command-path positionals. Scanning (rather than
+  // indexing a fixed slot) keeps this correct whether the top-level router
+  // passes the full argv (`_ = ['run','soak','start']`) or a stripped one.
+  const action = argv._.find((p) => p === 'start' || p === 'status' || p === 'stop');
+  if (action === 'start') return soakStart(argv);
+  if (action === 'status') return soakStatus(argv);
+  if (action === 'stop') return soakStop(argv);
+  return usageExit(SOAK_USAGE);
+}
+
+// ---------------------------------------------------------------------------
+// start
+// ---------------------------------------------------------------------------
+async function soakStart(argv: Argv): Promise<number> {
+  const allowHub = asBool(argv['allow-hub']);
+  const pg = pgConfigFromArgv(argv);
+  const outDir = resolveOutDir(argv);
+  const repoRoot = findRepoRoot();
+  const serverCmd = resolveServerCmd(argv, repoRoot);
+
+  const label = typeof argv.label === 'string' && argv.label ? argv.label : 'soak';
+  const port = asInt(argv.port, 3333);
+  assertPortAllowed(port, allowHub, 'server-port');
+  const heapMb = asInt(argv['heap-mb'], 3584);
+  const durationSec = asInt(argv['duration-sec'], 86400);
+  const instanceHeapBytes = asInt(argv['instance-heap-bytes'], 1450000000);
+  const rps = asInt(argv.rps, 30);
+  const container = typeof argv.container === 'string' && argv.container ? argv.container : 'constructive-scale-pg';
+
+  const fleetArg = typeof argv.fleet === 'string' ? argv.fleet : '';
+  const fleetPath = fleetArg ? path.resolve(process.cwd(), fleetArg) : '';
+  if (!fleetPath || !fs.existsSync(fleetPath)) {
+    err('run soak start: --fleet <file> is required (harness + churn drive it)');
+    return 1;
+  }
+
+  const creds = resolveCreds(argv);
+  if (!creds.password) {
+    err('run soak start: no password — set --password or PERF_PASSWORD (the soak harness authenticates)');
+    return 1;
+  }
+
+  // Refuse to stack a second soak on top of a live one.
+  const existing = readPid(outDir, compName(label, 'server'));
+  if (existing && isAlive(existing)) {
+    err(`run soak start: a soak labelled "${label}" is already running (server pid ${existing}). Stop it first or pick a new --label.`);
+    return 1;
+  }
+
+  const metricsFile = path.join(outDir, `metrics-${label}.jsonl`);
+  const harnessOut = path.join(outDir, `harness-${label}.json`);
+  const collectorOut = path.join(outDir, `collector-${label}.json`);
+  const pgFile = path.join(outDir, `pg-${label}.jsonl`);
+
+  const pgEnv: Record<string, string> = {
+    PGHOST: pg.host,
+    PGPORT: String(pg.port),
+    PGUSER: pg.user,
+    PGPASSWORD: pg.password,
+    PGDATABASE: pg.database
+  };
+
+  // 1) server (detached; waits for the port before returning).
+  err(`[soak] ${new Date().toISOString()} starting server on :${port} (heap=${heapMb}MB instanceHeap=${instanceHeapBytes})`);
+  let server: SpawnedServer;
+  try {
+    server = await spawnServer({
+      name: compName(label, 'server'),
+      port,
+      heapMb,
+      metricsFile,
+      pg,
+      repoRoot,
+      outDir,
+      serverCmd,
+      instanceHeapBytes,
+      metricsEndpoint: true,
+      detached: true,
+      allowHub
+    });
+  } catch (e: any) {
+    if (e && e.server) {
+      try {
+        await e.server.stop();
+      } catch {
+        /* best effort */
+      }
+    }
+    err(`[soak] server never came up: ${e && e.message ? e.message : e}`);
+    writeDone(outDir, label, `server-never-came-up ${new Date().toISOString()}`);
+    return 1;
+  }
+  err(`[soak] server up (pid ${server.pid}); starting load stack`);
+
+  const self = process.argv[1];
+  const pids: Record<ComponentKey, number> = { server: server.pid } as any;
+
+  // 2) harness — creds via env PERF_PASSWORD, never argv.
+  pids.harness = spawnDetached({
+    name: compName(label, 'harness'),
+    cmd: process.execPath,
+    args: [
+      self, 'load', 'harness',
+      '--fleet', fleetPath,
+      '--port', String(port),
+      '--duration-sec', String(durationSec),
+      '--rps', String(rps),
+      '--mix', 'read:0.7,write:0.25,meta:0.05',
+      '--shape', 'zipf',
+      '--auth', '1',
+      '--sentinel-interval-sec', '60',
+      '--email', creds.email,
+      '--out', harnessOut
+    ],
+    env: { PERF_PASSWORD: creds.password },
+    cwd: repoRoot,
+    outDir
+  }).pid;
+
+  // 3) churn — NOTE: run-soak-load.sh omitted --fleet, which churn-driver
+  // requires and would reject; the orchestrator passes it.
+  pids.churn = spawnDetached({
+    name: compName(label, 'churn'),
+    cmd: process.execPath,
+    args: [
+      self, 'load', 'churn',
+      '--fleet', fleetPath,
+      '--interval-notify-sec', '3600',
+      '--provision-every-sec', '0',
+      '--duration-sec', String(durationSec)
+    ],
+    env: pgEnv,
+    cwd: repoRoot,
+    outDir
+  }).pid;
+
+  // 4) soak-ops — provision/drop cycles (PG via env, creds via PERF_PASSWORD).
+  pids['soak-ops'] = spawnDetached({
+    name: compName(label, 'soak-ops'),
+    cmd: process.execPath,
+    args: [self, 'run', 'soak-ops', '--interval-sec', '7200', '--duration-sec', String(durationSec)],
+    env: { ...pgEnv, PERF_PASSWORD: creds.password },
+    cwd: repoRoot,
+    outDir
+  }).pid;
+
+  // 5) collector — RSS + metrics tail on the server pid (runs until pid exits).
+  pids.collector = spawnDetached({
+    name: compName(label, 'collector'),
+    cmd: process.execPath,
+    args: [self, 'measure', 'collector', '--pid', String(server.pid), '--metrics-file', metricsFile, '--out', collectorOut],
+    cwd: repoRoot,
+    outDir
+  }).pid;
+
+  // 6) pg-sampler — docker + pg_stat_activity every 30s for the full soak.
+  pids['pg-sampler'] = spawnDetached({
+    name: compName(label, 'pg-sampler'),
+    cmd: process.execPath,
+    args: [
+      self, 'measure', 'pg',
+      '--out', pgFile,
+      '--interval-sec', '30',
+      '--duration-sec', String(durationSec),
+      '--container', container
+    ],
+    env: pgEnv,
+    cwd: repoRoot,
+    outDir
+  }).pid;
+
+  err(`[soak] started: ${COMPONENTS.map((k) => `${k}=${pids[k]}`).join(' ')}`);
+  out({
+    t: 'soak-start',
+    label,
+    port,
+    durationSec,
+    heapMb,
+    instanceHeapBytes,
+    pids,
+    artifacts: {
+      outDir,
+      metricsFile,
+      harnessOut,
+      collectorOut,
+      pgFile,
+      logs: Object.fromEntries(COMPONENTS.map((k) => [k, path.join(outDir, `${compName(label, k)}.log`)]))
+    }
+  });
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// status
+// ---------------------------------------------------------------------------
+async function soakStatus(argv: Argv): Promise<number> {
+  const allowHub = asBool(argv['allow-hub']);
+  const outDir = resolveOutDir(argv);
+  const label = typeof argv.label === 'string' && argv.label ? argv.label : 'soak';
+  const port = asInt(argv.port, 3333);
+  assertPortAllowed(port, allowHub, 'server-port');
+
+  const components = COMPONENTS.map((key) => {
+    const pid = readPid(outDir, compName(label, key));
+    return { name: key, pid, alive: pid ? isAlive(pid) : false };
+  });
+  const serverAlive = components.find((c) => c.name === 'server')?.alive === true;
+
+  // Last harness progress line from its log (JSON lines; stderr noise skipped).
+  const harnessLog = path.join(outDir, `${compName(label, 'harness')}.log`);
+  const lines = readJsonl(harnessLog);
+  const progress = lines.filter((l) => l && l.t === 'progress');
+  const lastHarnessProgress = progress.length ? progress[progress.length - 1] : lines.length ? lines[lines.length - 1] : null;
+
+  // /metrics snapshot — loopback only, only if the server pid is alive.
+  const metrics = serverAlive ? await fetchMetrics(port) : null;
+
+  out({
+    t: 'soak-status',
+    label,
+    running: components.some((c) => c.alive),
+    components,
+    lastHarnessProgress,
+    metrics
+  });
+  return 0;
+}
+
+async function fetchMetrics(port: number): Promise<any> {
+  for (const host of ['127.0.0.1', '[::1]']) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), 2000);
+    try {
+      const res = await fetch(`http://${host}:${port}/metrics`, { signal: ac.signal });
+      const text = await res.text();
+      try {
+        return { host, status: res.status, json: JSON.parse(text) };
+      } catch {
+        return { host, status: res.status, text: text.slice(0, 4000) };
+      }
+    } catch {
+      /* try the next loopback family */
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// stop
+// ---------------------------------------------------------------------------
+async function soakStop(argv: Argv): Promise<number> {
+  const outDir = resolveOutDir(argv);
+  const label = typeof argv.label === 'string' && argv.label ? argv.label : 'soak';
+
+  const results: Array<{ name: ComponentKey; pid: number | null; result: string }> = [];
+  for (const key of SOAK_STOP_ORDER) {
+    const pid = readPid(outDir, compName(label, key));
+    if (!pid || !isAlive(pid)) {
+      results.push({ name: key, pid, result: pid ? 'gone' : 'absent' });
+      err(`[soak] stop ${key}: ${pid ? 'already gone' : 'no pid file'}`);
+      continue;
+    }
+    err(`[soak] stopping ${key} (pid ${pid})...`);
+    const result = await stopPid(pid, STOP_TERM_TIMEOUT_MS[key]);
+    results.push({ name: key, pid, result });
+    err(`[soak] ${key} -> ${result}`);
+  }
+
+  const doneBody = `stopped ${new Date().toISOString()} :: ${results.map((r) => `${r.name}=${r.result}`).join(' ')}`;
+  writeDone(outDir, label, doneBody);
+  out({ t: 'soak-stop', label, order: SOAK_STOP_ORDER, results, done: path.join(outDir, `${label}.done`) });
+  return 0;
+}
diff --git a/packages/perf-harness/src/run/soakOps.ts b/packages/perf-harness/src/run/soakOps.ts
new file mode 100644
index 0000000000..afce207bb0
--- /dev/null
+++ b/packages/perf-harness/src/run/soakOps.ts
@@ -0,0 +1,149 @@
+/**
+ * `run soak-ops` — V3 soak operations churn (port of soak-ops.mjs).
+ *
+ * Every --interval-sec: provision ONE new tenant (`fleet provision`, own
+ * prefix), then drop the tenant created by the PREVIOUS cycle (`fleet
+ * teardown`). Net effect: the soak continuously exercises the full provision +
+ * teardown paths (catalog writes, schema:update NOTIFY -> flush -> rebuild on
+ * next hit) WITHOUT net catalog growth — important because instance heap scales
+ * ~21KB/pg_class row, so unbounded provisioning would inflate the resident
+ * instance past the heap mid-soak and turn a longevity test into a slow OOM.
+ *
+ * Both provision and teardown are child invocations of THIS CLI. The created
+ * tenant name is recovered from the provision child's stdout.
+ *
+ * FIX vs the original: a SIGINT/SIGTERM now stops AFTER the in-flight cycle's
+ * child processes exit, performs the final drop, and exits cleanly — the
+ * original had no signal handler, so a stop mid-soak could leak the last tenant.
+ */
+import { spawnSync } from 'node:child_process';
+
+import { Argv, asBool, asInt } from '../core/args';
+import { pgConfigFromArgv } from '../core/config';
+
+export const SOAK_OPS_USAGE = `perf-harness run soak-ops — cycle tenant provision/teardown during a soak
+
+Options:
+  --interval-sec <n>          cycle period (default 7200)
+  --duration-sec <n>          total run length (default 86400)
+  --prefix <name>             provision prefix (default soak)
+  --blueprint <name>          blueprint to provision (default marketplace)
+  --pg-* / PG*                Postgres connection overrides (default :5433 constructive)
+  --allow-hub                 permit reserved hub ports (danger)
+  --help
+
+Provision/teardown run as child invocations of this CLI; credentials flow via
+the inherited environment (PERF_PASSWORD), PG connection via injected PG* env.`;
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+const now = (): string => new Date().toISOString();
+
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for tests)
+// ---------------------------------------------------------------------------
+export interface CycleTiming {
+  waitMs: number;
+  stop: boolean;
+}
+
+// Cycle-pacing math ported verbatim from soak-ops.mjs:
+//   wait = max(0, interval - elapsed); stop if now + wait would cross deadline.
+export function computeCycleTiming(opts: { intervalSec: number; elapsedMs: number; now: number; deadline: number }): CycleTiming {
+  const waitMs = Math.max(0, opts.intervalSec * 1000 - opts.elapsedMs);
+  const stop = opts.now + waitMs >= opts.deadline;
+  return { waitMs, stop };
+}
+
+// tenant-factory / `fleet provision` auto-picks the next free index; recover the
+// name it made from its stdout ("[<name>] OK db=" or "indices=<n>..").
+export function recoverCreatedName(out: string, prefix: string): string | null {
+  const m = /\[(\w+)\] OK db=/.exec(out) || /indices=(\d+)\.\./.exec(out);
+  if (!m) return null;
+  return m[1].startsWith(prefix) ? m[1] : `${prefix}${m[1]}`;
+}
+
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+export async function runSoakOps(argv: Argv): Promise<number> {
+  if (asBool(argv.help)) {
+    console.log(SOAK_OPS_USAGE);
+    return 0;
+  }
+  const intervalSec = asInt(argv['interval-sec'], 7200);
+  const durationSec = asInt(argv['duration-sec'], 86400);
+  const prefix = typeof argv.prefix === 'string' ? argv.prefix : 'soak';
+  const blueprint = typeof argv.blueprint === 'string' ? argv.blueprint : 'marketplace';
+
+  // Resolve PG once (this also runs the hub-port guardrail) and inject it into
+  // the child env so provision/teardown hit the same DB without creds on argv.
+  const pg = pgConfigFromArgv(argv);
+  const childEnv: Record<string, string> = {
+    ...process.env,
+    PGHOST: pg.host,
+    PGPORT: String(pg.port),
+    PGUSER: pg.user,
+    PGPASSWORD: pg.password,
+    PGDATABASE: pg.database
+  };
+
+  const runCli = (args: string[]): { status: number | null; out: string; tail: string } => {
+    const res = spawnSync(process.execPath, [process.argv[1], ...args], {
+      env: childEnv,
+      encoding: 'utf8',
+      timeout: 30 * 60 * 1000
+    });
+    const out = `${res.stdout || ''}${res.stderr || ''}`;
+    return { status: res.status, out, tail: out.split('\n').filter(Boolean).slice(-3).join(' | ') };
+  };
+
+  const deadline = Date.now() + durationSec * 1000;
+  let cycle = 0;
+  let previousName: string | null = null;
+  let stopping = false;
+  let stopReason: string | null = null;
+  const onSig = (sig: string): void => {
+    stopping = true;
+    stopReason = stopReason || sig;
+  };
+  process.on('SIGINT', () => onSig('SIGINT'));
+  process.on('SIGTERM', () => onSig('SIGTERM'));
+
+  console.log(`[soak-ops] ${now()} start: interval=${intervalSec}s duration=${durationSec}s prefix=${prefix}`);
+
+  while (!stopping && Date.now() < deadline) {
+    cycle++;
+    const t0 = Date.now();
+
+    const create = runCli(['fleet', 'provision', '--count', '1', '--prefix', prefix, '--blueprint', blueprint]);
+    const createdName = recoverCreatedName(create.out, prefix);
+    console.log(
+      `[soak-ops] ${now()} cycle=${cycle} provision status=${create.status} created=${createdName || '?'} :: ${create.tail}`
+    );
+
+    if (previousName) {
+      const drop = runCli(['fleet', 'teardown', '--only', previousName]);
+      console.log(`[soak-ops] ${now()} cycle=${cycle} drop ${previousName} status=${drop.status} :: ${drop.tail}`);
+    }
+    previousName = createdName || previousName;
+
+    // A signal that landed during the (synchronous) child runs is delivered
+    // now — stop before starting the next cycle's provision.
+    if (stopping) break;
+
+    const timing = computeCycleTiming({ intervalSec, elapsedMs: Date.now() - t0, now: Date.now(), deadline });
+    if (timing.stop) break;
+    // Interruptible wait so a signal during the long idle breaks promptly.
+    const until = Date.now() + timing.waitMs;
+    while (!stopping && Date.now() < until) await sleep(500);
+  }
+
+  // Final cleanup: drop the last soak tenant so the fleet is back to baseline.
+  // This runs on normal completion AND on signal (the fix).
+  if (previousName) {
+    const drop = runCli(['fleet', 'teardown', '--only', previousName]);
+    console.log(`[soak-ops] ${now()} final cleanup ${previousName} status=${drop.status} :: ${drop.tail}`);
+  }
+  console.log(`[soak-ops] ${now()} done after ${cycle} cycles${stopReason ? ` (${stopReason})` : ''}`);
+  return 0;
+}
diff --git a/packages/perf-harness/tsconfig.esm.json b/packages/perf-harness/tsconfig.esm.json
new file mode 100644
index 0000000000..800d7506d3
--- /dev/null
+++ b/packages/perf-harness/tsconfig.esm.json
@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist/esm",
+    "module": "es2022",
+    "rootDir": "src/",
+    "declaration": false
+  }
+}
diff --git a/packages/perf-harness/tsconfig.json b/packages/perf-harness/tsconfig.json
new file mode 100644
index 0000000000..1a9d5696cb
--- /dev/null
+++ b/packages/perf-harness/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src/"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "node_modules", "**/*.spec.*", "**/*.test.*"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0a8c79ca0a..a8e1545397 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2553,6 +2553,38 @@ importers:
         version: 0.3.0
     publishDirectory: dist
 
+  packages/perf-harness:
+    dependencies:
+      '@inquirerer/utils':
+        specifier: ^3.3.9
+        version: 3.3.9
+      graphile-cache:
+        specifier: workspace:^
+        version: link:../../graphile/graphile-cache/dist
+      inquirerer:
+        specifier: ^4.9.1
+        version: 4.9.1
+      pg:
+        specifier: ^8.21.0
+        version: 8.21.0
+    devDependencies:
+      '@inquirerer/test':
+        specifier: ^1.4.3
+        version: 1.4.3(jest@30.4.2(@types/node@22.19.19)(ts-node@10.9.2(@types/node@22.19.19)(typescript@5.9.3)))
+      '@types/node':
+        specifier: ^22.19.11
+        version: 22.19.19
+      '@types/pg':
+        specifier: ^8.20.0
+        version: 8.20.0
+      makage:
+        specifier: ^0.3.0
+        version: 0.3.0
+      ts-node:
+        specifier: ^10.9.2
+        version: 10.9.2(@types/node@22.19.19)(typescript@5.9.3)
+    publishDirectory: dist
+
   packages/postmaster:
     dependencies:
       12factor-env:
@@ -12038,6 +12070,13 @@ snapshots:
     optionalDependencies:
       jest: 30.4.2(@types/node@22.19.11)(ts-node@10.9.2(@types/node@22.19.11)(typescript@5.9.3))
 
+  '@inquirerer/test@1.4.3(jest@30.4.2(@types/node@22.19.19)(ts-node@10.9.2(@types/node@22.19.19)(typescript@5.9.3)))':
+    dependencies:
+      clean-ansi: 0.2.1
+      inquirerer: 4.9.1
+    optionalDependencies:
+      jest: 30.4.2(@types/node@22.19.19)(ts-node@10.9.2(@types/node@22.19.19)(typescript@5.9.3))
+
   '@inquirerer/utils@3.3.9':
     dependencies:
       appstash: 0.7.0
@@ -12112,6 +12151,43 @@ snapshots:
       - supports-color
       - ts-node
 
+  '@jest/core@30.4.2(ts-node@10.9.2(@types/node@22.19.19)(typescript@5.9.3))':
+    dependencies:
+      '@jest/console': 30.4.1
+      '@jest/pattern': 30.4.0
+      '@jest/reporters': 30.4.1
+      '@jest/test-result': 30.4.1
+      '@jest/transform': 30.4.1
+      '@jest/types': 30.4.1
+      '@types/node': 22.19.19
+      ansi-escapes: 4.3.2
+      chalk: 4.1.2
+      ci-info: 4.4.0
+      exit-x: 0.2.2
+      fast-json-stable-stringify: 2.1.0
+      graceful-fs: 4.2.11
+      jest-changed-files: 30.4.1
+      jest-config: 30.4.2(@types/node@22.19.19)(ts-node@10.9.2(@types/node@22.19.19)(typescript@5.9.3))
+      jest-haste-map: 30.4.1
+      jest-message-util: 30.4.1
+      jest-regex-util: 30.4.0
+      jest-resolve: 30.4.1
+      jest-resolve-dependencies: 30.4.2
+      jest-runner: 30.4.2
+      jest-runtime: 30.4.2
+      jest-snapshot: 30.4.1
+      jest-util: 30.4.1
+      jest-validate: 30.4.1
+      jest-watcher: 30.4.1
+      pretty-format: 30.4.1
+      slash: 3.0.0
+    transitivePeerDependencies:
+      - babel-plugin-macros
+      - esbuild-register
+      - supports-color
+      - ts-node
+    optional: true
+
   '@jest/diff-sequences@30.0.1': {}
 
   '@jest/diff-sequences@30.4.0': {}
@@ -16257,6 +16333,26 @@ snapshots:
       - supports-color
       - ts-node
 
+  jest-cli@30.4.2(@types/node@22.19.19)(ts-node@10.9.2(@types/node@22.19.19)(typescript@5.9.3)):
+    dependencies:
+      '@jest/core': 30.4.2(ts-node@10.9.2(@types/node@22.19.19)(typescript@5.9.3))
+      '@jest/test-result': 30.4.1
+      '@jest/types': 30.4.1
+      chalk: 4.1.2
+      exit-x: 0.2.2
+      import-local: 3.2.0
+      jest-config: 30.4.2(@types/node@22.19.19)(ts-node@10.9.2(@types/node@22.19.19)(typescript@5.9.3))
+      jest-util: 30.4.1
+      jest-validate: 30.4.1
+      yargs: 17.7.2
+    transitivePeerDependencies:
+      - '@types/node'
+      - babel-plugin-macros
+      - esbuild-register
+      - supports-color
+      - ts-node
+    optional: true
+
   jest-config@30.4.2(@types/node@22.19.11)(ts-node@10.9.2(@types/node@22.19.11)(typescript@5.9.3)):
     dependencies:
       '@babel/core': 7.29.0
@@ -16321,6 +16417,39 @@ snapshots:
       - babel-plugin-macros
       - supports-color
 
+  jest-config@30.4.2(@types/node@22.19.19)(ts-node@10.9.2(@types/node@22.19.19)(typescript@5.9.3)):
+    dependencies:
+      '@babel/core': 7.29.0
+      '@jest/get-type': 30.1.0
+      '@jest/pattern': 30.4.0
+      '@jest/test-sequencer': 30.4.1
+      '@jest/types': 30.4.1
+      babel-jest: 30.4.1(@babel/core@7.29.0)
+      chalk: 4.1.2
+      ci-info: 4.4.0
+      deepmerge: 4.3.1
+      glob: 10.5.0
+      graceful-fs: 4.2.11
+      jest-circus: 30.4.2
+      jest-docblock: 30.4.0
+      jest-environment-node: 30.4.1
+      jest-regex-util: 30.4.0
+      jest-resolve: 30.4.1
+      jest-runner: 30.4.2
+      jest-util: 30.4.1
+      jest-validate: 30.4.1
+      parse-json: 5.2.0
+      pretty-format: 30.4.1
+      slash: 3.0.0
+      strip-json-comments: 3.1.1
+    optionalDependencies:
+      '@types/node': 22.19.19
+      ts-node: 10.9.2(@types/node@22.19.19)(typescript@5.9.3)
+    transitivePeerDependencies:
+      - babel-plugin-macros
+      - supports-color
+    optional: true
+
   jest-diff@29.7.0:
     dependencies:
       chalk: 4.1.2
@@ -16614,6 +16743,20 @@ snapshots:
       - supports-color
       - ts-node
 
+  jest@30.4.2(@types/node@22.19.19)(ts-node@10.9.2(@types/node@22.19.19)(typescript@5.9.3)):
+    dependencies:
+      '@jest/core': 30.4.2(ts-node@10.9.2(@types/node@22.19.19)(typescript@5.9.3))
+      '@jest/types': 30.4.1
+      import-local: 3.2.0
+      jest-cli: 30.4.2(@types/node@22.19.19)(ts-node@10.9.2(@types/node@22.19.19)(typescript@5.9.3))
+    transitivePeerDependencies:
+      - '@types/node'
+      - babel-plugin-macros
+      - esbuild-register
+      - supports-color
+      - ts-node
+    optional: true
+
   jiti@2.7.0: {}
 
   js-beautify@1.15.4:
@@ -19250,6 +19393,24 @@ snapshots:
       v8-compile-cache-lib: 3.0.1
       yn: 3.1.1
 
+  ts-node@10.9.2(@types/node@22.19.19)(typescript@5.9.3):
+    dependencies:
+      '@cspotcode/source-map-support': 0.8.1
+      '@tsconfig/node10': 1.0.12
+      '@tsconfig/node12': 1.0.11
+      '@tsconfig/node14': 1.0.3
+      '@tsconfig/node16': 1.0.4
+      '@types/node': 22.19.19
+      acorn: 8.15.0
+      acorn-walk: 8.3.4
+      arg: 4.1.3
+      create-require: 1.1.1
+      diff: 4.0.2
+      make-error: 1.3.6
+      typescript: 5.9.3
+      v8-compile-cache-lib: 3.0.1
+      yn: 3.1.1
+
   ts-node@10.9.2(@types/node@25.9.1)(typescript@5.9.3):
     dependencies:
       '@cspotcode/source-map-support': 0.8.1
diff --git a/scripts/scale-validate/SIZING.md b/scripts/scale-validate/SIZING.md
new file mode 100644
index 0000000000..e42efa2baf
--- /dev/null
+++ b/scripts/scale-validate/SIZING.md
@@ -0,0 +1,205 @@
+# Multi-Tenant Sizing Model — cnc PostGraphile server with blueprint pooling
+
+All constants measured on `feat/scale-phase0` (blueprint pooling + hardening), isolated
+PG 17 rig, 47-tenant fleet, catalog 61k `pg_class` rows. Method and raw data:
+`V2-RESULTS.md` + `out/v2-*-results.jsonl`.
+
+## 2026-07-06 — the introspection filter rewrites the constants
+
+With `GRAPHILE_INTROSPECTION_FILTER=1` (namespace-scoped catalog introspection at the
+pool seam; SDL byte-identical, MD5-proven), the catalog-size axis collapses:
+
+| constant | stock | filtered | factor |
+|---|---|---|---|
+| instance retained heap @61k rows | 1305.6MB (21.9KB/row) | **14.7MB (0.24KB/row)** | 87× |
+| cold schema build | 7165ms | **417ms** | 17× |
+| PG-side introspection spike | +1283MiB | **+17MiB** | 75× |
+| realtime tenant (dedicated instance) | 2596MB | **14.7MB** | 176× |
+
+Capacity with the shipped defaults (B=256MB, T=768MB, planning I=40MiB — measured
+15–35MB): `R(H) = clamp(min(⌊(H−B)/I⌋, ⌊(H−B−T)/I⌋+1), 1, 50)` →
+**1024MB→1 · 1536MB→13 · 2048MB→26 · 3072MB+→50 (cap)**. Measured at 2048MB: six
+resident blueprints use 167MB total; the 187rps knee runs at 339MB. T=768 is a
+stock-era transient reserve — with the filter the true transient is ~50–100MB, so
+`GRAPHILE_CACHE_BUILD_RESERVE_BYTES` can unlock 1024MB→13 / 1536MB→26 / 2048MB→39
+when density at small heaps matters. **Floor: 1024MB minimum heap** (≤768MB heaps die
+under 100%-miss rebuild churn before any governor signal can fire — not a supported
+configuration). RSS ≈ heap×~2.2 at these working sets. Set
+`GRAPHILE_CACHE_INSTANCE_HEAP_BYTES=41943040` so admission plans with the filtered
+instance size.
+
+Churn robustness (fix `46636d4b4`): the build-wait race timer no longer pins built
+instances (was: every evicted ~15MB instance stayed reachable for 180s → forced
+`max=1` churn OOM-killed a 2GB heap in 65s). Post-fix, worst-case all-miss churn at
+2048MB runs a bounded sawtooth at 23 builds/s and recovers cleanly; the realistic
+over-capacity mode (blueprints = capacity+1 rotating) sustains 100% success. The
+heap-pressure governor now measures against V8's actually-exhaustible headroom
+(`used/(used+total_available_size)`) — the old `heap_size_limit` denominator made the
+0.85/0.92 watermarks unreachable at every heap size — and re-checks inside the build
+critical section with `GRAPHILE_BUILD_PRESSURE_SPACING_MS` (default 250ms) spacing
+under elevated pressure.
+
+## The model in one paragraph
+
+Memory cost is driven by **catalog size** (total relations in the PG database), not by
+tenant count. Every *resident schema instance* on the node retains
+`I ≈ 50MB + 21KB × pg_class_rows`, and every *schema build* spikes a PG backend by
+`≈ 37KB × pg_class_rows`. Tenants sharing a blueprint are free (zero marginal heap,
+zero marginal builds). So you size in two axes: **how many relations live in one PG
+database** (shard size) and **how many distinct blueprint shapes a node must keep
+resident** (node capacity R).
+
+## Corrected scaling axes (2026-07-03)
+
+Re-measurement on the isolated 48-logical-tenant rig (catalog **61,341 `pg_class` rows**,
+all tenants as hash-prefixed schema sets inside one physical DB) sharpens the two axes
+above — the laws are unchanged; the *interpretation of R* is refined.
+
+**Per-tenant catalog cost is a near-constant set by the base stack, not the blueprint.**
+Each logical tenant adds a uniform **~901–904 `pg_class` rows**, of which only **~18 come
+from the app blueprint** — the rest is the ~40-module base stack (auth, billing, events,
+limits, `pg_partman` partitions, …) that every tenant carries. Blueprints in
+`constructive-db` are 1–5 tables, so **blueprint size variance is immaterial** to sizing:
+price shards on tenant *count*, treating per-tenant catalog cost as fixed.
+
+**Node memory scales with actively-hot API surfaces × settings variants (R), priced
+class-independently at `I = 22KB × shard catalog rows`** (≈1.45GB at 61k rows; the same
+measurement as the banked 21KB/row V2 constant, rounded). What multiplies I is **R = the
+number of distinct pool keys concurrently hot on the node**. The blueprint cache key is
+`[logicalSchemas, relname-shape-fingerprint, databaseSettings-flags, apiName, mode,
+dbname]`, so **each API surface and each settings variant splits the pool
+independently**. A tenant exposes **~9 APIs / 8 routable hosts** on the rig (admin,
+agent, api, auth, compute, config, objects, usage are routable; notifications is not),
+but **only concurrently-hit surfaces count toward R** — api+auth resident is R=2; add
+admin+usage under live traffic and it is R=4. (`regression run --suite deep`'s
+`multi-api-residency` check measures exactly this.)
+
+**Settings flags are part of the pool key.** The rig currently has **zero
+`services_public.database_settings` / `api_settings` rows** — every tenant runs on column
+defaults (postgis / search / uploads / m2m / connection_filter / ltree **ON**; aggregates
+/ llm / realtime / bulk / i18n **OFF**), so the fleet is uniform and settings split no
+pool *today*. The moment a tenant gets a non-default `database_settings` row its shape
+forks a **second** pooled instance (**+1 to R**) for the same relations.
+
+**`enable_realtime` makes a tenant unpoolable.** Per
+`graphql/server/src/middleware/pooling-decision.ts`, a service with `enableRealtime=true`
+gets a **dedicated per-tenant instance** and can never share — so every realtime tenant
+costs a full I of resident heap on its own. **House realtime tenants in small-catalog
+shards** so that dedicated instance is cheap.
+
+**partman partitions grow the catalog over time.** The base stack partman-partitions
+events / billing / limits / user_auth (~144 partition children per tenant, `premake=2`;
+`part_config` has 349 rows fleet-wide). Partitions are pre-created on each
+`partition_interval`, so catalog rows — and therefore I — **creep upward per tenant per
+interval** until retention drops old partitions. Retention bounds it; an
+unbounded-retention tenant grows I without limit.
+
+**Corrected sizing law (residency floor):**
+
+```
+heap ≥ 256MB  +  R × I  +  768MB
+       └ B ┘      └ resident ┘   └ T ┘
+       base       R instances    one build
+       reserve    @ 22KB/row      transient
+```
+
+i.e. `H ≥ B + R·I + T` — the residency form of the two-constraint budget in
+`computeCapacityFromBudget`. R counts every concurrently-hot **(surface × settings-variant)**
+instance, so a node serving api+auth+admin+usage for one blueprint is R=4, and any
+settings variant on those adds one more.
+
+## Node capacity (implemented in `computeCapacityFromBudget`)
+
+```
+I  = per-instance heap        (measure once per catalog size; 1.30–1.35GB @ 61k rows)
+B  = base reserve             (server + request working set; default 256MB)
+T  = build transient reserve  (one in-flight build;          default 768MB @ 61k rows)
+H  = --max-old-space-size
+
+R = clamp( min( ⌊(H − B) / I⌋,  ⌊(H − B − T) / I⌋ + 1 ), 1, 50 )
+```
+
+Validated points @61k-row catalog (I=1.45GB estimate):
+
+| Heap H | R | Evidence |
+|---|---|---|
+| 896MB / 1152MB | 0 → build aborts | V8 SIGABRT mid-build (floor probes) |
+| 1536MB | 1 | healthy k1, p99 34ms |
+| 2048MB | 1 | healthy single-bp at 188rps; thrash beyond 1 bp |
+| 3584MB | 2 | api+auth both resident, 0 evictions (r2 probe + live soak) |
+| ~5.9GB | 3 (computed) | unvalidated |
+
+**Container sizing:** RSS ≈ heap × 1.4–1.5 (native/external on top of V8 heap).
+A "2GB-heap" node needs a ~3GB container; for a hard-2GB container run heap ≤1400MB —
+which at a 61k-row catalog is BELOW the 1536MB single-instance floor. Practical
+minimum container at this catalog: ~2.5GB (heap 1792).
+
+**Operating rule:** R must cover the node's *actively hit* blueprint set — api AND
+auth shapes count separately. A tenant fleet on one node needs R ≥ 2 (validated: at
+R=1, hourly batch relogins collide with api traffic and failed relogins retry every
+30s → self-sustaining eviction oscillation; at R=2 the same workload runs clean).
+
+## Per-blueprint throughput (one 2GB node, 32 tenants, mixed authenticated workload)
+
+- ≥188 rps sustained, p50 13ms / p99 21ms, zero errors, PG pool at 5 connections —
+  no knee found up to 200 rps (per-request DB time 1–5ms).
+- Warm request latency is independent of tenant count within the blueprint
+  (10 vs 32 tenants: identical).
+- Cold build: ~8s (cold PG relcache) / ~1s rebuild (warm); builds serialize behind
+  `BuildSemaphore(1)`, protecting both node heap and PG.
+
+## PG-database shard sizing (the real tenant limit)
+
+Per-database catalog cost, measured at ~1.19k `pg_class` rows per marketplace tenant:
+
+| Cost | Scaling | Measured |
+|---|---|---|
+| Introspection backend spike | ~37KB/row, PER BUILD | 2.7GB @61k rows; OOM-killed >5.4GB @135k |
+| Backend relcache retention | multi-GB per pooled conn that ever ran a build | accumulates across pool; recycle via `idle_session_timeout` (validated) or pgbouncer `server_lifetime` |
+| Node instance heap | ~21KB/row per resident instance | 1.3GB @61k rows |
+| Provisioning wall time | superlinear | 74s @17k rows → 138s @135k rows |
+
+Shard guidance (marketplace-class tenants, ~1.2k rows each):
+
+| PG node RAM | Safe catalog | ≈ Tenants/shard | Node heap for R=2 |
+|---|---|---|---|
+| 8GB | ~60k rows | ~40–45 | 3.5–4GB |
+| 16GB | ~120k rows | ~85–95 | 5.5–6.5GB (I≈2.6GB) |
+| 32GB | ~250k rows | ~180–200 | 11–13GB (I≈5.4GB) |
+| 64GB | ~500k rows | ~380–400 | 22–26GB (I≈10.7GB) |
+
+(Instance heap I grows with the shard's catalog, so bigger shards need
+disproportionately bigger app nodes — favor MORE, SMALLER shards.)
+
+**1000 tenants, concretely:** 10 shards × ~100 tenants (16GB PG nodes), each shard
+served by one app node with R=2 (heap ~6GB, container ~9GB) — or split api/auth onto
+two 2.5-3GB-heap nodes per shard at R=1 each, accepting the auth/api isolation.
+The blueprint cache key already scopes by database (`d`), so shard-local pooling
+needs no code changes.
+
+## Hardening shipped with this branch (all validated live)
+
+| Mechanism | What it prevents | Knob |
+|---|---|---|
+| Heap-aware cap, floor 1 (`24d49252f`) | over-admission SIGABRT | `GRAPHILE_CACHE_MAX`, `GRAPHILE_CACHE_INSTANCE_HEAP_BYTES` |
+| Two-constraint budget (`0a8a95402`) | wasted capacity / unsafe admits | `GRAPHILE_CACHE_BASE_RESERVE_BYTES`, `GRAPHILE_CACHE_BUILD_RESERVE_BYTES` |
+| Evict-before-build headroom | build spike on a full cache | (automatic) |
+| Memory governor 85%/92% (`0a8a95402`) | pressure death-spiral; refuses builds at critical, keeps serving residents | `GRAPHILE_MEMORY_GOVERNOR[_ELEVATED/_CRITICAL]` |
+| Build wait timeout (`0a8a95402`) | unbounded request queues behind builds | `GRAPHILE_BUILD_TIMEOUT_MS` (503 BUILD_TIMEOUT; build completes in background) |
+| Connection-class error guard (`d42ca1769`) | PG restart killing the whole node | `GRAPHILE_CONNECTION_GUARD=0` to disable |
+| `/metrics` endpoint (`0a8a95402`) | blind operation | `GRAPHILE_METRICS_ENDPOINT=1` |
+| BuildSemaphore(1) | concurrent build spikes (node AND PG) | `GRAPHILE_BUILD_CONCURRENCY` |
+
+PG-side ops: cap the PG container (cgroup OOM → 15–20s crash-recovery, absorbed by
+the guard) and recycle idle backends (`idle_session_timeout` — beware it also reaps
+long-idle clients: LISTEN connections and drivers must reconnect; the server's
+listener does).
+
+## Measuring I for YOUR catalog
+
+```
+node scripts/scale-validate/measure-instance-heap.mjs \
+  --label my-api --host api-<tenant>.<domain> --port 3344 --heap-mb 4096
+```
+Then set `GRAPHILE_CACHE_INSTANCE_HEAP_BYTES` to the measured delta + ~10%.
+Rule of thumb without measuring: `I ≈ 50MB + 21KB × pg_class_rows`.
diff --git a/scripts/scale-validate/V2-RESULTS.md b/scripts/scale-validate/V2-RESULTS.md
new file mode 100644
index 0000000000..78cc2d108a
--- /dev/null
+++ b/scripts/scale-validate/V2-RESULTS.md
@@ -0,0 +1,115 @@
+# V2 — Limits Discovery Results (2GB validation program)
+
+Rig: isolated PG 17 (`constructive-scale-pg`, :5433, container capped 4.5GiB + 1.5GiB swap,
+`idle_session_timeout=120s`), cnc server from `feat/scale-phase0`, blueprint pooling ON,
+fleet = 47 tenants (40 factory clones + reference + 6 divergent seeder tenants),
+catalog = **61,238 pg_class rows / 1,876 namespaces / 48 databases**.
+Workload: token-bucket open-loop harness, authenticated, mix read:0.7 write:0.25 meta:0.05,
+per-tenant bleed sentinel every 60s. All numbers from `out/v2-*-results.jsonl` +
+`out/harness-*.json` + 10s metrics samples (`out/metrics-*.jsonl`).
+
+## Headline findings (chronological discovery order)
+
+1. **PG-side catalog wall.** PostGraphile v5 introspection scans the whole catalog
+   (no schema filter in `pg-introspection@1.0.1`). Backend memory ≈ **37KB per
+   pg_class row** net: ~2.7GiB spike at 61k rows (15s wall); OOM-killed >5.4GiB at
+   135k rows (101 tenants) *even running alone*. JIT/parallel-off does NOT help
+   (inherent: catalog JSON materialization + relcache). Introspection backends
+   RETAIN multi-GB relcache per pooled connection and accumulate across the pool.
+2. **Node-side catalog wall.** EVERY resident instance retains **~1.3GB heap at
+   this catalog** (tenant-api 1304MB ≡ tenant-auth 1307MB ≡ schema-builder 1316MB
+   — class-independent ⇒ it's the introspection graph, ~**21KB per pg_class row**,
+   consistent with the earlier 464MB floor at a ~17k-row catalog). A 700MB-heap
+   build aborts mid-introspection-receive: live memory, not garbage.
+3. **Cap floor over-admission (FIXED, `24d49252f`).** `MIN_CACHE_MAX = 3` overrode
+   the heap-aware budget; count-based headroom never evicted; admitting a second
+   1.3GB build SIGABRT'd the 2GB process (as-shipped div-k1 crash record). Floor
+   is now 1.
+4. **PG restart killed the whole server (FIXED, `d42ca1769`).** PG crash-recovery
+   (its own introspection OOM) terminated every pooled connection; one orphaned pg
+   Client raised an unhandled 'error' event → process exit. A ~15s PG hiccup was a
+   full multi-tenant outage. `installConnectionErrorGuard()` absorbs
+   connection-class errors only (counted in metrics `counters.connGuard`);
+   validated live: **332/349/344 absorbed per thrash step, zero process deaths**.
+
+## Measured constants (61k-row catalog)
+
+| Constant | Value |
+|---|---|
+| Resident instance heap (any class) | ~1.30–1.32GB (~21KB/pg_class row) |
+| Server base heap | ~46–66MB |
+| Build transient | >700MB (1152MB heap aborts with 0 residents) |
+| Min viable heap, 1 resident | **1536MB PASS / 1152MB ABORT** |
+| RSS vs heap | heapMax 1.46GB → RSS 2.2–2.4GB (≈1.5×) |
+| Cold build (cold PG) | ~8s |
+| Rebuild (warm PG relcache) | ~1s; thrash sustains ~1 build/s |
+| Warm request latency (healthy) | p50 21ms / p95 34ms / p99 34ms |
+| Marginal heap per tenant (same blueprint) | **~0** (1460.1/1459.6/1464.1MB @ 10/20/32 tenants) |
+| PG introspection spike | ~37KB/pg_class row; per BUILD; serialized by BuildSemaphore |
+| Provisioning wall time | 74s @17k rows → 138s @135k rows (superlinear in catalog) |
+
+## Regime results @2GB heap (tuned estimate 1.45GB → capacity R=1)
+
+| Step | Result |
+|---|---|
+| div-k1 (1 blueprint ×2 tenants) | HEALTHY: 5584/5584 HTTP 200, p99 34ms, 2 builds, 1 evict |
+| div-k2/k3/k5 (2–5 blueprints, uniform) | THRASH-NOT-CRASH: errRate 1.0, p50 ~1s, p99 6.8s, 429–525 builds/step, heap bounded ≤1.42GB, sentinel passing, 0 process deaths |
+| ten-10/20/33 (1 blueprint, zipf) | HEALTHY at all sizes; zero marginal heap |
+| rps-10/25/50 (full 47-tenant fleet, ~10 blueprints, zipf) | THRASH: zipf tail keeps touching non-resident blueprints; bimodal latency (p50 144ms→89ms resident hits vs 6.8s timeouts) |
+| cold-burst (5 blueprints at once) | 0/5 cold successes at R=1 (mutual eviction + PG churn); warm wave ≤58ms |
+| 3584MB k1/k3/k5 | Same as 2048: R still 1 (budget formula: 3584×0.5/1450 → 1) |
+| Heap floor | 1536 PASS / 1152 ABORT / 896 ABORT |
+| As-shipped control (512MB estimate, floor 3) | div-k1 SIGABRT ~40s in (banked in v2-2048-results.jsonl) |
+
+**Capacity law (current formula):** R = max(1, floor(heap × 0.5 / instanceEstimate)).
+With 1.3GB instances: R=1 for heap ∈ [1.5GB, ~5.8GB]. The safe-but-conservative 0.5
+fraction leaves a 3.5GB node at R=1; a budget of (heap − base − buildTransient)/instance
+would give R(3584)=2 — V4 hardening candidate (validated by the r2 probe below).
+
+**Operating rule:** healthy service requires resident capacity R ≥ number of actively-hit
+blueprints (api and auth blueprints both count; auth is touched at login/relogin only).
+Within one blueprint, tenant count is free (zero marginal heap) up to the PG-side
+catalog walls.
+
+## Architecture consequence (the 1000-tenant answer)
+
+Tenants-per-PG-database is the fundamental unit, bounded by catalog size on BOTH sides
+(PG introspection memory ~37KB/row/backend; node instance heap ~21KB/row/instance;
+provisioning slowdown). Shard tenants across PG databases (the blueprint cache key
+already scopes by dbname `d`); serve each shard with nodes sized R ≥ active blueprint
+shapes. Example: 1000 same-shape tenants = N shards × (1000/N) tenants; each shard
+served by a 2GB node at R=1 (api) — auth co-residency wants R=2 (heap ~4GB with the
+V4 budget formula, or a separate auth node at R=1).
+
+## Rig/ops guidance validated live
+
+- Cap the PG container (cgroup OOM → 15–20s crash-recovery, absorbed by the
+  connection guard) rather than letting the VM OOM-killer roam.
+- `idle_session_timeout` recycles relcache-bloated backends in healthy regimes;
+  under sustained build churn backends never idle — churn regimes need pgbouncer
+  `server_lifetime` or equivalent forced recycling.
+- BuildSemaphore(1) serendipitously serializes PG introspection spikes as well as
+  node build transients — keep it.
+
+## Follow-up probes (both PASS)
+
+- **Capacity-2 at 3584MB** (`r2-div-k1`, estimate lowered to 896MB → cap 2):
+  builds=2, **evictions=0** (api + auth blueprints simultaneously resident),
+  errRate 0, p99 34ms, heapMax **2750MB** (= 2×1.35GB + base, as modeled),
+  rssMax 3.24GB, no crash. True capacity at 3584MB is 2; only the 0.5-fraction
+  budget formula holds it at 1 → V4 hardening: budget = heap − base −
+  buildTransient, divided by instance estimate.
+- **Single-blueprint rps ceiling** (2048MB, 32 tenants, zipf, authenticated
+  mixed workload): 50→100→200 target rps achieved 47/94.3/188.4, errRate 0
+  at every level, p99 34/21/21ms, pgConnMax stayed 5 (PG_POOL_MAX=5/dbname is
+  NOT a bottleneck ≤200rps; queries are 1-5ms). heapMax 1508→1588MB (request
+  working set ≈ +150-250MB over the resident instance at 200rps).
+  **Headline: a 2GB-heap node serves 32 pooled tenants at ≥188rps, p99 21ms,
+  zero errors.**
+
+## Remaining known limitations
+
+- Shape fingerprint covers relation names only (columns excluded — documented
+  limitation; column-drift tenants share a blueprint by design).
+- rps ceiling beyond 200rps unmeasured (no knee found yet).
+- 24h longevity (V3) + memory governor / smarter budget / build timeout (V4).
diff --git a/scripts/scale-validate/VALIDATION-REPORT.md b/scripts/scale-validate/VALIDATION-REPORT.md
new file mode 100644
index 0000000000..9407f803b9
--- /dev/null
+++ b/scripts/scale-validate/VALIDATION-REPORT.md
@@ -0,0 +1,189 @@
+# Scale Validation Program — Final Report (feat/scale-phase0)
+
+**Question under validation:** can the cnc PostGraphile-v5 server host hundreds of
+tenant databases on a small fixed heap, using blueprint pooling (one shared instance
+per schema-shape) — and what actually bounds it?
+
+**Verdict:** pooling works and is production-ready **within a quantified envelope**.
+Tenant count is effectively free *within a blueprint*; the real limits are
+**catalog size per PG database** and **resident blueprint count per node** — both
+now measured, modeled (`SIZING.md`), and enforced by shipped guardrails. The
+original "1000 tenants on one 2GB node" framing resolves to a shard-per-PG-database
+architecture: ~40–200 tenants per shard (PG-node-RAM-dependent), each shard served
+at p99 ≤34ms by a 2–6GB-heap node. Full V2 data: `V2-RESULTS.md`.
+
+## What was validated, in order
+
+**V1 — instrumentation + fleet.** Metrics sampler (10s JSON lines: heap/RSS/cache/
+build/eviction/guard counters), workload harness (open-loop token bucket,
+authenticated read/write/meta mix, zipf/uniform/burst, per-tenant **cross-tenant
+bleed sentinel** that hard-fails on foreign canary rows), SQL tenant factory
+(~0.8 tenants/min, fingerprint-validated identical to seeder output), drift/subset
+tooling, teardown tooling. Fleet: 47 tenants (40 factory + reference + 6 divergent),
+5 deliberate blueprint groups + 2 column-drift probes.
+
+**V2 — limits discovery.** See `V2-RESULTS.md` for the full matrix. Constants:
+instance heap ≈ 50MB + **21KB/pg_class row** (class-independent — it is the
+introspection graph); PG introspection spike ≈ **37KB/row per build**; min viable
+heap 1536MB at the 61k-row catalog; **zero marginal heap per tenant** within a
+blueprint; **188rps p99 21ms zero errors** on one 2GB node (no knee ≤200rps);
+capacity law validated at R=1 (2048MB) and R=2 (3584MB); thrash-not-crash beyond
+capacity; cold-burst needs R ≥ concurrent cold blueprints.
+
+**V3 — 24h soak** (in flight at time of writing; final numbers appended on
+completion). Configuration: hardened build, heap 3584 (capacity 2), 32 same-blueprint
+tenants, 30rps zipf authenticated + hourly NOTIFY churn + 2-hourly tenant
+provision/teardown cycles + RSS/heap collector. Hour-1: 108k requests, 0 errors,
+p99 34ms, **zero LRU evictions through the batch-relogin cliff** that (by design)
+destroyed the capacity-1 control attempt.
+
+**V4 — hardening + model.** `SIZING.md` (capacity law, shard guidance, container
+sizing, knob reference) + the fixes below.
+
+## Findings → fixes (all discovered live by the program)
+
+| # | Finding | Consequence | Fix / disposition |
+|---|---|---|---|
+| 1 | PostGraphile introspection scans the ENTIRE catalog (no schema filter); backend spikes ~37KB/pg_class row and pooled backends RETAIN multi-GB relcache | PG OOM at ~100 tenants/DB even idle; crash-recovery storms | Shard-per-database architecture (SIZING.md); PG container caps; `idle_session_timeout`/pgbouncer `server_lifetime` backend recycling; BuildSemaphore already serializes spikes |
+| 2 | Node instance heap ∝ total catalog (~21KB/row), class-independent, live (not GC-able) | 2GB heap = ONE resident instance at 61k rows; "instance size" is not a constant | Measured model + `GRAPHILE_CACHE_INSTANCE_HEAP_BYTES`; measurement tool shipped |
+| 3 | `MIN_CACHE_MAX=3` floor overrode the heap budget; count-based headroom never evicted | Second build → V8 SIGABRT (whole node dies) — reproduced on demand | **`24d49252f`** floor→1 + regression test |
+| 4 | PG crash-recovery killed the whole server via unhandled 'error' on an orphaned pg Client | 15s PG hiccup = full multi-tenant outage | **`d42ca1769`** scoped connection-class guard (absorbs 57P01/08006/ECONNRESET/…, counts in metrics; everything else stays fatal). Validated: ~330 absorbed/step, 0 process deaths |
+| 5 | Blunt `heap×0.5` budget wasted capacity (3.5GB node stuck at R=1) | Unnecessary thrash for fleets needing api+auth resident | **`0a8a95402`** two-constraint budget (residency + rebuild-with-evict); R=2@3584 proven live |
+| 6 | At R=1, hourly batch relogins + failed-relogin retries create SELF-SUSTAINING api↔auth eviction oscillation | "Capacity ≥ active blueprints" is a hard operating rule, not advice | Soak redesigned to R=2 (clean); rule + math in SIZING.md |
+| 7 | No backpressure: builds admitted at any heap level; requests wait unboundedly | Pressure death-spiral risk; queue pileups | **`0a8a95402`** memory governor (85% proactive evict / 92% refuse builds with 503+Retry-After) + `GRAPHILE_BUILD_TIMEOUT_MS` request wait bound (build continues in background, timed-out requests no longer break coalescing) |
+| 8 | No runtime visibility | blind ops | **`0a8a95402`** `/metrics` endpoint (env-gated, loopback-guarded) + sampler counters incl. governor/guard/refusals |
+| 9 | `pg_partman` registry rows are name-keyed, not FK-cascaded; schema hashes are deterministic per dbname | Re-provisioning a reused tenant name fails with unique_violation | **`d00100631`** teardown cleans part_config(+sub); 434 orphans purged |
+| 10 | `idle_session_timeout` (finding-1 mitigation) reaps ANY long-idle client | killed the churn driver; would kill LISTEN clients lacking reconnect | Server listener already reconnects; driver fixed (**`073f8bd58`**); documented as an ops tradeoff |
+| 11 | `flushService` cleared ALL `bp:` instances on ANY `schema:update`, and the immediate rebuild raced evicted-but-DRAINING instances whose heap was still live (invisible to count-based headroom) | Every tenant PROVISION cold-restarted the whole pooled fleet; rebuild transient stacked on ~GB of draining heap → SIGABRT at 3584MB (killed soak attempt 2 at hour 2) | **`65c3056f9`** surgical per-database flush (`PoolDecision.databaseId` stamped at memoization; only the changed DB's decisions + blueprint invalidated; provisions are no-ops for resident blueprints) + drain-aware build admission (`waitForDrainSettle` after headroom eviction). Validated live: soak attempt 3 survived three provision/drop cycles at the exact event that killed attempt 2 |
+
+Also validated en route: bleed sentinel NEVER fired across the entire program
+(hundreds of thousands of authenticated cross-tenant-adjacent requests, thrash
+included) — pooling isolation held under every regime tested.
+
+## Prior banked results (pre-V1, same branch)
+
+Pooling correctness: SDL byte-identical pooled-vs-dedicated; engine-level zero-bleed;
+HTTP-authenticated zero-bleed (interleaved sessions + cross-token control); 7
+same-shape tenants → 1 build; RSS 1475MB (6 per-tenant instances) → 711MB (pooled,
+8 tenants); collision linter + shape fingerprint + safety fallbacks (realtime,
+empty-schema, name-collision, transient probe); W3 login fix (`public` appended to
+pooled search_path); plugin audit with fixes (i18n RLS bypass, search adapters,
+LLM/RAG, presigned-url, meta-schema caches).
+
+## Reproduction quickstart
+
+```
+# fleet + validation rig (isolated PG :5433)
+node scripts/scale-validate/tenant-factory.mjs --count N --prefix factory
+node scripts/scale-validate/drift-tenants.mjs --groups 4 --per-group 2 --column-drift 2
+node scripts/scale-validate/fleet.mjs --like '%' --out fleet-all.json   # filter nulls → fleet.json
+node scripts/scale-validate/canary-seed.mjs --fleet fleet.json
+node scripts/scale-validate/subset-fleet.mjs ...                        # k/tenant subsets
+node scripts/scale-validate/v2-ramps.mjs --plan plans/v2-2048-tuned.json --out out/results.jsonl
+node scripts/scale-validate/summarize-results.mjs out/results.jsonl
+node scripts/scale-validate/measure-instance-heap.mjs --label x --host api-...localhost
+```
+
+## V3 soak — final verdict: **PASS** (5-hour scope)
+
+Attempt 3, 2026-07-03 00:26→05:26 UTC, hardened build (findings 3/4/5/7/8/11 fixes
+in), heap 3584MB / instance estimate 1450MB → capacity R=2, 32-tenant same-shape
+fleet + auth at 30rps zipf, hourly relogin batches, provision+drop cycle every 2h,
+PG-side sampler recording. Scope note: the user shortened the planned 24h to 5h;
+all three prior attempts' failure modes fired inside 2h, so 5 clean hours is 2.5×
+past every observed failure point — but the original 12h/<5MB/h leak criterion was
+adapted to the 4h post-warmup window (below).
+
+| Criterion | Result | Verdict |
+|---|---|---|
+| No node/PG OOM, no crash, no restart | server up the full 5h; PG container ≤3153MB of 4.4GiB cap; backends ≤16 | ✅ |
+| Cross-tenant bleed | **0 violations** / 235 sentinel checks (469/470 own-canary seen; 1 inconclusive during the blip window) | ✅ |
+| Availability / latency | 392,794 requests completed, cumulative errRate **0.094%** (370 errors, ALL inside one ~2min recovery blip at the hour-2 provision/drop; every other window 0); overall p50/p95/p99 = **13/21/55ms** (steady windows p99 21–34ms) | ✅ |
+| Schema-churn survival (finding 11 validation) | **3 provision/drop cycles + 5 hourly relogin batches survived live** (128 relogins, 0 auth failures); attempt 2 died at cycle 1 on the same event | ✅ |
+| Heap stability / leak | like-for-like (cache=2) heap plateaus at **~2.78GB ±45MB** with non-monotonic hour-over-hour floors → no detectable leak at 5h resolution; naive all-sample slope (481MB/h) is a state-mix artifact of cache 1↔2 transitions, not growth | ✅ (5h bound; 24h run would tighten below the original 5MB/h criterion) |
+| Counters clean | governor evictions 0, buildRefusals 0, drainTimeouts 0, buildWaitTimeouts 0, connGuard 0/0; lru=6 evictions + 8 builds vs **481,610 pooling attaches** (~60k:1 instance reuse) | ✅ |
+
+Ops observations (non-blocking): server SIGTERM→exit exceeded 30s under pooling
+(SIGKILL after data-plane stop is safe; document in runbooks). macOS `ps` RSS is
+not usable for leak detection under memory compression — use sampler `heapUsed`.
+Raw artifacts: `out/soak-results.json`, `out/soak-collector.json`,
+`out/metrics-soak.jsonl`, `out/pg-soak.jsonl`, `out/metrics-final.json`,
+`out/soak-{harness,churn,ops,server}.log`.
+
+## Tooling productionized
+
+The entire validation toolkit was ported to a reusable package:
+**`packages/perf-harness`** (`@constructive-io/perf-harness`, bins `perf-harness`/
+`cperf`) — fleet provision/drift/canary/teardown, load harness/churn, measure
+collector/pg/instance-heap, run ramp/soak (detached, ordered stop), report
+summarize/merge/predict, and `cperf regression run` comparing fresh runs against
+baselines banked from this program (21KB/row, capacity law, zero-marginal,
+thrash-not-crash, bleed=0). Hub-port guardrail built in (5432/3000-3002/9000
+refused without `--allow-hub`); credentials via `PERF_PASSWORD` only. 156 unit
+tests; smoke-tested against this soak's live data. See the package README for the
+"regression reappeared" quickstart. The `scripts/scale-validate/` originals remain
+as-run for provenance.
+
+## Status
+
+- V1 instrumentation+fleet ✅ · V2 limits discovery ✅ (`V2-RESULTS.md`) · V3 soak
+  **PASS** (above) · V4 sizing+hardening ✅ (`SIZING.md`, fixes in the findings
+  table, perf-harness package).
+- Deep-scenario regression suite (`cperf regression run --suite deep`) added to cover the
+  four previously-untested scaling axes — **multi-API residency**, **settings-variant
+  splits**, **realtime dedicated cost**, and **partition creep** (each mutates the rig
+  under guaranteed teardown); code + baselines landed, **live results pending** (run by
+  the lead in the live phase).
+- All work is local to `feat/scale-phase0`; nothing pushed.
+
+## 2026-07-06 — Capacity-10× + ship-validation program (introspection filter, churn fix, compliance audit)
+
+Question under test: *can one node host the whole tenant fleet under real client
+traffic without crashing, and what is the memory footprint at 2GB / N GB?*
+
+**Headline (a3-day-clean, final ship tree):** 47 authenticated tenants, zipf @50rps,
+mixed read/write/meta, 30 minutes → **104,818/104,818 HTTP 200, errRate 0, p99 21ms,
+heap max 195.7MB of 2048MB (9.6%), RSS max 380MB, 0 evictions, 0 build refusals,
+115,907 pool-rewritten queries with 0 fail-closed, introspection filter 7/7 swaps,
+bleed 0.** (`out/a3-day-rerun-results.jsonl`; the earlier 0.22 errRate was fully
+attributed to a null-apiHost platform row in the fleet manifest — every error came
+from the harness fetching `http://null`; all real tenants had 0 errors.)
+
+Program evidence (perf-out/stress/, graded per-arm):
+- **Arm 1, pooling OFF**: 2048MB → SIGABRT; 3584MB → total thrash death (errRate 1.0,
+  964 evictions). The regression is real: dedicated instances cannot host a fleet at
+  the 61k-row catalog.
+- **Arm 2, pooled unfiltered**: 2048MB OOM on concurrent api+auth cold builds —
+  knife-edge; pooling needs the filter at production heap sizes.
+- **Arm 3, pooled + `GRAPHILE_INTROSPECTION_FILTER=1`**: k1–k5 blueprint diversity all
+  healthy at 2048MB (errRate 0, heap 131–167MB, 0 evictions); 900s storm errRate 0;
+  cold-burst 5/5 < 700ms; 187rps sustained; zero marginal heap per tenant.
+- **Constants transformed** (SDL byte-identical, MD5): instance 1305.6→14.7MB
+  (21.9→0.24KB per pg_class row, 87×), cold build 7165→417ms (17×), PG introspection
+  spike +1283→+17MiB, realtime dedicated 2596→14.7MB (176×). See SIZING.md
+  (2026-07-06 section) for the updated capacity law and knobs; floor is 1024MB heap.
+- **Eviction-churn OOM found + fixed (`46636d4b4`)**: the build-wait Promise.race
+  armed a 180s timer per waiting request and never cleared it on build success —
+  every evicted ~15MB instance stayed reachable for 180s, so forced max=1 churn
+  OOM-killed a 2GB heap in 65s (heap-snapshot proven; post-timer-expiry memory
+  collapsed 1766→52.9MB). Fixed with raceBuildAgainstTimeout() + made the
+  heap-pressure governor reachable (ratio vs V8's exhaustible headroom, not
+  heap_size_limit) + in-critical-section refusal (503) + 250ms build spacing under
+  elevated pressure. Post-fix: worst-case all-miss churn at 2048MB is a bounded
+  sawtooth at 23 builds/s with clean recovery; capacity+1 rotation sustains
+  1444/1444 OK.
+- **1h churn soak**: 9 provision/drop cycles, RSS slope +8.3MB/h, 0 bleed, rewrite
+  pool 0 fail-closed over 103,384 queries. pg_class +189 residue explained: 21
+  orphaned `partman.template_*` tables per dropped tenant (teardown follow-up noted).
+- **CTO compliance audit (4 lenses + adversarial verify, perf-out/cto-audit-result.json)**:
+  search_path ZERO in product code; identifier emission fully qualified (no
+  pgIdentifiers overrides; upstream default verified); 13/13 scope-pollution checks
+  clean (transaction-local GUCs, per-tenant prepared-statement namespacing +
+  DEALLOCATE, LISTEN on a dedicated client, tenant-keyed caches). One blocker found
+  and fixed (`e38f4b52d`): settings-query detection now byte-matches the adaptor's
+  statement text instead of trusting bind-value shape. Credential literal purged
+  from unpushed history (base untouched — normal push).
+
+Verdict: **SHIP.** All gates pass on the final tree; remaining advisories (bm25
+index name under pooling, PublicKeySignature withPgClient(null) — preexisting,
+partman template teardown) are documented follow-ups, none load-bearing.
diff --git a/scripts/scale-validate/_lib.mjs b/scripts/scale-validate/_lib.mjs
new file mode 100644
index 0000000000..133bf79cf3
--- /dev/null
+++ b/scripts/scale-validate/_lib.mjs
@@ -0,0 +1,456 @@
+/**
+ * Shared helpers for the scale-validate harness v2 (Task B).
+ *
+ * Pure tooling — no server/package code is imported at module load beyond `pg`
+ * (resolved via the @dataplan/pg chain, exactly like scripts/scale-spike).
+ * Every script imports from here; each script stays independently runnable via
+ *   node scripts/scale-validate/<script>.mjs
+ */
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import fs from 'node:fs';
+import path from 'path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const WORKTREE = path.resolve(__dirname, '..', '..');
+
+// ---------------------------------------------------------------------------
+// pg resolution
+// ---------------------------------------------------------------------------
+// `pg` is not a direct dep of the worktree root, but it is present in the pnpm
+// store reachable through the @dataplan/pg dependency chain (same trick the
+// scale-spike scripts use).
+export function resolvePg() {
+  const req = createRequire(path.join(WORKTREE, 'graphql', 'query', 'package.json'));
+  const reqAdaptor = createRequire(req.resolve('postgraphile/adaptors/pg'));
+  const reqDataplan = createRequire(reqAdaptor.resolve('@dataplan/pg'));
+  return reqDataplan('pg');
+}
+
+// ---------------------------------------------------------------------------
+// Postgres connection config
+// ---------------------------------------------------------------------------
+// Defaults target the isolated dev database on :5433. CLI flags win over env,
+// env wins over defaults. We NEVER default to 5432.
+export function pgConfigFromArgs(args = {}) {
+  const num = (v, d) => {
+    const n = Number.parseInt(v, 10);
+    return Number.isFinite(n) ? n : d;
+  };
+  return {
+    host: args['pg-host'] || process.env.PGHOST || 'localhost',
+    port: num(args['pg-port'] ?? process.env.PGPORT, 5433),
+    user: args['pg-user'] || process.env.PGUSER || 'postgres',
+    password: args['pg-password'] ?? process.env.PGPASSWORD ?? 'password',
+    database: args['pg-database'] || process.env.PGDATABASE || 'constructive'
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Minimal arg parsing: --flag value | --flag=value | --flag (boolean true)
+// ---------------------------------------------------------------------------
+export function parseArgs(argv) {
+  const args = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq !== -1) {
+        args[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+          args[key] = true;
+        } else {
+          args[key] = next;
+          i++;
+        }
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { args, positional };
+}
+
+export function asBool(v, dflt = false) {
+  if (v === undefined || v === null) return dflt;
+  if (typeof v === 'boolean') return v;
+  const s = String(v).toLowerCase();
+  return s === '1' || s === 'true' || s === 'yes' || s === 'on';
+}
+
+export function asInt(v, dflt) {
+  const n = Number.parseInt(v, 10);
+  return Number.isFinite(n) ? n : dflt;
+}
+
+export function asFloat(v, dflt) {
+  const n = Number.parseFloat(v);
+  return Number.isFinite(n) ? n : dflt;
+}
+
+export const nowIso = () => new Date().toISOString();
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export const round2 = (n) => Math.round(n * 100) / 100;
+
+// Seedable RNG (mulberry32) for reproducible shape/tenant selection.
+export function makeRng(seed) {
+  let a = (seed >>> 0) || 0x9e3779b9;
+  return function rng() {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Fleet manifest
+// ---------------------------------------------------------------------------
+export function loadFleet(fleetPath) {
+  const raw = fs.readFileSync(fleetPath, 'utf8');
+  const parsed = JSON.parse(raw);
+  const tenants = Array.isArray(parsed) ? parsed : parsed.tenants;
+  if (!Array.isArray(tenants) || tenants.length === 0) {
+    throw new Error(`fleet file ${fleetPath} has no tenants`);
+  }
+  return { manifest: parsed, tenants };
+}
+
+// The token used inside CANARY-<token> rows. MUST match between canary-seed.mjs
+// and the harness sentinel so bleed can be attributed to a foreign tenant.
+export const canaryToken = (tenant) => tenant.dbname;
+export const canaryName = (tenant) => `CANARY-${canaryToken(tenant)}`;
+export const CANARY_PREFIX = 'CANARY-';
+
+// ---------------------------------------------------------------------------
+// GraphQL over HTTP
+// ---------------------------------------------------------------------------
+// We put the tenant host in the URL (e.g. api-xxx.localhost) because undici
+// ignores an explicit `host` header. `*.localhost` resolves to loopback, so the
+// connection lands on 127.0.0.1 while the server sees the correct Host header
+// for subdomain routing.
+export async function gqlFetch({ host, port, query, variables, token, timeoutMs = 30000, gqlPath = '/graphql' }) {
+  const url = `http://${host}:${port}${gqlPath}`;
+  const headers = { 'content-type': 'application/json', accept: 'application/json' };
+  if (token) headers.authorization = `Bearer ${token}`;
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  const start = performance.now();
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(variables ? { query, variables } : { query }),
+      signal: ac.signal
+    });
+    const elapsedMs = performance.now() - start;
+    const ct = res.headers.get('content-type') || '';
+    let json = null;
+    let text = null;
+    if (ct.includes('json')) {
+      json = await res.json().catch(() => null);
+    } else {
+      text = await res.text().catch(() => null);
+      // Some error paths return JSON without the header — try to parse.
+      if (text) {
+        try { json = JSON.parse(text); } catch { /* not json */ }
+      }
+    }
+    return { status: res.status, ok: res.ok, json, text, elapsedMs, error: null };
+  } catch (err) {
+    const elapsedMs = performance.now() - start;
+    const error = err && err.name === 'AbortError' ? 'timeout' : (err && (err.code || err.message)) || 'network';
+    return { status: 0, ok: false, json: null, text: null, elapsedMs, error };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function isRotating(resp) {
+  if (resp.status === 503) {
+    const code = resp.json && resp.json.error && resp.json.error.code;
+    return code === 'SERVICE_ROTATING' || true; // any 503 counts as rotating
+  }
+  return false;
+}
+
+export function gqlErrors(resp) {
+  return (resp.json && Array.isArray(resp.json.errors)) ? resp.json.errors : [];
+}
+
+export function isUnauthenticated(resp) {
+  const errs = gqlErrors(resp);
+  for (const e of errs) {
+    const code = e && e.extensions && e.extensions.code;
+    if (code === 'UNAUTHENTICATED' || code === 'FORBIDDEN') return true;
+    const msg = (e && e.message) || '';
+    if (/unauthenticated|not authori[sz]ed|permission denied|jwt|login required|invalid token|expired/i.test(msg)) return true;
+  }
+  if (resp.status === 401 || resp.status === 403) return true;
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Introspection helpers (operate on the JSON introspection result)
+// ---------------------------------------------------------------------------
+export const INTROSPECTION_QUERY = `query Introspect {
+  __schema {
+    queryType { name }
+    mutationType { name }
+    types {
+      kind
+      name
+      fields(includeDeprecated: true) { name args { name type { ...T } } type { ...T } }
+      inputFields { name type { ...T } }
+    }
+  }
+}
+fragment T on __Type {
+  kind name
+  ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } } }
+}`;
+
+export function unwrapType(ref) {
+  let t = ref;
+  while (t && t.ofType) t = t.ofType;
+  return t || null;
+}
+
+export function isNonNull(ref) {
+  return !!(ref && ref.kind === 'NON_NULL');
+}
+
+export function buildTypeIndex(introspect) {
+  const index = new Map();
+  const schema = introspect && introspect.__schema;
+  if (!schema) return { index, queryType: null, mutationType: null };
+  for (const t of schema.types) index.set(t.name, t);
+  return {
+    index,
+    queryType: schema.queryType && schema.queryType.name,
+    mutationType: schema.mutationType && schema.mutationType.name
+  };
+}
+
+function findConnectionField(index, queryTypeName, re) {
+  const qt = index.get(queryTypeName);
+  if (!qt) return null;
+  const candidates = (qt.fields || []).filter((f) => re.test(f.name));
+  for (const f of candidates) {
+    const named = unwrapType(f.type);
+    const nt = named && index.get(named.name);
+    if (nt && (nt.fields || []).some((sf) => sf.name === 'nodes')) return f.name;
+  }
+  return candidates[0] ? candidates[0].name : null;
+}
+
+const SCALAR_SAMPLE = (scalar, rand) => {
+  switch (scalar) {
+    case 'Int':
+    case 'BigInt':
+      return 0;
+    case 'Float':
+    case 'BigFloat':
+      return 0;
+    case 'Boolean':
+      return true;
+    default:
+      return `load-${rand}`;
+  }
+};
+
+// Discover create/delete/read/meta operations from an introspection result.
+export function discoverOps(introspect) {
+  const { index, queryType, mutationType } = buildTypeIndex(introspect);
+  const out = { queryType, mutationType, read: null, meta: false, create: null, del: null };
+  if (!queryType) return out;
+
+  // read (categories connection)
+  out.read = findConnectionField(index, queryType, /categor/i);
+
+  // meta (_meta { tables { name } })
+  const qt = index.get(queryType);
+  out.meta = !!(qt && (qt.fields || []).some((f) => f.name === '_meta'));
+
+  if (!mutationType) return out;
+  const mt = index.get(mutationType);
+
+  // delete mutation (prefer PK id-based over nodeId-based)
+  const delField = (mt.fields || []).find((f) => /^delete.*categor/i.test(f.name) && !/nodeid/i.test(f.name))
+    || (mt.fields || []).find((f) => /^delete.*categor/i.test(f.name));
+  if (delField) {
+    const inputArg = (delField.args || []).find((a) => a.name === 'input');
+    if (inputArg) {
+      const inputType = index.get(unwrapType(inputArg.type).name);
+      const innerFields = (inputType.inputFields || []).map((f) => ({ name: f.name, typeName: unwrapType(f.type).name }));
+      const byId = innerFields.find((f) => f.name === 'id');
+      const byNodeId = innerFields.find((f) => f.name === 'nodeId');
+      const key = byId ? 'id' : (byNodeId ? 'nodeId' : (innerFields[0] && innerFields[0].name));
+      if (key) {
+        out.del = { name: delField.name, inputTypeName: unwrapType(inputArg.type).name, key };
+      }
+    }
+  }
+
+  // create mutation
+  const createField = (mt.fields || []).find((f) => /^create.*categor/i.test(f.name));
+  if (createField) {
+    const inputArg = (createField.args || []).find((a) => a.name === 'input');
+    if (inputArg) {
+      const inputTypeName = unwrapType(inputArg.type).name;
+      const inputType = index.get(inputTypeName);
+      const innerField = (inputType.inputFields || []).find((f) => {
+        const nt = index.get(unwrapType(f.type).name);
+        return nt && nt.kind === 'INPUT_OBJECT';
+      });
+      if (innerField) {
+        const innerType = index.get(unwrapType(innerField.type).name);
+        const requiredScalars = (innerType.inputFields || [])
+          .filter((f) => isNonNull(f.type))
+          .map((f) => ({ name: f.name, scalar: unwrapType(f.type).name, kind: unwrapType(f.type).kind }))
+          .filter((f) => f.kind === 'SCALAR' || f.kind === 'ENUM');
+        const payloadType = index.get(unwrapType(createField.type).name);
+        const payloadField = (payloadType.fields || []).find((f) => {
+          const nt = index.get(unwrapType(f.type).name);
+          return nt && nt.kind === 'OBJECT' && /categor/i.test(nt.name) && (nt.fields || []).some((sf) => sf.name === 'id');
+        });
+        out.create = {
+          name: createField.name,
+          inputTypeName,
+          innerName: innerField.name,
+          requiredScalars,
+          payloadFieldName: payloadField ? payloadField.name : null,
+          // which key to select in the payload so we can delete afterwards
+          keySelect: out.del ? out.del.key : 'id'
+        };
+      }
+    }
+  }
+  return out;
+}
+
+// Build the record input object for a create write. `nameValue` is forced onto
+// the `name` column; everything else required gets a type-appropriate value.
+export function buildCreateRecord(create, nameValue, rand) {
+  const rec = {};
+  for (const f of create.requiredScalars) {
+    if (f.name === 'name') rec[f.name] = nameValue;
+    else if (f.name === 'slug') rec[f.name] = `load-${rand}`;
+    else rec[f.name] = SCALAR_SAMPLE(f.scalar, rand);
+  }
+  if (rec.name === undefined) rec.name = nameValue; // ensure name present even if not flagged required
+  return rec;
+}
+
+// ---------------------------------------------------------------------------
+// Bucketed latency histogram (bounded memory — safe for multi-hour soaks)
+// ---------------------------------------------------------------------------
+const DEFAULT_BUCKETS = [
+  1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610,
+  1000, 1600, 2600, 4200, 6800, 11000, 18000, 30000, 60000
+];
+
+export class Histogram {
+  constructor(buckets = DEFAULT_BUCKETS) {
+    this.buckets = buckets;
+    this.counts = new Array(buckets.length + 1).fill(0);
+    this.count = 0;
+    this.sum = 0;
+    this.min = Infinity;
+    this.max = 0;
+  }
+
+  record(ms) {
+    this.count++;
+    this.sum += ms;
+    if (ms < this.min) this.min = ms;
+    if (ms > this.max) this.max = ms;
+    let i = 0;
+    while (i < this.buckets.length && ms > this.buckets[i]) i++;
+    this.counts[i]++;
+  }
+
+  percentile(p) {
+    if (this.count === 0) return 0;
+    const target = Math.ceil((p / 100) * this.count);
+    let cum = 0;
+    for (let i = 0; i < this.counts.length; i++) {
+      cum += this.counts[i];
+      if (cum >= target) {
+        return i < this.buckets.length ? this.buckets[i] : Math.round(this.max);
+      }
+    }
+    return Math.round(this.max);
+  }
+
+  summary() {
+    return {
+      count: this.count,
+      min: this.count ? round2(this.min) : 0,
+      mean: this.count ? round2(this.sum / this.count) : 0,
+      p50: this.percentile(50),
+      p95: this.percentile(95),
+      p99: this.percentile(99),
+      max: round2(this.max)
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shape samplers over the tenant array
+// ---------------------------------------------------------------------------
+// zipf: weight_i = 1 / (i + 1) over fleet order; returns index sampler.
+export function makeZipfSampler(n, rng) {
+  const weights = [];
+  let total = 0;
+  for (let i = 0; i < n; i++) {
+    const w = 1 / (i + 1);
+    weights.push(w);
+    total += w;
+  }
+  const cum = [];
+  let acc = 0;
+  for (let i = 0; i < n; i++) {
+    acc += weights[i] / total;
+    cum.push(acc);
+  }
+  return () => {
+    const r = rng();
+    for (let i = 0; i < n; i++) if (r <= cum[i]) return i;
+    return n - 1;
+  };
+}
+
+export function makeMixSampler(mixStr, rng) {
+  // "read:0.7,write:0.25,meta:0.05"
+  const entries = [];
+  let total = 0;
+  for (const part of String(mixStr).split(',')) {
+    const [k, v] = part.split(':');
+    const w = Number.parseFloat(v);
+    if (k && Number.isFinite(w) && w > 0) {
+      entries.push([k.trim(), w]);
+      total += w;
+    }
+  }
+  if (entries.length === 0) {
+    entries.push(['read', 1]);
+    total = 1;
+  }
+  const cum = [];
+  let acc = 0;
+  for (const [k, w] of entries) {
+    acc += w / total;
+    cum.push([k, acc]);
+  }
+  return () => {
+    const r = rng();
+    for (const [k, c] of cum) if (r <= c) return k;
+    return cum[cum.length - 1][0];
+  };
+}
diff --git a/scripts/scale-validate/canary-seed.mjs b/scripts/scale-validate/canary-seed.mjs
new file mode 100644
index 0000000000..20239e126d
--- /dev/null
+++ b/scripts/scale-validate/canary-seed.mjs
@@ -0,0 +1,159 @@
+/**
+ * canary-seed.mjs — seed one CANARY-<dbname> row into each tenant's
+ * app-public.categories table (superuser pg client). Idempotent.
+ *
+ * The harness bleed-sentinel reads a tenant's categories and FAILS HARD if it
+ * ever sees a CANARY-<other-dbname> row — so these rows must exist for the
+ * sentinel to have anything to detect cross-tenant bleed with.
+ *
+ * NOT NULL columns without a default are discovered via information_schema and
+ * filled (name -> the canary name, slug/other text -> a canary slug).
+ *
+ * Usage:
+ *   node scripts/scale-validate/canary-seed.mjs --fleet fleet.json
+ *   node scripts/scale-validate/canary-seed.mjs --fleet fleet.json --cleanup
+ */
+import { asBool, canaryName, canaryToken, loadFleet, parseArgs, pgConfigFromArgs, resolvePg } from './_lib.mjs';
+
+const HELP = `canary-seed.mjs — insert/remove CANARY-<dbname> rows in each tenant's categories
+
+Options:
+  --fleet <file>   fleet manifest from fleet.mjs (required)
+  --table <name>   target table (default: categories)
+  --cleanup        remove the canary rows instead of inserting
+  --pg-* / PG*     connection overrides
+  --help
+`;
+
+const REQUIRED_COLS_SQL = `
+SELECT column_name, data_type, udt_name
+FROM information_schema.columns
+WHERE table_schema = $1 AND table_name = $2
+  AND is_nullable = 'NO'
+  AND column_default IS NULL
+ORDER BY ordinal_position;
+`;
+
+const TABLE_EXISTS_SQL = `
+SELECT 1 FROM information_schema.tables
+WHERE table_schema = $1 AND table_name = $2 AND table_type = 'BASE TABLE';
+`;
+
+function valueForColumn(col, nameValue, slugValue) {
+  if (col.column_name === 'name') return nameValue;
+  if (col.column_name === 'slug') return slugValue;
+  const t = (col.data_type || '').toLowerCase();
+  const u = (col.udt_name || '').toLowerCase();
+  if (t.includes('char') || t === 'text' || u === 'citext') return slugValue;
+  if (t.includes('bool')) return true;
+  if (t.includes('int') || t === 'numeric' || t.includes('double') || t.includes('real')) return 0;
+  // Unknown required column type we cannot safely synthesize.
+  return undefined;
+}
+
+async function main() {
+  const { args } = parseArgs(process.argv.slice(2));
+  if (asBool(args.help) || !args.fleet) {
+    process.stdout.write(HELP);
+    if (!args.fleet && !asBool(args.help)) process.exitCode = 1;
+    return;
+  }
+  const table = typeof args.table === 'string' ? args.table : 'categories';
+  const cleanup = asBool(args.cleanup);
+  const { tenants } = loadFleet(args.fleet);
+  const cfg = pgConfigFromArgs(args);
+  const { Client } = resolvePg();
+  const client = new Client(cfg);
+  await client.connect();
+
+  const report = { table, mode: cleanup ? 'cleanup' : 'seed', results: [] };
+  try {
+    for (const t of tenants) {
+      const schema = t.appPublicSchema;
+      const entry = { dbname: t.dbname, schema, status: 'ok' };
+      if (!schema) {
+        entry.status = 'skipped';
+        entry.reason = 'no app-public schema';
+        report.results.push(entry);
+        continue;
+      }
+      const exists = await client.query(TABLE_EXISTS_SQL, [schema, table]);
+      if (exists.rowCount === 0) {
+        entry.status = 'skipped';
+        entry.reason = `no ${table} table (blank tenant)`;
+        report.results.push(entry);
+        continue;
+      }
+
+      const name = canaryName(t);
+      const slug = `canary-${canaryToken(t)}`.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+      const qSchema = `"${schema}"`;
+      const qTable = `"${table}"`;
+
+      if (cleanup) {
+        const del = await client.query(`DELETE FROM ${qSchema}.${qTable} WHERE name = $1`, [name]);
+        entry.removed = del.rowCount;
+        report.results.push(entry);
+        continue;
+      }
+
+      // Idempotent: skip if a canary row already exists.
+      const already = await client.query(
+        `SELECT count(*)::int AS n FROM ${qSchema}.${qTable} WHERE name = $1`, [name]);
+      if (already.rows[0].n > 0) {
+        entry.status = 'exists';
+        entry.inserted = 0;
+        report.results.push(entry);
+        continue;
+      }
+
+      const cols = await client.query(REQUIRED_COLS_SQL, [schema, table]);
+      const colNames = [];
+      const values = [];
+      const placeholders = [];
+      let bad = null;
+      let idx = 1;
+      const seen = new Set();
+      for (const col of cols.rows) {
+        const v = valueForColumn(col, name, slug);
+        if (v === undefined) { bad = col.column_name; break; }
+        colNames.push(`"${col.column_name}"`);
+        values.push(v);
+        placeholders.push(`$${idx++}`);
+        seen.add(col.column_name);
+      }
+      // Ensure `name` is always written even if it was not flagged required.
+      if (!seen.has('name')) {
+        colNames.push('"name"');
+        values.push(name);
+        placeholders.push(`$${idx++}`);
+      }
+      if (bad) {
+        entry.status = 'skipped';
+        entry.reason = `unsupported required column: ${bad}`;
+        report.results.push(entry);
+        continue;
+      }
+      const ins = await client.query(
+        `INSERT INTO ${qSchema}.${qTable} (${colNames.join(', ')}) VALUES (${placeholders.join(', ')})`,
+        values);
+      entry.inserted = ins.rowCount;
+      entry.name = name;
+      report.results.push(entry);
+    }
+  } finally {
+    await client.end();
+  }
+
+  const seeded = report.results.filter((r) => r.inserted > 0).length;
+  const existed = report.results.filter((r) => r.status === 'exists').length;
+  const removed = report.results.reduce((a, r) => a + (r.removed || 0), 0);
+  const skipped = report.results.filter((r) => r.status === 'skipped').length;
+  report.summary = { seeded, existed, removed, skipped, tenants: tenants.length };
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+main().catch((err) => {
+  process.stderr.write(`[canary-seed] ERROR: ${err && err.stack ? err.stack : err}\n`);
+  process.exitCode = 1;
+});
diff --git a/scripts/scale-validate/churn-driver.mjs b/scripts/scale-validate/churn-driver.mjs
new file mode 100644
index 0000000000..4afb1ca9c2
--- /dev/null
+++ b/scripts/scale-validate/churn-driver.mjs
@@ -0,0 +1,116 @@
+/**
+ * churn-driver.mjs — drive schema-cache churn during a soak.
+ *
+ * Every --interval-notify-sec it issues a NOTIFY on channel "schema:update"
+ * (via pg_notify) with a random tenant's databaseId as payload. The server
+ * LISTENs on "schema:update" and flushes that database's cached PostGraphile
+ * instance(s), forcing rebuilds — exercising eviction/drain/build paths.
+ *
+ * A provisioning hook fires every --provision-every-sec but only logs a marker;
+ * actual tenant provisioning is handled separately by the orchestrator.
+ *
+ * Timeline events are emitted as JSON lines to stdout.
+ *
+ * Usage:
+ *   node scripts/scale-validate/churn-driver.mjs --fleet fleet.json \
+ *     --interval-notify-sec 20 --provision-every-sec 300 --duration-sec 3600
+ */
+import { asBool, asInt, loadFleet, nowIso, parseArgs, pgConfigFromArgs, resolvePg } from './_lib.mjs';
+
+const HELP = `churn-driver.mjs — NOTIFY schema:update churn + provisioning markers
+
+Options:
+  --fleet <file>              fleet manifest (required)
+  --interval-notify-sec <n>   NOTIFY period (default 20; 0 disables)
+  --provision-every-sec <n>   provisioning-marker period (default 0 = off)
+  --duration-sec <n>          run length (default 3600; 0 = until SIGINT)
+  --channel <name>            notify channel (default schema:update)
+  --seed <n>                  RNG seed
+  --pg-* / PG*                connection overrides
+  --help
+`;
+
+async function main() {
+  const { args } = parseArgs(process.argv.slice(2));
+  if (asBool(args.help) || !args.fleet) {
+    process.stdout.write(HELP);
+    if (!args.fleet && !asBool(args.help)) process.exitCode = 1;
+    return;
+  }
+  const intervalNotifySec = asInt(args['interval-notify-sec'], 20);
+  const provisionEverySec = asInt(args['provision-every-sec'], 0);
+  const durationSec = asInt(args['duration-sec'], 3600);
+  const channel = typeof args.channel === 'string' ? args.channel : 'schema:update';
+  let seed = asInt(args.seed, (Date.now() & 0x7fffffff));
+  const { tenants } = loadFleet(args.fleet);
+  const cfg = pgConfigFromArgs(args);
+  const { Client } = resolvePg();
+  // Fresh connection per query: with long NOTIFY intervals a persistent client
+  // gets reaped by idle_session_timeout (57P05) and its socket error would
+  // kill the driver mid-soak. Hourly connects are free.
+  const withClient = async (fn) => {
+    const client = new Client(cfg);
+    client.on('error', () => {});
+    await client.connect();
+    try {
+      return await fn(client);
+    } finally {
+      try {
+        await client.end();
+      } catch {
+        /* ignore */
+      }
+    }
+  };
+
+  const emit = (obj) => process.stdout.write(`${JSON.stringify({ at: nowIso(), ...obj })}\n`);
+  const rand = () => { seed = (seed * 1103515245 + 12345) & 0x7fffffff; return seed / 0x7fffffff; };
+  const pickTenant = () => tenants[Math.floor(rand() * tenants.length)];
+
+  let notifies = 0;
+  let provisions = 0;
+  let failures = 0;
+  const timers = [];
+
+  emit({ t: 'start', channel, intervalNotifySec, provisionEverySec, durationSec, tenants: tenants.length, pid: process.pid });
+
+  if (intervalNotifySec > 0) {
+    timers.push(setInterval(async () => {
+      const tenant = pickTenant();
+      try {
+        await withClient((client) => client.query('SELECT pg_notify($1, $2)', [channel, tenant.databaseId]));
+        notifies++;
+        emit({ t: 'notify', channel, databaseId: tenant.databaseId, dbname: tenant.dbname, seq: notifies });
+      } catch (err) {
+        failures++;
+        emit({ t: 'notify-error', databaseId: tenant.databaseId, dbname: tenant.dbname, error: String(err && err.message || err) });
+      }
+    }, intervalNotifySec * 1000));
+  }
+
+  if (provisionEverySec > 0) {
+    timers.push(setInterval(() => {
+      provisions++;
+      // Provisioning hook — the orchestrator performs the real provision; we only
+      // mark the timeline so churn events can be correlated.
+      emit({ t: 'provision-marker', seq: provisions, note: 'provisioning handled by orchestrator' });
+    }, provisionEverySec * 1000));
+  }
+
+  const stop = async (reason) => {
+    for (const t of timers) clearInterval(t);
+    emit({ t: 'stop', reason, notifies, provisions, failures });
+    // per-query connections — nothing persistent to close
+  };
+
+  let stopTimer = null;
+  if (durationSec > 0) stopTimer = setTimeout(() => stop('duration'), durationSec * 1000);
+  const onSig = async () => { if (stopTimer) clearTimeout(stopTimer); await stop('signal'); process.exit(0); };
+  process.on('SIGINT', onSig);
+  process.on('SIGTERM', onSig);
+}
+
+main().catch((err) => {
+  process.stderr.write(`[churn] FATAL: ${err && err.stack ? err.stack : err}\n`);
+  process.exitCode = 1;
+});
diff --git a/scripts/scale-validate/collector.mjs b/scripts/scale-validate/collector.mjs
new file mode 100644
index 0000000000..d370a6470a
--- /dev/null
+++ b/scripts/scale-validate/collector.mjs
@@ -0,0 +1,207 @@
+/**
+ * collector.mjs — RSS sampler + server metrics tailer.
+ *
+ * Samples the server process RSS (ps -o rss=) every --interval-sec and tails the
+ * server's metrics.jsonl. At exit it computes:
+ *   - RSS min / max / final (MB)
+ *   - linear-regression slope (MB/hour) over the LAST HALF of the RSS samples
+ *   - eviction / drain / build totals parsed from the LAST metrics line
+ * and writes a summary JSON to --out.
+ *
+ * The metrics.jsonl schema is owned by the server instrumentation; this tailer
+ * is intentionally schema-tolerant: it flattens the last JSON object and picks
+ * the best numeric field per counter family (evict / drain / build).
+ *
+ * Exit is triggered by SIGINT/SIGTERM, by --duration-sec, or when the monitored
+ * PID disappears.
+ *
+ * Usage:
+ *   node scripts/scale-validate/collector.mjs --pid 12345 \
+ *     --metrics-file graphql/server/logs/metrics.jsonl --out collector.json
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { asInt, nowIso, parseArgs, round2, sleep } from './_lib.mjs';
+
+const HELP = `collector.mjs — sample RSS + tail metrics.jsonl, summarize at exit
+
+Options:
+  --pid <n>            server process id to sample (required)
+  --metrics-file <f>   server metrics.jsonl to tail (optional)
+  --interval-sec <n>   sample period (default 15)
+  --duration-sec <n>   run length (default 0 = until SIGINT or pid exit)
+  --out <file>         summary JSON (default collector.json)
+  --help
+`;
+
+function sampleRssMb(pid) {
+  const res = spawnSync('ps', ['-o', 'rss=', '-p', String(pid)], { encoding: 'utf8' });
+  if (res.status !== 0) return null;
+  const kb = Number.parseInt((res.stdout || '').trim(), 10);
+  if (!Number.isFinite(kb)) return null;
+  return round2(kb / 1024);
+}
+
+// Least-squares slope of y over x. Returns slope in y-units per x-unit.
+function linregSlope(points) {
+  const n = points.length;
+  if (n < 2) return 0;
+  let sx = 0, sy = 0, sxx = 0, sxy = 0;
+  for (const [x, y] of points) { sx += x; sy += y; sxx += x * x; sxy += x * y; }
+  const denom = n * sxx - sx * sx;
+  if (denom === 0) return 0;
+  return (n * sxy - sx * sy) / denom;
+}
+
+// Flatten nested object into [{ path, value }] for numeric leaves only.
+function flattenNumeric(obj, prefix = '', out = []) {
+  if (obj == null || typeof obj !== 'object') return out;
+  for (const [k, v] of Object.entries(obj)) {
+    const path = prefix ? `${prefix}.${k}` : k;
+    if (typeof v === 'number' && Number.isFinite(v)) out.push({ path, value: v });
+    else if (v && typeof v === 'object') flattenNumeric(v, path, out);
+  }
+  return out;
+}
+
+// Pick the best-matching numeric field for a counter family.
+function pickCounter(flat, family) {
+  const re = new RegExp(family, 'i');
+  const candidates = flat.filter((f) => re.test(f.path));
+  if (candidates.length === 0) return { value: null, path: null, candidates: [] };
+  // Prefer explicit totals/counts, then longer (more specific) paths.
+  const score = (p) => (/(total|count|sum|cumulative|s$)/i.test(p) ? 2 : 0) + p.length / 1000;
+  candidates.sort((a, b) => score(b.path) - score(a.path));
+  return { value: candidates[0].value, path: candidates[0].path, candidates: candidates.map((c) => ({ path: c.path, value: c.value })) };
+}
+
+async function main() {
+  const { args } = parseArgs(process.argv.slice(2));
+  if (args.help || args.pid === undefined) {
+    process.stdout.write(HELP);
+    if (args.pid === undefined && !args.help) process.exitCode = 1;
+    return;
+  }
+  const pid = asInt(args.pid, 0);
+  const metricsFile = typeof args['metrics-file'] === 'string' ? args['metrics-file'] : null;
+  const intervalSec = asInt(args['interval-sec'], 15);
+  const durationSec = asInt(args['duration-sec'], 0);
+  const out = typeof args.out === 'string' ? args.out : 'collector.json';
+
+  const startMs = Date.now();
+  const samples = []; // { tSec, rssMb }
+  let lastMetricsObj = null;
+  let lastMetricsRaw = null;
+  let metricsLinesSeen = 0;
+  let metricsOffset = 0;
+  let stopping = false;
+  let stopReason = null;
+
+  const readMetricsTail = () => {
+    if (!metricsFile) return;
+    let stat;
+    try { stat = fs.statSync(metricsFile); } catch { return; }
+    if (stat.size < metricsOffset) metricsOffset = 0; // rotated/truncated
+    if (stat.size === metricsOffset) return;
+    let chunk = '';
+    try {
+      const fd = fs.openSync(metricsFile, 'r');
+      const len = stat.size - metricsOffset;
+      const buf = Buffer.alloc(len);
+      fs.readSync(fd, buf, 0, len, metricsOffset);
+      fs.closeSync(fd);
+      chunk = buf.toString('utf8');
+      metricsOffset = stat.size;
+    } catch { return; }
+    for (const line of chunk.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      metricsLinesSeen++;
+      try {
+        lastMetricsObj = JSON.parse(trimmed);
+        lastMetricsRaw = trimmed;
+      } catch { /* partial/non-json line — ignore */ }
+    }
+  };
+
+  const emit = (obj) => process.stdout.write(`${JSON.stringify({ at: nowIso(), ...obj })}\n`);
+  emit({ t: 'start', pid, metricsFile, intervalSec, durationSec });
+
+  const finalize = () => {
+    const rssValues = samples.map((s) => s.rssMb);
+    const rssMin = rssValues.length ? Math.min(...rssValues) : null;
+    const rssMax = rssValues.length ? Math.max(...rssValues) : null;
+    const rssFinal = rssValues.length ? rssValues[rssValues.length - 1] : null;
+    // slope over the last half of samples
+    const half = samples.slice(Math.floor(samples.length / 2));
+    const slopeMbPerSec = linregSlope(half.map((s) => [s.tSec, s.rssMb]));
+    const slopeMbPerHour = round2(slopeMbPerSec * 3600);
+
+    const flat = lastMetricsObj ? flattenNumeric(lastMetricsObj) : [];
+    const evictions = pickCounter(flat, 'evict');
+    const drains = pickCounter(flat, 'drain');
+    const builds = pickCounter(flat, 'build');
+
+    const summary = {
+      generatedAt: nowIso(),
+      pid,
+      stopReason,
+      durationSec: round2((Date.now() - startMs) / 1000),
+      intervalSec,
+      rss: {
+        samples: samples.length,
+        minMb: rssMin,
+        maxMb: rssMax,
+        finalMb: rssFinal,
+        slopeMbPerHour,
+        slopeBasis: `last ${half.length} of ${samples.length} samples`,
+        series: samples
+      },
+      metrics: {
+        file: metricsFile,
+        linesSeen: metricsLinesSeen,
+        evictionsTotal: evictions.value,
+        evictionsField: evictions.path,
+        drainsTotal: drains.value,
+        drainsField: drains.path,
+        buildsTotal: builds.value,
+        buildsField: builds.path,
+        candidates: { evict: evictions.candidates, drain: drains.candidates, build: builds.candidates },
+        lastLine: lastMetricsObj
+      }
+    };
+    fs.writeFileSync(out, `${JSON.stringify(summary, null, 2)}\n`);
+    emit({
+      t: 'summary', rssMinMb: rssMin, rssMaxMb: rssMax, rssFinalMb: rssFinal, slopeMbPerHour,
+      evictionsTotal: evictions.value, drainsTotal: drains.value, buildsTotal: builds.value, out
+    });
+    return summary;
+  };
+
+  const onSig = () => { stopping = true; stopReason = stopReason || 'signal'; };
+  process.on('SIGINT', onSig);
+  process.on('SIGTERM', onSig);
+
+  // Prime the metrics offset so we start reading from current EOF-ish but still
+  // capture the last line: read everything once so lastMetricsObj is populated.
+  readMetricsTail();
+
+  while (!stopping) {
+    const rssMb = sampleRssMb(pid);
+    if (rssMb == null) { stopReason = 'pid-exited'; break; }
+    samples.push({ tSec: round2((Date.now() - startMs) / 1000), rssMb });
+    readMetricsTail();
+    emit({ t: 'sample', tSec: round2((Date.now() - startMs) / 1000), rssMb, metricsLines: metricsLinesSeen });
+    if (durationSec > 0 && (Date.now() - startMs) / 1000 >= durationSec) { stopReason = 'duration'; break; }
+    // sleep in small slices so SIGINT is responsive
+    const until = Date.now() + intervalSec * 1000;
+    while (!stopping && Date.now() < until) await sleep(200);
+  }
+  readMetricsTail();
+  finalize();
+}
+
+main().catch((err) => {
+  process.stderr.write(`[collector] FATAL: ${err && err.stack ? err.stack : err}\n`);
+  process.exitCode = 1;
+});
diff --git a/scripts/scale-validate/drift-tenants.mjs b/scripts/scale-validate/drift-tenants.mjs
new file mode 100644
index 0000000000..afbed2370b
--- /dev/null
+++ b/scripts/scale-validate/drift-tenants.mjs
@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * Apply deliberate shape drift to seeded tenants so the fleet spans multiple
+ * blueprints (the pooling shape-fingerprint hashes [logical schema, relname]
+ * pairs — only ADDING A RELATION changes a tenant's blueprint).
+ *
+ * Modes:
+ *   --groups K --per-group N   assign K drift groups; group g (1-based) gets a
+ *                              marker TABLE drift_marker_g<g> in app-public →
+ *                              K distinct blueprints (group 0 = undrifted).
+ *   --column-drift N           additionally give N tenants a benign EXTRA COLUMN
+ *                              on categories (same relname set → SAME blueprint;
+ *                              exercises the documented fingerprint limitation).
+ *
+ * Writes drifted.json describing the assignment. Idempotent (IF NOT EXISTS).
+ * Usage: node scripts/scale-validate/drift-tenants.mjs --groups 6 --per-group 4 --column-drift 2
+ */
+import { writeFileSync } from 'node:fs';
+
+import { resolvePg } from './_lib.mjs';
+
+const { Pool } = resolvePg();
+
+const arg = (name, dflt) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 ? process.argv[i + 1] : dflt;
+};
+const GROUPS = parseInt(arg('groups', '0'), 10);
+const PER_GROUP = parseInt(arg('per-group', '4'), 10);
+const COLUMN_DRIFT = parseInt(arg('column-drift', '0'), 10);
+
+const pool = new Pool({
+  host: process.env.PGHOST || 'localhost',
+  port: parseInt(process.env.PGPORT || '5433', 10),
+  user: process.env.PGUSER || 'postgres',
+  password: process.env.PGPASSWORD || 'password',
+  database: process.env.PGDATABASE || 'constructive'
+});
+
+const main = async () => {
+  // Tenant app-public schemas, oldest first for stable assignment.
+  const { rows } = await pool.query(`
+    SELECT db.name AS dbname, s.schema_name
+    FROM metaschema_public.database db
+    JOIN metaschema_public.schema s ON s.database_id = db.id
+    WHERE db.name NOT IN ('constructive') AND s.schema_name LIKE '%-app-public'
+    ORDER BY db.name`);
+
+  const assignment = { groups: {}, columnDrift: [] };
+  let idx = 0;
+
+  for (let g = 1; g <= GROUPS; g++) {
+    assignment.groups[g] = [];
+    for (let n = 0; n < PER_GROUP && idx < rows.length; n++, idx++) {
+      const { dbname, schema_name } = rows[idx];
+      await pool.query(
+        `CREATE TABLE IF NOT EXISTS "${schema_name.replace(/"/g, '""')}"."drift_marker_g${g}" (id serial PRIMARY KEY, note text)`
+      );
+      assignment.groups[g].push(dbname);
+      console.log(`table-drift g${g}: ${dbname}`);
+    }
+  }
+
+  for (let n = 0; n < COLUMN_DRIFT && idx < rows.length; n++, idx++) {
+    const { dbname, schema_name } = rows[idx];
+    await pool.query(
+      `ALTER TABLE "${schema_name.replace(/"/g, '""')}".categories ADD COLUMN IF NOT EXISTS drift_col_only text`
+    );
+    assignment.columnDrift.push(dbname);
+    console.log(`column-drift (same blueprint, documents fingerprint limit): ${dbname}`);
+  }
+
+  writeFileSync(new URL('./drifted.json', import.meta.url), JSON.stringify(assignment, null, 2));
+  console.log(`done: ${GROUPS} table-drift groups × ${PER_GROUP}, ${COLUMN_DRIFT} column-drift; assignment → drifted.json`);
+  await pool.end();
+};
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
diff --git a/scripts/scale-validate/drop-tenants.mjs b/scripts/scale-validate/drop-tenants.mjs
new file mode 100644
index 0000000000..b4fb1880e3
--- /dev/null
+++ b/scripts/scale-validate/drop-tenants.mjs
@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// =============================================================================
+// drop-tenants.mjs — tear down factory tenants above --keep (catalog-wall
+// remediation: the rig's PG cannot introspect a 100+-tenant catalog, so the
+// fleet is trimmed to a size the VM can serve).
+//
+// Per tenant, in one transaction:
+//   1. capture its physical schema names from metaschema_public.schema
+//   2. DELETE FROM metaschema_public.database (all control-plane FKs CASCADE;
+//      metaschema delete triggers may drop physical objects as they go —
+//      requires the constructive.allow_super_constructive GUC)
+//   3. DROP SCHEMA IF EXISTS ... CASCADE for any physical schema that survived
+// Then VACUUM ANALYZE the hot catalogs and report the new catalog size.
+//
+// Usage:
+//   node scripts/scale-validate/drop-tenants.mjs --prefix factory --keep 40 [--dry-run] [--only factory101]
+// Env: PGHOST PGPORT PGUSER PGPASSWORD PGDATABASE (defaults :5433 constructive)
+// =============================================================================
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WORKTREE = path.resolve(__dirname, '..', '..');
+const rootRequire = createRequire(path.join(WORKTREE, 'graphql', 'query', 'package.json'));
+const requireDpAdaptor = createRequire(rootRequire.resolve('postgraphile/adaptors/pg'));
+const requireDataplan = createRequire(requireDpAdaptor.resolve('@dataplan/pg'));
+const { Pool } = requireDataplan('pg');
+
+const arg = (name, dflt) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 ? process.argv[i + 1] : dflt;
+};
+const has = (name) => process.argv.includes(`--${name}`);
+
+const PREFIX = arg('prefix', 'factory');
+const KEEP = parseInt(arg('keep', '40'), 10);
+const ONLY = arg('only', null);
+const DRY = has('dry-run');
+
+const pool = new Pool({
+  host: process.env.PGHOST || 'localhost',
+  port: parseInt(process.env.PGPORT || '5433', 10),
+  user: process.env.PGUSER || 'postgres',
+  password: process.env.PGPASSWORD || 'password',
+  database: process.env.PGDATABASE || 'constructive',
+  max: 2
+});
+pool.on('error', (e) => console.error(`[pool] idle client error (continuing): ${e.message}`));
+
+const qid = (s) => `"${s.replace(/"/g, '""')}"`;
+
+async function dropOne(row) {
+  const client = await pool.connect();
+  const t0 = Date.now();
+  try {
+    await client.query('BEGIN');
+    await client.query('SET LOCAL statement_timeout = 0');
+    await client.query('SET LOCAL lock_timeout = 0');
+    await client.query(`SET LOCAL constructive.allow_super_constructive = 'true'`);
+
+    const schemas = (
+      await client.query(`SELECT schema_name FROM metaschema_public.schema WHERE database_id=$1`, [row.id])
+    ).rows.map((r) => r.schema_name);
+
+    await client.query(`DELETE FROM metaschema_public.database WHERE id=$1`, [row.id]);
+
+    let survivors = 0;
+    for (const s of schemas) {
+      const exists = await client.query(`SELECT 1 FROM pg_namespace WHERE nspname=$1`, [s]);
+      if (exists.rows.length) {
+        survivors++;
+        await client.query(`DROP SCHEMA IF EXISTS ${qid(s)} CASCADE`);
+      }
+    }
+
+    // pg_partman registers partitioned tables by NAME in partman.part_config —
+    // not schema-scoped, not FK-cascaded — and schema hashes are deterministic
+    // per dbname, so a leftover row blocks re-provisioning a reused tenant name
+    // (unique_violation on parent_table). Clean them with the schemas.
+    if (schemas.length) {
+      const patterns = schemas.map((s) => `${s}.%`);
+      try {
+        await client.query(`DELETE FROM partman.part_config_sub WHERE sub_parent LIKE ANY($1)`, [patterns]);
+      } catch {
+        /* part_config_sub may not exist */
+      }
+      try {
+        const del = await client.query(`DELETE FROM partman.part_config WHERE parent_table LIKE ANY($1)`, [
+          patterns
+        ]);
+        if (del.rowCount) console.log(`  [${row.name}] cleaned ${del.rowCount} partman.part_config row(s)`);
+      } catch {
+        /* partman may not be installed */
+      }
+    }
+
+    if (DRY) await client.query('ROLLBACK');
+    else await client.query('COMMIT');
+    console.log(
+      `  [${row.name}] dropped (schemas=${schemas.length} survivors-dropped=${survivors}) ${Date.now() - t0}ms${DRY ? ' [DRY]' : ''}`
+    );
+    return { ok: true };
+  } catch (e) {
+    try {
+      await client.query('ROLLBACK');
+    } catch {}
+    console.error(`  [${row.name}] FAILED: ${e.code || ''} ${e.message}`);
+    return { ok: false, error: e.message };
+  } finally {
+    client.release();
+  }
+}
+
+const main = async () => {
+  const where = ONLY
+    ? { sql: `name = $1`, params: [ONLY] }
+    : {
+        sql: `name ~ ('^' || $1 || '[0-9]+$') AND (regexp_replace(name, '^' || $1, ''))::int > $2`,
+        params: [PREFIX, KEEP]
+      };
+  const { rows } = await pool.query(
+    `SELECT id, name FROM metaschema_public.database WHERE ${where.sql}
+     ORDER BY (regexp_replace(name, '[^0-9]', '', 'g'))::int NULLS LAST`,
+    where.params
+  );
+  console.log(`drop-tenants: ${rows.length} tenant(s) to drop${DRY ? ' [DRY-RUN]' : ''}`);
+
+  let ok = 0;
+  for (const row of rows) {
+    const r = await dropOne(row);
+    if (r.ok) ok++;
+  }
+  console.log(`dropped ${ok}/${rows.length}`);
+
+  if (!DRY && ok > 0) {
+    console.log('VACUUM ANALYZE hot catalogs...');
+    for (const cat of ['pg_class', 'pg_attribute', 'pg_proc', 'pg_constraint', 'pg_policy', 'pg_namespace', 'pg_depend', 'pg_type']) {
+      await pool.query(`VACUUM ANALYZE ${cat}`);
+    }
+  }
+
+  const stats = await pool.query(`
+    SELECT (SELECT count(*) FROM pg_class) AS classes,
+           (SELECT count(*) FROM pg_attribute) AS attrs,
+           (SELECT count(*) FROM pg_namespace) AS namespaces,
+           (SELECT count(*) FROM metaschema_public.database) AS databases`);
+  console.log(`catalog now: ${JSON.stringify(stats.rows[0])}`);
+  await pool.end();
+};
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
diff --git a/scripts/scale-validate/fleet.mjs b/scripts/scale-validate/fleet.mjs
new file mode 100644
index 0000000000..4c89f0ba43
--- /dev/null
+++ b/scripts/scale-validate/fleet.mjs
@@ -0,0 +1,107 @@
+/**
+ * fleet.mjs — print a JSON fleet manifest describing every marketplace tenant.
+ *
+ * For each tenant database (metaschema_public.database where name like the
+ * --like pattern) it resolves:
+ *   - databaseId
+ *   - api host  (services_public.domains subdomain like 'api-%'  + '.' + domain)
+ *   - auth host (services_public.domains subdomain like 'auth-%' + '.' + domain)
+ *   - the physical schemas of the `api` API
+ *       (services_public.apis JOIN api_schemas JOIN metaschema_public.schema)
+ *
+ * Usage:
+ *   node scripts/scale-validate/fleet.mjs > fleet.json
+ *   node scripts/scale-validate/fleet.mjs --like 'marketplace%' --pretty
+ *   PGPORT=5433 node scripts/scale-validate/fleet.mjs --out fleet.json
+ */
+import fs from 'node:fs';
+import { asBool, nowIso, parseArgs, pgConfigFromArgs, resolvePg } from './_lib.mjs';
+
+const HELP = `fleet.mjs — emit JSON fleet manifest from the control-plane DB
+
+Options:
+  --like <pattern>   database name filter (default: 'marketplace%')
+  --out <file>       write JSON here instead of stdout
+  --pretty           pretty-print JSON
+  --pg-host/--pg-port/--pg-user/--pg-password/--pg-database  connection overrides
+  --help
+`;
+
+const FLEET_SQL = `
+SELECT
+  d.name AS dbname,
+  d.id::text AS database_id,
+  (SELECT dom.subdomain || '.' || dom.domain
+     FROM services_public.domains dom
+     WHERE dom.database_id = d.id AND dom.subdomain LIKE 'api-%'
+     ORDER BY dom.subdomain LIMIT 1) AS api_host,
+  (SELECT dom.subdomain || '.' || dom.domain
+     FROM services_public.domains dom
+     WHERE dom.database_id = d.id AND dom.subdomain LIKE 'auth-%'
+     ORDER BY dom.subdomain LIMIT 1) AS auth_host,
+  COALESCE((
+    SELECT array_agg(s.schema_name ORDER BY s.schema_name)
+      FROM services_public.apis a
+      JOIN services_public.api_schemas aps ON aps.api_id = a.id AND aps.database_id = a.database_id
+      JOIN metaschema_public.schema s ON s.id = aps.schema_id
+     WHERE a.database_id = d.id AND a.name = 'api'
+  ), ARRAY[]::text[]) AS schemas
+FROM metaschema_public.database d
+WHERE d.name LIKE $1
+ORDER BY d.name;
+`;
+
+async function main() {
+  const { args } = parseArgs(process.argv.slice(2));
+  if (asBool(args.help)) {
+    process.stdout.write(HELP);
+    return;
+  }
+  const like = typeof args.like === 'string' ? args.like : 'marketplace%';
+  const pretty = asBool(args.pretty);
+  const cfg = pgConfigFromArgs(args);
+  const { Client } = resolvePg();
+  const client = new Client(cfg);
+  await client.connect();
+  let rows;
+  try {
+    const res = await client.query(FLEET_SQL, [like]);
+    rows = res.rows;
+  } finally {
+    await client.end();
+  }
+
+  const tenants = rows.map((r) => {
+    const schemas = r.schemas || [];
+    const appPublicSchema = schemas.find((s) => /-app-public$/.test(s)) || schemas[0] || null;
+    return {
+      dbname: r.dbname,
+      databaseId: r.database_id,
+      apiHost: r.api_host,
+      authHost: r.auth_host,
+      schemas,
+      appPublicSchema
+    };
+  });
+
+  const manifest = {
+    generatedAt: nowIso(),
+    like,
+    pg: { host: cfg.host, port: cfg.port, database: cfg.database },
+    count: tenants.length,
+    tenants
+  };
+
+  const json = JSON.stringify(manifest, null, pretty ? 2 : 0);
+  if (typeof args.out === 'string') {
+    fs.writeFileSync(args.out, `${json}\n`, 'utf8');
+    process.stderr.write(`[fleet] wrote ${tenants.length} tenants to ${args.out}\n`);
+  } else {
+    process.stdout.write(`${json}\n`);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`[fleet] ERROR: ${err && err.stack ? err.stack : err}\n`);
+  process.exitCode = 1;
+});
diff --git a/scripts/scale-validate/harness.mjs b/scripts/scale-validate/harness.mjs
new file mode 100644
index 0000000000..e98349bccf
--- /dev/null
+++ b/scripts/scale-validate/harness.mjs
@@ -0,0 +1,694 @@
+/**
+ * harness.mjs — workload driver for the scale validation soak/ramp.
+ *
+ * Generates a token-bucket-paced request stream (open-loop) at a target RPS
+ * across the tenant fleet, with a read/write/meta class mix, tenant-selection
+ * shapes (zipf/uniform/burst), per-tenant auth, a cross-tenant bleed sentinel,
+ * latency histograms, rolling per-minute stdout summaries, and a final JSON
+ * report.
+ *
+ * NO server/package code is imported — this only speaks GraphQL over HTTP.
+ *
+ * Usage:
+ *   node scripts/scale-validate/harness.mjs --help
+ *   node scripts/scale-validate/harness.mjs --fleet fleet.json --port 3333 \
+ *     --duration-sec 600 --rps 40 --mix read:0.7,write:0.25,meta:0.05 \
+ *     --shape zipf --auth 1 --sentinel-interval-sec 60 --out results.json
+ *
+ * Exit codes: 0 ok, 1 fatal error, 2 bleed-sentinel violation.
+ */
+import fs from 'node:fs';
+import {
+  Histogram, INTROSPECTION_QUERY, asBool, asFloat, asInt, buildCreateRecord, buildTypeIndex,
+  canaryName, CANARY_PREFIX, discoverOps, gqlErrors, gqlFetch, isRotating, isUnauthenticated,
+  loadFleet, makeMixSampler, makeRng, makeZipfSampler, nowIso, parseArgs, round2, sleep, unwrapType
+} from './_lib.mjs';
+
+const HELP = `harness.mjs — workload driver (soaks + ramps) against the running cnc server
+
+Required:
+  --fleet <file>              fleet manifest from fleet.mjs
+Common:
+  --port <n>                  server port (default 3333)
+  --duration-sec <n>          run length (default 60)
+  --rps <n>                   target requests/sec (default 20)
+  --mix read:.7,write:.25,meta:.05   class mix (default that)
+  --shape zipf|uniform|burst  tenant selection (default zipf)
+  --auth 0|1                  authenticate reads/writes (default 1)
+  --sentinel-interval-sec <n> bleed sentinel period (default 60)
+  --out <file>                final JSON report (default results.json)
+Tuning:
+  --report-sec <n>            rolling summary interval (default 60)
+  --burst-window-sec <n>      burst shape focus window (default 30)
+  --relogin-sec <n>           token refresh period (default 3600)
+  --timeout-ms <n>            per-request timeout (default 30000)
+  --max-inflight <n>          concurrency cap (default max(64, rps*2))
+  --rotate-backoff-ms <n>     503 retry backoff (default 250)
+  --email / --password        seeder credentials (defaults provided)
+  --seed <n>                  RNG seed for reproducible selection
+  --quiet                     suppress per-minute lines (still written to --out)
+  --help
+
+Leaked LOAD- rows (only on delete failure) are reported as write.leaked; clean
+with: DELETE FROM "<schema>".categories WHERE name LIKE 'LOAD-%';
+`;
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+const { args } = parseArgs(process.argv.slice(2));
+if (asBool(args.help) || !args.fleet) {
+  process.stdout.write(HELP);
+  if (!args.fleet && !asBool(args.help)) process.exitCode = 1;
+  process.exit();
+}
+
+const PORT = asInt(args.port, 3333);
+const DURATION_SEC = asInt(args['duration-sec'], 60);
+const RPS = Math.max(asFloat(args.rps, 20), 0.1);
+const MIX = typeof args.mix === 'string' ? args.mix : 'read:0.7,write:0.25,meta:0.05';
+const SHAPE = ['zipf', 'uniform', 'burst'].includes(args.shape) ? args.shape : 'zipf';
+const AUTH = asBool(args.auth, true);
+const SENTINEL_SEC = asInt(args['sentinel-interval-sec'], 60);
+const OUT = typeof args.out === 'string' ? args.out : 'results.json';
+const REPORT_SEC = asInt(args['report-sec'], 60);
+const BURST_WINDOW_SEC = asInt(args['burst-window-sec'], 30);
+const RELOGIN_SEC = asInt(args['relogin-sec'], 3600);
+const TIMEOUT_MS = asInt(args['timeout-ms'], 30000);
+const MAX_INFLIGHT = asInt(args['max-inflight'], Math.max(64, Math.ceil(RPS * 2)));
+const ROTATE_BACKOFF_MS = asInt(args['rotate-backoff-ms'], 250);
+const EMAIL = typeof args.email === 'string' ? args.email : 'seeder@gmail.com';
+// Never a literal default: flag > PERF_PASSWORD env (matches packages/perf-harness resolveCreds).
+const PASSWORD = typeof args.password === 'string' ? args.password : (process.env.PERF_PASSWORD ?? null);
+if (AUTH && !PASSWORD) {
+  console.error('[harness] --auth requires credentials: pass --password or set PERF_PASSWORD');
+  // Exit 3 = config error. Exit 2 is reserved exclusively for the bleed sentinel
+  // (cross-tenant isolation violation) — suites key on it; never reuse it.
+  process.exit(3);
+}
+const SEED = asInt(args.seed, (Date.now() & 0x7fffffff));
+const QUIET = asBool(args.quiet);
+
+const rng = makeRng(SEED);
+const { tenants } = loadFleet(args.fleet);
+
+// ---------------------------------------------------------------------------
+// Metrics
+// ---------------------------------------------------------------------------
+const M = {
+  startedAt: nowIso(),
+  config: {
+    port: PORT, durationSec: DURATION_SEC, rps: RPS, mix: MIX, shape: SHAPE, auth: AUTH,
+    sentinelIntervalSec: SENTINEL_SEC, reportSec: REPORT_SEC, burstWindowSec: BURST_WINDOW_SEC,
+    reloginSec: RELOGIN_SEC, timeoutMs: TIMEOUT_MS, maxInflight: MAX_INFLIGHT, seed: SEED,
+    fleetCount: tenants.length
+  },
+  totals: { sent: 0, completed: 0, ok: 0, err: 0, requests: 0, dropped: 0, rotating: 0, rotatingRetried: 0, timeouts: 0, network: 0 },
+  http: {},
+  netErrors: {},
+  gqlByCode: {},
+  gqlByMsg: {},
+  gqlMsgOverflow: 0,
+  classes: {
+    read: { sent: 0, ok: 0, err: 0, unavailable: 0, hist: new Histogram() },
+    write: { sent: 0, ok: 0, err: 0, unavailable: 0, fallbackRead: 0, created: 0, deleted: 0, leaked: 0, createErr: 0, deleteErr: 0, hist: new Histogram() },
+    meta: { sent: 0, ok: 0, err: 0, unavailable: 0, hist: new Histogram() }
+  },
+  overallHist: new Histogram(),
+  perTenant: {},
+  auth: { enabled: AUTH, shape: null, logins: 0, loginFailures: 0, relogins: 0, unauth: 0 },
+  sentinel: { checks: 0, tenantsChecked: 0, ownCanarySeen: 0, inconclusive: 0, violations: [], ok: true },
+  progress: []
+};
+for (const t of tenants) M.perTenant[t.dbname] = { sent: 0, ok: 0, err: 0 };
+
+let windowHist = new Histogram();
+const startMs = Date.now();
+let pacingStartMs = 0;
+let inFlight = 0;
+let stopping = false;
+let stopReason = null;
+
+// ---------------------------------------------------------------------------
+// Runtime tenant state
+// ---------------------------------------------------------------------------
+const runtime = tenants.map((tenant) => ({
+  tenant,
+  ops: { read: null, meta: false, create: null, del: null },
+  token: null,
+  tokenAt: 0,
+  reloginInFlight: false,
+  authError: null,
+  introspectError: null,
+  leakedKeys: []
+}));
+
+let writeCounter = 0;
+const randId = () => `${(SEED & 0xffff).toString(36)}-${(writeCounter++).toString(36)}-${Math.floor(rng() * 1e9).toString(36)}`;
+const log = (...a) => { if (!QUIET) process.stderr.write(`${a.join(' ')}\n`); };
+const emit = (obj) => process.stdout.write(`${JSON.stringify(obj)}\n`);
+
+// ---------------------------------------------------------------------------
+// HTTP request with retry-once on 503 SERVICE_ROTATING
+// ---------------------------------------------------------------------------
+async function apiRequest(s, { query, variables, token }) {
+  let resp = await gqlFetch({ host: s.tenant.apiHost, port: PORT, query, variables, token, timeoutMs: TIMEOUT_MS });
+  if (isRotating(resp)) {
+    M.totals.rotating++;
+    await sleep(ROTATE_BACKOFF_MS);
+    resp = await gqlFetch({ host: s.tenant.apiHost, port: PORT, query, variables, token, timeoutMs: TIMEOUT_MS });
+    M.totals.rotatingRetried++;
+  }
+  return resp;
+}
+
+function trackHttp(resp, cls) {
+  M.totals.requests++;
+  M.overallHist.record(resp.elapsedMs);
+  windowHist.record(resp.elapsedMs);
+  M.classes[cls].hist.record(resp.elapsedMs);
+  const key = String(resp.status);
+  M.http[key] = (M.http[key] || 0) + 1;
+  if (resp.error === 'timeout') M.totals.timeouts++;
+  else if (resp.error) { M.totals.network++; M.netErrors[resp.error] = (M.netErrors[resp.error] || 0) + 1; }
+  for (const e of gqlErrors(resp)) {
+    const code = (e.extensions && e.extensions.code) || 'GRAPHQL_ERROR';
+    M.gqlByCode[code] = (M.gqlByCode[code] || 0) + 1;
+    const msg = String((e && e.message) || '').slice(0, 200);
+    // Cap distinct-message cardinality so a 24h soak with id-bearing messages
+    // cannot grow this map without bound.
+    if (M.gqlByMsg[msg] !== undefined || Object.keys(M.gqlByMsg).length < 1000) {
+      M.gqlByMsg[msg] = (M.gqlByMsg[msg] || 0) + 1;
+    } else {
+      M.gqlMsgOverflow++;
+    }
+  }
+}
+
+function bumpTenant(s, kind) { const p = M.perTenant[s.tenant.dbname]; if (p) p[kind]++; }
+
+function maybeRelogin(s, resp) {
+  if (!AUTH) return;
+  if (isUnauthenticated(resp)) { M.auth.unauth++; scheduleRelogin(s); }
+}
+
+// ---------------------------------------------------------------------------
+// Op executors — each returns { ok } or { skip:true }; runOp folds into totals.
+// ---------------------------------------------------------------------------
+async function execRead(s) {
+  const r = M.classes.read;
+  r.sent++;
+  const resp = await apiRequest(s, { query: `{ ${s.ops.read} { totalCount nodes { name } } }`, token: s.token });
+  trackHttp(resp, 'read');
+  maybeRelogin(s, resp);
+  const ok = resp.ok && gqlErrors(resp).length === 0 && !resp.error;
+  if (ok) r.ok++; else r.err++;
+  bumpTenant(s, ok ? 'ok' : 'err');
+  return { ok };
+}
+
+async function execMeta(s) {
+  const m = M.classes.meta;
+  m.sent++;
+  const resp = await apiRequest(s, { query: '{ _meta { tables { name } } }' });
+  trackHttp(resp, 'meta');
+  const ok = resp.ok && gqlErrors(resp).length === 0 && !resp.error;
+  if (ok) m.ok++; else m.err++;
+  bumpTenant(s, ok ? 'ok' : 'err');
+  return { ok };
+}
+
+function createQuery(c) {
+  return `mutation Create($input: ${c.inputTypeName}!) { ${c.name}(input: $input) { ${c.payloadFieldName} { ${c.keySelect} } } }`;
+}
+function deleteQuery(d) {
+  return `mutation Del($input: ${d.inputTypeName}!) { ${d.name}(input: $input) { clientMutationId } }`;
+}
+
+async function execWrite(s) {
+  const w = M.classes.write;
+  w.sent++;
+  const rand = randId();
+  const record = buildCreateRecord(s.ops.create, `LOAD-${rand}`, rand);
+  const cResp = await apiRequest(s, {
+    query: createQuery(s.ops.create),
+    variables: { input: { [s.ops.create.innerName]: record } },
+    token: s.token
+  });
+  trackHttp(cResp, 'write');
+  maybeRelogin(s, cResp);
+  const cOk = cResp.ok && gqlErrors(cResp).length === 0 && !cResp.error;
+  if (!cOk) { w.createErr++; w.err++; bumpTenant(s, 'err'); return { ok: false }; }
+  w.created++;
+  const payload = cResp.json && cResp.json.data && cResp.json.data[s.ops.create.name];
+  const rec = payload && payload[s.ops.create.payloadFieldName];
+  const keyVal = rec && rec[s.ops.create.keySelect];
+  if (keyVal == null) { w.err++; w.leaked++; bumpTenant(s, 'err'); return { ok: false }; }
+  const dResp = await apiRequest(s, {
+    query: deleteQuery(s.ops.del),
+    variables: { input: { [s.ops.del.key]: keyVal } },
+    token: s.token
+  });
+  trackHttp(dResp, 'write');
+  maybeRelogin(s, dResp);
+  const dOk = dResp.ok && gqlErrors(dResp).length === 0 && !dResp.error;
+  if (dOk) { w.deleted++; w.ok++; bumpTenant(s, 'ok'); return { ok: true }; }
+  w.deleteErr++; w.leaked++; w.err++;
+  if (s.leakedKeys.length < 200) s.leakedKeys.push(keyVal);
+  bumpTenant(s, 'err');
+  return { ok: false };
+}
+
+// Substitution keeps a tenant's PostGraphile instance under load even when a
+// class is unavailable for it (e.g. the blank tenant with no categories table).
+function canWrite(s) { return !!(s.ops.create && s.ops.del && s.ops.create.payloadFieldName); }
+
+async function opRead(s) {
+  if (s.ops.read) return execRead(s);
+  M.classes.read.unavailable++;
+  if (s.ops.meta) return execMeta(s);
+  return { skip: true };
+}
+async function opMeta(s) {
+  if (s.ops.meta) return execMeta(s);
+  M.classes.meta.unavailable++;
+  if (s.ops.read) return execRead(s);
+  return { skip: true };
+}
+async function opWrite(s) {
+  if (canWrite(s)) return execWrite(s);
+  M.classes.write.unavailable++;
+  if (s.ops.read) { M.classes.write.fallbackRead++; return execRead(s); }
+  if (s.ops.meta) { M.classes.write.fallbackRead++; return execMeta(s); }
+  return { skip: true };
+}
+
+async function runOp(cls, s) {
+  M.perTenant[s.tenant.dbname].sent++;
+  let res;
+  if (cls === 'read') res = await opRead(s);
+  else if (cls === 'write') res = await opWrite(s);
+  else res = await opMeta(s);
+  if (res && res.skip) return;
+  if (res && res.ok) M.totals.ok++; else M.totals.err++;
+}
+
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+function scoreTokenField(name) {
+  if (/^accesstoken$/i.test(name)) return 4;
+  if (/accesstoken/i.test(name)) return 3;
+  if (/token/i.test(name)) return 2;
+  if (/jwt/i.test(name)) return 1;
+  return 0;
+}
+function findTokenSelection(index, payloadTypeName) {
+  const pt = index.get(payloadTypeName);
+  if (!pt) return null;
+  let best = null;
+  const consider = (selection, path, score) => { if (score > 0 && (!best || score > best.score)) best = { selection, path, score }; };
+  for (const f of (pt.fields || [])) {
+    const nt = index.get(unwrapType(f.type).name);
+    if (nt && nt.kind === 'SCALAR') consider(f.name, [f.name], scoreTokenField(f.name));
+  }
+  if (best && best.score >= 3) return best;
+  for (const f of (pt.fields || [])) {
+    const nt = index.get(unwrapType(f.type).name);
+    if (nt && nt.kind === 'OBJECT') {
+      for (const sf of (nt.fields || [])) {
+        const st = index.get(unwrapType(sf.type).name);
+        if (st && st.kind === 'SCALAR') consider(`${f.name} { ${sf.name} }`, [f.name, sf.name], scoreTokenField(sf.name));
+      }
+    }
+  }
+  return best;
+}
+
+const getByPath = (obj, path) => {
+  let cur = obj;
+  for (const k of path) { if (cur == null) return null; cur = cur[k]; }
+  return cur == null ? null : cur;
+};
+
+async function resolveAuthShape() {
+  for (const s of runtime) {
+    if (!s.tenant.authHost) continue;
+    const resp = await gqlFetch({ host: s.tenant.authHost, port: PORT, query: INTROSPECTION_QUERY, timeoutMs: TIMEOUT_MS });
+    const data = resp.json && resp.json.data;
+    if (!data || !data.__schema) continue;
+    const { index, mutationType } = buildTypeIndex(data);
+    if (!mutationType) continue;
+    const mt = index.get(mutationType);
+    const field = (mt.fields || []).find((f) => /^signin$/i.test(f.name)) || (mt.fields || []).find((f) => /signin/i.test(f.name));
+    if (!field) continue;
+    const tokenSel = findTokenSelection(index, unwrapType(field.type).name);
+    if (!tokenSel) continue;
+    const query = `mutation SignIn($email: String!, $password: String!) { ${field.name}(input: { email: $email, password: $password }) { ${tokenSel.selection} } }`;
+    return { field: field.name, query, path: [field.name, ...tokenSel.path], selection: tokenSel.selection };
+  }
+  // Fallback: documented shape.
+  return {
+    field: 'signIn',
+    query: 'mutation SignIn($email: String!, $password: String!) { signIn(input: { email: $email, password: $password }) { result { accessToken } } }',
+    path: ['signIn', 'result', 'accessToken'],
+    selection: 'result { accessToken }'
+  };
+}
+
+let authShape = null;
+async function loginTenant(s, initial) {
+  if (!authShape || !s.tenant.authHost) return false;
+  const resp = await gqlFetch({ host: s.tenant.authHost, port: PORT, query: authShape.query, variables: { email: EMAIL, password: PASSWORD }, timeoutMs: TIMEOUT_MS });
+  const errs = gqlErrors(resp);
+  if (!resp.ok || errs.length || resp.error) {
+    M.auth.loginFailures++;
+    s.authError = (errs[0] && errs[0].message) || resp.error || `http ${resp.status}`;
+    return false;
+  }
+  const tok = getByPath(resp.json && resp.json.data, authShape.path);
+  if (!tok || typeof tok !== 'string') { M.auth.loginFailures++; s.authError = 'no token in signIn response'; return false; }
+  s.token = tok;
+  s.tokenAt = Date.now();
+  s.authError = null;
+  if (initial) M.auth.logins++; else M.auth.relogins++;
+  return true;
+}
+
+function scheduleRelogin(s) {
+  if (s.reloginInFlight) return;
+  s.reloginInFlight = true;
+  loginTenant(s, false).catch(() => {}).finally(() => { s.reloginInFlight = false; });
+}
+
+// ---------------------------------------------------------------------------
+// Startup capability discovery (introspection + probe verification)
+// ---------------------------------------------------------------------------
+const DEFAULT_OPS = () => ({
+  read: 'categories',
+  meta: true,
+  create: { name: 'createCategory', inputTypeName: 'CreateCategoryInput', innerName: 'category', requiredScalars: [{ name: 'name', scalar: 'String', kind: 'SCALAR' }, { name: 'slug', scalar: 'String', kind: 'SCALAR' }], payloadFieldName: 'category', keySelect: 'id' },
+  del: { name: 'deleteCategory', inputTypeName: 'DeleteCategoryInput', key: 'id' }
+});
+
+const isValidationAbsent = (resp) => gqlErrors(resp).some((e) => /cannot query field|unknown field|unknown argument|unknown type|does not exist on type|not defined|no field/i.test((e && e.message) || ''));
+
+async function resolveTenantOps(s) {
+  const resp = await apiRequest(s, { query: INTROSPECTION_QUERY });
+  const data = resp.json && resp.json.data;
+  if (data && data.__schema) {
+    s.ops = discoverOps(data);
+  } else {
+    s.introspectError = (gqlErrors(resp)[0] && gqlErrors(resp)[0].message) || resp.error || `http ${resp.status}`;
+    s.ops = DEFAULT_OPS();
+  }
+  // Probe read presence (schema-level) with token so RLS doesn't mask absence.
+  if (s.ops.read) {
+    const pr = await apiRequest(s, { query: `{ ${s.ops.read} { totalCount } }`, token: s.token });
+    if (isValidationAbsent(pr)) s.ops.read = null;
+  }
+  if (s.ops.meta) {
+    const pm = await apiRequest(s, { query: '{ _meta { tables { name } } }' });
+    if (isValidationAbsent(pm)) s.ops.meta = false;
+  }
+  // Probe write: attempt a real create+delete once; downgrade only on schema absence.
+  if (canWrite(s)) {
+    const rand = `probe-${randId()}`;
+    const record = buildCreateRecord(s.ops.create, `LOAD-${rand}`, rand);
+    const cr = await apiRequest(s, { query: createQuery(s.ops.create), variables: { input: { [s.ops.create.innerName]: record } }, token: s.token });
+    if (isValidationAbsent(cr)) {
+      s.ops.create = null;
+      s.ops.del = null;
+    } else {
+      const payload = cr.json && cr.json.data && cr.json.data[s.ops.create.name];
+      const rec = payload && payload[s.ops.create.payloadFieldName];
+      const keyVal = rec && rec[s.ops.create.keySelect];
+      if (keyVal != null) {
+        await apiRequest(s, { query: deleteQuery(s.ops.del), variables: { input: { [s.ops.del.key]: keyVal } }, token: s.token });
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Bleed sentinel
+// ---------------------------------------------------------------------------
+function pickTwo(arr) {
+  if (arr.length <= 1) return arr.slice();
+  const i = Math.floor(rng() * arr.length);
+  let j = Math.floor(rng() * arr.length);
+  if (j === i) j = (j + 1) % arr.length;
+  return [arr[i], arr[j]];
+}
+
+async function runSentinel() {
+  if (stopping) return;
+  M.sentinel.checks++;
+  const eligible = runtime.filter((s) => s.ops.read && (!AUTH || s.token));
+  if (eligible.length === 0) { M.sentinel.inconclusive++; return; }
+  const picks = pickTwo(eligible);
+  for (const s of picks) {
+    M.sentinel.tenantsChecked++;
+    const resp = await apiRequest(s, { query: `{ ${s.ops.read} { nodes { name } } }`, token: s.token });
+    if (!resp.ok || gqlErrors(resp).length || resp.error) { M.sentinel.inconclusive++; continue; }
+    const nodes = (((resp.json || {}).data || {})[s.ops.read] || {}).nodes || [];
+    const own = canaryName(s.tenant);
+    let sawOwn = false;
+    for (const node of nodes) {
+      const nm = node && node.name;
+      if (typeof nm !== 'string') continue;
+      if (nm === own) { sawOwn = true; continue; }
+      if (nm.startsWith(CANARY_PREFIX)) {
+        M.sentinel.ok = false;
+        M.sentinel.violations.push({
+          at: nowIso(),
+          readTenant: s.tenant.dbname,
+          readHost: s.tenant.apiHost,
+          foreignCanary: nm,
+          sampleNames: nodes.map((n) => n && n.name).filter(Boolean).slice(0, 50)
+        });
+      }
+    }
+    if (sawOwn) M.sentinel.ownCanarySeen++;
+  }
+  if (!M.sentinel.ok) {
+    process.exitCode = 2;
+    finish('sentinel-violation');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pacer (token bucket) + worker pool
+// ---------------------------------------------------------------------------
+const zipfSampler = SHAPE === 'zipf' ? makeZipfSampler(runtime.length, rng) : null;
+let burstIndex = Math.floor(rng() * runtime.length);
+let burstUntil = Date.now() + BURST_WINDOW_SEC * 1000;
+
+function pickTenant() {
+  if (SHAPE === 'uniform') return runtime[Math.floor(rng() * runtime.length)];
+  if (SHAPE === 'burst') {
+    if (Date.now() >= burstUntil) {
+      burstIndex = Math.floor(rng() * runtime.length);
+      burstUntil = Date.now() + BURST_WINDOW_SEC * 1000;
+    }
+    return runtime[burstIndex];
+  }
+  return runtime[zipfSampler()];
+}
+
+const mixSampler = makeMixSampler(MIX, rng);
+
+let tokens = 0;
+const capacity = Math.max(RPS, 1);
+const tickMs = 20;
+const refillPerTick = RPS * (tickMs / 1000);
+
+function launchOne() {
+  inFlight++;
+  M.totals.sent++;
+  const s = pickTenant();
+  const cls = mixSampler();
+  runOp(cls, s).catch(() => {}).finally(() => {
+    inFlight--;
+    M.totals.completed++;
+    pump();
+  });
+}
+
+function pump() {
+  while (!stopping && tokens >= 1 && inFlight < MAX_INFLIGHT) {
+    tokens -= 1;
+    launchOne();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rolling per-interval reporter
+// ---------------------------------------------------------------------------
+let snap = { t: startMs, completed: 0, ok: 0, err: 0 };
+function report(kind) {
+  const nowT = Date.now();
+  const elapsedSec = (nowT - startMs) / 1000;
+  const winSec = Math.max((nowT - snap.t) / 1000, 0.001);
+  const dc = M.totals.completed - snap.completed;
+  const der = M.totals.err - snap.err;
+  const line = {
+    t: kind,
+    at: nowIso(),
+    elapsedSec: round2(elapsedSec),
+    windowSec: round2(winSec),
+    sent: M.totals.sent,
+    completed: M.totals.completed,
+    ok: M.totals.ok,
+    err: M.totals.err,
+    windowRps: round2(dc / winSec),
+    cumRps: round2(M.totals.completed / Math.max(elapsedSec, 0.001)),
+    windowErrRate: dc ? round2(der / dc) : 0,
+    inFlight,
+    dropped: Math.round(M.totals.dropped),
+    rotating: M.totals.rotating,
+    latencyWindow: windowHist.summary(),
+    sentinelChecks: M.sentinel.checks,
+    sentinelOwnSeen: M.sentinel.ownCanarySeen,
+    sentinelOk: M.sentinel.ok
+  };
+  emit(line);
+  M.progress.push(line);
+  snap = { t: nowT, completed: M.totals.completed, ok: M.totals.ok, err: M.totals.err };
+  windowHist = new Histogram();
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle
+// ---------------------------------------------------------------------------
+let timers = [];
+let durationTimer = null;
+let donePromiseResolve;
+const donePromise = new Promise((res) => { donePromiseResolve = res; });
+
+function finish(reason) {
+  if (stopping) return;
+  stopping = true;
+  stopReason = reason;
+  for (const t of timers) clearInterval(t);
+  timers = [];
+  if (durationTimer) { clearTimeout(durationTimer); durationTimer = null; }
+  donePromiseResolve();
+}
+
+async function drain() {
+  const deadline = Date.now() + 15000;
+  while (inFlight > 0 && Date.now() < deadline) await sleep(50);
+}
+
+function finalize() {
+  const endMs = Date.now();
+  const wallSec = (endMs - startMs) / 1000;
+  const loadSec = (endMs - (pacingStartMs || startMs)) / 1000;
+  const topN = (obj, n = 20) => Object.entries(obj).sort((a, b) => b[1] - a[1]).slice(0, n).map(([k, v]) => ({ key: k, count: v }));
+  const classSummary = (c) => {
+    const base = { sent: c.sent, ok: c.ok, err: c.err, unavailable: c.unavailable, latency: c.hist.summary() };
+    if (c === M.classes.write) {
+      return { ...base, created: c.created, deleted: c.deleted, leaked: c.leaked, createErr: c.createErr, deleteErr: c.deleteErr, fallbackRead: c.fallbackRead };
+    }
+    return base;
+  };
+  const out = {
+    startedAt: M.startedAt,
+    endedAt: nowIso(),
+    wallSec: round2(wallSec),
+    loadSec: round2(loadSec),
+    stopReason,
+    config: M.config,
+    fleet: { count: tenants.length, file: args.fleet },
+    capabilities: runtime.map((s) => ({
+      dbname: s.tenant.dbname,
+      apiHost: s.tenant.apiHost,
+      read: !!s.ops.read,
+      write: canWrite(s),
+      meta: !!s.ops.meta,
+      authed: !!s.token,
+      authError: s.authError,
+      introspectError: s.introspectError,
+      leakedKeys: s.leakedKeys.length
+    })),
+    totals: {
+      ...M.totals,
+      dropped: Math.round(M.totals.dropped),
+      achievedRps: round2(M.totals.completed / Math.max(loadSec, 0.001)),
+      errRate: M.totals.completed ? round2(M.totals.err / M.totals.completed) : 0
+    },
+    latencyOverall: M.overallHist.summary(),
+    byClass: { read: classSummary(M.classes.read), write: classSummary(M.classes.write), meta: classSummary(M.classes.meta) },
+    http: M.http,
+    netErrors: M.netErrors,
+    gqlErrorsByCode: M.gqlByCode,
+    gqlErrorsTop: topN(M.gqlByMsg),
+    gqlErrorsMsgOverflow: M.gqlMsgOverflow,
+    perTenant: M.perTenant,
+    auth: M.auth,
+    sentinel: M.sentinel,
+    progress: M.progress,
+    verdict: {
+      pass: M.sentinel.ok,
+      bleedViolations: M.sentinel.violations.length,
+      note: M.sentinel.ok ? 'no cross-tenant bleed detected' : 'BLEED SENTINEL VIOLATION'
+    }
+  };
+  fs.writeFileSync(OUT, `${JSON.stringify(out, null, 2)}\n`);
+  return out;
+}
+
+async function main() {
+  log(`[harness] seed=${SEED} shape=${SHAPE} rps=${RPS} dur=${DURATION_SEC}s mix=${MIX} auth=${AUTH} tenants=${tenants.length} -> ${OUT}`);
+
+  if (AUTH) {
+    authShape = await resolveAuthShape();
+    M.auth.shape = authShape.selection;
+    log(`[harness] auth shape: ${authShape.field} { ${authShape.selection} }`);
+    await Promise.all(runtime.map((s) => loginTenant(s, true)));
+    log(`[harness] logins ok=${M.auth.logins} failed=${M.auth.loginFailures}`);
+  }
+
+  await Promise.all(runtime.map((s) => resolveTenantOps(s).catch((e) => { s.introspectError = String(e && e.message || e); })));
+  const caps = runtime.map((s) => `${s.tenant.dbname.replace('marketplace_db_', '')}[r=${s.ops.read ? 1 : 0}w=${canWrite(s) ? 1 : 0}m=${s.ops.meta ? 1 : 0}${s.token ? 'a' : ''}]`);
+  log(`[harness] capabilities: ${caps.join(' ')}`);
+
+  // Timers
+  pacingStartMs = Date.now();
+  snap = { t: pacingStartMs, completed: 0, ok: 0, err: 0 };
+  timers.push(setInterval(() => {
+    if (stopping) return;
+    tokens += refillPerTick;
+    if (tokens > capacity) { M.totals.dropped += (tokens - capacity); tokens = capacity; }
+    pump();
+  }, tickMs));
+  timers.push(setInterval(() => report('progress'), REPORT_SEC * 1000));
+  timers.push(setInterval(() => { runSentinel().catch(() => {}); }, SENTINEL_SEC * 1000));
+  timers.push(setInterval(() => {
+    if (!AUTH) return;
+    const cutoff = Date.now() - RELOGIN_SEC * 1000;
+    for (const s of runtime) if (s.token && s.tokenAt < cutoff) scheduleRelogin(s);
+  }, 30000));
+
+  durationTimer = setTimeout(() => finish('duration'), DURATION_SEC * 1000);
+  const onSig = () => finish('signal');
+  process.on('SIGINT', onSig);
+  process.on('SIGTERM', onSig);
+
+  await donePromise;
+  await drain();
+  const out = finalize();
+
+  const c = out.byClass;
+  log(`[harness] DONE reason=${stopReason} wall=${out.wallSec}s load=${out.loadSec}s completed=${out.totals.completed} ok=${out.totals.ok} err=${out.totals.err} achievedRps=${out.totals.achievedRps} p50=${out.latencyOverall.p50} p95=${out.latencyOverall.p95} p99=${out.latencyOverall.p99}`);
+  log(`[harness] read ${c.read.ok}/${c.read.err} write ${c.write.ok}/${c.write.err}(created=${c.write.created} leaked=${c.write.leaked}) meta ${c.meta.ok}/${c.meta.err} | sentinel checks=${M.sentinel.checks} ownSeen=${M.sentinel.ownCanarySeen} violations=${M.sentinel.violations.length}`);
+  log(`[harness] wrote ${OUT}`);
+  if (!M.sentinel.ok) log('[harness] *** BLEED SENTINEL VIOLATION — exit 2 ***');
+}
+
+main().catch((err) => {
+  process.stderr.write(`[harness] FATAL: ${err && err.stack ? err.stack : err}\n`);
+  try { finalize(); } catch {}
+  process.exitCode = process.exitCode || 1;
+});
diff --git a/scripts/scale-validate/measure-instance-heap.mjs b/scripts/scale-validate/measure-instance-heap.mjs
new file mode 100644
index 0000000000..c0858f5ccf
--- /dev/null
+++ b/scripts/scale-validate/measure-instance-heap.mjs
@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+// =============================================================================
+// measure-instance-heap.mjs — per-class instance heap cost (V2 sizing input)
+//
+// Boots a FRESH cnc server (own child process, own metrics file), waits for the
+// metrics sampler baseline, cold-builds exactly ONE instance class by hitting a
+// single virtual host, lets the heap settle, and records the delta. Because the
+// server is fresh and only one host is ever hit, the delta IS the marginal cost
+// of the first resident instance of that class (instance + its share of lazily
+// initialized caches).
+//
+// Usage:
+//   node scripts/scale-validate/measure-instance-heap.mjs \
+//     --label tenant-api --host api-factory1-26c6da94.localhost \
+//     [--port 3344] [--heap-mb 2048] [--cache-max 1] [--settle-sec 70] \
+//     [--out scripts/scale-validate/out/instance-heap.jsonl]
+//
+// Env: PGHOST PGPORT PGUSER PGPASSWORD PGDATABASE (defaults :5433 constructive)
+// =============================================================================
+import { spawn } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WORKTREE = path.resolve(__dirname, '..', '..');
+
+const arg = (name, dflt) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 ? process.argv[i + 1] : dflt;
+};
+const LABEL = arg('label', 'unlabeled');
+const HOST = arg('host', null);
+const PORT = parseInt(arg('port', '3344'), 10);
+const HEAP_MB = parseInt(arg('heap-mb', '2048'), 10);
+const CACHE_MAX = arg('cache-max', '1');
+const SETTLE_SEC = parseInt(arg('settle-sec', '70'), 10);
+const OUT = path.resolve(WORKTREE, arg('out', 'scripts/scale-validate/out/instance-heap.jsonl'));
+if (!HOST) {
+  console.error('--host is required');
+  process.exit(1);
+}
+
+const METRICS_FILE = path.resolve(
+  WORKTREE,
+  'scripts/scale-validate/out',
+  `metrics-cap1-${LABEL}.jsonl`
+);
+mkdirSync(path.dirname(METRICS_FILE), { recursive: true });
+if (existsSync(METRICS_FILE)) rmSync(METRICS_FILE);
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const MB = (b) => Math.round((b / 1024 / 1024) * 10) / 10;
+
+function readMetrics() {
+  if (!existsSync(METRICS_FILE)) return [];
+  return readFileSync(METRICS_FILE, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function waitForPort(port, timeoutMs) {
+  // The server binds "localhost", which on macOS may resolve to ::1 only —
+  // probe both families.
+  const hosts = ['127.0.0.1', '::1'];
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve, reject) => {
+    let i = 0;
+    const tryOnce = () => {
+      const host = hosts[i++ % hosts.length];
+      const sock = net.connect({ host, port }, () => {
+        sock.destroy();
+        resolve();
+      });
+      sock.on('error', () => {
+        sock.destroy();
+        if (Date.now() > deadline) reject(new Error(`port ${port} not listening after ${timeoutMs}ms`));
+        else setTimeout(tryOnce, 300);
+      });
+    };
+    tryOnce();
+  });
+}
+
+async function gql(host, port, timeoutMs) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  const start = performance.now();
+  try {
+    const res = await fetch(`http://${host}:${port}/graphql`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify({ query: 'query { __typename }' }),
+      signal: ac.signal
+    });
+    const body = await res.text();
+    return { status: res.status, ms: Math.round(performance.now() - start), body: body.slice(0, 200) };
+  } catch (e) {
+    return { status: 0, ms: Math.round(performance.now() - start), body: String(e).slice(0, 200) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const main = async () => {
+  console.log(`[${LABEL}] starting server port=${PORT} heap=${HEAP_MB}MB cacheMax=${CACHE_MAX} host=${HOST}`);
+  const child = spawn(
+    'node',
+    [
+      'packages/cli/dist/index.js',
+      'server',
+      '--port',
+      String(PORT),
+      '--origin',
+      '*',
+      '--simpleInflection',
+      '--postgis',
+      '--servicesApi'
+    ],
+    {
+      cwd: WORKTREE,
+      env: {
+        ...process.env,
+        NODE_ENV: 'production',
+        NODE_OPTIONS: `--max-old-space-size=${HEAP_MB}`,
+        GRAPHILE_DEBUG_METRICS: '1',
+        GRAPHILE_DEBUG_METRICS_FILE: METRICS_FILE,
+        GRAPHILE_BLUEPRINT_POOLING: '1',
+        GRAPHILE_CACHE_MAX: CACHE_MAX,
+        PGHOST: process.env.PGHOST || 'localhost',
+        PGPORT: process.env.PGPORT || '5433',
+        PGUSER: process.env.PGUSER || 'postgres',
+        PGPASSWORD: process.env.PGPASSWORD || 'password',
+        PGDATABASE: process.env.PGDATABASE || 'constructive'
+      },
+      stdio: ['ignore', 'pipe', 'pipe']
+    }
+  );
+  let serverLog = '';
+  child.stdout.on('data', (d) => (serverLog += d));
+  child.stderr.on('data', (d) => (serverLog += d));
+  let exited = false;
+  child.on('exit', () => (exited = true));
+
+  const result = { label: LABEL, host: HOST, heapMb: HEAP_MB, cacheMax: CACHE_MAX, ok: false };
+  try {
+    await waitForPort(PORT, 120000);
+    console.log(`[${LABEL}] listening; waiting for baseline metrics...`);
+
+    // Baseline: at least 2 sampler lines (20s) so init transients are past.
+    let m = [];
+    const baseDeadline = Date.now() + 90000;
+    while (Date.now() < baseDeadline) {
+      m = readMetrics();
+      if (m.length >= 2) break;
+      await sleep(2000);
+    }
+    if (m.length < 2) throw new Error(`no metrics baseline (${m.length} lines): sampler not writing?`);
+    const baseline = m[m.length - 1];
+    const baselineCount = m.length;
+    result.baseline = { heapUsedMB: MB(baseline.heapUsed), rssMB: MB(baseline.rss) };
+    console.log(`[${LABEL}] baseline heapUsed=${result.baseline.heapUsedMB}MB rss=${result.baseline.rssMB}MB`);
+
+    // Cold build: first request to this host builds the instance.
+    const cold = await gql(HOST, PORT, 420000);
+    result.cold = cold;
+    console.log(`[${LABEL}] cold request: status=${cold.status} ${cold.ms}ms ${cold.body}`);
+    if (cold.status !== 200) throw new Error(`cold request failed: ${cold.status} ${cold.body}`);
+
+    // Settle and sample.
+    const targetLines = baselineCount + Math.ceil(SETTLE_SEC / 10);
+    const settleDeadline = Date.now() + SETTLE_SEC * 1000 + 60000;
+    while (Date.now() < settleDeadline) {
+      m = readMetrics();
+      if (m.length >= targetLines) break;
+      await sleep(5000);
+    }
+    const post = m.slice(baselineCount);
+    if (post.length === 0) throw new Error('no post-build metrics samples');
+    const last = post[post.length - 1];
+    const heaps = post.map((x) => x.heapUsed);
+    const rsss = post.map((x) => x.rss);
+    result.postBuild = {
+      samples: post.length,
+      heapUsedLastMB: MB(last.heapUsed),
+      heapUsedMinMB: MB(Math.min(...heaps)),
+      heapUsedMaxMB: MB(Math.max(...heaps)),
+      rssLastMB: MB(last.rss),
+      rssMaxMB: MB(Math.max(...rsss)),
+      cache: last.cache,
+      counters: last.counters
+    };
+    result.deltaHeapMB = Math.round((result.postBuild.heapUsedLastMB - result.baseline.heapUsedMB) * 10) / 10;
+    result.deltaRssMB = Math.round((result.postBuild.rssLastMB - result.baseline.rssMB) * 10) / 10;
+
+    // Warm request: instance resident, should be fast.
+    const warm = await gql(HOST, PORT, 30000);
+    result.warm = { status: warm.status, ms: warm.ms };
+    result.ok = warm.status === 200;
+    console.log(
+      `[${LABEL}] deltaHeap=${result.deltaHeapMB}MB deltaRss=${result.deltaRssMB}MB ` +
+        `(post last=${result.postBuild.heapUsedLastMB}MB min=${result.postBuild.heapUsedMinMB}MB ` +
+        `max=${result.postBuild.heapUsedMaxMB}MB) warm=${warm.ms}ms`
+    );
+  } catch (e) {
+    result.error = String(e && e.message ? e.message : e);
+    result.serverLogTail = serverLog.slice(-1500);
+    console.error(`[${LABEL}] FAILED: ${result.error}`);
+  } finally {
+    if (!exited) {
+      child.kill('SIGTERM');
+      const killDeadline = Date.now() + 15000;
+      while (!exited && Date.now() < killDeadline) await sleep(500);
+      if (!exited) child.kill('SIGKILL');
+    }
+  }
+
+  appendFileSync(OUT, JSON.stringify(result) + '\n');
+  console.log(`[${LABEL}] result appended to ${OUT}`);
+  if (!result.ok) process.exitCode = 1;
+};
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
diff --git a/scripts/scale-validate/pg-sampler.mjs b/scripts/scale-validate/pg-sampler.mjs
new file mode 100644
index 0000000000..c84ffc3bb5
--- /dev/null
+++ b/scripts/scale-validate/pg-sampler.mjs
@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * pg-sampler.mjs — PG-side time series for perf runs (the node side is covered
+ * by the server's GRAPHILE_DEBUG_METRICS JSONL; this captures the Postgres half).
+ *
+ * Every --interval-sec appends one JSONL line to --out with:
+ *   - docker container memory (usage/limit bytes) for --container
+ *   - pg_stat_activity backend counts by state (+ total)
+ *   - pg_class row count (catalog size proxy) and current database size
+ *
+ * Connection: standard PG* env vars (or --pg-* flags via pgConfigFromArgs).
+ * A FRESH client per sample (rig runs idle_session_timeout=120s; a persistent
+ * idle client would be reaped mid-run). Sampling errors are recorded on the
+ * line ({err}) and never kill the sampler — a PG crash/recovery window is
+ * exactly the data we want to keep collecting through.
+ *
+ * Exit: --duration-sec elapsed, or SIGINT/SIGTERM (JSONL is append-per-line,
+ * nothing to flush).
+ */
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { asInt, nowIso, parseArgs, pgConfigFromArgs, resolvePg, sleep } from './_lib.mjs';
+
+const { args } = parseArgs(process.argv.slice(2));
+if (args.help) {
+  console.log(`usage: node pg-sampler.mjs [--out out/pg-soak.jsonl] [--interval-sec 30]
+       [--duration-sec 0=until signal] [--container constructive-scale-pg]
+       PG* env / --pg-* flags        connection overrides`);
+  process.exit(0);
+}
+
+const OUT = args.out || 'out/pg-soak.jsonl';
+const INTERVAL_SEC = asInt(args['interval-sec'], 30);
+const DURATION_SEC = asInt(args['duration-sec'], 0);
+const CONTAINER = args.container || 'constructive-scale-pg';
+
+const { Client } = resolvePg();
+const pgConfig = pgConfigFromArgs(args);
+
+fs.mkdirSync(path.dirname(OUT), { recursive: true });
+
+let stopping = false;
+process.on('SIGINT', () => { stopping = true; });
+process.on('SIGTERM', () => { stopping = true; });
+
+function dockerMem(name) {
+  return new Promise((resolve) => {
+    execFile('docker', ['stats', '--no-stream', '--format', '{{.MemUsage}}', name],
+      { timeout: 10_000 }, (err, stdout) => {
+        if (err) return resolve({ err: String(err.message || err).slice(0, 200) });
+        // e.g. "1.234GiB / 4GiB"
+        const m = String(stdout).trim();
+        const toBytes = (s) => {
+          const mm = /([\d.]+)\s*(B|KiB|MiB|GiB)/.exec(s);
+          if (!mm) return null;
+          const mult = { B: 1, KiB: 1024, MiB: 1024 ** 2, GiB: 1024 ** 3 }[mm[2]];
+          return Math.round(parseFloat(mm[1]) * mult);
+        };
+        const [used, limit] = m.split('/').map((s) => toBytes(s));
+        resolve({ raw: m, usedBytes: used, limitBytes: limit });
+      });
+  });
+}
+
+async function pgSample() {
+  const client = new Client(pgConfig);
+  try {
+    await client.connect();
+    // sequential on purpose: pg queues concurrent query() on one client (deprecated)
+    const act = await client.query('SELECT COALESCE(state, \'null\') AS state, count(*)::int AS n FROM pg_stat_activity GROUP BY 1');
+    const cls = await client.query('SELECT count(*)::int AS n FROM pg_class');
+    const size = await client.query('SELECT pg_database_size(current_database())::bigint AS b, (SELECT sum(numbackends)::int FROM pg_stat_database) AS backends');
+    const byState = {};
+    let total = 0;
+    for (const r of act.rows) { byState[r.state] = r.n; total += r.n; }
+    return {
+      backendsByState: byState,
+      backendsTotal: total,
+      backendsAllDbs: size.rows[0].backends,
+      pgClassRows: cls.rows[0].n,
+      dbSizeBytes: Number(size.rows[0].b)
+    };
+  } finally {
+    try { await client.end(); } catch { /* recovery window; line already has data or err */ }
+  }
+}
+
+const startMs = Date.now();
+console.log(`[pg-sampler] out=${OUT} interval=${INTERVAL_SEC}s duration=${DURATION_SEC || 'until-signal'}s container=${CONTAINER} pg=${pgConfig.host}:${pgConfig.port}/${pgConfig.database}`);
+
+for (;;) {
+  if (stopping) break;
+  if (DURATION_SEC && (Date.now() - startMs) / 1000 >= DURATION_SEC) break;
+  const line = { t: nowIso() };
+  try {
+    line.docker = await dockerMem(CONTAINER);
+  } catch (e) {
+    line.docker = { err: String(e.message || e).slice(0, 200) };
+  }
+  try {
+    Object.assign(line, await pgSample());
+  } catch (e) {
+    line.err = String(e.message || e).slice(0, 200);
+  }
+  fs.appendFileSync(OUT, `${JSON.stringify(line)}\n`);
+  // sleep in small slices so signals stay responsive
+  const until = Date.now() + INTERVAL_SEC * 1000;
+  while (Date.now() < until && !stopping) await sleep(500);
+}
+console.log('[pg-sampler] done');
diff --git a/scripts/scale-validate/plans/v2-1152.json b/scripts/scale-validate/plans/v2-1152.json
new file mode 100644
index 0000000000..61b9f38190
--- /dev/null
+++ b/scripts/scale-validate/plans/v2-1152.json
@@ -0,0 +1,13 @@
+{
+  "port": 3345,
+  "defaults": {
+    "heapMb": 1152,
+    "rps": 10,
+    "durationSec": 300,
+    "shape": "uniform",
+    "auth": 1,
+    "mix": "read:0.7,write:0.25,meta:0.05",
+    "serverEnv": { "GRAPHILE_CACHE_INSTANCE_HEAP_BYTES": "1450000000" }
+  },
+  "steps": [{ "name": "floor-div-k1", "fleet": "out/fleet-k1.json" }]
+}
diff --git a/scripts/scale-validate/plans/v2-1536.json b/scripts/scale-validate/plans/v2-1536.json
new file mode 100644
index 0000000000..f769e579c4
--- /dev/null
+++ b/scripts/scale-validate/plans/v2-1536.json
@@ -0,0 +1,13 @@
+{
+  "port": 3345,
+  "defaults": {
+    "heapMb": 1536,
+    "rps": 10,
+    "durationSec": 300,
+    "shape": "uniform",
+    "auth": 1,
+    "mix": "read:0.7,write:0.25,meta:0.05",
+    "serverEnv": { "GRAPHILE_CACHE_INSTANCE_HEAP_BYTES": "1450000000" }
+  },
+  "steps": [{ "name": "floor-div-k1", "fleet": "out/fleet-k1.json" }]
+}
diff --git a/scripts/scale-validate/plans/v2-2048-rps-single.json b/scripts/scale-validate/plans/v2-2048-rps-single.json
new file mode 100644
index 0000000000..933ec0d6cb
--- /dev/null
+++ b/scripts/scale-validate/plans/v2-2048-rps-single.json
@@ -0,0 +1,16 @@
+{
+  "port": 3345,
+  "defaults": {
+    "heapMb": 2048,
+    "durationSec": 300,
+    "shape": "zipf",
+    "auth": 1,
+    "mix": "read:0.7,write:0.25,meta:0.05",
+    "serverEnv": { "GRAPHILE_CACHE_INSTANCE_HEAP_BYTES": "1450000000" }
+  },
+  "steps": [
+    { "name": "rps-s-50", "fleet": "out/fleet-t33.json", "rps": 50 },
+    { "name": "rps-s-100", "fleet": "out/fleet-t33.json", "rps": 100 },
+    { "name": "rps-s-200", "fleet": "out/fleet-t33.json", "rps": 200 }
+  ]
+}
diff --git a/scripts/scale-validate/plans/v2-2048-tuned.json b/scripts/scale-validate/plans/v2-2048-tuned.json
new file mode 100644
index 0000000000..f61948de68
--- /dev/null
+++ b/scripts/scale-validate/plans/v2-2048-tuned.json
@@ -0,0 +1,26 @@
+{
+  "port": 3345,
+  "defaults": {
+    "heapMb": 2048,
+    "rps": 10,
+    "durationSec": 480,
+    "shape": "uniform",
+    "auth": 1,
+    "mix": "read:0.7,write:0.25,meta:0.05",
+    "serverEnv": { "GRAPHILE_CACHE_INSTANCE_HEAP_BYTES": "1450000000" }
+  },
+  "steps": [
+    { "name": "tuned-div-k1", "fleet": "out/fleet-k1.json" },
+    { "name": "tuned-div-k2", "fleet": "out/fleet-k2.json" },
+    { "name": "tuned-div-k3", "fleet": "out/fleet-k3.json" },
+    { "name": "tuned-div-k5", "fleet": "out/fleet-k5.json" },
+    { "name": "tuned-ten-10", "fleet": "out/fleet-t10.json", "shape": "zipf", "rps": 15 },
+    { "name": "tuned-ten-20", "fleet": "out/fleet-t20.json", "shape": "zipf", "rps": 15 },
+    { "name": "tuned-ten-33", "fleet": "out/fleet-t33.json", "shape": "zipf", "rps": 15 },
+    { "name": "tuned-rps-10", "fleet": "fleet.json", "shape": "zipf", "rps": 10, "durationSec": 300 },
+    { "name": "tuned-rps-25", "fleet": "fleet.json", "shape": "zipf", "rps": 25, "durationSec": 300 },
+    { "name": "tuned-rps-50", "fleet": "fleet.json", "shape": "zipf", "rps": 50, "durationSec": 300 },
+    { "name": "tuned-rps-100", "fleet": "fleet.json", "shape": "zipf", "rps": 100, "durationSec": 300 },
+    { "name": "tuned-cold-burst", "fleet": "out/fleet-burst.json", "coldBurst": true }
+  ]
+}
diff --git a/scripts/scale-validate/plans/v2-2048.json b/scripts/scale-validate/plans/v2-2048.json
new file mode 100644
index 0000000000..b2143c9226
--- /dev/null
+++ b/scripts/scale-validate/plans/v2-2048.json
@@ -0,0 +1,25 @@
+{
+  "port": 3345,
+  "defaults": {
+    "heapMb": 2048,
+    "rps": 10,
+    "durationSec": 480,
+    "shape": "uniform",
+    "auth": 1,
+    "mix": "read:0.7,write:0.25,meta:0.05"
+  },
+  "steps": [
+    { "name": "div-k1", "fleet": "out/fleet-k1.json" },
+    { "name": "div-k2", "fleet": "out/fleet-k2.json" },
+    { "name": "div-k3", "fleet": "out/fleet-k3.json" },
+    { "name": "div-k5", "fleet": "out/fleet-k5.json" },
+    { "name": "ten-10", "fleet": "out/fleet-t10.json", "shape": "zipf", "rps": 15 },
+    { "name": "ten-20", "fleet": "out/fleet-t20.json", "shape": "zipf", "rps": 15 },
+    { "name": "ten-33", "fleet": "out/fleet-t33.json", "shape": "zipf", "rps": 15 },
+    { "name": "rps-10", "fleet": "fleet.json", "shape": "zipf", "rps": 10, "durationSec": 300 },
+    { "name": "rps-25", "fleet": "fleet.json", "shape": "zipf", "rps": 25, "durationSec": 300 },
+    { "name": "rps-50", "fleet": "fleet.json", "shape": "zipf", "rps": 50, "durationSec": 300 },
+    { "name": "rps-100", "fleet": "fleet.json", "shape": "zipf", "rps": 100, "durationSec": 300 },
+    { "name": "cold-burst", "fleet": "out/fleet-burst.json", "coldBurst": true }
+  ]
+}
diff --git a/scripts/scale-validate/plans/v2-3584-r2.json b/scripts/scale-validate/plans/v2-3584-r2.json
new file mode 100644
index 0000000000..1139c279c8
--- /dev/null
+++ b/scripts/scale-validate/plans/v2-3584-r2.json
@@ -0,0 +1,13 @@
+{
+  "port": 3345,
+  "defaults": {
+    "heapMb": 3584,
+    "rps": 10,
+    "durationSec": 420,
+    "shape": "uniform",
+    "auth": 1,
+    "mix": "read:0.7,write:0.25,meta:0.05",
+    "serverEnv": { "GRAPHILE_CACHE_INSTANCE_HEAP_BYTES": "896000000" }
+  },
+  "steps": [{ "name": "r2-div-k1", "fleet": "out/fleet-k1.json" }]
+}
diff --git a/scripts/scale-validate/plans/v2-3584.json b/scripts/scale-validate/plans/v2-3584.json
new file mode 100644
index 0000000000..892ef2d0f7
--- /dev/null
+++ b/scripts/scale-validate/plans/v2-3584.json
@@ -0,0 +1,19 @@
+{
+  "port": 3345,
+  "defaults": {
+    "heapMb": 3584,
+    "rps": 10,
+    "durationSec": 420,
+    "shape": "uniform",
+    "auth": 1,
+    "mix": "read:0.7,write:0.25,meta:0.05",
+    "serverEnv": { "GRAPHILE_CACHE_INSTANCE_HEAP_BYTES": "1450000000" }
+  },
+  "steps": [
+    { "name": "big-div-k1", "fleet": "out/fleet-k1.json" },
+    { "name": "big-div-k3", "fleet": "out/fleet-k3.json" },
+    { "name": "big-div-k5", "fleet": "out/fleet-k5.json" },
+    { "name": "big-ten-10", "fleet": "out/fleet-t10.json", "shape": "zipf", "rps": 15 },
+    { "name": "big-ten-33", "fleet": "out/fleet-t33.json", "shape": "zipf", "rps": 15 }
+  ]
+}
diff --git a/scripts/scale-validate/plans/v2-896.json b/scripts/scale-validate/plans/v2-896.json
new file mode 100644
index 0000000000..f85f03360b
--- /dev/null
+++ b/scripts/scale-validate/plans/v2-896.json
@@ -0,0 +1,13 @@
+{
+  "port": 3345,
+  "defaults": {
+    "heapMb": 896,
+    "rps": 10,
+    "durationSec": 300,
+    "shape": "uniform",
+    "auth": 1,
+    "mix": "read:0.7,write:0.25,meta:0.05",
+    "serverEnv": { "GRAPHILE_CACHE_INSTANCE_HEAP_BYTES": "1450000000" }
+  },
+  "steps": [{ "name": "floor-div-k1", "fleet": "out/fleet-k1.json" }]
+}
diff --git a/scripts/scale-validate/soak-ops.mjs b/scripts/scale-validate/soak-ops.mjs
new file mode 100644
index 0000000000..6114d9509c
--- /dev/null
+++ b/scripts/scale-validate/soak-ops.mjs
@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// =============================================================================
+// soak-ops.mjs — V3 soak operations churn: cycle tenant provisioning/teardown.
+//
+// Every --interval-sec: provision ONE new tenant (tenant-factory, own prefix),
+// then drop the tenant created by the PREVIOUS cycle. Net effect: the soak
+// continuously exercises the full provision + teardown paths (catalog writes,
+// schema:update NOTIFY -> flush -> rebuild on next hit) WITHOUT net catalog
+// growth — important because instance heap scales ~21KB/pg_class row, so
+// unbounded provisioning would inflate the resident instance past a 2GB heap
+// mid-soak and turn a longevity test into a slow OOM test.
+//
+// Usage:
+//   node scripts/scale-validate/soak-ops.mjs --interval-sec 7200 \
+//     --duration-sec 86400 [--prefix soak]
+// Env: PGHOST PGPORT PGUSER PGPASSWORD PGDATABASE (defaults :5433 constructive)
+// =============================================================================
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const arg = (name, dflt) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 ? process.argv[i + 1] : dflt;
+};
+const INTERVAL_SEC = parseInt(arg('interval-sec', '7200'), 10);
+const DURATION_SEC = parseInt(arg('duration-sec', '86400'), 10);
+const PREFIX = arg('prefix', 'soak');
+
+const run = (script, args) => {
+  const res = spawnSync('node', [path.join(__dirname, script), ...args], {
+    env: process.env,
+    encoding: 'utf8',
+    timeout: 30 * 60 * 1000
+  });
+  const out = `${res.stdout || ''}${res.stderr || ''}`;
+  return { status: res.status, out, tail: out.split('\n').filter(Boolean).slice(-3).join(' | ') };
+};
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const now = () => new Date().toISOString();
+
+const main = async () => {
+  const deadline = Date.now() + DURATION_SEC * 1000;
+  let cycle = 0;
+  let previousName = null;
+
+  console.log(`[soak-ops] ${now()} start: interval=${INTERVAL_SEC}s duration=${DURATION_SEC}s prefix=${PREFIX}`);
+
+  while (Date.now() < deadline) {
+    cycle++;
+    const t0 = Date.now();
+
+    const create = run('tenant-factory.mjs', ['--count', '1', '--prefix', PREFIX, '--blueprint', 'marketplace']);
+    // tenant-factory auto-picks the next free index; recover the name it made.
+    const m = /\[(\w+)\] OK db=/.exec(create.out) || /indices=(\d+)\.\./.exec(create.out);
+    const createdName = m ? (m[1].startsWith(PREFIX) ? m[1] : `${PREFIX}${m[1]}`) : null;
+    console.log(
+      `[soak-ops] ${now()} cycle=${cycle} provision status=${create.status} created=${createdName || '?'} :: ${create.tail}`
+    );
+
+    if (previousName) {
+      const drop = run('drop-tenants.mjs', ['--only', previousName]);
+      console.log(`[soak-ops] ${now()} cycle=${cycle} drop ${previousName} status=${drop.status} :: ${drop.tail}`);
+    }
+    previousName = createdName || previousName;
+
+    const elapsed = Date.now() - t0;
+    const wait = Math.max(0, INTERVAL_SEC * 1000 - elapsed);
+    if (Date.now() + wait >= deadline) break;
+    await sleep(wait);
+  }
+
+  // Final cleanup: drop the last soak tenant so the fleet is back to baseline.
+  if (previousName) {
+    const drop = run('drop-tenants.mjs', ['--only', previousName]);
+    console.log(`[soak-ops] ${now()} final cleanup ${previousName} status=${drop.status}`);
+  }
+  console.log(`[soak-ops] ${now()} done after ${cycle} cycles`);
+};
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
diff --git a/scripts/scale-validate/subset-fleet.mjs b/scripts/scale-validate/subset-fleet.mjs
new file mode 100644
index 0000000000..9c1e2af2ad
--- /dev/null
+++ b/scripts/scale-validate/subset-fleet.mjs
@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// =============================================================================
+// subset-fleet.mjs — derive ramp-specific fleet manifests from fleet.json +
+// drifted.json (V2 limits discovery).
+//
+// Blueprint groups: group 0 = undrifted tenants (majority blueprint; includes
+// column-drift tenants — same relname set => same blueprint), groups 1..K =
+// drift_marker_g<g> table-drift groups from drift-tenants.mjs.
+//
+// Modes:
+//   --blueprints K --per-blueprint N   diversity subset: first K groups
+//                                      (0,1,2,...), N tenants from each →
+//                                      K distinct blueprints, K*N tenants.
+//   --tenants N                        tenant-count subset: N undrifted
+//                                      (group-0) tenants → 1 blueprint.
+//
+// Usage:
+//   node scripts/scale-validate/subset-fleet.mjs --fleet fleet.json \
+//     --drifted drifted.json --blueprints 3 --per-blueprint 5 --out out/fleet-k3.json
+//   node scripts/scale-validate/subset-fleet.mjs --fleet fleet.json \
+//     --drifted drifted.json --tenants 50 --out out/fleet-t50.json
+// =============================================================================
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const arg = (name, dflt) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 ? process.argv[i + 1] : dflt;
+};
+
+const FLEET = path.resolve(__dirname, arg('fleet', 'fleet.json'));
+const DRIFTED = path.resolve(__dirname, arg('drifted', 'drifted.json'));
+const BLUEPRINTS = parseInt(arg('blueprints', '0'), 10);
+const PER_BLUEPRINT = parseInt(arg('per-blueprint', '5'), 10);
+const TENANTS = parseInt(arg('tenants', '0'), 10);
+const OUT = path.resolve(__dirname, arg('out', ''));
+if (!OUT || OUT === __dirname) {
+  console.error('--out is required');
+  process.exit(1);
+}
+
+const fleet = JSON.parse(fs.readFileSync(FLEET, 'utf8'));
+const drifted = JSON.parse(fs.readFileSync(DRIFTED, 'utf8'));
+const all = fleet.tenants;
+const byName = new Map(all.map((t) => [t.dbname, t]));
+
+const driftedNames = new Set();
+for (const names of Object.values(drifted.groups || {})) names.forEach((n) => driftedNames.add(n));
+
+// group 0 = the KNOWN-identical blueprint pool, minus table-drifted tenants.
+// Factory tenants are clones of marketplace_db_tenant1 (fingerprint-validated);
+// other seeder tenants (tenant2...) have DIVERGENT shapes — never group 0.
+// Column-drift tenants keep their relname set => still the same blueprint.
+const SAME_BP_RE = new RegExp(arg('same-bp-regex', '^(factory[0-9]+|marketplace_db_tenant1)$'));
+const group0 = all
+  .filter((t) => SAME_BP_RE.test(t.dbname) && !driftedNames.has(t.dbname))
+  .map((t) => t.dbname);
+const groups = [group0];
+for (const g of Object.keys(drifted.groups || {}).sort((a, b) => Number(a) - Number(b))) {
+  groups.push(drifted.groups[g]);
+}
+
+let picked = [];
+let label = '';
+if (BLUEPRINTS > 0) {
+  if (BLUEPRINTS > groups.length) {
+    console.error(`only ${groups.length} blueprint groups available, asked for ${BLUEPRINTS}`);
+    process.exit(1);
+  }
+  for (let k = 0; k < BLUEPRINTS; k++) {
+    const take = groups[k].slice(0, PER_BLUEPRINT);
+    if (take.length < PER_BLUEPRINT)
+      console.error(`warn: group ${k} has only ${take.length}/${PER_BLUEPRINT} tenants`);
+    picked.push(...take);
+  }
+  label = `diversity k=${BLUEPRINTS} per=${PER_BLUEPRINT}`;
+} else if (TENANTS > 0) {
+  picked = group0.slice(0, TENANTS);
+  if (picked.length < TENANTS)
+    console.error(`warn: only ${picked.length}/${TENANTS} undrifted tenants available`);
+  label = `tenant-count n=${picked.length} (single blueprint)`;
+} else {
+  console.error('one of --blueprints or --tenants is required');
+  process.exit(1);
+}
+
+const tenants = picked.map((n) => byName.get(n)).filter(Boolean);
+const missing = picked.filter((n) => !byName.has(n));
+if (missing.length) console.error(`warn: ${missing.length} drifted names not in fleet: ${missing.join(',')}`);
+
+const manifest = {
+  generatedAt: new Date().toISOString(),
+  derivedFrom: FLEET,
+  subset: label,
+  count: tenants.length,
+  tenants
+};
+fs.mkdirSync(path.dirname(OUT), { recursive: true });
+fs.writeFileSync(OUT, JSON.stringify(manifest) + '\n');
+console.log(`[subset] ${label}: ${tenants.length} tenants -> ${OUT}`);
diff --git a/scripts/scale-validate/summarize-results.mjs b/scripts/scale-validate/summarize-results.mjs
new file mode 100644
index 0000000000..e790050bbe
--- /dev/null
+++ b/scripts/scale-validate/summarize-results.mjs
@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// Summarize v2-ramps result JSONL files: one line per step.
+// Usage: node summarize-results.mjs out/v2-2048-tuned-results.jsonl [...more]
+import fs from 'node:fs';
+
+for (const file of process.argv.slice(2)) {
+  if (!fs.existsSync(file)) {
+    console.log(`-- ${file}: missing`);
+    continue;
+  }
+  console.log(`== ${file}`);
+  for (const line of fs.readFileSync(file, 'utf8').trim().split('\n').filter(Boolean)) {
+    let r;
+    try {
+      r = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const s = r.summary || {};
+    const lat = s.latency || {};
+    const m = r.metrics || {};
+    const c = m.lastCounters || {};
+    const out = [
+      r.name,
+      `crashed=${r.serverCrashed ? JSON.stringify(r.serverExit) : false}`,
+      `err=${r.error || '-'}`,
+      s.errRate !== undefined ? `errRate=${s.errRate}` : null,
+      s.achievedRps !== undefined ? `rps=${s.achievedRps}` : null,
+      lat.p50 !== undefined ? `p50/p95/p99=${lat.p50}/${lat.p95}/${lat.p99}` : null,
+      s.http ? `http=${JSON.stringify(s.http)}` : null,
+      s.sentinelOk !== undefined ? `sentinelOk=${s.sentinelOk}` : null,
+      r.coldBurst ? `cold=${JSON.stringify(s)}` : null,
+      m.heapUsedMaxMB !== undefined ? `heapMax=${m.heapUsedMaxMB}MB` : null,
+      m.rssMaxMB !== undefined ? `rssMax=${m.rssMaxMB}MB` : null,
+      m.buildQueueDepthMax !== undefined ? `queueMax=${m.buildQueueDepthMax}` : null,
+      c.evictions ? `evict=${JSON.stringify(c.evictions)}` : null,
+      c.builds !== undefined ? `builds=${c.builds}` : null,
+      c.connGuard ? `connGuard=${JSON.stringify(c.connGuard)}` : null,
+      r.pgBackends ? `pgConnMax=${r.pgBackends.max}${r.pgBackends.reconnects ? ` reconn=${r.pgBackends.reconnects}` : ''}` : null,
+      `wall=${r.wallSec}s`
+    ]
+      .filter(Boolean)
+      .join(' | ');
+    console.log('  ' + out);
+  }
+}
diff --git a/scripts/scale-validate/tenant-factory.mjs b/scripts/scale-validate/tenant-factory.mjs
new file mode 100644
index 0000000000..69f0760dfe
--- /dev/null
+++ b/scripts/scale-validate/tenant-factory.mjs
@@ -0,0 +1,421 @@
+#!/usr/bin/env node
+// =============================================================================
+// tenant-factory.mjs — the 200-tenant fast path (TASK D spike)
+//
+// Creates blueprint-identical marketplace tenants directly via SQL, reusing the
+// SAME control-plane procedures the GraphQL seeder ultimately invokes, but
+// WITHOUT the GraphQL/undici layer (and its 300s HTTP cap). Per tenant it runs,
+// in one committed transaction:
+//
+//   1. metaschema_generators.provision_database(...)   — db + domains + apis +
+//        site + ~40 modules + the app_public/app_private application schemas.
+//   2. metaschema_private.bootstrap_owner_into_database(...) — copies the owner
+//        user + primary email + password_hash from the control-plane ("source")
+//        database into the new tenant so password sign-in works (this is what the
+//        seeder's async provision trigger does when bootstrap_user = true).
+//   3. INSERT metaschema_modules_public.blueprint (copy of the reference
+//        marketplace definition) + metaschema_modules_public.construct_blueprint(
+//        blueprint_id, app_public_schema_id) — builds the 5 marketplace tables
+//        (categories, products, orders, order_items, reviews) into app_public.
+//
+// Session GUC: the module install triggers (events/function/config/agent/...) call
+// metaschema_private.ensure_super_constructive(), which RAISES unless
+// `constructive.allow_super_constructive = 'true'`. We set it per-transaction.
+//
+// Usage:
+//   node scripts/scale-validate/tenant-factory.mjs --count 5 --prefix factory \
+//        --blueprint marketplace [--concurrency 1] [--dry-run]
+//   node scripts/scale-validate/tenant-factory.mjs --validate factory1   # shape check vs reference
+//
+// Env: PGHOST PGPORT PGUSER PGPASSWORD PGDATABASE (defaults target :5433 constructive)
+// =============================================================================
+
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import crypto from 'crypto';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WORKTREE = path.resolve(__dirname, '..', '..');
+
+// `pg` is not a root dep; resolve it via the @dataplan/pg chain (same trick the
+// other scale-spike scripts use).
+const rootRequire = createRequire(path.join(WORKTREE, 'graphql', 'query', 'package.json'));
+const requireDpAdaptor = createRequire(rootRequire.resolve('postgraphile/adaptors/pg'));
+const requireDataplan = createRequire(requireDpAdaptor.resolve('@dataplan/pg'));
+const { Pool } = requireDataplan('pg');
+
+// ---------------------------------------------------------------------------
+// args
+// ---------------------------------------------------------------------------
+function parseArgs(argv) {
+  const out = {
+    count: 1,
+    prefix: 'factory',
+    blueprint: 'marketplace',
+    reference: 'marketplace_db_tenant1',
+    sourceDb: 'constructive',
+    domain: 'localhost',
+    concurrency: 1,
+    maxRetries: 3,
+    dryRun: false,
+    validate: null,
+    startIndex: null
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => argv[++i];
+    if (a === '--count') out.count = parseInt(next(), 10);
+    else if (a === '--prefix') out.prefix = next();
+    else if (a === '--blueprint') out.blueprint = next();
+    else if (a === '--reference') out.reference = next();
+    else if (a === '--source-db') out.sourceDb = next();
+    else if (a === '--domain') out.domain = next();
+    else if (a === '--concurrency') out.concurrency = parseInt(next(), 10);
+    else if (a === '--max-retries') out.maxRetries = parseInt(next(), 10);
+    else if (a === '--start-index') out.startIndex = parseInt(next(), 10);
+    else if (a === '--dry-run') out.dryRun = true;
+    else if (a === '--validate') out.validate = next();
+    else throw new Error(`unknown arg: ${a}`);
+  }
+  return out;
+}
+
+const PG = {
+  host: process.env.PGHOST || 'localhost',
+  port: parseInt(process.env.PGPORT || '5433', 10),
+  user: process.env.PGUSER || 'postgres',
+  password: process.env.PGPASSWORD || 'password',
+  database: process.env.PGDATABASE || 'constructive'
+};
+
+const ms = (t) => `${(Number(t) / 1e6).toFixed(0)}ms`;
+const now = () => process.hrtime.bigint();
+
+// ---------------------------------------------------------------------------
+// reference loading
+// ---------------------------------------------------------------------------
+async function loadReference(pool, opts) {
+  const ref = await pool.query(
+    `SELECT d.id AS db_id, d.owner_id
+       FROM metaschema_public.database d
+      WHERE d.name = $1`,
+    [opts.reference]
+  );
+  if (ref.rows.length === 0) throw new Error(`reference database "${opts.reference}" not found`);
+  const { db_id: refDbId, owner_id: ownerId } = ref.rows[0];
+
+  const prov = await pool.query(
+    `SELECT modules, options, domain
+       FROM metaschema_modules_public.database_provision_module
+      WHERE database_id = $1
+      ORDER BY created_at
+      LIMIT 1`,
+    [refDbId]
+  );
+  if (prov.rows.length === 0)
+    throw new Error(`no database_provision_module row for reference "${opts.reference}"`);
+  const modules = prov.rows[0].modules;
+  const options = prov.rows[0].options;
+
+  const bp = await pool.query(
+    `SELECT name, display_name, definition
+       FROM metaschema_modules_public.blueprint
+      WHERE database_id = $1 AND name = $2`,
+    [refDbId, opts.blueprint]
+  );
+  if (bp.rows.length === 0)
+    throw new Error(`reference blueprint "${opts.blueprint}" not found on "${opts.reference}"`);
+  const blueprint = bp.rows[0];
+
+  const src = await pool.query(
+    `SELECT id FROM metaschema_public.database WHERE name = $1`,
+    [opts.sourceDb]
+  );
+  if (src.rows.length === 0) throw new Error(`source database "${opts.sourceDb}" not found`);
+  const sourceDbId = src.rows[0].id;
+
+  return { refDbId, ownerId, modules, options, blueprint, sourceDbId };
+}
+
+async function nextStartIndex(pool, prefix) {
+  const r = await pool.query(
+    `SELECT COALESCE(MAX((regexp_replace(name, '^' || $1, ''))::int), 0) AS mx
+       FROM metaschema_public.database
+      WHERE name ~ ('^' || $1 || '[0-9]+$')`,
+    [prefix]
+  );
+  return (r.rows[0].mx || 0) + 1;
+}
+
+// ---------------------------------------------------------------------------
+// per-tenant provisioning (one committed transaction)
+// ---------------------------------------------------------------------------
+async function createTenant(pool, ref, opts, index) {
+  const name = `${opts.prefix}${index}`;
+  const subdomain = `${name}-${crypto.randomBytes(4).toString('hex')}`;
+
+  let attempt = 0;
+  for (;;) {
+    attempt++;
+    const client = await pool.connect();
+    const t = {};
+    try {
+      await client.query('BEGIN');
+      await client.query('SET LOCAL statement_timeout = 0');
+      await client.query('SET LOCAL idle_in_transaction_session_timeout = 0');
+      await client.query('SET LOCAL lock_timeout = 0');
+      await client.query(`SET LOCAL constructive.allow_super_constructive = 'true'`);
+
+      // Phase 1: provision_database
+      let s = now();
+      const provRes = await client.query(
+        `SELECT metaschema_generators.provision_database($1,$2,$3,$4,$5::jsonb,$6::jsonb) AS db_id`,
+        [name, ref.ownerId, subdomain, opts.domain, JSON.stringify(ref.modules), JSON.stringify(ref.options)]
+      );
+      const dbId = provRes.rows[0].db_id;
+      t.provision = now() - s;
+
+      // Phase 2: bootstrap owner (password sign-in path)
+      s = now();
+      await client.query(
+        `SELECT metaschema_private.bootstrap_owner_into_database($1,$2,$3,false)`,
+        [dbId, ref.sourceDbId, ref.ownerId]
+      );
+      t.bootstrap = now() - s;
+
+      // Phase 3: blueprint copy + construct
+      s = now();
+      const bpRes = await client.query(
+        `INSERT INTO metaschema_modules_public.blueprint
+           (owner_id, database_id, name, display_name, definition)
+         VALUES ($1,$2,$3,$4,$5::jsonb)
+         RETURNING id`,
+        [ref.ownerId, dbId, ref.blueprint.name, ref.blueprint.display_name, JSON.stringify(ref.blueprint.definition)]
+      );
+      const blueprintId = bpRes.rows[0].id;
+      const schemaRes = await client.query(
+        `SELECT id, schema_name FROM metaschema_public.schema
+          WHERE database_id = $1 AND name = 'app_public'`,
+        [dbId]
+      );
+      if (schemaRes.rows.length === 0) throw new Error('app_public schema not found after provision');
+      const appPublicSchemaId = schemaRes.rows[0].id;
+      const appPublicPhysical = schemaRes.rows[0].schema_name;
+      await client.query(`SELECT metaschema_modules_public.construct_blueprint($1,$2)`, [
+        blueprintId,
+        appPublicSchemaId
+      ]);
+      t.blueprint = now() - s;
+
+      // Phase 4: in-txn verification
+      const verify = {};
+      verify.schemaCount = (
+        await client.query(
+          `SELECT count(*)::int AS c FROM metaschema_public.schema WHERE database_id=$1`,
+          [dbId]
+        )
+      ).rows[0].c;
+      verify.appTables = (
+        await client.query(
+          `SELECT array_agg(c.relname::text ORDER BY c.relname) AS tables
+             FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace
+            WHERE n.nspname=$1 AND c.relkind='r'`,
+          [appPublicPhysical]
+        )
+      ).rows[0].tables;
+      verify.domains = (
+        await client.query(
+          `SELECT array_agg(d.subdomain || '.' || d.domain ORDER BY d.subdomain) AS hosts
+             FROM services_public.domains d WHERE d.database_id=$1
+              AND (d.subdomain LIKE 'api-%' OR d.subdomain LIKE 'auth-%')`,
+          [dbId]
+        )
+      ).rows[0].hosts;
+
+      if (opts.dryRun) await client.query('ROLLBACK');
+      else await client.query('COMMIT');
+
+      return {
+        ok: true,
+        name,
+        subdomain,
+        dbId,
+        appPublicPhysical,
+        apiHost: `api-${subdomain}.${opts.domain}`,
+        authHost: `auth-${subdomain}.${opts.domain}`,
+        timings: t,
+        verify,
+        attempt,
+        rolledBack: opts.dryRun
+      };
+    } catch (err) {
+      try {
+        await client.query('ROLLBACK');
+      } catch {}
+      // 40P01/40001: deadlock/serialization. 57P01/08006/08003/53300 + message
+      // sniff: connection-class (e.g. PG crash recovery) — retry after a long
+      // backoff so the run survives a server restart.
+      const connLost =
+        ['57P01', '08006', '08003', '53300'].includes(err && err.code) ||
+        /connection terminated|terminating connection|server closed the connection/i.test(
+          (err && err.message) || ''
+        );
+      const retriable = connLost || (err && (err.code === '40P01' || err.code === '40001'));
+      if (retriable && attempt <= opts.maxRetries) {
+        const backoff = (connLost ? 10000 : 100) * attempt + Math.floor(Math.random() * 100);
+        console.error(`  [${name}] ${err.code} (attempt ${attempt}) — retrying in ${backoff}ms`);
+        await new Promise((r) => setTimeout(r, backoff));
+        continue;
+      }
+      return { ok: false, name, subdomain, error: err.message, code: err.code, attempt };
+    } finally {
+      client.release();
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// shape validation (step 3.i): compare the logical [schema,relname] set of a
+// tenant's `api` API to the reference tenant's — same set => same fingerprint =>
+// same bp: key. Mirrors graphql/server/src/middleware/blueprint.ts:
+// stripSchemaHashPrefix + fingerprintFromRelations.
+// ---------------------------------------------------------------------------
+const SHAPE_SQL = `
+  WITH api_schema AS (
+    SELECT s.schema_name
+      FROM metaschema_public.database d
+      JOIN services_public.apis a ON a.database_id = d.id AND a.name = 'api'
+      JOIN services_public.api_schemas x ON x.api_id = a.id
+      JOIN metaschema_public.schema s ON s.id = x.schema_id
+     WHERE d.name = $1
+  )
+  SELECT regexp_replace(n.nspname, '^.*?-[0-9a-f]{8}-', '') AS logical_schema, c.relname
+    FROM api_schema aps
+    JOIN pg_namespace n ON n.nspname = aps.schema_name
+    JOIN pg_class c ON c.relnamespace = n.oid AND c.relkind IN ('r','v','m','p')
+   ORDER BY 1, 2`;
+
+function sha256(str) {
+  return crypto.createHash('sha256').update(str).digest('hex');
+}
+
+async function shapeOf(pool, dbName) {
+  const r = await pool.query(SHAPE_SQL, [dbName]);
+  const pairs = r.rows.map((row) => [row.logical_schema, row.relname]);
+  // fingerprintFromRelations sorts then sha256(JSON.stringify(pairs))
+  pairs.sort((a, b) => (a[0] !== b[0] ? (a[0] < b[0] ? -1 : 1) : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0));
+  return { pairs, fingerprint: sha256(JSON.stringify(pairs)) };
+}
+
+async function validateShape(pool, opts) {
+  const ref = await shapeOf(pool, opts.reference);
+  const cand = await shapeOf(pool, opts.validate);
+  const same = ref.fingerprint === cand.fingerprint;
+  console.log(`\n=== SHAPE CHECK: "${opts.validate}" vs reference "${opts.reference}" ===`);
+  console.log(`reference api relations (${ref.pairs.length}):`);
+  for (const [s, r] of ref.pairs) console.log(`    ${s}.${r}`);
+  console.log(`candidate api relations (${cand.pairs.length}):`);
+  for (const [s, r] of cand.pairs) console.log(`    ${s}.${r}`);
+  console.log(`reference shapeFingerprint: ${ref.fingerprint}`);
+  console.log(`candidate shapeFingerprint: ${cand.fingerprint}`);
+  console.log(`IDENTICAL SHAPE => same bp: key expected: ${same ? 'YES' : 'NO'}`);
+  return same;
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const pool = new Pool({ ...PG, max: Math.max(2, opts.concurrency + 1) });
+  // An idle pooled client dying (PG crash/restart) must not take down the run.
+  pool.on('error', (e) => console.error(`  [pool] idle client error (continuing): ${e.message}`));
+
+  try {
+    if (opts.validate) {
+      const ok = await validateShape(pool, opts);
+      process.exitCode = ok ? 0 : 1;
+      return;
+    }
+
+    const ref = await loadReference(pool, opts);
+    const start = opts.startIndex ?? (await nextStartIndex(pool, opts.prefix));
+    const indices = Array.from({ length: opts.count }, (_, k) => start + k);
+
+    console.log(
+      `tenant-factory: creating ${opts.count} tenant(s) prefix=${opts.prefix} indices=${start}..${
+        start + opts.count - 1
+      } blueprint=${opts.blueprint} concurrency=${opts.concurrency}${opts.dryRun ? ' [DRY-RUN]' : ''}`
+    );
+    console.log(
+      `  owner=${ref.ownerId} source-db=${ref.sourceDbId} modules=${ref.modules.length} items`
+    );
+
+    const results = [];
+    const wallStart = now();
+
+    // simple concurrency pool
+    let cursor = 0;
+    async function worker() {
+      for (;;) {
+        const i = cursor++;
+        if (i >= indices.length) return;
+        const idx = indices[i];
+        const tStart = now();
+        const res = await createTenant(pool, ref, opts, idx);
+        const wall = now() - tStart;
+        res.wall = wall;
+        results.push(res);
+        if (res.ok) {
+          const okTables =
+            Array.isArray(res.verify.appTables) && res.verify.appTables.length === 5;
+          console.log(
+            `  [${res.name}] OK db=${res.dbId} schemas=${res.verify.schemaCount} ` +
+              `appTables=${(res.verify.appTables || []).join(',')} ${okTables ? '✓' : '✗5'} ` +
+              `(prov ${ms(res.timings.provision)} boot ${ms(res.timings.bootstrap)} ` +
+              `bp ${ms(res.timings.blueprint)} wall ${ms(wall)}${
+                res.attempt > 1 ? ` retries=${res.attempt - 1}` : ''
+              })`
+          );
+        } else {
+          console.error(`  [${res.name}] FAILED code=${res.code} ${res.error}`);
+        }
+      }
+    }
+    await Promise.all(Array.from({ length: opts.concurrency }, () => worker()));
+
+    const wall = now() - wallStart;
+    const ok = results.filter((r) => r.ok);
+    const failed = results.filter((r) => !r.ok);
+    const totalSec = Number(wall) / 1e9;
+    const perMin = ok.length > 0 ? (ok.length / totalSec) * 60 : 0;
+
+    console.log(`\n=== SUMMARY ===`);
+    console.log(`created ${ok.length}/${opts.count} tenants in ${totalSec.toFixed(1)}s`);
+    if (ok.length) {
+      const avg = (sel) => ok.reduce((a, r) => a + Number(sel(r)), 0) / ok.length / 1e6;
+      console.log(
+        `  avg per-tenant: provision ${avg((r) => r.timings.provision).toFixed(0)}ms ` +
+          `bootstrap ${avg((r) => r.timings.bootstrap).toFixed(0)}ms ` +
+          `blueprint ${avg((r) => r.timings.blueprint).toFixed(0)}ms ` +
+          `wall ${avg((r) => r.wall).toFixed(0)}ms`
+      );
+      console.log(`  throughput: ${perMin.toFixed(2)} tenants/minute (concurrency=${opts.concurrency})`);
+      console.log(`  api hosts:`);
+      for (const r of ok) console.log(`    ${r.name}: ${r.apiHost}  (auth: ${r.authHost})`);
+    }
+    if (failed.length) {
+      console.log(`  FAILURES:`);
+      for (const r of failed) console.log(`    ${r.name}: [${r.code}] ${r.error}`);
+      process.exitCode = 1;
+    }
+  } finally {
+    await pool.end();
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
diff --git a/scripts/scale-validate/v2-ramps.mjs b/scripts/scale-validate/v2-ramps.mjs
new file mode 100644
index 0000000000..36f9b8fbfc
--- /dev/null
+++ b/scripts/scale-validate/v2-ramps.mjs
@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+// =============================================================================
+// v2-ramps.mjs — V2 limits-discovery executor.
+//
+// Runs a plan of ramp steps. Each step gets a FRESH server (clean cache, fresh
+// cumulative counters, own metrics file), then either:
+//   - drives the workload harness (harness.mjs) against a fleet manifest, or
+//   - fires a cold-burst: one concurrent first-hit per tenant in the manifest
+//     (use a 1-tenant-per-blueprint subset so every request is a cold build).
+//
+// Per step it records: harness latency/error summary, metrics-file maxima
+// (rss/heapUsed/buildQueueDepth), final cache+build counters, max PG backend
+// count during the run, and whether the server crashed (an 896MB-heap OOM is a
+// legitimate FINDING, not a script failure — steps continue).
+//
+// Usage:
+//   node scripts/scale-validate/v2-ramps.mjs --plan plans/v2-2048.json \
+//     [--out out/v2-2048-results.jsonl] [--only step1,step2]
+//
+// Plan file:
+//   { "port": 3345,
+//     "defaults": { "heapMb": 2048, "rps": 10, "durationSec": 420,
+//                   "shape": "uniform", "auth": 1, "mix": "read:0.7,write:0.25,meta:0.05" },
+//     "steps": [ { "name": "div-k3", "fleet": "out/fleet-k3.json" },
+//                { "name": "cold-burst", "fleet": "out/fleet-burst.json", "coldBurst": true } ] }
+//
+// Env: PGHOST PGPORT PGUSER PGPASSWORD PGDATABASE (defaults :5433 constructive)
+// =============================================================================
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { loadFleet, resolvePg, sleep } from './_lib.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WORKTREE = path.resolve(__dirname, '..', '..');
+const arg = (name, dflt) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 ? process.argv[i + 1] : dflt;
+};
+
+const PLAN_FILE = path.resolve(__dirname, arg('plan', ''));
+const OUT = path.resolve(__dirname, arg('out', 'out/v2-results.jsonl'));
+const ONLY = (arg('only', '') || '').split(',').filter(Boolean);
+if (!PLAN_FILE || !fs.existsSync(PLAN_FILE)) {
+  console.error('--plan <file> is required');
+  process.exit(1);
+}
+const plan = JSON.parse(fs.readFileSync(PLAN_FILE, 'utf8'));
+const PORT = plan.port || 3345;
+const MB = (b) => Math.round((b / 1024 / 1024) * 10) / 10;
+
+const PG = {
+  host: process.env.PGHOST || 'localhost',
+  port: parseInt(process.env.PGPORT || '5433', 10),
+  user: process.env.PGUSER || 'postgres',
+  password: process.env.PGPASSWORD || 'password',
+  database: process.env.PGDATABASE || 'constructive'
+};
+
+// ---------------------------------------------------------------------------
+// server lifecycle
+// ---------------------------------------------------------------------------
+function waitForPort(port, timeoutMs) {
+  const hosts = ['127.0.0.1', '::1'];
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve, reject) => {
+    let i = 0;
+    const tryOnce = () => {
+      const sock = net.connect({ host: hosts[i++ % hosts.length], port }, () => {
+        sock.destroy();
+        resolve();
+      });
+      sock.on('error', () => {
+        sock.destroy();
+        if (Date.now() > deadline) reject(new Error(`port ${port} not listening after ${timeoutMs}ms`));
+        else setTimeout(tryOnce, 300);
+      });
+    };
+    tryOnce();
+  });
+}
+
+function readMetrics(file) {
+  if (!fs.existsSync(file)) return [];
+  return fs
+    .readFileSync(file, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function startServer({ heapMb, cacheMax, metricsFile, serverEnv }) {
+  const child = spawn(
+    'node',
+    ['packages/cli/dist/index.js', 'server', '--port', String(PORT), '--origin', '*', '--simpleInflection', '--postgis', '--servicesApi'],
+    {
+      cwd: WORKTREE,
+      env: {
+        ...process.env,
+        NODE_ENV: 'production',
+        NODE_OPTIONS: `--max-old-space-size=${heapMb}`,
+        GRAPHILE_DEBUG_METRICS: '1',
+        GRAPHILE_DEBUG_METRICS_FILE: metricsFile,
+        GRAPHILE_BLUEPRINT_POOLING: '1',
+        ...(cacheMax ? { GRAPHILE_CACHE_MAX: String(cacheMax) } : {}),
+        ...(serverEnv || {}),
+        PGHOST: PG.host,
+        PGPORT: String(PG.port),
+        PGUSER: PG.user,
+        PGPASSWORD: PG.password,
+        PGDATABASE: PG.database
+      },
+      stdio: ['ignore', 'pipe', 'pipe']
+    }
+  );
+  const state = { child, log: '', exited: false, exitCode: null, exitSignal: null };
+  child.stdout.on('data', (d) => (state.log = (state.log + d).slice(-8000)));
+  child.stderr.on('data', (d) => (state.log = (state.log + d).slice(-8000)));
+  child.on('exit', (code, signal) => {
+    state.exited = true;
+    state.exitCode = code;
+    state.exitSignal = signal;
+  });
+  return state;
+}
+
+async function stopServer(state) {
+  if (state.exited) return;
+  state.child.kill('SIGTERM');
+  const deadline = Date.now() + 15000;
+  while (!state.exited && Date.now() < deadline) await sleep(300);
+  if (!state.exited) {
+    state.child.kill('SIGKILL');
+    while (!state.exited) await sleep(200);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// pg backend sampling (server pools + LISTEN connections)
+// ---------------------------------------------------------------------------
+function startPgSampler() {
+  const { Client } = resolvePg();
+  const state = { max: 0, last: 0, samples: 0, stop: false, err: null, reconnects: 0 };
+  (async () => {
+    // PG may crash-recover mid-step (introspection OOM inside its cgroup) —
+    // swallow client errors and reconnect rather than killing the executor.
+    while (!state.stop) {
+      let client;
+      try {
+        client = new Client(PG);
+        client.on('error', () => {});
+        await client.connect();
+        while (!state.stop) {
+          const r = await client.query(
+            `SELECT count(*)::int AS c FROM pg_stat_activity
+              WHERE datname = current_database() AND pid <> pg_backend_pid()`
+          );
+          state.last = r.rows[0].c;
+          state.max = Math.max(state.max, state.last);
+          state.samples++;
+          await sleep(5000);
+        }
+      } catch (e) {
+        state.err = String(e && e.message ? e.message : e);
+        state.reconnects++;
+      } finally {
+        try {
+          await client?.end();
+        } catch {}
+      }
+      if (!state.stop) await sleep(5000);
+    }
+  })();
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// workloads
+// ---------------------------------------------------------------------------
+function runHarness(step, cfg, harnessOut) {
+  return new Promise((resolve) => {
+    const args = [
+      path.join(__dirname, 'harness.mjs'),
+      '--fleet', path.resolve(__dirname, step.fleet),
+      '--port', String(PORT),
+      '--duration-sec', String(cfg.durationSec),
+      '--rps', String(cfg.rps),
+      '--mix', cfg.mix,
+      '--shape', cfg.shape,
+      '--auth', String(cfg.auth),
+      '--sentinel-interval-sec', String(cfg.sentinelSec ?? 60),
+      '--seed', String(cfg.seed ?? 42),
+      '--out', harnessOut
+    ];
+    const child = spawn('node', args, { cwd: __dirname, stdio: ['ignore', 'pipe', 'pipe'] });
+    let tail = '';
+    child.stdout.on('data', (d) => {
+      process.stdout.write(d);
+      tail = (tail + d).slice(-4000);
+    });
+    child.stderr.on('data', (d) => {
+      process.stderr.write(d);
+      tail = (tail + d).slice(-4000);
+    });
+    child.on('exit', (code) => resolve({ code, tail }));
+  });
+}
+
+async function coldBurst(step, cfg) {
+  const { tenants } = loadFleet(path.resolve(__dirname, step.fleet));
+  const one = async (t) => {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), cfg.coldTimeoutMs ?? 420000);
+    const start = performance.now();
+    try {
+      const res = await fetch(`http://${t.apiHost}:${PORT}/graphql`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ query: 'query { __typename }' }),
+        signal: ac.signal
+      });
+      await res.text();
+      return { dbname: t.dbname, status: res.status, ms: Math.round(performance.now() - start) };
+    } catch (e) {
+      return { dbname: t.dbname, status: 0, ms: Math.round(performance.now() - start), err: String(e).slice(0, 120) };
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  console.log(`[cold-burst] firing ${tenants.length} concurrent first-hits...`);
+  const wave1 = await Promise.all(tenants.map(one));
+  const wave2 = await Promise.all(tenants.map(one)); // warm check
+  return { wave1, wave2 };
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+const main = async () => {
+  fs.mkdirSync(path.join(__dirname, 'out'), { recursive: true });
+  const steps = plan.steps.filter((s) => ONLY.length === 0 || ONLY.includes(s.name));
+  console.log(`[v2-ramps] plan=${path.basename(PLAN_FILE)} steps=${steps.map((s) => s.name).join(',')} port=${PORT}`);
+
+  for (const step of steps) {
+    const cfg = { ...plan.defaults, ...step };
+    const name = `${step.name}-h${cfg.heapMb}`;
+    const metricsFile = path.join(__dirname, 'out', `metrics-${name}.jsonl`);
+    const harnessOut = path.join(__dirname, 'out', `harness-${name}.json`);
+    if (fs.existsSync(metricsFile)) fs.rmSync(metricsFile);
+
+    console.log(`\n===== STEP ${name}: heap=${cfg.heapMb}MB fleet=${step.fleet} ${step.coldBurst ? 'COLD-BURST' : `rps=${cfg.rps} dur=${cfg.durationSec}s shape=${cfg.shape}`} =====`);
+    const record = { name: step.name, heapMb: cfg.heapMb, fleet: step.fleet, config: cfg, startedAt: new Date().toISOString() };
+    const server = startServer({ heapMb: cfg.heapMb, cacheMax: cfg.cacheMax, metricsFile, serverEnv: cfg.serverEnv });
+    const pgSampler = startPgSampler();
+    const t0 = Date.now();
+    try {
+      await waitForPort(PORT, 120000);
+      // metrics baseline so the sampler is known-alive before load
+      const bDeadline = Date.now() + 60000;
+      while (readMetrics(metricsFile).length < 1 && Date.now() < bDeadline) await sleep(2000);
+
+      if (step.coldBurst) {
+        record.coldBurst = await coldBurst(step, cfg);
+        const w1 = record.coldBurst.wave1;
+        record.summary = {
+          coldOk: w1.filter((r) => r.status === 200).length,
+          cold503: w1.filter((r) => r.status === 503).length,
+          coldErr: w1.filter((r) => r.status !== 200 && r.status !== 503).length,
+          coldMsMax: Math.max(...w1.map((r) => r.ms)),
+          warmMsMax: Math.max(...record.coldBurst.wave2.map((r) => r.ms))
+        };
+        await sleep(15000); // let the sampler catch the post-burst state
+      } else {
+        const h = await runHarness(step, cfg, harnessOut);
+        record.harnessExit = h.code; // 2 = bleed sentinel violation
+        if (fs.existsSync(harnessOut)) {
+          const rep = JSON.parse(fs.readFileSync(harnessOut, 'utf8'));
+          record.summary = {
+            achievedRps: rep.totals?.achievedRps,
+            completed: rep.totals?.completed,
+            errRate: rep.totals?.errRate,
+            latency: rep.latencyOverall,
+            readLatency: rep.byClass?.read?.latency,
+            http: rep.http,
+            netErrors: rep.netErrors,
+            sentinelOk: rep.sentinel?.ok,
+            verdict: rep.verdict
+          };
+        } else {
+          record.error = `harness produced no report (exit ${h.code})`;
+          record.harnessTail = h.tail;
+        }
+      }
+    } catch (e) {
+      record.error = String(e && e.message ? e.message : e);
+    } finally {
+      pgSampler.stop = true;
+      const crashed = server.exited;
+      const m = readMetrics(metricsFile);
+      if (m.length) {
+        const last = m[m.length - 1];
+        record.metrics = {
+          samples: m.length,
+          rssMaxMB: MB(Math.max(...m.map((x) => x.rss))),
+          heapUsedMaxMB: MB(Math.max(...m.map((x) => x.heapUsed))),
+          heapUsedLastMB: MB(last.heapUsed),
+          buildQueueDepthMax: Math.max(...m.map((x) => x.counters?.buildQueueDepth ?? 0)),
+          lastCache: last.cache,
+          lastCounters: last.counters
+        };
+      }
+      await stopServer(server);
+      if (crashed) {
+        record.serverCrashed = true;
+        record.serverExit = { code: server.exitCode, signal: server.exitSignal };
+        record.serverLogTail = server.log.slice(-2500);
+        console.error(`[v2-ramps] SERVER CRASHED during ${name}: code=${server.exitCode} signal=${server.exitSignal}`);
+      }
+      record.pgBackends = { max: pgSampler.max, samples: pgSampler.samples, err: pgSampler.err };
+      record.wallSec = Math.round((Date.now() - t0) / 1000);
+      record.endedAt = new Date().toISOString();
+      fs.appendFileSync(OUT, JSON.stringify(record) + '\n');
+      console.log(`[v2-ramps] step ${name} done in ${record.wallSec}s -> ${OUT}`);
+    }
+  }
+  console.log(`\n[v2-ramps] all steps complete -> ${OUT}`);
+};
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});