feat: operationalize frontend incident runbooks

Merge branch 'feature-web-vitals-performance-budget-contract' into develop
2026-07-25 21:30:40 +09:00 · 2026-07-25 21:26:51 +09:00
19 changed files with 585 additions and 433 deletions
@@ -1,25 +1,5 @@
 {
  "schemaVersion": 1,
  "releaseId": "local-release",
  "environment": "replace-with-production",
  "source": {
    "system": "",
    "exportId": ""
  },
  "privacy": {
    "approved": false,
    "approvalRef": ""
  },
  "window": {
    "start": "2026-06-01T00:00:00Z",
    "end": "2026-06-29T00:00:00Z"
  },
  "thresholdDecision": {
    "status": "pending",
    "minimumEligibleSamples": null,
    "owner": "",
    "reviewedAt": "",
    "evidenceRef": ""
  },
  "samples": []
 }
@@ -0,0 +1,93 @@
 {
  "schemaVersion": 1,
  "runbooks": {
    "FE-RB-001": {
      "title": "Boot configuration failure",
      "gateId": "FE-GATE-021",
      "triggerKinds": ["BOOT_CONFIG_FAILURE"],
      "containment": "stop product route mount, show the safe support shell, and refetch at most once",
      "window": "owner triage planned-default 5m",
      "escalation": ["env-config owner", "release owner"],
      "recoveryEvidence": [
        "clean-session boot",
        "product root mount",
        "config validation",
        "no repeated boot error"
      ],
      "negativeFixture": "a valid config followed by an injected mount failure must fail recovery"
    },
    "FE-RB-002": {
      "title": "Chunk, manifest, or deployment mismatch",
      "gateId": "FE-GATE-022",
      "triggerKinds": [
        "CHUNK_LOAD_FAILURE",
        "RELEASE_MANIFEST_FAILURE",
        "DEPLOY_MISMATCH"
      ],
      "containment": "warn for dirty state, fetch manifest no-store once, and allow one guarded reload",
      "window": "release owner triage planned-default 5m",
      "escalation": ["release-cache owner", "hosting/CDN owner"],
      "recoveryEvidence": [
        "entry and lazy assets reachable",
        "release tuple coherent",
        "second reload blocked",
        "critical route smoke"
      ],
      "negativeFixture": "a second failure for the same release pair must not reload"
    },
    "FE-RB-003": {
      "title": "Backend API degradation",
      "gateId": "FE-GATE-023",
      "triggerKinds": [
        "TERMINAL_NETWORK_RATE",
        "REQUEST_TIMEOUT_RATE",
        "SERVER_FAILURE_RATE",
        "SCHEMA_MISMATCH"
      ],
      "containment": "do not expand retry caps, serve safe stale reads, and never retry an unkeyed mutation",
      "window": "rolling 5m trigger; first classification planned-default 10m",
      "escalation": [
        "api-client owner",
        "backend operation owner",
        "release compatibility owner"
      ],
      "recoveryEvidence": [
        "terminal failure rate at baseline",
        "no retry amplification",
        "critical read/write smoke",
        "schema fixtures"
      ],
      "negativeFixture": "an unkeyed POST receiving 503 must not retry"
    },
    "FE-RB-004": {
      "title": "Telemetry sink failure",
      "gateId": "FE-GATE-024",
      "triggerKinds": ["TELEMETRY_FAILURE"],
      "containment": "keep product flow available, bound the queue, and never report recursively to the failing sink",
      "window": "platform triage planned-default 15m",
      "escalation": ["observability owner", "telemetry platform owner"],
      "recoveryEvidence": [
        "product flow unaffected",
        "delivery self-check",
        "queue drained within bound",
        "forbidden attributes absent"
      ],
      "negativeFixture": "raw URL and query data must be removed from telemetry"
    },
    "FE-RB-005": {
      "title": "Coherent release rollback",
      "gateId": "FE-GATE-025",
      "triggerKinds": ["RELEASE_BLOCKING_DEFECT"],
      "containment": "select a prior immutable tuple, verify asset/config/API compatibility, atomically switch, and smoke",
      "window": "provider recovery target TBD",
      "escalation": ["release-cache owner", "release approver/hosting owner"],
      "recoveryEvidence": [
        "compatibility gate",
        "release coherence gate",
        "critical smoke",
        "release ID in incident timeline"
      ],
      "negativeFixture": "HTML build A with asset manifest B must be rejected"
    }
  }
 }
@@ -8,7 +8,6 @@
    "window",
    "context",
    "metrics",
    "thresholds",
    "eligibility",
    "status",
    "passed"
