settld 0.1.2 → 0.2.0

package/scripts/chaos.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+import { Readable } from "node:stream";
+
+import { createApi } from "../src/api/app.js";
+import { createStore } from "../src/api/store.js";
+import { createPgStore } from "../src/db/store-pg.js";
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (!a.startsWith("--")) continue;
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith("--")) {
+      out[key] = next;
+      i += 1;
+    } else {
+      out[key] = "true";
+    }
+  }
+  return out;
+}
+
+function makeReq({ method, path, headers, body }) {
+  const chunks = body === undefined ? [] : [Buffer.from(JSON.stringify(body), "utf8")];
+  const req = Readable.from(chunks);
+  req.method = method;
+  req.url = path;
+  req.headers = headers ?? {};
+  return req;
+}
+
+function makeRes() {
+  const headers = new Map();
+  return {
+    statusCode: 200,
+    setHeader(name, value) {
+      headers.set(String(name).toLowerCase(), String(value));
+    },
+    end(payload) {
+      this.body = payload ?? "";
+      this.headers = headers;
+      this.ended = true;
+    }
+  };
+}
+
+async function request(api, { method, path, body, headers }) {
+  const reqHeaders = { ...(headers ?? {}) };
+  if (body !== undefined) reqHeaders["content-type"] = "application/json";
+  const req = makeReq({ method, path, headers: reqHeaders, body });
+  const res = makeRes();
+  await api.handle(req, res);
+  const text = typeof res.body === "string" ? res.body : Buffer.from(res.body ?? "").toString("utf8");
+  const json = text ? JSON.parse(text) : null;
+  return { statusCode: res.statusCode, json, headers: res.headers };
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  const mode = args.store ?? process.env.STORE ?? (process.env.DATABASE_URL ? "pg" : "memory");
+  const jobsCount = Number(args.jobs ?? "200");
+  const robotsCount = Number(args.robots ?? "20");
+  const dispatchWorkers = Number(args["dispatch-workers"] ?? "2");
+  const zoneId = args.zone ?? "zone_default";
+
+  if (!Number.isSafeInteger(jobsCount) || jobsCount <= 0) throw new Error("--jobs must be a positive integer");
+  if (!Number.isSafeInteger(robotsCount) || robotsCount <= 0) throw new Error("--robots must be a positive integer");
+  if (!Number.isSafeInteger(dispatchWorkers) || dispatchWorkers <= 0) throw new Error("--dispatch-workers must be a positive integer");
+
+  let schema = args.schema ?? null;
+  const databaseUrl = process.env.DATABASE_URL ?? null;
+  if (mode === "pg") {
+    if (!databaseUrl) throw new Error("STORE=pg requires DATABASE_URL");
+    if (!schema) schema = `chaos_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+  }
+
+  const stores = [];
+  const apis = [];
+
+  if (mode === "pg") {
+    for (let i = 0; i < dispatchWorkers; i += 1) {
+      const store = await createPgStore({ databaseUrl, schema, dropSchemaOnClose: i === 0 });
+      stores.push(store);
+      apis.push(createApi({ store }));
+    }
+  } else {
+    const store = createStore();
+    stores.push(store);
+    apis.push(createApi({ store }));
+  }
+
+  const api0 = apis[0];
+  const now = Date.now();
+  const availStartAt = new Date(now - 60 * 60_000).toISOString();
+  const availEndAt = new Date(now + 48 * 60 * 60_000).toISOString();
+
+  // Seed robots.
+  for (let i = 0; i < robotsCount; i += 1) {
+    const robotId = `rob_chaos_${i}`;
+    const reg = await request(api0, { method: "POST", path: "/robots/register", body: { robotId, trustScore: 0.8, homeZoneId: zoneId } });
+    if (reg.statusCode !== 201) throw new Error(`robot register failed: ${JSON.stringify(reg.json)}`);
+    const prev = reg.json.robot.lastChainHash;
+    const avail = await request(api0, {
+      method: "POST",
+      path: `/robots/${robotId}/availability`,
+      headers: { "x-proxy-expected-prev-chain-hash": prev },
+      body: { availability: [{ startAt: availStartAt, endAt: availEndAt }], timezone: "UTC" }
+    });
+    if (avail.statusCode !== 201) throw new Error(`robot availability failed: ${JSON.stringify(avail.json)}`);
+  }
+
+  // Create jobs (booked + dispatch requested).
+  const pilotStartBase = new Date(now + 10 * 60_000).toISOString();
+  for (let i = 0; i < jobsCount; i += 1) {
+    const startAt = new Date(Date.parse(pilotStartBase) + (i % 120) * 60_000).toISOString(); // spread over ~2h
+    const res = await request(api0, {
+      method: "POST",
+      path: "/pilot/jobs",
+      body: { startAt, autoBook: true, zoneId }
+    });
+    if (res.statusCode !== 201 && res.statusCode !== 409) {
+      throw new Error(`pilot job create failed: status=${res.statusCode} body=${JSON.stringify(res.json)}`);
+    }
+  }
+
+  if (mode !== "pg") {
+    // Single-process dispatch loop for memory store.
+    let loops = 0;
+    while (loops < 10_000) {
+      loops += 1;
+      const r = await api0.tickDispatch({ maxMessages: 100 });
+      if (!r.processed.length) break;
+    }
+    console.log(`dispatch processed (memory): jobs=${jobsCount}`);
+    return;
+  }
+
+  const pool = stores[0].pg.pool;
+  async function countPending(topic) {
+    const res = await pool.query("SELECT COUNT(*)::int AS c FROM outbox WHERE processed_at IS NULL AND topic = $1", [topic]);
+    return Number(res.rows[0].c);
+  }
+
+  // Dispatch loop with random restarts.
+  let tick = 0;
+  while (true) {
+    const pending = await countPending("DISPATCH_REQUESTED");
+    if (pending === 0) break;
+
+    tick += 1;
+    await Promise.all(apis.map((api) => api.tickDispatch({ maxMessages: 100 })));
+
+    // Randomly restart one worker every ~10 ticks.
+    if (tick % 10 === 0 && apis.length > 1) {
+      const idx = 1 + Math.floor(Math.random() * (apis.length - 1));
+      const store = stores[idx];
+      await store.close();
+      const newStore = await createPgStore({ databaseUrl, schema, dropSchemaOnClose: false });
+      stores[idx] = newStore;
+      apis[idx] = createApi({ store: newStore });
+    }
+
+    // Avoid tight loop.
+    await sleep(25);
+  }
+
+  // Invariants.
+  const confirmedRes = await pool.query(
+    `
+      SELECT aggregate_id, COUNT(*) FILTER (WHERE type = 'DISPATCH_CONFIRMED')::int AS confirmed
+      FROM events
+      WHERE aggregate_type = 'job'
+      GROUP BY aggregate_id
+    `
+  );
+  for (const row of confirmedRes.rows) {
+    const confirmed = Number(row.confirmed);
+    if (confirmed > 1) throw new Error(`invariant violation: job ${row.aggregate_id} has ${confirmed} DISPATCH_CONFIRMED events`);
+  }
+
+  const pendingDispatch = await countPending("DISPATCH_REQUESTED");
+  const pendingLedgerRes = await pool.query("SELECT COUNT(*)::int AS c FROM outbox WHERE processed_at IS NULL AND topic = 'LEDGER_ENTRY_APPLY'");
+  const pendingNotifyRes = await pool.query("SELECT COUNT(*)::int AS c FROM outbox WHERE processed_at IS NULL AND topic LIKE 'NOTIFY_%'");
+
+  console.log(
+    JSON.stringify(
+      {
+        schema,
+        jobsCount,
+        robotsCount,
+        dispatchWorkers,
+        pending: {
+          dispatch: pendingDispatch,
+          ledger: Number(pendingLedgerRes.rows[0].c),
+          notify: Number(pendingNotifyRes.rows[0].c)
+        },
+        jobsConfirmedChecked: confirmedRes.rows.length
+      },
+      null,
+      2
+    )
+  );
+
+  for (const store of stores) {
+    await store.close();
+  }
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error(err);
+  process.exit(1);
+});
+

package/scripts/ci/build-launch-cutover-packet.mjs

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { evaluateLighthouseTracker } from "./lib/lighthouse-tracker.mjs";
+import { canonicalJsonStringify } from "../../src/core/canonical-json.js";
+import { sha256Hex, signHashHexEd25519 } from "../../src/core/crypto.js";
+
+const SIGNING_KEY_FILE_ENV = "LAUNCH_CUTOVER_PACKET_SIGNING_KEY_FILE";
+const SIGNATURE_KEY_ID_ENV = "LAUNCH_CUTOVER_PACKET_SIGNATURE_KEY_ID";
+const PACKET_NOW_ENV = "LAUNCH_CUTOVER_PACKET_NOW";
+const GO_LIVE_GATE_SCHEMA_VERSION = "GoLiveGateReport.v1";
+const THROUGHPUT_REPORT_SCHEMA_VERSION = "ThroughputDrill10xReport.v1";
+const INCIDENT_REHEARSAL_REPORT_SCHEMA_VERSION = "ThroughputIncidentRehearsalReport.v1";
+const LIGHTHOUSE_TRACKER_SCHEMA_VERSION = "LighthouseProductionTracker.v1";
+
+function normalizeOptionalString(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+}
+
+function resolveSigningConfig(env = process.env) {
+  const signingKeyFile = normalizeOptionalString(env[SIGNING_KEY_FILE_ENV]);
+  const signatureKeyId = normalizeOptionalString(env[SIGNATURE_KEY_ID_ENV]);
+  return {
+    requested: Boolean(signingKeyFile || signatureKeyId),
+    signingKeyFile,
+    signatureKeyId
+  };
+}
+
+function resolveGeneratedAtIso(env = process.env) {
+  const raw = normalizeOptionalString(env[PACKET_NOW_ENV]);
+  if (!raw) return new Date().toISOString();
+  const epochMs = Date.parse(raw);
+  if (!Number.isFinite(epochMs)) throw new Error(`${PACKET_NOW_ENV} must be a valid ISO-8601 timestamp`);
+  return new Date(epochMs).toISOString();
+}
+
+async function readJson(pathname) {
+  try {
+    const raw = await readFile(pathname, "utf8");
+    return { ok: true, value: JSON.parse(raw), errorCode: null, error: null };
+  } catch (err) {
+    const isMissing = err?.code === "ENOENT";
+    return {
+      ok: false,
+      value: null,
+      errorCode: isMissing ? "file_missing" : "json_read_or_parse_error",
+      error: err?.message ?? "unable to read JSON file"
+    };
+  }
+}
+
+function checkFromGoLiveGate(gateReport) {
+  const checks = Array.isArray(gateReport?.checks) ? gateReport.checks : [];
+  const byId = new Map(checks.map((row) => [String(row?.id ?? ""), row]));
+  const deterministic = byId.get("deterministic_critical_suite") ?? null;
+  const throughput = byId.get("throughput_10x_drill") ?? null;
+  const incidentRehearsal = byId.get("throughput_incident_rehearsal") ?? null;
+  const lighthouse = byId.get("lighthouse_customers_paid_production") ?? null;
+  return {
+    deterministic,
+    throughput,
+    incidentRehearsal,
+    lighthouse
+  };
+}
+
+function buildPacketCore({ sources, checks, gateReference, blockingIssues, signing }) {
+  const passedChecks = checks.filter((row) => row.ok === true).length;
+  const checksOk = passedChecks === checks.length;
+  return {
+    schemaVersion: "LaunchCutoverPacket.v1",
+    sources,
+    checks,
+    gateReference,
+    blockingIssues,
+    signing: {
+      requested: signing.requested,
+      keyId: signing.keyId,
+      ok: signing.ok,
+      error: signing.error
+    },
+    verdict: {
+      ok: checksOk && signing.ok === true,
+      requiredChecks: checks.length,
+      passedChecks,
+      signingRequired: signing.requested,
+      signingOk: signing.ok === true
+    }
+  };
+}
+
+async function main() {
+  const packetPath = resolve(process.cwd(), process.env.LAUNCH_CUTOVER_PACKET_PATH || "artifacts/gates/s13-launch-cutover-packet.json");
+  const gateReportPath = resolve(process.cwd(), process.env.GO_LIVE_GATE_REPORT_PATH || "artifacts/gates/s13-go-live-gate.json");
+  const throughputReportPath = resolve(process.cwd(), process.env.THROUGHPUT_REPORT_PATH || "artifacts/throughput/10x-drill-summary.json");
+  const incidentRehearsalReportPath = resolve(
+    process.cwd(),
+    process.env.THROUGHPUT_INCIDENT_REHEARSAL_REPORT_PATH || "artifacts/throughput/10x-incident-rehearsal-summary.json"
+  );
+  const lighthouseTrackerPath = resolve(
+    process.cwd(),
+    process.env.LIGHTHOUSE_TRACKER_PATH || "planning/launch/lighthouse-production-tracker.json"
+  );
+  const signingConfig = resolveSigningConfig(process.env);
+  const generatedAtIso = resolveGeneratedAtIso(process.env);
+  await mkdir(dirname(packetPath), { recursive: true });
+
+  const gateRead = await readJson(gateReportPath);
+  const throughputRead = await readJson(throughputReportPath);
+  const incidentRehearsalRead = await readJson(incidentRehearsalReportPath);
+  const lighthouseRead = await readJson(lighthouseTrackerPath);
+  const lighthouse = lighthouseRead.ok ? evaluateLighthouseTracker(lighthouseRead.value) : null;
+
+  const gateCheckRefs = gateRead.ok ? checkFromGoLiveGate(gateRead.value) : null;
+  const checks = [
+    {
+      id: "go_live_gate_report_present",
+      ok: gateRead.ok,
+      path: gateReportPath,
+      details: gateRead.ok ? null : { code: gateRead.errorCode, message: gateRead.error }
+    },
+    {
+      id: "go_live_gate_schema_valid",
+      ok: gateRead.ok ? gateRead.value?.schemaVersion === GO_LIVE_GATE_SCHEMA_VERSION : false,
+      path: gateReportPath,
+      details: gateRead.ok ? { expected: GO_LIVE_GATE_SCHEMA_VERSION, observed: gateRead.value?.schemaVersion ?? null } : null
+    },
+    {
+      id: "go_live_gate_verdict_ok",
+      ok: gateRead.ok ? gateRead.value?.verdict?.ok === true : false,
+      path: gateReportPath,
+      details: gateRead.ok
+        ? {
+            requiredChecks: gateRead.value?.verdict?.requiredChecks ?? null,
+            passedChecks: gateRead.value?.verdict?.passedChecks ?? null
+          }
+        : null
+    },
+    {
+      id: "throughput_report_present",
+      ok: throughputRead.ok,
+      path: throughputReportPath,
+      details: throughputRead.ok ? null : { code: throughputRead.errorCode, message: throughputRead.error }
+    },
+    {
+      id: "throughput_schema_valid",
+      ok: throughputRead.ok ? throughputRead.value?.schemaVersion === THROUGHPUT_REPORT_SCHEMA_VERSION : false,
+      path: throughputReportPath,
+      details: throughputRead.ok
+        ? {
+            expected: THROUGHPUT_REPORT_SCHEMA_VERSION,
+            observed: throughputRead.value?.schemaVersion ?? null
+          }
+        : null
+    },
+    {
+      id: "throughput_verdict_ok",
+      ok: throughputRead.ok ? throughputRead.value?.verdict?.ok === true : false,
+      path: throughputReportPath,
+      details: throughputRead.ok ? { runner: throughputRead.value?.runConfig?.runner ?? null } : null
+    },
+    {
+      id: "throughput_incident_rehearsal_report_present",
+      ok: incidentRehearsalRead.ok,
+      path: incidentRehearsalReportPath,
+      details: incidentRehearsalRead.ok ? null : { code: incidentRehearsalRead.errorCode, message: incidentRehearsalRead.error }
+    },
+    {
+      id: "throughput_incident_rehearsal_schema_valid",
+      ok: incidentRehearsalRead.ok ? incidentRehearsalRead.value?.schemaVersion === INCIDENT_REHEARSAL_REPORT_SCHEMA_VERSION : false,
+      path: incidentRehearsalReportPath,
+      details: incidentRehearsalRead.ok
+        ? {
+            expected: INCIDENT_REHEARSAL_REPORT_SCHEMA_VERSION,
+            observed: incidentRehearsalRead.value?.schemaVersion ?? null
+          }
+        : null
+    },
+    {
+      id: "throughput_incident_rehearsal_verdict_ok",
+      ok: incidentRehearsalRead.ok ? incidentRehearsalRead.value?.verdict?.ok === true : false,
+      path: incidentRehearsalReportPath,
+      details: incidentRehearsalRead.ok
+        ? {
+            requiredChecks: incidentRehearsalRead.value?.verdict?.requiredChecks ?? null,
+            passedChecks: incidentRehearsalRead.value?.verdict?.passedChecks ?? null
+          }
+        : null
+    },
+    {
+      id: "lighthouse_tracker_present",
+      ok: lighthouseRead.ok,
+      path: lighthouseTrackerPath,
+      details: lighthouseRead.ok ? null : { code: lighthouseRead.errorCode, message: lighthouseRead.error }
+    },
+    {
+      id: "lighthouse_tracker_schema_valid",
+      ok: lighthouseRead.ok ? lighthouseRead.value?.schemaVersion === LIGHTHOUSE_TRACKER_SCHEMA_VERSION : false,
+      path: lighthouseTrackerPath,
+      details: lighthouseRead.ok
+        ? {
+            expected: LIGHTHOUSE_TRACKER_SCHEMA_VERSION,
+            observed: lighthouseRead.value?.schemaVersion ?? null
+          }
+        : null
+    },
+    {
+      id: "lighthouse_tracker_ready",
+      ok: lighthouse?.ok === true,
+      path: lighthouseTrackerPath,
+      details: lighthouseRead.ok ? lighthouse : { code: lighthouseRead.errorCode, message: lighthouseRead.error }
+    }
+  ];
+
+  const blockingIssues = [];
+  for (const check of checks) {
+    if (check.ok === true) continue;
+    blockingIssues.push({
+      checkId: check.id,
+      path: check.path ?? null,
+      details: check.details ?? null
+    });
+  }
+
+  const signing = {
+    requested: signingConfig.requested,
+    keyId: signingConfig.signatureKeyId,
+    ok: false,
+    error: null
+  };
+  let signingPrivateKeyPem = null;
+  if (!signing.requested) {
+    signing.ok = true;
+  } else if (!signingConfig.signingKeyFile || !signingConfig.signatureKeyId) {
+    signing.ok = false;
+    signing.error = `${SIGNING_KEY_FILE_ENV} and ${SIGNATURE_KEY_ID_ENV} are both required when signing is requested`;
+  } else {
+    try {
+      signingPrivateKeyPem = await readFile(resolve(process.cwd(), signingConfig.signingKeyFile), "utf8");
+      if (!String(signingPrivateKeyPem).trim()) throw new Error(`${SIGNING_KEY_FILE_ENV} resolved to an empty file`);
+      signing.ok = true;
+    } catch (err) {
+      signing.ok = false;
+      signing.error = err?.message ?? "unable to load signing private key";
+    }
+  }
+
+  let packetCore = buildPacketCore({
+    sources: {
+      goLiveGateReportPath: gateReportPath,
+      throughputReportPath,
+      incidentRehearsalReportPath,
+      lighthouseTrackerPath
+    },
+    checks,
+    gateReference: gateCheckRefs,
+    blockingIssues,
+    signing
+  });
+  let packetChecksumSha256 = sha256Hex(canonicalJsonStringify(packetCore));
+  let signature = null;
+  if (signing.requested && signing.ok && signingPrivateKeyPem) {
+    try {
+      signature = {
+        schemaVersion: "LaunchCutoverPacketSignature.v1",
+        algorithm: "ed25519-sha256",
+        keyId: signing.keyId,
+        messageSha256: packetChecksumSha256,
+        signatureBase64: signHashHexEd25519(packetChecksumSha256, signingPrivateKeyPem)
+      };
+    } catch (err) {
+      signing.ok = false;
+      signing.error = err?.message ?? "unable to sign launch cutover packet";
+      packetCore = buildPacketCore({
+        sources: packetCore.sources,
+        checks,
+        gateReference: gateCheckRefs,
+        blockingIssues,
+        signing
+      });
+      packetChecksumSha256 = sha256Hex(canonicalJsonStringify(packetCore));
+      signature = null;
+    }
+  }
+
+  const report = {
+    ...packetCore,
+    generatedAt: generatedAtIso,
+    packetChecksumSha256,
+    signature
+  };
+
+  await writeFile(packetPath, JSON.stringify(report, null, 2) + "\n", "utf8");
+  process.stdout.write(`wrote launch cutover packet: ${packetPath}\n`);
+  if (report.verdict.ok !== true) process.exitCode = 1;
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack || err?.message || String(err)}\n`);
+  process.exit(1);
+});

