Files
tech-log-frontend/scripts/drill-runbook.ts
T
DongHyeonka c80320dfc7 chore: sync the frontend template from ebea300 to af3d8e6
Carries 359 template commits, tag v0.2.0 plus one documentation commit: the
generator-built feature index with its app, bounded-context and feature
declarations, the src/platform kernel and scale tooling, the 2026-09-24 src
review fixes, and the 2026-09-25 maturity review round with its CHANGELOG
[보안]/[계약] rows. 691 of the 824 template paths are applied, 85 of them
merged with product changes; 127 are not carried.

Product identity is unchanged: name, version 0.1.0, routes, design and the
TechLog domain.

Three decisions worth naming. TechLog stays composed directly, as the last
two syncs recorded; its directory carries a NOT_INSTALLED marker that says so,
and every installed-* composer takes the template's projection with TechLog
added on top. The reference sample is no longer installed: the template now
installs a feature only through feature-module.ts and context-routes.ts,
which load the screens this product deleted, so its three operations, six
schemas and one topic leave the registries, recorded as registry change
evidence. And AppRouter mounts the platform and TechLog routes only; the
template's bounded-context route gateway waits for a generator-installed
feature.

Required fixes: readSubject on the BFF session owner (without it every HTTP
Studio session would close as integration-failed), zod through the facade in
nine TechLog files, noUnusedLocals, and public/config.json written out to
match the local profile. Derived baselines were recomputed after reproducing
both sides' values: CI contract 101 commands / 106 references / 141
artifacts, gate shape c9adcf85; registry approval 2dc6c3a3; the runtime
config schema baseline equals the schema at 8210d48.

Verified here: types, lint, architecture, adapter inventory, CI contract,
i18n, design system, diagnostics, browser security, dev release manifest,
TechLog contract and build pass; 220 component, 155 integration, 15
contract, 418 TechLog, 43 reference-feature, 18 recipe and 46
release-coherence tests pass, and 2381 of 2383 unit tests. Reproduced at
8210d48 first and unchanged: check:registries (byte-identical),
test:runtime-schema, verify:documentation. Brought by the template and
escalated rather than suppressed: check:request-fanout on TechLog's cursor
pagination, check:remediation-ledger (fails upstream too), the shared-chunk
hash test, and the registry-dependent sample removal and second-feature
tests. Playwright suites were not run.

Full record, the five open questions and the follow-ups in
docs/operations/template-sync-2026-09-29.md.

(cherry picked from commit b2170cf265dea45dc9cc05d3c61e627e97f31cdb)
2026-11-12 08:28:54 +09:00

502 lines
18 KiB
TypeScript