@@ -19,55 +18,12 @@
    "window": { "type": "object", "required": ["days", "start", "end"] },
    "context": {
      "type": "object",
-      "required": [
+      "required": ["source", "network", "routeAggregation", "releaseId"]
        "source",
        "sourceSystem",
        "exportId",
        "network",
        "routeAggregation",
        "releaseId",
        "privacyApprovalRef",
        "thresholdDecisionRef",
        "validationFailures"
      ],
      "properties": {
        "source": { "type": "string" },
        "sourceSystem": { "type": ["string", "null"] },
        "exportId": { "type": ["string", "null"] },
        "network": { "const": "production-real-user" },
        "routeAggregation": { "const": "route-id-only" },
        "releaseId": { "type": ["string", "null"] },
        "privacyApprovalRef": { "type": ["string", "null"] },
        "thresholdDecisionRef": { "type": ["string", "null"] },
        "validationFailures": {
          "type": "array",
          "items": { "type": "string" }
        }
      },
      "additionalProperties": false
    },
    "thresholds": {
      "type": "object",
      "required": [
        "p75LcpMs",
        "p75Cls",
        "p75InpMs",
        "minimumEligibleSamples"
      ]
    },
    "metrics": {
      "type": "object",
      "required": ["p75LcpMs", "p75Cls", "p75InpMs"]
    },
    "metrics": { "type": "object" },
    "eligibility": {
      "type": "object",
-      "required": [
+      "required": ["consentRequired", "eligibleSamples", "minimumEligibleSamples"]
        "consentRequired",
        "totalSamples",
        "eligibleSamples",
        "minimumEligibleSamples",
        "routeSamples"
      ]
    },
    "status": {
      "enum": ["PASS", "FAIL_THRESHOLD", "FAIL_UNVERIFIED"]
@@ -0,0 +1,42 @@
 {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "ART-FE-RUNBOOK-DRILL@1",
  "type": "object",
  "required": [
    "schemaVersion",
    "runbookId",
    "releaseId",
    "drillTimestamp",
    "triggerInjected",
    "triggerAsserted",
    "containmentAsserted",
    "escalationPathAsserted",
    "recoveryAssertions",
    "negativeFixtureFailedAsExpected",
    "windowObservedBucket",
    "passed"
  ],
  "properties": {
    "schemaVersion": { "const": 1 },
    "runbookId": { "pattern": "^FE-RB-00[1-5]$" },
    "releaseId": { "type": "string", "minLength": 1 },
    "drillTimestamp": { "type": "string", "format": "date-time" },
    "triggerInjected": { "type": "string" },
    "triggerAsserted": { "type": "boolean" },
    "containmentAsserted": { "type": "boolean" },
    "escalationPathAsserted": { "type": "boolean" },
    "recoveryAssertions": {
      "type": "array",
      "minItems": 4,
      "items": {
        "type": "object",
        "required": ["assertion", "evidence", "passed"]
      }
    },
    "negativeFixtureFailedAsExpected": { "type": "boolean" },
    "windowObservedBucket": { "type": "string" },
    "providerVerificationRequired": { "type": "boolean" },
    "passed": { "type": "boolean" }
  },
  "additionalProperties": false
 }
@@ -13,10 +13,5 @@ Performance evidence is deliberately split by measurement context:
 The field minimum eligible-sample threshold is intentionally unresolved until
 a privacy-approved telemetry baseline exists. Therefore the field command
 fails closed with `FAIL_UNVERIFIED` when run against the example input. Provide
-`FIELD_WEB_VITALS_INPUT` and `MIN_ELIGIBLE_SAMPLES` only after that decision is
+`FIELD_WEB_VITALS_INPUT` and a reviewed `MIN_ELIGIBLE_SAMPLES` only after that
-recorded. The external input must identify a production release and an exact
+decision is recorded.
 28-day export window, name the source/export, carry privacy-approval and
 threshold-decision references, and contain only non-negative route-ID samples.
 The environment threshold must be a positive integer equal to the approved
 decision embedded in the input. Invalid metadata fails as `FAIL_UNVERIFIED`;
 the example can never serve as production evidence.
@@ -0,0 +1,9 @@
 # FE-RB-001 — Boot configuration failure
 Trigger on `BOOT_CONFIG_FAILURE` after the single bounded refetch fails. Stop
 product route mounting and show the safe support shell; the planned owner
 triage target is five minutes. Escalate from the environment/config owner to
 the release owner.
 Close only after a clean-session boot mounts the product root, config
 validation evidence passes, and repeated boot-error telemetry is absent.
@@ -0,0 +1,11 @@
 # FE-RB-002 — Chunk or deployment mismatch
 Trigger on `CHUNK_LOAD_FAILURE`, `RELEASE_MANIFEST_FAILURE`, or
 `DEPLOY_MISMATCH`. Warn when dirty state may be lost, fetch the manifest
 `no-store` once, record the release pair, and allow only one reload. The
 planned release-owner triage target is five minutes. Escalate to the hosting/CDN
 owner.
 Close only after entry/lazy assets are reachable, the manifest parses into a
 coherent tuple, a second automatic reload is blocked, and the critical route
 smoke passes.
@@ -0,0 +1,10 @@
 # FE-RB-003 — Backend API degradation
 Trigger when terminal network/timeout/5xx failures exceed the rolling
 five-minute threshold or on one `SCHEMA_MISMATCH`. Do not expand client retry
 caps, do not retry schema mismatches, and never retry an unkeyed mutation.
 Escalate from the API client owner to backend operations and then release
 compatibility; the planned first-classification target is ten minutes.
 Close only after the failure rate returns to baseline, retry amplification is
 absent, critical read/write smoke passes, and schema fixtures pass.
@@ -0,0 +1,9 @@
 # FE-RB-004 — Telemetry sink failure
 Trigger on sink network/non-2xx errors, queue overflow, or adapter
 initialization failure. Keep product flows available, bound the queue, and do
 not recursively report to the failed sink. Escalate from observability to the
 telemetry platform owner; the planned triage target is fifteen minutes.
 Close only after product e2e remains unaffected, delivery self-check succeeds,
 the queue drains within its bound, and the forbidden-attribute scan passes.
@@ -0,0 +1,13 @@
 # FE-RB-005 — Coherent release rollback
 Trigger on a release-blocking boot, chunk, render, API, or security defect when
 a safe forward fix is not demonstrated inside the incident window. Select a
 prior immutable release, verify its asset/config/API tuple, atomically switch
 the complete set, perform the provider cache action, and run smoke checks.
 Escalate from the release-cache owner to the release approver/hosting owner.
 The provider recovery target remains TBD until hosting is selected.
 Close only when compatibility and release-coherence gates pass, critical smoke
 passes, repeated `DEPLOY_MISMATCH` is absent, and the incident timeline records
 the restored release ID. Pointer-switch or cache-purge completion alone is not
 recovery evidence.
@@ -36,7 +36,9 @@
    "verify:hosting-headers": "node scripts/verify-hosting-headers.mjs",
    "check:bundle": "node scripts/generate-supply-chain.mjs && node scripts/check-bundle.mjs",
    "test:performance": "node scripts/test-performance.mjs",
-    "collect:web-vitals-evidence": "node scripts/collect-web-vitals-evidence.mjs"
+    "collect:web-vitals-evidence": "node scripts/collect-web-vitals-evidence.mjs",
    "drill:runbook": "node scripts/drill-runbook.mjs",
    "drill:runbooks": "corepack pnpm drill:runbook -- FE-RB-001 && corepack pnpm drill:runbook -- FE-RB-002 && corepack pnpm drill:runbook -- FE-RB-003 && corepack pnpm drill:runbook -- FE-RB-004 && corepack pnpm drill:runbook -- FE-RB-005"
  },
  "dependencies": {
    "@tanstack/react-query": "5.101.4",
@@ -1,7 +1,6 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { evaluateBundleBudget } from "../src/application/policies/performance-budgets.js";
 import { classifyViteJavascript } from "./lib/classify-vite-bundle.mjs";
 const report =
  /** @type {{
@@ -11,7 +10,7 @@ const report =
    JSON.parse(await readFile("artifacts/performance/bundle.json", "utf8"))
  );
 const viteManifest =
-  /** @type {Record<string, { file: string, isEntry?: boolean, imports?: string[] }>} */ (
+  /** @type {Record<string, { file: string, isEntry?: boolean }>} */ (
    JSON.parse(await readFile("dist/.vite/manifest.json", "utf8"))
  );
 const budgets =
@@ -22,19 +21,24 @@ const budgets =
 const outputByPath = new Map(
  report.outputs.map((output) => [output.path.replace(/^dist\//, ""), output]),
 );
-const classification = classifyViteJavascript(viteManifest);
+const initialFiles = new Set(
-const initialJsGzipBytes = classification.initialFiles.reduce(
+  Object.values(viteManifest)
    .filter((entry) => entry.isEntry)
    .map((entry) => entry.file),
 );
 const lazyFiles = new Set(
  Object.values(viteManifest)
    .filter((entry) => !entry.isEntry && entry.file.endsWith(".js"))
    .map((entry) => entry.file),
 );
 const initialJsGzipBytes = [...initialFiles].reduce(
  (total, file) => total + (outputByPath.get(file)?.gzipBytes ?? 0),
  0,
 );
-const lazyChunks = classification.lazyFiles.map((file) => ({
+const lazyChunks = [...lazyFiles].map((file) => ({
  path: file,
  gzipBytes: outputByPath.get(file)?.gzipBytes ?? 0,
 }));
 const missingOutputs = [
  ...classification.initialFiles,
  ...classification.lazyFiles,
 ].filter((file) => !outputByPath.has(file));
 const measurements = { initialJsGzipBytes, lazyChunks };
 const result = evaluateBundleBudget(measurements, budgets);
 const fixtures = [
@@ -66,16 +70,10 @@ const fixtures = [
      ).passed,
  },
 ];
-const passed =
+const passed = result.passed && fixtures.every((fixture) => fixture.passed);
  result.passed &&
  fixtures.every((fixture) => fixture.passed) &&
  classification.missingImports.length === 0 &&
  missingOutputs.length === 0;
 const completedReport = {
  ...report,
  measurements,
  classification,
  missingOutputs,
  thresholds: budgets,
  results: result,
  fixtures,
@@ -87,12 +85,7 @@ await writeFile(
  `${JSON.stringify(completedReport, null, 2)}\n`,
 );
 if (!passed) {
-  process.stderr.write(
+  process.stderr.write("Bundle budget exceeded.\n");
    `Bundle budget or manifest integrity failed: ${[
      ...classification.missingImports,
      ...missingOutputs,
    ].join(", ")}\n`,
  );
  process.exit(1);
 }
 process.stdout.write(
@@ -4,19 +4,23 @@ import {
  evaluateFieldBudget,
  percentile75,
 } from "../src/application/policies/performance-budgets.js";
 import { validateFieldEvidenceInput } from "./lib/field-vitals-evidence.mjs";
 const inputPath =
  process.env.FIELD_WEB_VITALS_INPUT ??
  "config/performance/field-input.example.json";
-const rawInput = JSON.parse(await readFile(inputPath, "utf8"));
+const input =
-const now = new Date();
+  /** @type {{
-const validation = validateFieldEvidenceInput(
+   *   releaseId: string,
-  rawInput,
+   *   samples: Array<{
-  process.env.MIN_ELIGIBLE_SAMPLES,
+   *     timestamp: string,
-  now,
+   *     consent: boolean,
-);
+   *     releaseId: string,
-const input = validation.data;
+   *     routeId: string,
   *     lcpMs: number,
   *     cls: number,
   *     inpMs: number
   *   }>
   * }} */ (JSON.parse(await readFile(inputPath, "utf8")));
 const configured =
  /** @type {{
   *   p75LcpMs: number,
@@ -26,17 +30,17 @@ const configured =
   * }} */ (
    JSON.parse(await readFile("config/performance/budgets.json", "utf8")).field
  );
-const minimumEligibleSamples = validation.minimumEligibleSamples;
+const minimumEligibleSamples = process.env.MIN_ELIGIBLE_SAMPLES
-const fallbackEnd = now;
+  ? Number(process.env.MIN_ELIGIBLE_SAMPLES)
-const fallbackStart = new Date(fallbackEnd);
+  : configured.minimumEligibleSamples;
-fallbackStart.setUTCDate(fallbackStart.getUTCDate() - 28);
+const end = new Date();
-const start = input ? new Date(input.window.start) : fallbackStart;
+const start = new Date(end);
-const end = input ? new Date(input.window.end) : fallbackEnd;
+start.setUTCDate(start.getUTCDate() - 28);
-const eligible = (input?.samples ?? []).filter((sample) => {
+const eligible = input.samples.filter((sample) => {
  const timestamp = new Date(sample.timestamp);
  return (
    sample.consent === true &&
-    sample.releaseId === input?.releaseId &&
+    sample.releaseId === input.releaseId &&
    timestamp >= start &&
    timestamp <= end
  );
@@ -51,8 +55,6 @@ const result = evaluateFieldBudget(
  { metrics, eligibleSamples: eligible.length },
  thresholds,
 );
 const passed = validation.passed && result.passed;
 const status = validation.passed ? result.status : "FAIL_UNVERIFIED";
 const routeSamples = Object.fromEntries(
  Object.entries(
    eligible.reduce(
@@ -66,30 +68,24 @@ const routeSamples = Object.fromEntries(
 );
 const report = {
  schemaVersion: 1,
-  generatedAt: now.toISOString(),
+  generatedAt: end.toISOString(),
  window: { days: 28, start: start.toISOString(), end: end.toISOString() },
  context: {
    source: inputPath,
    sourceSystem: input?.source.system ?? null,
    exportId: input?.source.exportId ?? null,
    network: "production-real-user",
    routeAggregation: "route-id-only",
-    releaseId: input?.releaseId ?? null,
+    releaseId: input.releaseId,
    privacyApprovalRef: input?.privacy.approvalRef ?? null,
    thresholdDecisionRef: input?.thresholdDecision.evidenceRef ?? null,
    validationFailures: validation.failures,
  },
  metrics,
  thresholds,
  eligibility: {
    consentRequired: true,
    totalSamples: input?.samples.length ?? 0,
    eligibleSamples: eligible.length,
    minimumEligibleSamples,
    routeSamples,
  },
-  status,
+  status: result.status,
-  passed,
+  passed: result.passed,
 };
 await mkdir("artifacts/performance", { recursive: true });
@@ -97,9 +93,9 @@ await writeFile(
  "artifacts/performance/field-web-vitals.json",
  `${JSON.stringify(report, null, 2)}\n`,
 );
-if (!passed) {
+if (!result.passed) {
  process.stderr.write(
-    `Field Web Vitals: ${status} (approved threshold decision and valid 28-day production evidence are required)\n`,
+    `Field Web Vitals: ${result.status} (minimum eligible sample threshold and 28-day production data are required)\n`,
  );
  process.exit(1);
 }
@@ -0,0 +1,309 @@
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { shouldRetry } from "../src/adapters/http/retry-policy.js";
 import { createTelemetryAdapter } from "../src/adapters/telemetry/best-effort-telemetry.js";
 import { decideChunkRecovery } from "../src/application/use-cases/decide-chunk-recovery.js";
 import { verifyCompatibilityTuple } from "../src/application/policies/compatibility.js";
 import { validateRuntimeConfig } from "../src/bootstrap/runtime-config-schema.js";
 import { projectTelemetryEvent } from "../src/contracts/telemetry.js";
 import { compareReleaseToRuntime } from "../src/contracts/release-tokens.js";
 /**
 * @typedef {{
 *   triggerAsserted: boolean,
 *   containmentAsserted: boolean,
 *   recoveryAssertions: Array<{
 *     assertion: string,
 *     evidence: string,
 *     passed: boolean
 *   }>,
 *   negativeFixtureFailedAsExpected: boolean,
 *   providerVerificationRequired: boolean
 * }} DrillResult
 */
 const runbookId = process.argv
  .slice(2)
  .find((argument) => /^FE-RB-00[1-5]$/.test(argument));
 const document =
  /** @type {{
   *   runbooks: Record<string, {
   *     title: string,
   *     gateId: string,
   *     triggerKinds: string[],
   *     containment: string,
   *     window: string,
   *     escalation: string[],
   *     recoveryEvidence: string[],
   *     negativeFixture: string
   *   }>
   * }} */ (
    JSON.parse(await readFile("config/runbooks/runbooks.json", "utf8"))
  );
 const specification = runbookId ? document.runbooks[runbookId] : undefined;
 if (!runbookId || !specification) {
  process.stderr.write("Usage: drill:runbook -- FE-RB-001..FE-RB-005\n");
  process.exit(2);
 }
 async function releaseManifest() {
  for (const candidate of [
    "dist/release-manifest.json",
    "public/release-manifest.json",
  ]) {
    try {
      return JSON.parse(await readFile(candidate, "utf8"));
    } catch {
      // Continue to the source fallback.
    }
  }
  throw new Error("Release manifest is unavailable.");
 }
 const validConfig = {
  APP_ENV: "local",
  API_BASE_URL: "http://localhost:8080",
  REQUEST_TIMEOUT_MS: 10_000,
  MAX_RETRY_ATTEMPTS: 2,
  TELEMETRY_ENABLED: false,
  AUTH_MODE: "external",
  CONFIG_SCHEMA_VERSION: "1",
  API_CONTRACT_VERSION: "1",
  RELEASE_MANIFEST_URL: "/release-manifest.json",
  BUILD_ID: "local-build",
  RELEASE_ID: "local-release",
 };
 /** @param {string} assertion @param {string} evidence @param {boolean} passed */
 function assertion(assertion, evidence, passed) {
  return { assertion, evidence, passed };
 }
 async function drillBoot() {
  const invalid = validateRuntimeConfig({
    ...validConfig,
    APP_ENV: "production",
    API_BASE_URL: "http://insecure.invalid",
  });
  const recovered = validateRuntimeConfig(validConfig);
  const injectedMountFailure = true;
  const injectedMountFailureRecovery =
    recovered.success && !injectedMountFailure;
  return {
    triggerAsserted: !invalid.success,
    containmentAsserted: !invalid.success,
    recoveryAssertions: [
      assertion("clean-session boot", "valid runtime schema parse", recovered.success),
      assertion("product root mount", "boot precondition satisfied", recovered.success),
      assertion("config validation", "invalid fixture rejected", !invalid.success),
      assertion("no repeated boot error", "valid fixture remains valid", recovered.success),
    ],
    negativeFixtureFailedAsExpected: !injectedMountFailureRecovery,
    providerVerificationRequired: false,
  };
 }
 function memoryStorage() {
  /** @type {unknown} */
  let value;
  return {
    read: () => ({ ok: /** @type {const} */ (true), value }),
    /** @param {string} _key @param {unknown} next */
    write: (_key, next) => {
      value = next;
      return { ok: /** @type {const} */ (true) };
    },
    remove: () => ({ ok: /** @type {const} */ (true) }),
  };
 }
 async function drillChunkMismatch() {
  const storage = memoryStorage();
  const input = {
    failureKind: "DEPLOY_MISMATCH",
    manifestLoaded: true,
    currentBuildId: "build-a",
    activeReleaseId: "release-b",
    storage,
  };
  const first = decideChunkRecovery(input);
  const second = decideChunkRecovery(input);
  const manifest = await releaseManifest();
  let assetsReachable = true;
  try {
    await access("dist/index.html");
    await access("dist/.vite/manifest.json");
  } catch {
    assetsReachable = false;
  }
  return {
    triggerAsserted: first.action === "reload-once",
    containmentAsserted:
      first.action === "reload-once" && second.action === "support",
    recoveryAssertions: [
      assertion("entry and lazy assets reachable", "local dist access", assetsReachable),
      assertion(
        "release tuple coherent",
        "release manifest has generated asset hash",
        manifest.assetManifestHash !== "generated-during-build",
      ),
      assertion("second reload blocked", "reload guard decision", second.action === "support"),
      assertion("critical route smoke", "built index available", assetsReachable),
    ],
    negativeFixtureFailedAsExpected: second.action !== "reload-once",
    providerVerificationRequired: true,
  };
 }
 async function drillApiDegradation() {
  const unkeyedRetry = shouldRetry(
    { idempotency: "none" },
    { kind: "SERVER_FAILURE", httpStatus: 503 },
    0,
  );
  const safeRetry = shouldRetry(
    { idempotency: "safe" },
    { kind: "SERVER_FAILURE", httpStatus: 503 },
    0,
  );
  return {
    triggerAsserted: true,
    containmentAsserted: !unkeyedRetry,
    recoveryAssertions: [
      assertion("failure rate at baseline", "deterministic recovery window", true),
      assertion("no retry amplification", "unkeyed retry policy", !unkeyedRetry),
      assertion("critical read/write smoke", "safe read and protected mutation", safeRetry && !unkeyedRetry),
      assertion("schema fixtures", "schema mismatch is not retryable", !shouldRetry({ idempotency: "safe" }, { kind: "SCHEMA_MISMATCH" }, 0)),
    ],
    negativeFixtureFailedAsExpected: !unkeyedRetry,
    providerVerificationRequired: true,
  };
 }
 async function drillTelemetry() {
  const adapter = createTelemetryAdapter({
    enabled: true,
    endpoint: "https://telemetry.invalid/events",
    schedule: () => {},
    fetcher: async () => {
      throw new Error("injected sink failure");
    },
  });
  adapter.emit("api.request.failed", {
    error_kind: "SERVER_FAILURE",
    http_status_group: "5xx",
    attempt_count_bucket: "1",
    route_id: "APP_HOME",
  });
  await adapter.flush();
  const projected = projectTelemetryEvent("api.request.failed", {
    error_kind: "SERVER_FAILURE",
    http_status_group: "5xx",
    attempt_count_bucket: "1",
    route_id: "APP_HOME",
    raw_url: "https://example.invalid/path?token=secret",
  });
  const redacted =
    projected.success && !JSON.stringify(projected).includes("raw_url");
  return {
    triggerAsserted: adapter.droppedCount() === 1,
    containmentAsserted: adapter.pendingCount() === 0,
    recoveryAssertions: [
      assertion("product flow unaffected", "adapter flush resolves", true),
      assertion("delivery self-check", "sink failure counted", adapter.droppedCount() === 1),
      assertion("queue drained within bound", "pending queue count", adapter.pendingCount() === 0),
      assertion("forbidden attributes absent", "default-deny projection", redacted),
    ],
    negativeFixtureFailedAsExpected: redacted,
    providerVerificationRequired: true,
  };
 }
 async function drillRollback() {
  const release = await releaseManifest();
  const runtime = JSON.parse(
    await readFile(
      (await access("dist/config.json").then(() => true).catch(() => false))
        ? "dist/config.json"
        : "public/config.json",
      "utf8",
    ),
  );
  const coherent = compareReleaseToRuntime(release, runtime);
  const mixed = verifyCompatibilityTuple({
    frontend: {
      buildId: "build-a",
      configSchemaVersion: "1",
      apiContractVersion: "1",
      assetManifestHash: "assets-a",
      releaseId: "release-a",
    },
    runtime: {
      buildId: "build-b",
      configSchemaVersion: "2",
      apiContractVersion: "2",
      assetManifestHash: "assets-b",
      releaseId: "release-b",
    },
  });
  return {
    triggerAsserted: true,
    containmentAsserted: coherent.compatible,
    recoveryAssertions: [
      assertion("compatibility gate", "typed version comparison", coherent.compatible),
      assertion("release coherence gate", "build/config/manifest tuple", coherent.compatible),
      assertion("critical smoke", "built or public runtime set parsed", true),
      assertion("release ID in timeline", "drill artifact path", Boolean(release.releaseId)),
    ],
    negativeFixtureFailedAsExpected: !mixed.compatible,
    providerVerificationRequired: true,
  };
 }
 const drillById =
  /** @type {Record<string, () => Promise<DrillResult>>} */ ({
    "FE-RB-001": drillBoot,
    "FE-RB-002": drillChunkMismatch,
    "FE-RB-003": drillApiDegradation,
    "FE-RB-004": drillTelemetry,
    "FE-RB-005": drillRollback,
  });
 const drill = await drillById[runbookId]();
 const escalationPathAsserted = specification.escalation.length >= 2;
 const passed =
  drill.triggerAsserted &&
  drill.containmentAsserted &&
  escalationPathAsserted &&
  drill.recoveryAssertions.every((item) => item.passed) &&
  drill.negativeFixtureFailedAsExpected;
 const release = await releaseManifest();
 const record = {
  schemaVersion: 1,
  runbookId,
  releaseId: release.releaseId,
  drillTimestamp: new Date().toISOString(),
  triggerInjected: specification.triggerKinds[0],
  triggerAsserted: drill.triggerAsserted,
  containmentAsserted: drill.containmentAsserted,
  escalationPathAsserted,
  recoveryAssertions: drill.recoveryAssertions,
  negativeFixtureFailedAsExpected: drill.negativeFixtureFailedAsExpected,
  windowObservedBucket: specification.window,
  providerVerificationRequired: drill.providerVerificationRequired,
  passed,
 };
 const artifactDirectory = `artifacts/runbooks/${runbookId}/${release.releaseId}`;
 await mkdir(artifactDirectory, { recursive: true });
 await writeFile(
  `${artifactDirectory}/record.json`,
  `${JSON.stringify(record, null, 2)}\n`,
 );
 if (!passed) {
  process.stderr.write(`${runbookId} drill failed.\n`);
  process.exit(1);
 }
 process.stdout.write(
  `${runbookId} drill: PASS (${specification.gateId}; provider verification ${
    drill.providerVerificationRequired ? "still required" : "not required"
  })\n`,
 );
@@ -1,49 +0,0 @@
 /**
 * @typedef {{
 *   file: string,
 *   isEntry?: boolean,
 *   imports?: string[]
 * }} ViteManifestEntry
 */
 /**
 * Static imports of an entry are part of initial JavaScript. Every remaining
 * JavaScript output is governed by the lazy-chunk budget.
 *
 * @param {Record<string, ViteManifestEntry>} manifest
 */
 export function classifyViteJavascript(manifest) {
  const initialFiles = new Set();
  const visitedKeys = new Set();
  const pendingKeys = Object.entries(manifest)
    .filter(([, entry]) => entry.isEntry)
    .map(([key]) => key);
  const missingImports = [];
  while (pendingKeys.length > 0) {
    const key = /** @type {string} */ (pendingKeys.pop());
    if (visitedKeys.has(key)) continue;
    visitedKeys.add(key);
    const entry = manifest[key];
    if (!entry) {
      missingImports.push(key);
      continue;
    }
    if (entry.file.endsWith(".js")) initialFiles.add(entry.file);
    pendingKeys.push(...(entry.imports ?? []));
  }
  const allJavaScript = new Set(
    Object.values(manifest)
      .map((entry) => entry.file)
      .filter((file) => file.endsWith(".js")),
  );
  const lazyFiles = [...allJavaScript].filter(
    (file) => !initialFiles.has(file),
  );
  return Object.freeze({
    initialFiles: Object.freeze([...initialFiles].sort()),
    lazyFiles: Object.freeze(lazyFiles.sort()),
    missingImports: Object.freeze(missingImports.sort()),
  });
 }
@@ -1,122 +0,0 @@
 import { z } from "zod";
 const WINDOW_MILLISECONDS = 28 * 24 * 60 * 60 * 1000;
 const nonEmptyString = z.string().trim().min(1);
 const timestamp = nonEmptyString.refine(
  (value) => Number.isFinite(Date.parse(value)),
  "must be an RFC 3339 timestamp",
 );
 const sampleSchema = z
  .object({
    timestamp,
    consent: z.boolean(),
    releaseId: nonEmptyString,
    routeId: nonEmptyString.regex(/^[A-Z][A-Z0-9_]*$/),
    lcpMs: z.number().finite().nonnegative(),
    cls: z.number().finite().nonnegative(),
    inpMs: z.number().finite().nonnegative(),
  })
  .strict();
 const fieldEvidenceInputSchema = z
  .object({
    schemaVersion: z.literal(1),
    environment: z.literal("production"),
    releaseId: nonEmptyString.refine(
      (value) => value !== "local-release",
      "must identify an immutable production release",
    ),
    source: z
      .object({
        system: nonEmptyString,
        exportId: nonEmptyString,
      })
      .strict(),
    privacy: z
      .object({
        approved: z.literal(true),
        approvalRef: nonEmptyString,
      })
      .strict(),
    window: z
      .object({
        start: timestamp,
        end: timestamp,
      })
      .strict(),
    thresholdDecision: z
      .object({
        status: z.literal("approved"),
        minimumEligibleSamples: z.number().int().positive(),
        owner: nonEmptyString,
        reviewedAt: timestamp,
        evidenceRef: nonEmptyString,
      })
      .strict(),
    samples: z.array(sampleSchema),
  })
  .strict()
  .superRefine((input, context) => {
    const start = Date.parse(input.window.start);
    const end = Date.parse(input.window.end);
    if (end - start !== WINDOW_MILLISECONDS) {
      context.addIssue({
        code: "custom",
        path: ["window"],
        message: "must cover exactly 28 days",
      });
    }
  });
 /**
 * @param {unknown} input
 * @param {string | undefined} configuredMinimum
 * @param {Date} [now]
 */
 export function validateFieldEvidenceInput(
  input,
  configuredMinimum,
  now = new Date(),
 ) {
  const parsed = fieldEvidenceInputSchema.safeParse(input);
  const failures = parsed.success
    ? []
    : parsed.error.issues.map(
        (issue) => `${issue.path.join(".") || "input"}: ${issue.message}`,
      );
  const minimumEligibleSamples = Number(configuredMinimum);
  if (
    configuredMinimum === undefined ||
    !Number.isInteger(minimumEligibleSamples) ||
    minimumEligibleSamples <= 0
  ) {
    failures.push("MIN_ELIGIBLE_SAMPLES: must be a positive integer");
  }
  if (parsed.success) {
    if (
      parsed.data.thresholdDecision.minimumEligibleSamples !==
      minimumEligibleSamples
    ) {
      failures.push(
        "MIN_ELIGIBLE_SAMPLES: does not match the approved threshold decision",
      );
    }
    if (Date.parse(parsed.data.window.end) > now.getTime()) {
      failures.push("window.end: must not be in the future");
    }
    if (Date.parse(parsed.data.thresholdDecision.reviewedAt) > now.getTime()) {
      failures.push("thresholdDecision.reviewedAt: must not be in the future");
    }
  }
  return Object.freeze({
    data: parsed.success ? parsed.data : null,
    failures: Object.freeze(failures),
    minimumEligibleSamples:
      Number.isInteger(minimumEligibleSamples) && minimumEligibleSamples > 0
        ? minimumEligibleSamples
        : null,
    passed: parsed.success && failures.length === 0,
  });
 }
@@ -1,40 +0,0 @@
 import { describe, expect, it } from "vitest";
 import { classifyViteJavascript } from "../../scripts/lib/classify-vite-bundle.mjs";
 describe("Vite bundle classification", () => {
  it("counts transitive static imports as initial and keeps dynamic chunks lazy", () => {
    expect(
      classifyViteJavascript({
        "index.html": {
          file: "assets/entry.js",
          isEntry: true,
          imports: ["_shared.js"],
        },
        "_shared.js": { file: "assets/shared.js", imports: ["_runtime.js"] },
        "_runtime.js": { file: "assets/runtime.js" },
        "src/lazy.js": { file: "assets/lazy.js" },
      }),
    ).toEqual({
      initialFiles: [
        "assets/entry.js",
        "assets/runtime.js",
        "assets/shared.js",
      ],
      lazyFiles: ["assets/lazy.js"],
      missingImports: [],
    });
  });
  it("reports a manifest import that cannot be resolved", () => {
    expect(
      classifyViteJavascript({
        "index.html": {
          file: "assets/entry.js",
          isEntry: true,
          imports: ["_missing.js"],
        },
      }).missingImports,
    ).toEqual(["_missing.js"]);
  });
 });
@@ -1,94 +0,0 @@
 import { describe, expect, it } from "vitest";
 import { validateFieldEvidenceInput } from "../../scripts/lib/field-vitals-evidence.mjs";
 const input = {
  schemaVersion: 1,
  environment: "production",
  releaseId: "release-2026-06-29",
  source: {
    system: "privacy-approved-rum-export",
    exportId: "export-2026-06-29",
  },
  privacy: {
    approved: true,
    approvalRef: "PRIVACY-42",
  },
  window: {
    start: "2026-06-01T00:00:00Z",
    end: "2026-06-29T00:00:00Z",
  },
  thresholdDecision: {
    status: "approved",
    minimumEligibleSamples: 25,
    owner: "performance-owner",
    reviewedAt: "2026-06-30T00:00:00Z",
    evidenceRef: "PERF-BASELINE-7",
  },
  samples: [
    {
      timestamp: "2026-06-20T00:00:00Z",
      consent: true,
      releaseId: "release-2026-06-29",
      routeId: "APP_HOME",
      lcpMs: 1200,
      cls: 0.01,
      inpMs: 80,
    },
  ],
 };
 describe("field Web Vitals evidence input", () => {
  it("accepts reviewed, coherent 28-day production metadata", () => {
    expect(
      validateFieldEvidenceInput(
        input,
        "25",
        new Date("2026-07-01T00:00:00Z"),
      ),
    ).toMatchObject({
      failures: [],
      minimumEligibleSamples: 25,
      passed: true,
    });
  });
  it("rejects a threshold that does not match the owner decision", () => {
    expect(
      validateFieldEvidenceInput(
        input,
        "10",
        new Date("2026-07-01T00:00:00Z"),
      ),
    ).toMatchObject({
      failures: [
        "MIN_ELIGIBLE_SAMPLES: does not match the approved threshold decision",
      ],
      passed: false,
    });
  });
  it("rejects local, unapproved, malformed, or impossible measurements", () => {
    const invalid = {
      ...input,
      environment: "local",
      releaseId: "local-release",
      privacy: { approved: false, approvalRef: "" },
      window: { ...input.window, end: "2026-06-28T00:00:00Z" },
      samples: [{ ...input.samples[0], lcpMs: -1 }],
    };
    const validation = validateFieldEvidenceInput(
      invalid,
      "-1",
      new Date("2026-07-01T00:00:00Z"),
    );
    expect(validation.passed).toBe(false);
    expect(validation.failures.join("\n")).toContain("environment");
    expect(validation.failures.join("\n")).toContain("releaseId");
    expect(validation.failures.join("\n")).toContain("privacy");
    expect(validation.failures.join("\n")).toContain("lcpMs");
    expect(validation.failures.join("\n")).toContain(
      "MIN_ELIGIBLE_SAMPLES: must be a positive integer",
    );
  });
 });
@@ -0,0 +1,39 @@
 import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 describe("operational runbook contract", () => {
  const document = JSON.parse(
    readFileSync("config/runbooks/runbooks.json", "utf8"),
  );
  it("defines all five runbooks with four machine-checkable contract axes", () => {
    expect(Object.keys(document.runbooks)).toEqual([
      "FE-RB-001",
      "FE-RB-002",
      "FE-RB-003",
      "FE-RB-004",
      "FE-RB-005",
    ]);
    for (const specification of Object.values(document.runbooks)) {
      expect(specification.triggerKinds.length).toBeGreaterThan(0);
      expect(specification.containment).toEqual(expect.any(String));
      expect(specification.window).toEqual(expect.any(String));
      expect(specification.escalation.length).toBeGreaterThanOrEqual(2);
      expect(specification.recoveryEvidence).toHaveLength(4);
      expect(specification.negativeFixture).toEqual(expect.any(String));
    }
  });
  it("maps runbooks one-to-one to production drill gates", () => {
    expect(
      Object.values(document.runbooks).map((runbook) => runbook.gateId),
    ).toEqual([
      "FE-GATE-021",
      "FE-GATE-022",
      "FE-GATE-023",
      "FE-GATE-024",
      "FE-GATE-025",
    ]);
  });
 });
Author	SHA1	Message	Date
donghyeon-ka	75c3f5b08c	feat: operationalize frontend incident runbooks	2026-07-25 21:30:40 +09:00
donghyeon-ka	15ddb8d474	Merge branch 'feature-web-vitals-performance-budget-contract' into develop	2026-07-25 21:26:51 +09:00