package/scripts/ci/build-self-serve-benchmark-report.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+async function readJsonBestEffort(pathname) {
+  try {
+    return JSON.parse(await readFile(pathname, "utf8"));
+  } catch (err) {
+    return { _error: err?.message ?? "unable to read json" };
+  }
+}
+
+function pickGateMetric(summary, key) {
+  const rows = Array.isArray(summary?.metrics) ? summary.metrics : [];
+  const found = rows.find((row) => row?.key === key);
+  return found && Number.isFinite(Number(found.value)) ? Number(found.value) : null;
+}
+
+function pickTrackerMetric(tracker, key) {
+  const row = tracker?.metrics?.[key];
+  return row && Number.isFinite(Number(row.value)) ? Number(row.value) : null;
+}
+
+async function main() {
+  const launchGatePath = resolve(
+    process.cwd(),
+    process.env.SELF_SERVE_LAUNCH_GATE_REPORT_PATH || "artifacts/gates/self-serve-launch-gate.json"
+  );
+  const throughputPath = resolve(
+    process.cwd(),
+    process.env.THROUGHPUT_REPORT_PATH || "artifacts/throughput/10x-drill-summary.json"
+  );
+  const incidentPath = resolve(
+    process.cwd(),
+    process.env.THROUGHPUT_INCIDENT_REHEARSAL_REPORT_PATH || "artifacts/throughput/10x-incident-rehearsal-summary.json"
+  );
+  const outPath = resolve(
+    process.cwd(),
+    process.env.SELF_SERVE_BENCHMARK_REPORT_PATH || "artifacts/launch/self-serve-benchmark-report.json"
+  );
+  await mkdir(dirname(outPath), { recursive: true });
+
+  const launchGate = await readJsonBestEffort(launchGatePath);
+  const throughput = await readJsonBestEffort(throughputPath);
+  const incident = await readJsonBestEffort(incidentPath);
+
+  const launchSummary = launchGate?.checks?.[0]?.summary ?? null;
+  const launchGateOk = launchGate?.verdict?.ok === true;
+  const throughputOk = throughput?.verdict?.ok === true;
+  const incidentOk = incident?.verdict?.ok === true;
+  const trackerPath =
+    typeof launchGate?.checks?.[0]?.trackerPath === "string" && launchGate.checks[0].trackerPath.trim() !== ""
+      ? launchGate.checks[0].trackerPath
+      : null;
+  const tracker = trackerPath ? await readJsonBestEffort(trackerPath) : null;
+
+  const referralLinkShares = pickGateMetric(launchSummary, "referralLinkShares") ?? pickTrackerMetric(tracker, "referralLinkShares");
+  const referralSignups = pickGateMetric(launchSummary, "referralSignups") ?? pickTrackerMetric(tracker, "referralSignups");
+  const referralConversionRatePct =
+    pickGateMetric(launchSummary, "referralConversionRatePct") ?? pickTrackerMetric(tracker, "referralConversionRatePct");
+
+  const report = {
+    schemaVersion: "SelfServeBenchmarkReport.v1",
+    generatedAt: new Date().toISOString(),
+    sources: {
+      launchGatePath,
+      throughputPath,
+      incidentPath
+    },
+    benchmark: {
+      launchKpis: {
+        gateOk: launchGateOk,
+        mvsvUsd: pickGateMetric(launchSummary, "mvsvUsd"),
+        signups: pickGateMetric(launchSummary, "signups"),
+        teamsFirstLiveSettlement: pickGateMetric(launchSummary, "teamsFirstLiveSettlement"),
+        payingCustomers: pickGateMetric(launchSummary, "payingCustomers"),
+        medianTimeToFirstSettlementMinutes: pickGateMetric(launchSummary, "medianTimeToFirstSettlementMinutes"),
+        arbitrationMedianResolutionHours: pickGateMetric(launchSummary, "arbitrationMedianResolutionHours")
+      },
+      throughput10x: {
+        ok: throughputOk,
+        httpReqDurationP95Ms: Number.isFinite(Number(throughput?.metrics?.httpReqDurationP95Ms))
+          ? Number(throughput.metrics.httpReqDurationP95Ms)
+          : null,
+        httpReqFailedRate: Number.isFinite(Number(throughput?.metrics?.httpReqFailedRate))
+          ? Number(throughput.metrics.httpReqFailedRate)
+          : null,
+        ingestRejectedPerMin: Number.isFinite(Number(throughput?.metrics?.ingestRejectedPerMin))
+          ? Number(throughput.metrics.ingestRejectedPerMin)
+          : null
+      },
+      incidentRehearsal: {
+        ok: incidentOk,
+        durationMs: Number.isFinite(Number(incident?.durationMs)) ? Number(incident.durationMs) : null,
+        failedChecks: Array.isArray(incident?.checks) ? incident.checks.filter((row) => row?.ok !== true).map((row) => row?.id).filter(Boolean) : []
+      },
+      referral: {
+        linkShares: referralLinkShares,
+        signups: referralSignups,
+        conversionRatePct: referralConversionRatePct
+      }
+    }
+  };
+
+  report.verdict = {
+    ok: Boolean(launchGateOk && throughputOk && incidentOk),
+    checks: {
+      launchGateOk,
+      throughputOk,
+      incidentOk
+    }
+  };
+
+  await writeFile(outPath, JSON.stringify(report, null, 2) + "\n", "utf8");
+  process.stdout.write(`wrote self-serve benchmark report: ${outPath}\n`);
+  if (!report.verdict.ok) process.exitCode = 1;
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack || err?.message || String(err)}\n`);
+  process.exit(1);
+});