settld 0.1.1 → 0.1.5

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,148 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { loadLighthouseTrackerFromPath } from "./lib/lighthouse-tracker.mjs";
+
+async function readJson(pathname) {
+  try {
+    const raw = await readFile(pathname, "utf8");
+    return { ok: true, value: JSON.parse(raw) };
+  } catch (err) {
+    return { ok: false, 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
+  };
+}
+
+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"
+  );
+  await mkdir(dirname(packetPath), { recursive: true });
+
+  const gateRead = await readJson(gateReportPath);
+  const throughputRead = await readJson(throughputReportPath);
+  const incidentRehearsalRead = await readJson(incidentRehearsalReportPath);
+  let lighthouse = null;
+  let lighthouseLoadError = null;
+  try {
+    lighthouse = await loadLighthouseTrackerFromPath(lighthouseTrackerPath);
+  } catch (err) {
+    lighthouseLoadError = err?.message ?? "unable to load lighthouse tracker";
+  }
+
+  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 : gateRead.error
+    },
+    {
+      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 : throughputRead.error
+    },
+    {
+      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 : incidentRehearsalRead.error
+    },
+    {
+      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_ready",
+      ok: lighthouse?.ok === true,
+      path: lighthouseTrackerPath,
+      details: lighthouse ?? { error: lighthouseLoadError }
+    }
+  ];
+
+  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 report = {
+    schemaVersion: "LaunchCutoverPacket.v1",
+    generatedAt: new Date().toISOString(),
+    sources: {
+      goLiveGateReportPath: gateReportPath,
+      throughputReportPath,
+      incidentRehearsalReportPath,
+      lighthouseTrackerPath
+    },
+    checks,
+    gateReference: gateCheckRefs,
+    blockingIssues,
+    verdict: {
+      ok: checks.every((row) => row.ok === true),
+      requiredChecks: checks.length,
+      passedChecks: checks.filter((row) => row.ok === true).length
+    }
+  };
+
+  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);
+});

package/scripts/ci/changelog-guard.mjs

@@ -0,0 +1,145 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+
+function loadV1FreezeFiles() {
+  try {
+    const raw = fs.readFileSync("test/fixtures/protocol-v1-freeze.json", "utf8");
+    const json = JSON.parse(raw);
+    const files = json?.files && typeof json.files === "object" && !Array.isArray(json.files) ? Object.keys(json.files) : [];
+    return new Set(files);
+  } catch {
+    return new Set();
+  }
+}
+
+const V1_FROZEN_FILES = loadV1FreezeFiles();
+
+function usage() {
+  // eslint-disable-next-line no-console
+  console.error("usage: node scripts/ci/changelog-guard.mjs --base <sha> --head <sha>");
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  let base = null;
+  let head = null;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--base") {
+      base = argv[i + 1] ?? null;
+      i += 1;
+      continue;
+    }
+    if (a === "--head") {
+      head = argv[i + 1] ?? null;
+      i += 1;
+      continue;
+    }
+    if (a === "--help" || a === "-h") usage();
+    usage();
+  }
+  if (!base || !head) usage();
+  return { base, head };
+}
+
+function changedFiles(base, head) {
+  const out = execFileSync("git", ["diff", "--name-only", `${base}..${head}`], { encoding: "utf8" });
+  return out
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function commitMessages(base, head) {
+  try {
+    const out = execFileSync("git", ["log", "--format=%B", `${base}..${head}`], { encoding: "utf8" });
+    return String(out ?? "");
+  } catch {
+    return "";
+  }
+}
+
+function readLabelsFromGithubEvent() {
+  try {
+    const p = process.env.GITHUB_EVENT_PATH ?? null;
+    if (!p || !fs.existsSync(p)) return [];
+    const raw = fs.readFileSync(p, "utf8");
+    const json = JSON.parse(raw);
+    const labels = json?.pull_request?.labels ?? [];
+    if (!Array.isArray(labels)) return [];
+    return labels.map((l) => String(l?.name ?? "")).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function readPrBodyFromGithubEvent() {
+  try {
+    const p = process.env.GITHUB_EVENT_PATH ?? null;
+    if (!p || !fs.existsSync(p)) return "";
+    const raw = fs.readFileSync(p, "utf8");
+    const json = JSON.parse(raw);
+    return String(json?.pull_request?.body ?? "");
+  } catch {
+    return "";
+  }
+}
+
+function matchesProtocolSurface(fp) {
+  const prefixes = [
+    "docs/spec/",
+    "scripts/spec/",
+    "test/fixtures/protocol-vectors/",
+    "test/fixtures/bundles/"
+  ];
+  return prefixes.some((p) => fp.startsWith(p));
+}
+
+function isV1FrozenSurface(fp) {
+  return V1_FROZEN_FILES.has(fp);
+}
+
+function hasProtocolChangeMarker(text) {
+  const t = String(text ?? "").toLowerCase();
+  return t.includes("[protocol-change]") || t.includes("protocol-change:");
+}
+
+const { base, head } = parseArgs(process.argv.slice(2));
+const files = changedFiles(base, head);
+const touchedChangelog = files.includes("CHANGELOG.md");
+const protocolSurfaceChanged = files.some(matchesProtocolSurface);
+const v1FrozenChanged = files.some(isV1FrozenSurface);
+const labels = readLabelsFromGithubEvent();
+const hasReleaseNoteLabel = labels.includes("release-note");
+
+if (!touchedChangelog && (protocolSurfaceChanged || hasReleaseNoteLabel)) {
+  // eslint-disable-next-line no-console
+  console.error("CHANGELOG.md must be updated for this PR.");
+  // eslint-disable-next-line no-console
+  if (protocolSurfaceChanged) console.error("- Reason: protocol surface files changed (docs/spec, schemas, vectors, or fixtures).");
+  // eslint-disable-next-line no-console
+  if (hasReleaseNoteLabel) console.error("- Reason: PR is labeled release-note.");
+  process.exit(1);
+}
+
+if (v1FrozenChanged && process.env.ALLOW_PROTOCOL_V1_MUTATION !== "1") {
+  const markerText = `${readPrBodyFromGithubEvent()}\n${commitMessages(base, head)}`;
+  const hasMarker = hasProtocolChangeMarker(markerText);
+  if (!hasMarker || !touchedChangelog) {
+    // eslint-disable-next-line no-console
+    console.error("Protocol v1 freeze gate: v1 schemas/vectors changed.");
+    // eslint-disable-next-line no-console
+    console.error("- This requires (1) CHANGELOG.md update and (2) an explicit protocol-change marker in the PR body or commit message.");
+    // eslint-disable-next-line no-console
+    console.error("- Marker examples: [protocol-change] or protocol-change:");
+    // eslint-disable-next-line no-console
+    console.error("- Override (local only): ALLOW_PROTOCOL_V1_MUTATION=1");
+    // eslint-disable-next-line no-console
+    console.error("Changed frozen files:");
+    for (const fp of files.filter(isV1FrozenSurface)) {
+      // eslint-disable-next-line no-console
+      console.error(`- ${fp}`);
+    }
+    process.exit(1);
+  }
+}