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)
This commit is contained in:
DongHyeonka
2026-11-12 08:28:54 +09:00
parent 585c62431a
commit c80320dfc7
738 changed files with 55027 additions and 13567 deletions
+148 -160
View File
@@ -4,8 +4,8 @@ import path from "node:path";
import { z } from "zod";
import { PROMOTION_FORMULA } from "../../src/application/policies/promotion-readiness.ts";
import { MANUAL_A11Y_ROUTE_IDS } from "../lib/manual-a11y-evidence.ts";
import { PROMOTION_FORMULA } from "../lib/promotion-readiness.ts";
import {
RELEASE_CANDIDATE_EVIDENCE_PATHS,
RELEASE_CANDIDATE_MANIFEST_PATH,
@@ -439,56 +439,42 @@ export type CiGateContractIndex = Readonly<{
jobs: ReadonlyMap<string, CiWorkflowJob>;
retentionClasses: ReadonlyMap<string, CiGateContract["retention"]["classes"][number]>;
}>;
export type LoadCiGateContractOptions = Readonly<{
mode?: "canonical" | "removal-fixture";
}>;
const CANONICAL_GATE_SHAPE_SHA256 =
// 환경 구성(SETUP) 문서 종류: FE-GATE-009 가 TECH_LOG_SETUP 수동 접근성 증거를 얻어 다시
// 계산했다. 같은 방법이다 — 이전 상수 e4e61b06… 을 이전 gates.json 에서 먼저 재현해
// 계산이 맞는지 확인한 뒤 새 파일을 해싱했다.
// 개념(CONCEPT) 문서 종류: FE-GATE-009 가 TECH_LOG_CONCEPT 수동 접근성 증거를 얻어 다시 계산했다.
// 같은 방법으로 — 옛 gates.json 에서 이전 상수 fb138e7c… 를 먼저 재현해 계산이 맞는지
// 확인한 뒤 새 파일을 해싱했다.
// Template merge. Both sides carried a digest of their own gate set; neither
// describes the merged one. Recomputed from the merged config/ci/gates.json.
// Task 11: recomputed again after FE-GATE-009 gained the
// TECH_LOG_STUDIO_ASSETS manual accessibility evidence artifact.
// Final fix wave item 1: recomputed again after FE-GATE-010 gained
// `check-tech-log-contract`. Recomputed with `canonicalGateShapeSha256`
// below, verified by first reproducing the previous constant from the
// previous `config/ci/gates.json` before hashing the new one.
// Alignment follow-up item 2: recomputed again after FE-GATE-007 gained
// `test-tech-log` and its junit evidence, by the same method — the previous
// constant f3cc9075… was reproduced from the previous gates.json first, so
// the transcription that produced this value is known to be the real one.
// Dev release manifest drift fix, item 2: recomputed again after FE-GATE-010
// gained `check-dev-release-manifest`. Same method — 98d19911… was first
// reproduced from the previous gates.json before this value was hashed.
// Taxonomy route: recomputed again after FE-GATE-009 gained the
// TECH_LOG_STUDIO_TAXONOMY manual accessibility evidence artifact. The gate
// lists one evidence artifact per installed route and refuses a set that does
// not match the route scope exactly, so adding a route necessarily moves this
// digest — that is the point of pinning it.
// Release authoring: recomputed again after FE-GATE-009 gained the
// TECH_LOG_STUDIO_RELEASES evidence artifact, by the same method — 8c73d447…
// was first reproduced from the previous gates.json, so the computation that
// produced this value is known to be the one the constant was pinned under.
// 프로젝트 편집 화면: FE-GATE-009 가 TECH_LOG_STUDIO_PROJECT_EDIT 증거 아티팩트를
// 얻어 다시 계산했다. 같은 방법이다 — 187dbd96… 을 이전 gates.json 에서 먼저 재현해,
// 이 값을 만든 계산이 상수가 고정될 때 쓰인 그 계산임을 확인했다.
// 릴리즈 편집 화면: 같은 방법으로 다시 계산했다. f9e7e521… 을 이전 gates.json 에서 먼저
// 재현했다.
// 주제 화면 셋(`/topics`, `/topics/:slug/:variant`, `/studio/topics/:id`): FE-GATE-009 가 각
// 라우트의 수동 접근성 증거를 얻어 다시 계산했다. 같은 방법이다 — 87a22f68… 을 이전
// gates.json 에서 먼저 재현해 계산이 맞는지 확인한 뒤 새 파일을 해싱했다.
// Template sync (ebea300). Both sides again carried a digest of their own
// gate set — 8a1a5479… here, 43dc4ed1… upstream — and neither describes the
// merged config/ci/gates.json. Recomputed from the merged file by the same
// method: 8a1a5479… was first reproduced from the pre-merge gates.json, so
// the computation that produced this value is the one the constant is
// pinned under.
"629e5898f6a38d5056fc6a4bee834c47f363669ce9925a2c0dabeddd64d11879";
/**
* D-14. FE-GATE-016 (rollback-drill) ran the same FE-RB-005 drill as
* FE-GATE-025 and counted it twice toward production readiness. Its id stays
* retired so no later gate reuses it with a different meaning.
*/
export const RETIRED_GATE_IDS: readonly string[] = Object.freeze(["FE-GATE-016"]);
export const CANONICAL_GATE_IDS: readonly string[] = Object.freeze(
Array.from({ length: 28 }, (_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`)
.filter((gateId) => !RETIRED_GATE_IDS.includes(gateId)),
);
/**
* D-13. The contract's size and gate shape are a reviewed baseline, not code
* constants: a project that removes a sample or adds a gate records the new
* shape with `update:ci-contract-baseline` (owner and reason required) and the
* diff of this file is what review sees.
*/
export const CI_CONTRACT_BASELINE_PATH = "config/ci/contract-baseline.json";
const ciContractBaselineSchema = z
.object({
schemaVersion: z.literal(1),
owner: nonEmpty,
reason: nonEmpty,
gates: z.number().int().nonnegative(),
commands: z.number().int().nonnegative(),
commandReferences: z.number().int().nonnegative(),
artifacts: z.number().int().nonnegative(),
stages: z.number().int().nonnegative(),
gateShapeSha256: z.string().regex(/^[0-9a-f]{64}$/u),
})
.strict();
export type CiContractBaseline = z.infer<typeof ciContractBaselineSchema>;
function canonicalGateShapeSha256(gates: CiGateContract["gates"]): string {
const normalized = gates.map(
@@ -513,57 +499,52 @@ function canonicalGateShapeSha256(gates: CiGateContract["gates"]): string {
return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
}
function canonicalAuthorityBaselineFailures(contract: CiGateContract): string[] {
const failures: string[] = [];
const commandReferenceCount = contract.gates.reduce(
(total, gate) => total + gate.commandIds.length,
0,
export function measureCiContractBaseline(
contract: CiGateContract,
): Omit<CiContractBaseline, "schemaVersion" | "owner" | "reason"> {
return {
gates: contract.gates.length,
commands: contract.commands.length,
commandReferences: contract.gates.reduce(
(total, gate) => total + gate.commandIds.length,
0,
),
artifacts: contract.artifacts.length,
stages: contract.stages.length,
gateShapeSha256: canonicalGateShapeSha256(contract.gates),
};
}
async function assertCiContractBaseline(
root: string,
contract: CiGateContract,
): Promise<void> {
const parsed = ciContractBaselineSchema.safeParse(
JSON.parse(await readFile(path.join(root, CI_CONTRACT_BASELINE_PATH), "utf8")),
);
if (contract.gates.length !== 27) {
failures.push(`gate authority baseline must contain exactly 27 gates; received ${contract.gates.length}`);
}
// Final fix wave, item 1: FE-GATE-010 gained `check-tech-log-contract`, the
// drift gate that pins the vendored canonical Studio contract to its digest.
// Until it was referenced by a gate it ran only when typed by hand.
// Alignment follow-up, item 2: FE-GATE-007 gained `test-tech-log`. The suite
// already ran inside `test:coverage`'s combined vitest invocation, so a
// TechLog failure was reported as a coverage-gate failure with no junit of
// its own to name it.
// Dev release manifest drift fix, item 2: FE-GATE-010 gained
// `check-dev-release-manifest`. No gate read `public/*.json` at all, so a
// fixture that did not declare the compiled contract set broke `pnpm dev`
// outright while every static gate stayed green.
// Template sync (ebea300). The template's own baseline was 91/103; this
// product's was 85/97. Recomputed from the merged config/ci/gates.json.
if (contract.commands.length !== 94 || commandReferenceCount !== 106) {
failures.push(
`command authority baseline must contain exactly 94 definitions and 106 references; received ${contract.commands.length} definitions and ${commandReferenceCount} references`,
if (!parsed.success) {
throw new TypeError(
`${CI_CONTRACT_BASELINE_PATH} invalid:\n${parsed.error.issues
.map((issue) => `${issue.path.join(".") || "root"}: ${issue.message}`)
.join("\n")}`,
);
}
// Template merge. 126 product artifacts plus the two the template added.
// Task 11 added one more: the TECH_LOG_STUDIO_ASSETS manual a11y evidence file.
// Alignment follow-up, item 2 added the TechLog junit report.
// The taxonomy route added its own manual a11y evidence file — every installed
// route carries one, and the gate checks that the two sets match exactly.
// The project edit route did the same: it is what finally lets a project carry
// a purpose, a current objective, and a next step, so the public screens that
// read those fields stop rendering blanks.
// The release edit route followed: the editor used to open below the release
// list, so editing meant scrolling past every release to reach it.
// 개념(CONCEPT) 문서 종류가 `/concepts/:slug` 를 더했다 — 설치된 라우트마다 수동 접근성 증거를
// 하나씩 갖는 규칙이 그대로 적용된다.
// 주제(Topic) 화면 셋이 뒤를 이었다: 목록 `/topics`, 축 상세 `/topics/:slug/:variant`,
// 그리고 Studio 의 주제 편집 `/studio/topics/:id`.
// 환경 구성(SETUP) 문서 종류가 `/setups/:slug` 를 더했다 — 설치된 라우트마다 수동 접근성
// 증거를 하나씩 갖는 규칙이 그대로 적용된다.
// Template sync (ebea300). The template's own baseline was 109 artifacts;
// this product's was 139. Recomputed from the merged config/ci/gates.json.
if (contract.artifacts.length !== 141) {
failures.push(`artifact authority baseline must contain exactly 141 artifacts; received ${contract.artifacts.length}`);
}
if (contract.stages.length !== 5) {
failures.push(`stage authority baseline must contain exactly 5 stages; received ${contract.stages.length}`);
const baseline = parsed.data;
const drift = Object.entries(measureCiContractBaseline(contract))
.filter(([key, value]) => baseline[key as keyof CiContractBaseline] !== value)
.map(([key, value]) =>
`${key}: baseline ${String(baseline[key as keyof CiContractBaseline])}, contract ${String(value)}`
);
if (drift.length > 0) {
throw new TypeError(
`CI gate contract does not match ${CI_CONTRACT_BASELINE_PATH}:\n${drift.join("\n")}\n` +
"If the change is intended, review it and run " +
"CI_CONTRACT_BASELINE_OWNER=<team> CI_CONTRACT_BASELINE_REASON=<why> corepack pnpm update:ci-contract-baseline",
);
}
}
function retentionRegistryFailures(contract: CiGateContract): string[] {
const expectedRetentionClasses = [
{ id: "merge-cycle", policy: "at least through pull-request readiness decision" },
{ id: "release-coherence", policy: "at least until the next release is promoted" },
@@ -571,16 +552,12 @@ function canonicalAuthorityBaselineFailures(contract: CiGateContract): string[]
{ id: "field", policy: "through the 28-day window and aggregation" },
{ id: "documentation", policy: "through documentation readiness review" },
];
if (JSON.stringify(contract.retention.classes) !== JSON.stringify(expectedRetentionClasses)) {
failures.push("retention registry must contain exactly the five canonical retention classes");
}
return failures;
return JSON.stringify(contract.retention.classes) === JSON.stringify(expectedRetentionClasses)
? []
: ["retention registry must contain exactly the five canonical retention classes"];
}
export function parseCiGateContract(
value: unknown,
options: LoadCiGateContractOptions = {},
): CiGateContract {
export function parseCiGateContract(value: unknown): CiGateContract {
const result = ciGateContractSchema.safeParse(value);
if (!result.success) {
const diagnostic = result.error.issues
@@ -588,49 +565,21 @@ export function parseCiGateContract(
.join("\n");
throw new TypeError(`CI gate contract invalid:\n${diagnostic}`);
}
if ((options.mode ?? defaultCiContractMode()) === "canonical") {
const failures = canonicalAuthorityBaselineFailures(result.data);
if (failures.length > 0) {
throw new TypeError(`CI gate contract invalid:\n${failures.map((failure) => `root: ${failure}`).join("\n")}`);
}
const failures = retentionRegistryFailures(result.data);
if (failures.length > 0) {
throw new TypeError(`CI gate contract invalid:\n${failures.map((failure) => `root: ${failure}`).join("\n")}`);
}
return result.data;
}
/**
* A removal fixture runs the whole suite against a deliberately *reduced* CI
* contract: the removed capability's gates, commands and artifacts are pruned.
* Loading that contract in canonical mode re-imposes the full exact-count
* authority on it, so the fixture failed on the very reduction it exists to
* prove. `runRemovalFixturePnpm` marks those runs, and this is where the mark
* is honoured.
*/
export function defaultCiContractMode(): "canonical" | "removal-fixture" {
return process.env.CI_CONTRACT_MODE === "removal-fixture"
? "removal-fixture"
: "canonical";
}
export function isReducedCiContractRun(): boolean {
return defaultCiContractMode() === "removal-fixture";
}
export async function loadCiGateContract(
root = process.cwd(),
options: LoadCiGateContractOptions = {},
): Promise<CiGateContract> {
const mode = options.mode ?? defaultCiContractMode();
const [rawContract, rawPackage] = await Promise.all([
readFile(path.join(root, "config/ci/gates.json"), "utf8"),
readFile(path.join(root, "package.json"), "utf8"),
]);
const contract = parseCiGateContract(JSON.parse(rawContract), { mode });
if (
mode === "canonical" &&
canonicalGateShapeSha256(contract.gates) !== CANONICAL_GATE_SHAPE_SHA256
) {
throw new TypeError("CI gate contract canonical gate semantic shape drift");
}
const contract = parseCiGateContract(JSON.parse(rawContract));
const packageDocument = z
.object({ scripts: z.record(z.string(), z.string()).default({}) })
.passthrough()
@@ -642,17 +591,17 @@ export async function loadCiGateContract(
if (missing.length > 0) {
throw new TypeError(`CI gate contract missing package scripts: ${missing.join(", ")}`);
}
const expectedCheckCi = mode === "canonical"
? "corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts && corepack pnpm check:ci-workflow"
: "corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts --reduced-removal-fixture && corepack pnpm check:ci-workflow";
const expectedCheckCi =
"corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts && corepack pnpm check:ci-workflow";
if (packageDocument.scripts["check:ci"] !== expectedCheckCi) {
throw new TypeError("check:ci must use the exact canonical non-recursive orchestration");
}
const canonicalCheckCiDependencies = {
"check:artifact-schemas": "node scripts/generate-artifact-schemas.ts --check",
"check:ci-workflow": mode === "canonical"
? "node scripts/generate-ci-workflow.ts --check"
: "node scripts/generate-ci-workflow.ts --check --reduced-removal-fixture",
// R-0. The schema generator imports src, which loads the gitignored
// product index, so the index is rendered first.
"check:artifact-schemas":
"node scripts/generate-product-feature-index.ts && node scripts/generate-artifact-schemas.ts --check",
"check:ci-workflow": "node scripts/generate-ci-workflow.ts --check",
} as const;
for (const [script, expected] of Object.entries(canonicalCheckCiDependencies)) {
if (packageDocument.scripts[script] !== expected) {
@@ -682,6 +631,7 @@ export async function loadCiGateContract(
`CI package script install policy invalid:\n${installPolicyFailures.join("\n")}`,
);
}
await assertCiContractBaseline(root, contract);
return contract;
}
@@ -819,15 +769,17 @@ function validateContractSemantics(
}
}
// Template sync (af3d8e6). The signed manual review moved from FE-GATE-009
// to release gate FE-GATE-028 upstream (08-06); the one-artifact-per-route
// rule this product pins moved with it.
const accessibilityGate = contract.gates.find(
({ id: gateId }) => gateId === "FE-GATE-009",
({ id: gateId }) => gateId === "FE-GATE-028",
);
const manualAccessibilityArtifacts = MANUAL_A11Y_ROUTE_IDS.map((routeId) => ({
id: `artifact-artifacts-tests-a11y-manual-${routeId.replaceAll("_", "-")}-md`,
path: `artifacts/tests/a11y-manual/${routeId}.md`,
}));
const expectedAccessibilityEvidenceArtifactIds = [
"artifact-artifacts-tests-a11y-json",
...manualAccessibilityArtifacts.map(({ id: artifactId }) => artifactId),
"artifact-artifacts-tests-a11y-manual-report-json",
];
@@ -837,7 +789,7 @@ function validateContractSemantics(
JSON.stringify(expectedAccessibilityEvidenceArtifactIds)
) {
issue(
"FE-GATE-009 manual accessibility evidence must exactly match the installed route scope",
"FE-GATE-028 manual accessibility evidence must exactly match the installed route scope",
);
}
for (const expected of manualAccessibilityArtifacts) {
@@ -851,7 +803,7 @@ function validateContractSemantics(
artifact.production !== "source-controlled"
) {
issue(
`FE-GATE-009 manual accessibility artifact registration is invalid: ${expected.id}`,
`FE-GATE-028 manual accessibility artifact registration is invalid: ${expected.id}`,
);
}
}
@@ -891,12 +843,9 @@ function validateContractSemantics(
issue(`stage dependency cycle: ${cycle.join(" -> ")}`);
}
const expectedGateIds = Array.from(
{ length: 27 },
(_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`,
);
const expectedGateIds = CANONICAL_GATE_IDS;
if (JSON.stringify(contract.gates.map(({ id }) => id)) !== JSON.stringify(expectedGateIds)) {
issue("gate registry must contain FE-GATE-001..027 in canonical order");
issue(`gate registry must contain FE-GATE-001..028 without retired ${RETIRED_GATE_IDS.join(", ")} in canonical order`);
}
const expectedStages: ReadonlyArray<readonly [string, string, readonly string[], readonly string[]]> = [
["merge", "MERGE_READY", [], PROMOTION_FORMULA.MERGE_READY],
@@ -966,12 +915,12 @@ function validateContractSemantics(
}
const expectedJobOwnership: Readonly<Record<string, readonly string[]>> = {
merge_gate: ["FE-GATE-001", "FE-GATE-002", "FE-GATE-003", "FE-GATE-004", "FE-GATE-005", "FE-GATE-006", "FE-GATE-007", "FE-GATE-008", "FE-GATE-009", "FE-GATE-010", "FE-GATE-011", "FE-GATE-013", "FE-GATE-020"],
release_gate: ["FE-GATE-012", "FE-GATE-014", "FE-GATE-019", "FE-GATE-026"],
release_gate: ["FE-GATE-012", "FE-GATE-014", "FE-GATE-026", "FE-GATE-028"],
immutable_build: ["FE-GATE-015", "FE-GATE-027"],
vulnerability_provider: [],
provenance_provider: [],
promotion: [],
production_gate: ["FE-GATE-016", "FE-GATE-021", "FE-GATE-022", "FE-GATE-023", "FE-GATE-024", "FE-GATE-025"],
production_gate: ["FE-GATE-019", "FE-GATE-021", "FE-GATE-022", "FE-GATE-023", "FE-GATE-024", "FE-GATE-025"],
field_gate: ["FE-GATE-018"],
documentation_gate: ["FE-GATE-017"],
};
@@ -991,7 +940,7 @@ function validateContractSemantics(
vulnerability_provider: ["provider", ["immutable_build"], "always"],
provenance_provider: ["provider", ["immutable_build"], "always"],
promotion: ["promotion", ["immutable_build", "vulnerability_provider", "provenance_provider"], "needs-success"],
production_gate: ["gate-matrix", ["promotion"], "production"],
production_gate: ["gate-matrix", ["immutable_build", "promotion"], "production"],
field_gate: ["gate-single", ["production_gate"], "field"],
documentation_gate: ["gate-single", [], "documentation"],
};
@@ -1008,7 +957,7 @@ function validateContractSemantics(
vulnerability_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"],
provenance_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"],
promotion: ["checkout", "setup-node", "frozen-install", "download", "download", "download", "verify-promotion", "upload", "cleanup-promotion"],
production_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
production_gate: ["checkout", "setup-node", "frozen-install", "download", "extract", "run-gate", "upload"],
field_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
documentation_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
};
@@ -1020,7 +969,7 @@ function validateContractSemantics(
}
const expectedEnvironmentBindings: Readonly<Record<string, readonly Readonly<{ name: string; value: string }> []>> = {
merge_gate: [],
release_gate: [{ name: "HOSTING_BASE_URL", value: "${{ vars.HOSTING_BASE_URL }}" }],
release_gate: [],
immutable_build: [
// FE-GATE-027 admits the built artifact to a named environment, so both
// the profile it was built from and the destination it is claimed for are
@@ -1066,7 +1015,14 @@ function validateContractSemantics(
{ name: "VULNERABILITY_INVOCATION_NONCE", value: "${{ needs.vulnerability_provider.outputs.invocation_nonce }}" },
{ name: "PROVENANCE_INVOCATION_NONCE", value: "${{ needs.provenance_provider.outputs.invocation_nonce }}" },
],
production_gate: [],
// 13-05: FE-GATE-019 probes the promoted release after the provider has
// deployed it, so the live base URL belongs to the production stage.
// 13-03: the drills extract the promoted archive and check it against the
// digest immutable_build recorded.
production_gate: [
{ name: "HOSTING_BASE_URL", value: "${{ vars.HOSTING_BASE_URL }}" },
{ name: "CANDIDATE_ARCHIVE_SHA256", value: "${{ needs.immutable_build.outputs.archive_sha256 }}" },
],
field_gate: [
{ name: "FIELD_WEB_VITALS_INPUT", value: "${{ vars.FIELD_WEB_VITALS_INPUT }}" },
{ name: "MIN_ELIGIBLE_SAMPLES", value: "${{ vars.MIN_ELIGIBLE_SAMPLES }}" },
@@ -1261,6 +1217,38 @@ function validateCanonicalStepFields(
) {
issue("promotion download fields and finalizer/cleanup step identities must remain linked");
}
// 13-03: the production stage drills the promoted archive it downloads. It
// used to rebuild from source, so the drilled bytes were not the release.
const production = contract.jobs.find(({ id }) => id === "production_gate");
const promotedDownload = production?.steps.find(
(step) => step.kind === "download" && step.transferId === "promoted-release",
);
const promotedExtract = production?.steps.find(({ kind }) => kind === "extract");
if (
!production ||
promotedDownload?.kind !== "download" ||
promotedExtract?.kind !== "extract" ||
promotedExtract.archivePath !== `${promotedDownload.path}/release-candidate.tar.gz`
) {
issue("production_gate must download the promoted release and extract its release-candidate.tar.gz");
} else {
for (const gateId of production.gateIds) {
const commands = (contract.gates.find(({ id }) => id === gateId)?.commandIds ?? [])
.map((commandId) => contract.commands.find(({ id }) => id === commandId));
if (!commands.some((command) => command?.script === "drill:runbook")) continue;
if (commands.some((command) => command?.script !== "drill:runbook")) {
issue(`production drill gate must drill the promoted archive only, without rebuilding: ${gateId}`);
}
for (const command of commands) {
const args = command?.args ?? [];
const releaseRoot = args.indexOf("--release-root");
if (releaseRoot < 0 || args[releaseRoot + 1] !== promotedExtract.targetRoot) {
issue(`production drill must pass --release-root ${promotedExtract.targetRoot} (the promoted archive): ${command?.id ?? gateId}`);
}
}
}
}
}
function validateJobStepKinds(
@@ -1268,7 +1256,7 @@ function validateJobStepKinds(
issue: (message: string, path?: PropertyKey[]) => void,
): void {
const allowed: Readonly<Record<z.infer<typeof jobSchema>["kind"], ReadonlySet<string>>> = {
"gate-matrix": new Set(["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"]),
"gate-matrix": new Set(["checkout", "setup-node", "frozen-install", "browser-install", "download", "extract", "run-gate", "upload"]),
"gate-single": new Set(["checkout", "setup-node", "frozen-install", "run-gate", "upload"]),
immutable: new Set(["checkout", "setup-node", "frozen-install", "run-gate", "archive-candidate", "upload"]),
provider: new Set(["checkout", "setup-node", "frozen-install", "download", "extract", "run-provider", "validate-provider-evidence", "upload"]),
+97 -47
View File
@@ -152,6 +152,8 @@ export const moduleInventoryArtifactSchema = z
})
.strict(),
),
// 13-12: `name@version` of every package with a module in the bundle.
packages: z.array(z.string().regex(/^(?:@[^/@]+\/)?[^/@]+@[^/@]+$/u)),
})
.strict();
@@ -688,6 +690,11 @@ export const deploymentAdmissionArtifactSchema = z
violations: z.array(
z.object({ field: nonEmptyString, reason: nonEmptyString }).strict(),
),
// 09-09. Findings that do not refuse the artifact, e.g. an override key
// naming a feature this build does not declare.
warnings: z.array(
z.object({ field: nonEmptyString, reason: nonEmptyString }).strict(),
),
})
.strict();
@@ -718,31 +725,67 @@ export const releaseVerificationArtifactSchema = z
})
.strict();
// 11-01 / 13-03 (D-14): each verdict is PASS or FAIL only when observed on the
// local build; anything that needs a boot, live traffic or the provider is
// UNVERIFIED, and so is a drill with provider scope.
const drillVerdict = z.enum(["PASS", "FAIL", "UNVERIFIED"]);
export type DrillVerdict = z.infer<typeof drillVerdict>;
/** FAIL beats UNVERIFIED beats PASS; provider scope alone keeps a drill UNVERIFIED. */
export function combineDrillVerdicts(
verdicts: readonly DrillVerdict[],
providerVerificationRequired: boolean,
): DrillVerdict {
if (verdicts.includes("FAIL")) return "FAIL";
if (verdicts.includes("UNVERIFIED") || providerVerificationRequired) return "UNVERIFIED";
return "PASS";
}
export const runbookRecordArtifactSchema = z
.object({
schemaVersion: z.literal(1),
schemaVersion: z.literal(2),
runbookId: z.string().regex(/^FE-RB-00[1-5]$/u),
releaseId: nonEmptyString,
drillTimestamp: timestamp,
triggerInjected: nonEmptyString,
triggerAsserted: z.boolean(),
containmentAsserted: z.boolean(),
escalationPathAsserted: z.boolean(),
triggerAsserted: drillVerdict,
containmentAsserted: drillVerdict,
escalationPathAsserted: drillVerdict,
recoveryAssertions: z.array(
z
.object({
assertion: nonEmptyString,
evidence: nonEmptyString,
passed: z.boolean(),
result: drillVerdict,
})
.strict(),
),
negativeFixtureFailedAsExpected: z.boolean(),
negativeFixtureFailedAsExpected: drillVerdict,
windowObservedBucket: nonEmptyString,
providerVerificationRequired: z.boolean(),
passed: z.boolean(),
result: drillVerdict,
})
.strict();
.strict()
.superRefine((record, context) => {
const expected = combineDrillVerdicts(
[
record.triggerAsserted,
record.containmentAsserted,
record.escalationPathAsserted,
...record.recoveryAssertions.map(({ result }) => result),
record.negativeFixtureFailedAsExpected,
],
record.providerVerificationRequired,
);
if (record.result !== expected) {
context.addIssue({
code: "custom",
path: ["result"],
message: `result must be ${expected} for these verdicts`,
});
}
});
const failureList = z.array(nonEmptyString).max(4_096);
const sourceOrFixtureMode = z.enum(["source", "negative-fixture"]);
@@ -943,33 +986,11 @@ const staticImportGraphSchema = z
context.addIssue({ code: "custom", path: ["typeScriptOnlySourcePolicy", "passed"], message: "must agree with violations and summary" });
}
});
const dependencyCruiserSummarySchema = z
.object({
violations: z.array(jsonObject),
error: z.int().nonnegative(),
warn: z.int().nonnegative(),
info: z.int().nonnegative(),
ignore: z.int().nonnegative(),
totalCruised: z.int().nonnegative(),
totalDependenciesCruised: z.int().nonnegative(),
})
.catchall(z.json());
export const architectureDependencyReportArtifactSchema = z.union([
z
.object({
modules: z.array(jsonObject),
summary: dependencyCruiserSummarySchema,
staticImportGraph: staticImportGraphSchema,
})
.strict(),
z
.object({
summary: z.object({ errors: z.literal(1) }).strict(),
dependencyCruiserOutput: z.string(),
staticImportGraph: staticImportGraphSchema,
})
.strict(),
]);
// 12-05 (D-11): dependency-cruiser checked zero modules under TypeScript 7 and
// no longer runs; the report carries the import graph that enforces the rules.
export const architectureDependencyReportArtifactSchema = z
.object({ staticImportGraph: staticImportGraphSchema })
.strict();
export const designSystemReportArtifactSchema = z
.object({
@@ -1018,7 +1039,6 @@ export const realtimeBoundariesArtifactSchema = z
ruleId: z.enum([
"NATIVE_REALTIME_API_OUTSIDE_ADAPTER",
"PRESENTATION_INTERVAL_OWNER",
"UNSELECTED_REALTIME_RUNTIME_COMPOSED",
]),
file: nonEmptyString,
line: z.int().positive(),
@@ -1284,6 +1304,10 @@ export const supplyChainProviderFixturesArtifactSchema = z
validImmutable: providerFixtureResultSchema,
wrongDigest: providerFixtureResultSchema,
invalidTar: providerFixtureResultSchema,
// 13-04: archived re-verification of the same bundle three hours on.
archivedAfterWindow: providerFixtureResultSchema,
currentAfterWindow: providerFixtureResultSchema,
archivedTampered: providerFixtureResultSchema,
})
.strict(),
externalTreeCanary: providerFixtureResultSchema,
@@ -1295,43 +1319,60 @@ export const supplyChainProviderFixturesArtifactSchema = z
const expectedPass =
artifact.actualDefaultVerifier.status === "PASS" &&
artifact.fixtures.validImmutable.status === "PASS" &&
artifact.fixtures.archivedAfterWindow.status === "PASS" &&
artifact.externalTreeCanary.status === "PASS" &&
[artifact.fixtures.absent, artifact.fixtures.wrongDigest, artifact.fixtures.invalidTar]
.every(({ status }) => status === "FAIL_UNVERIFIED");
if (artifact.passingFixtureCount !== (artifact.fixtures.validImmutable.status === "PASS" ? 1 : 0)) {
context.addIssue({ code: "custom", path: ["passingFixtureCount"], message: "must count the passing immutable fixture" });
[
artifact.fixtures.absent,
artifact.fixtures.wrongDigest,
artifact.fixtures.invalidTar,
artifact.fixtures.currentAfterWindow,
artifact.fixtures.archivedTampered,
].every(({ status }) => status === "FAIL_UNVERIFIED");
const passing = [artifact.fixtures.validImmutable, artifact.fixtures.archivedAfterWindow]
.filter(({ status }) => status === "PASS").length;
if (artifact.passingFixtureCount !== passing) {
context.addIssue({ code: "custom", path: ["passingFixtureCount"], message: "must count the passing fixtures" });
}
if ((artifact.status === "PASS") !== expectedPass) {
context.addIssue({ code: "custom", path: ["status"], message: "must agree with required fixture outcomes" });
}
});
const compatibilityClassificationSchema = z.enum(["additive", "breaking"]);
const compatibilityClassificationSchema = z.enum(["additive", "breaking", "none"]);
export const compatibilityFixturesArtifactSchema = z
.object({
schemaVersion: z.literal(1),
schemaVersion: z.literal(2),
generatedAt: timestamp,
rules: z.array(nonEmptyString).length(5),
rules: z.array(nonEmptyString).min(1),
results: z.array(
z
.object({
family: z.enum(["api", "config", "storage", "release"]),
id: nonEmptyString,
expected: compatibilityClassificationSchema,
actual: compatibilityClassificationSchema,
passed: z.boolean(),
})
.strict(),
).length(8),
).min(1),
baseline: z
.object({
path: nonEmptyString,
classification: compatibilityClassificationSchema,
passed: z.boolean(),
})
.strict(),
})
.strict()
.superRefine((artifact, context) => {
const keys = artifact.results.map(({ family, expected }) => `${family}\0${expected}`);
addUniqueStringIssues(keys, ["results"], context);
addUniqueStringIssues(artifact.results.map(({ id }) => id), ["results"], context);
artifact.results.forEach((result, index) => {
if (result.passed !== (result.actual === result.expected)) {
context.addIssue({ code: "custom", path: ["results", index, "passed"], message: "must agree with expected and actual" });
}
});
if (artifact.baseline.passed !== (artifact.baseline.classification !== "breaking")) {
context.addIssue({ code: "custom", path: ["baseline", "passed"], message: "must fail exactly when the baseline change is breaking" });
}
});
export const documentationReviewArtifactSchema = z
@@ -1364,6 +1405,8 @@ export const documentationReviewArtifactSchema = z
.strict(),
).min(1),
routeScopeDocumented: z.boolean(),
// 13-15: build and deploy variables README.md does not name.
missingRuntimeVariables: z.array(nonEmptyString),
results: z.array(
z
.object({
@@ -1402,6 +1445,7 @@ export const documentationReviewArtifactSchema = z
artifact.passed !==
(artifact.reportDigestValid &&
artifact.routeScopeDocumented &&
artifact.missingRuntimeVariables.length === 0 &&
artifact.results.every(({ passed }) => passed))
) {
context.addIssue({ code: "custom", path: ["passed"], message: "must agree with report digest, documented scope and review results" });
@@ -1428,9 +1472,15 @@ export const hostingHeadersArtifactSchema = z
.strict(),
).min(1),
passed: z.boolean(),
// 13-05 (D-14): only a live probe can PASS; the fixture is UNVERIFIED.
status: z.enum(["PASS", "FAIL", "UNVERIFIED"]),
})
.strict()
.superRefine((artifact, context) => {
const expectedStatus = !artifact.passed ? "FAIL" : artifact.mode === "live" ? "PASS" : "UNVERIFIED";
if (artifact.status !== expectedStatus) {
context.addIssue({ code: "custom", path: ["status"], message: `must be ${expectedStatus} for this mode and result` });
}
const keys = artifact.results.map(({ surface, header }) => `${surface}\0${header}`);
addUniqueStringIssues(keys, ["results"], context);
const requiredKeys = [