import { access, mkdir, readFile } from "node:fs/promises";
import path from "node:path";
import { pathToFileURL } from "node:url";
import { shouldRetry } from "../src/adapters/http/retry-policy.ts";
import { createTelemetryAdapter } from "../src/adapters/telemetry/best-effort-telemetry.ts";
import { verifyCompatibilityTuple } from "../src/contracts/compatibility.ts";
import type { StoragePort } from "../src/application/ports/storage-port.ts";
import { decideChunkRecovery } from "../src/application/use-cases/decide-chunk-recovery.ts";
import { validateRuntimeConfig } from "../src/bootstrap/runtime-config-schema.ts";
import type { InstalledContractPackageIdentity } from "../src/contracts/external-contract-runtime.ts";
import {
parseReleaseArtifact,
parseRuntimeConfigArtifact,
} from "../src/contracts/release-artifacts.ts";
import { projectTelemetryEvent } from "../src/contracts/telemetry.ts";
import { EXPECTED_CONTRACT_SET_PACKAGES } from "../src/features/installed-contract-contributions.ts";
import {
combineDrillVerdicts,
runbookRecordArtifactSchema,
type DrillVerdict,
} from "./contracts/release-artifacts.ts";
import { verifyReleaseRuntimeCoherence } from "./lib/release-runtime-coherence.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
// 11-01 / 13-03 (D-14). A verdict is PASS or FAIL only when the drill observed
// it on the local build. What needs a browser boot, live traffic or the hosting
// provider is UNVERIFIED, and so is every drill whose runbook needs provider
// verification: a local drill never claims the release can be recovered.
type RecoveryAssertion = Readonly<{
assertion: string;
evidence: string;
result: DrillVerdict;
}>;
type DrillResult = Readonly<{
triggerAsserted: DrillVerdict;
containmentAsserted: DrillVerdict;
recoveryAssertions: RecoveryAssertion[];
negativeFixtureFailedAsExpected: DrillVerdict;
providerVerificationRequired: boolean;
}>;
type RunbookSpecification = Readonly<{
title: string;
gateId: string;
triggerKinds: string[];
containment: string;
window: string;
escalation: string[];
recoveryEvidence: string[];
negativeFixture: string;
}>;
type RunbookDocument = Readonly<{
runbooks: Record<string, RunbookSpecification>;
}>;
export type JsonArtifactReader = (path: string) => Promise<unknown>;
export type RollbackArtifactPaths = Readonly<{
release: string;
runtime: string;
}>;
export type RollbackCoherenceOptions = Readonly<{
readArtifact?: JsonArtifactReader;
contractPackages?: readonly InstalledContractPackageIdentity[];
paths?: RollbackArtifactPaths;
}>;
export type DrillOptions = Readonly<{
/**
* Directory holding the release's `dist/`. Defaults to the cwd (the local
* build). 13-04: pass an extracted candidate or promoted archive to drill
* the release that is actually deployed or rolled back to.
*/
releaseRoot?: string;
contractPackages?: readonly InstalledContractPackageIdentity[];
}>;
type DrillContext = Readonly<{
root: string;
contractPackages: readonly InstalledContractPackageIdentity[];
}>;
// 13-03: the drill reads the built release only. It used to fall back to the
// placeholders in public/, so it passed without any build at all.
const DEFAULT_ROLLBACK_PATHS = Object.freeze({
release: "dist/release-manifest.json",
runtime: "dist/config.json",
});
async function readJsonArtifact(path: string): Promise<unknown> {
try {
return JSON.parse(await readFile(path, "utf8"));
} catch (error) {
if (hasErrorCode(error, "ENOENT")) {
throw new Error(`${path} is missing; build the release before running the drill`, { cause: error });
}
throw error;
}
}
function rootedReader(root: string): JsonArtifactReader {
return (file) => readJsonArtifact(path.join(root, file));
}
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",
};
function verdict(passed: boolean): DrillVerdict {
return passed ? "PASS" : "FAIL";
}
function assertion(
assertion: string,
evidence: string,
result: DrillVerdict,
): RecoveryAssertion {
return { assertion, evidence, result };
}
/** An assertion the local drill cannot observe; `needs` names what can. */
function notObserved(name: string, needs: string): RecoveryAssertion {
return assertion(name, `not observed locally; needs ${needs}`, "UNVERIFIED");
}
/**
* Every file the Vite manifest names (entries, lazy chunks, CSS, assets) exists
* in the local dist. Hosting reachability still needs the provider smoke.
*/
async function builtAssetsPresent(root: string): Promise<boolean> {
const manifest = await readJsonArtifact(path.join(root, "dist/.vite/manifest.json"));
if (!manifest || typeof manifest !== "object") return false;
const files = new Set<string>();
for (const chunk of Object.values(manifest as Record<string, Record<string, unknown>>)) {
for (const key of ["file", "css", "assets"] as const) {
const value = chunk[key];
for (const file of Array.isArray(value) ? value : [value]) {
if (typeof file === "string") files.add(file);
}
}
}
if (![...files].some((file) => file.endsWith(".js"))) return false;
try {
await Promise.all(
["index.html", ...files].map((file) => access(path.join(root, "dist", file))),
);
return true;
} catch {
return false;
}
}
async function drillBoot(): Promise<DrillResult> {
const invalid = validateRuntimeConfig({
...validConfig,
APP_ENV: "production",
API_BASE_URL: "http://insecure.invalid",
});
const recovered = validateRuntimeConfig(validConfig);
return {
triggerAsserted: verdict(!invalid.success),
containmentAsserted: verdict(!invalid.success),
recoveryAssertions: [
notObserved("clean-session boot", "a browser boot of the promoted release"),
notObserved("product root mount", "a browser boot of the promoted release"),
assertion(
"config validation",
"invalid fixture rejected, valid fixture accepted",
verdict(!invalid.success && recovered.success),
),
notObserved("no repeated boot error", "boot telemetry from the promoted release"),
],
// The runbook's negative fixture injects a mount failure after a valid
// config; that needs a mounted app, which a Node drill does not have.
negativeFixtureFailedAsExpected: "UNVERIFIED",
providerVerificationRequired: false,
};
}
function memoryStorage(): StoragePort {
let value: unknown;
return {
read: () => ({ ok: true, value }),
write: (_key: string, next: unknown) => {
value = next;
return { ok: true };
},
remove: () => ({ ok: true }),
};
}
async function drillChunkMismatch(context: DrillContext): Promise<DrillResult> {
const storage = memoryStorage();
const input: Parameters<typeof decideChunkRecovery>[0] = {
failureKind: "DEPLOY_MISMATCH",
manifestLoaded: true,
currentBuildId: "build-a",
currentReleaseId: "release-a",
activeBuildId: "build-b",
activeReleaseId: "release-b",
storage,
};
const first = decideChunkRecovery(input);
const second = decideChunkRecovery(input);
const { coherence } = await verifyRollbackReleaseCoherence({
readArtifact: rootedReader(context.root),
contractPackages: context.contractPackages,
});
return {
triggerAsserted: verdict(first.action === "reload-once"),
containmentAsserted: verdict(
first.action === "reload-once" && second.action === "support",
),
recoveryAssertions: [
assertion(
"entry and lazy assets reachable",
"every Vite manifest file exists in the local dist",
verdict(await builtAssetsPresent(context.root)),
),
assertion("release tuple coherent", "build/config/manifest tuple", verdict(coherence.compatible)),
assertion("second reload blocked", "reload guard decision", verdict(second.action === "support")),
notObserved("critical route smoke", "a browser smoke against the hosted release"),
],
negativeFixtureFailedAsExpected: verdict(second.action !== "reload-once"),
providerVerificationRequired: true,
};
}
async function drillApiDegradation(): Promise<DrillResult> {
const unkeyedRetry = shouldRetry(
{ idempotency: "none" },
{ kind: "SERVER_FAILURE", httpStatus: 503 },
0,
);
const safeRetry = shouldRetry(
{ idempotency: "safe" },
{ kind: "SERVER_FAILURE", httpStatus: 503 },
0,
);
return {
// The trigger is a failure rate over live traffic.
triggerAsserted: "UNVERIFIED",
containmentAsserted: verdict(!unkeyedRetry && safeRetry),
recoveryAssertions: [
notObserved("terminal failure rate at baseline", "API failure telemetry from the promoted release"),
assertion("no retry amplification", "unkeyed retry policy", verdict(!unkeyedRetry)),
notObserved("critical read/write smoke", "a read and a write against the live API"),
assertion(
"schema fixtures",
"schema mismatch is not retryable",
verdict(!shouldRetry({ idempotency: "safe" }, { kind: "SCHEMA_MISMATCH" }, 0)),
),
],
negativeFixtureFailedAsExpected: verdict(!unkeyedRetry),
providerVerificationRequired: true,
};
}
async function drillTelemetry(): Promise<DrillResult> {
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",
});
const flushResolved = await adapter.flush().then(
() => true,
() => false,
);
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: verdict(adapter.droppedCount() === 1),
containmentAsserted: verdict(adapter.pendingCount() === 0),
recoveryAssertions: [
assertion("product flow unaffected", "adapter flush resolves despite the sink failure", verdict(flushResolved)),
assertion("delivery self-check", "sink failure counted", verdict(adapter.droppedCount() === 1)),
assertion("queue drained within bound", "pending queue count", verdict(adapter.pendingCount() === 0)),
assertion("forbidden attributes absent", "default-deny projection", verdict(redacted)),
],
negativeFixtureFailedAsExpected: verdict(redacted),
providerVerificationRequired: true,
};
}
async function drillRollback(context: DrillContext): Promise<DrillResult> {
const { release, coherence: coherent } = await verifyRollbackReleaseCoherence({
readArtifact: rootedReader(context.root),
contractPackages: context.contractPackages,
});
const assetsPresent = await builtAssetsPresent(context.root);
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 {
// A release-blocking defect is declared by a person during an incident.
triggerAsserted: "UNVERIFIED",
containmentAsserted: verdict(coherent.compatible && assetsPresent),
recoveryAssertions: [
assertion("compatibility gate", "typed version comparison", verdict(coherent.compatible)),
assertion(
"release coherence gate",
"build/config/manifest tuple and every Vite manifest file in the local dist",
verdict(coherent.compatible && assetsPresent),
),
notObserved("critical smoke", "a browser smoke after the provider switches to the prior release"),
assertion("release ID in timeline", "drill record releaseId", verdict(Boolean(release.releaseId))),
],
negativeFixtureFailedAsExpected: verdict(!mixed.compatible),
providerVerificationRequired: true,
};
}
const drillById: Record<string, (context: DrillContext) => Promise<DrillResult>> = {
"FE-RB-001": drillBoot,
"FE-RB-002": drillChunkMismatch,
"FE-RB-003": drillApiDegradation,
"FE-RB-004": drillTelemetry,
"FE-RB-005": drillRollback,
};
export async function verifyRollbackReleaseCoherence(
options: RollbackCoherenceOptions = {},
) {
const readArtifact = options.readArtifact ?? readJsonArtifact;
const paths = options.paths ?? DEFAULT_ROLLBACK_PATHS;
const [releaseValue, runtimeValue] = await Promise.all([
readArtifact(paths.release),
readArtifact(paths.runtime),
]);
const release = parseReleaseArtifact(releaseValue);
const runtimeArtifact = parseRuntimeConfigArtifact(runtimeValue);
const runtime = {
...runtimeArtifact,
BUILD_ID: requireIdentity(runtimeArtifact.BUILD_ID, "runtime BUILD_ID"),
RELEASE_ID: requireIdentity(
runtimeArtifact.RELEASE_ID,
"runtime RELEASE_ID",
),
};
const coherence = await verifyReleaseRuntimeCoherence({
release,
runtime,
contractPackages:
options.contractPackages ?? EXPECTED_CONTRACT_SET_PACKAGES,
});
return Object.freeze({ release, runtime, coherence });
}
export async function runRunbookDrill(runbookId: string, options: DrillOptions = {}) {
const context: DrillContext = {
root: options.releaseRoot ?? process.cwd(),
contractPackages: options.contractPackages ?? EXPECTED_CONTRACT_SET_PACKAGES,
};
const document = JSON.parse(
await readFile("config/runbooks/runbooks.json", "utf8"),
) as RunbookDocument;
const specification = document.runbooks[runbookId];
const drill = drillById[runbookId];
if (!specification || !drill) throw new RangeError(`unknown runbook: ${runbookId}`);
const release = parseReleaseArtifact(
await rootedReader(context.root)(DEFAULT_ROLLBACK_PATHS.release),
);
const result = await drill(context);
const escalationPathAsserted = verdict(specification.escalation.length >= 2);
return {
schemaVersion: 2 as const,
runbookId,
gateId: specification.gateId,
releaseId: release.releaseId,
drillTimestamp: new Date().toISOString(),
triggerInjected: specification.triggerKinds[0] ?? "",
triggerAsserted: result.triggerAsserted,
containmentAsserted: result.containmentAsserted,
escalationPathAsserted,
recoveryAssertions: result.recoveryAssertions,
negativeFixtureFailedAsExpected: result.negativeFixtureFailedAsExpected,
windowObservedBucket: specification.window,
providerVerificationRequired: result.providerVerificationRequired,
result: combineDrillVerdicts(
[
result.triggerAsserted,
result.containmentAsserted,
escalationPathAsserted,
...result.recoveryAssertions.map((item) => item.result),
result.negativeFixtureFailedAsExpected,
],
result.providerVerificationRequired,
),
};
}
async function main(): Promise<void> {
const runbookId = process.argv
.slice(2)
.find((argument) => /^FE-RB-00[1-5]$/.test(argument));
const releaseRootFlag = process.argv.indexOf("--release-root");
const releaseRoot = releaseRootFlag >= 0 ? process.argv[releaseRootFlag + 1] : undefined;
if (!runbookId || (releaseRootFlag >= 0 && !releaseRoot)) {
process.stderr.write(
"Usage: drill:runbook -- FE-RB-001..FE-RB-005 [--release-root <extracted release archive>]\n",
);
process.exit(2);
}
const { gateId, ...record } = await runRunbookDrill(runbookId, releaseRoot ? { releaseRoot } : {});
const artifactDirectory = `artifacts/runbooks/${runbookId}`;
await mkdir(artifactDirectory, { recursive: true });
await writeValidatedJsonArtifact({
path: `${artifactDirectory}/record.json`,
schema: runbookRecordArtifactSchema,
value: record,
});
if (record.result === "FAIL") {
process.stderr.write(`${runbookId} drill: FAIL (${gateId})\n`);
process.exit(1);
}
if (record.result === "UNVERIFIED") {
// Not a pass: the gate stays red until provider evidence exists (D-14).
const open = [
["trigger", record.triggerAsserted],
["containment", record.containmentAsserted],
...record.recoveryAssertions.map((item) => [item.assertion, item.result] as const),
["negative fixture", record.negativeFixtureFailedAsExpected],
["provider verification", record.providerVerificationRequired ? "UNVERIFIED" : "PASS"],
].filter(([, result]) => result === "UNVERIFIED").map(([name]) => name);
process.stderr.write(
`${runbookId} drill: UNVERIFIED (${gateId}; no local check failed; not observed locally: ${open.join(", ")})\n`,
);
process.exit(3);
}
process.stdout.write(`${runbookId} drill: PASS (${gateId})\n`);
}
function requireIdentity(value: string | undefined, label: string): string {
if (value === undefined || value.length === 0) {
throw new TypeError(`${label} must be a non-empty string`);
}
return value;
}
function hasErrorCode(error: unknown, code: string): boolean {
return Boolean(
error &&
typeof error === "object" &&
"code" in error &&
error.code === code,
);
}
const invokedPath = process.argv[1];
if (
invokedPath !== undefined &&
import.meta.url === pathToFileURL(invokedPath).href
) {
await main();
}