@beyondwork/docx-react-component 1.0.0

package/services/react-word-editor/lib/regression-report.ts

@@ -0,0 +1,896 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+
+import type { ManualCertificationRecord } from "./certification-store.ts";
+import type { HarnessSourceRecord } from "./storage.ts";
+import type {
+  HarnessRunStory,
+  ProofWave,
+  RunCompatibilitySummary,
+  RunExecutionOutcome,
+} from "./run-artifacts.ts";
+
+const execFile = promisify(execFileCallback);
+
+const moduleDirPath = path.dirname(fileURLToPath(import.meta.url));
+const serviceRootDir = path.resolve(moduleDirPath, "..");
+const repoRootDir = path.resolve(serviceRootDir, "../..");
+
+export const wave10BundleRootDir = path.join(repoRootDir, ".tmp/wave-10-certification");
+export const wave10CertificationManifestPath = path.join(
+  repoRootDir,
+  "test/fixtures/docx/certification-manifest.json",
+);
+
+const regressionReportPath = path.join(wave10BundleRootDir, "regression-report.json");
+const fixtureCoveragePath = path.join(wave10BundleRootDir, "fixture-coverage.json");
+const certificationFreshnessPath = path.join(wave10BundleRootDir, "certification-freshness.json");
+
+export type Wave10CertificationManifest = {
+  manifestVersion: "docx-certification/1";
+  wave: 10;
+  bundleRoot: ".tmp/wave-10-certification";
+  automationRoute: "/api/fixtures/[fixtureId]/run";
+  releaseGateFixtures: string[];
+  supportedRoundtripFixtures: string[];
+  preserveOnlyFixtures: string[];
+  unsupportedFatalFixtures: string[];
+  representativeScenarios: string[];
+  manualReviewFixtures: string[];
+  manualReviewScenarios: string[];
+  expectedBlockedScenarios?: string[];
+  requiredArtifacts: string[];
+  freshnessPolicy: {
+    requireRepoCommit: boolean;
+    requireCleanWorkingTree: boolean;
+    requiredProofWave: 10;
+    requiredCommitPrefixLength: number;
+    rejectLegacyRoots: string[];
+  };
+  notes: string[];
+};
+
+export type RepoFreshnessState = {
+  repoCommitSha?: string;
+  workingTreeDirty: boolean;
+  gitAvailable: boolean;
+};
+
+export type Wave10SourceRunArtifact = {
+  schemaVersion: "wave-10-source-run/1";
+  generatedAt: string;
+  sourceKey: string;
+  sourceId: string;
+  sourceKind: HarnessSourceRecord["sourceKind"];
+  proofContext: {
+    proofWave: ProofWave;
+    bundleId: string;
+  };
+  runStory: HarnessRunStory;
+  source: HarnessSourceRecord;
+  executionOutcome: RunExecutionOutcome;
+  compatibilitySummary: RunCompatibilitySummary;
+  exportRecord?: {
+    exportId: string;
+    fileName: string;
+    byteLength: number;
+    createdAt: string;
+  };
+  validationRun?: {
+    runId: string;
+    summary: {
+      isValid: boolean;
+      packageFindingCount: number;
+      sdkFindingCount: number;
+    };
+    createdAt: string;
+  };
+  validationDeltaFromSource?: {
+    packageFindingDelta: number;
+    sdkFindingDelta: number;
+  };
+};
+
+type Wave10StatusValue = "passed" | "pending" | "issues-found" | "missing";
+
+export type Wave10SignoffArtifactStatus = {
+  relativePath: string;
+  exists: boolean;
+  status: Wave10StatusValue;
+};
+
+type Wave10ManualSurfaceCoverage = {
+  required: boolean;
+  status: "missing" | "not-reviewed" | "passed" | "issues-found";
+  certificationId?: string;
+  observedAt?: string;
+  operator?: string;
+  targetType?: string;
+  targetId?: string;
+};
+
+export type Wave10CoverageEntry = {
+  sourceKey: string;
+  sourceId: string;
+  sourceKind: HarnessSourceRecord["sourceKind"];
+  sourceLabel: string;
+  featureClassFocus?: HarnessSourceRecord["featureClassFocus"];
+  requiredManualReview: boolean;
+  artifactRelativePath: string;
+  status: "passed" | "blocked" | "missing" | "failed";
+  detail: string;
+  freshness: {
+    status: "fresh" | "stale" | "missing";
+    bundleId?: string;
+    reasons: string[];
+  };
+  runId?: string;
+  executionOutcome?: RunExecutionOutcome["state"];
+  proofWave?: number;
+  bundleId?: string;
+  validator: {
+    present: boolean;
+    isValid?: boolean;
+    packageFindingCount?: number;
+    sdkFindingCount?: number;
+    packageFindingDelta?: number;
+    sdkFindingDelta?: number;
+  };
+  compatibility: RunCompatibilitySummary | undefined;
+  manualReviews: {
+    wordDesktop: Wave10ManualSurfaceCoverage;
+    wordWeb: Wave10ManualSurfaceCoverage;
+  };
+};
+
+export type Wave10FixtureCoverageManifest = {
+  schemaVersion: "wave-10-fixture-coverage/1";
+  generatedAt: string;
+  bundleRoot: string;
+  repoState: RepoFreshnessState;
+  releaseGateFixtures: Wave10CoverageEntry[];
+  representativeScenarios: Wave10CoverageEntry[];
+  summary: {
+    releaseGateFixtures: number;
+    scenarios: number;
+    passedFixtures: number;
+    blockedFixtures: number;
+    passedScenarios: number;
+    blockedScenarios: number;
+  };
+};
+
+export type Wave10CertificationFreshnessManifest = {
+  schemaVersion: "wave-10-certification-freshness/1";
+  generatedAt: string;
+  bundleRoot: string;
+  repoState: RepoFreshnessState;
+  overallStatus: "ready" | "blocked";
+  blockingReasons: string[];
+  ignoredLegacyRoots: Array<{
+    relativePath: string;
+    exists: boolean;
+  }>;
+  requiredArtifacts: Wave10SignoffArtifactStatus[];
+  requiredManualCoverage: Array<{
+    sourceKey: string;
+    wordDesktop: Wave10ManualSurfaceCoverage;
+    wordWeb: Wave10ManualSurfaceCoverage;
+  }>;
+};
+
+export type Wave10RegressionReport = {
+  schemaVersion: "wave-10-regression-report/1";
+  generatedAt: string;
+  bundleRoot: string;
+  repoState: RepoFreshnessState;
+  overallStatus: "ready" | "blocked";
+  blockingReasons: string[];
+  summary: {
+    releaseGateFixturesPassed: number;
+    releaseGateFixturesTotal: number;
+    representativeScenariosPassed: number;
+    representativeScenariosTotal: number;
+    requiredArtifactsPassed: number;
+    requiredArtifactsTotal: number;
+    requiredManualSurfacesPassed: number;
+    requiredManualSurfacesTotal: number;
+  };
+};
+
+type Wave10ReportModel = {
+  coverage: Wave10FixtureCoverageManifest;
+  freshness: Wave10CertificationFreshnessManifest;
+  regression: Wave10RegressionReport;
+};
+
+function getSourceArtifactRelativePath(sourceKey: string): string {
+  return `${sourceKey.toLowerCase()}-run.json`;
+}
+
+async function writeJsonAtomic(filePath: string, value: unknown): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(tempPath, JSON.stringify(value, null, 2));
+  await rename(tempPath, filePath);
+}
+
+async function readJsonFile<T>(filePath: string): Promise<T | undefined> {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return JSON.parse(raw) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseStatusFromTextArtifact(raw: string): Wave10StatusValue {
+  const match = /^status:\s*(passed|pending|issues-found)$/im.exec(raw);
+  return match ? (match[1] as Wave10StatusValue) : "pending";
+}
+
+function normalizeJsonSignoffStatus(status: string | undefined): Wave10StatusValue {
+  if (status === "passed" || status === "pending" || status === "issues-found") {
+    return status;
+  }
+
+  if (status === "blocked" || status === "failed") {
+    return "issues-found";
+  }
+
+  return "pending";
+}
+
+async function readSignoffArtifactStatus(relativePath: string): Promise<Wave10SignoffArtifactStatus> {
+  if (
+    relativePath === "regression-report.json" ||
+    relativePath === "fixture-coverage.json" ||
+    relativePath === "certification-freshness.json"
+  ) {
+    return {
+      relativePath,
+      exists: true,
+      status: "passed",
+    };
+  }
+
+  const absolutePath = path.join(wave10BundleRootDir, relativePath);
+
+  if (!(await fileExists(absolutePath))) {
+    return {
+      relativePath,
+      exists: false,
+      status: "missing",
+    };
+  }
+
+  if (relativePath.endsWith(".json")) {
+    const parsed = await readJsonFile<{ status?: string }>(absolutePath);
+    return {
+      relativePath,
+      exists: true,
+      status: normalizeJsonSignoffStatus(parsed?.status),
+    };
+  }
+
+  const raw = await readFile(absolutePath, "utf8");
+  return {
+    relativePath,
+    exists: true,
+    status: parseStatusFromTextArtifact(raw),
+  };
+}
+
+function buildMissingSurface(required: boolean): Wave10ManualSurfaceCoverage {
+  return {
+    required,
+    status: required ? "missing" : "not-reviewed",
+  };
+}
+
+function getCommitPrefix(commitSha: string | undefined, length: number): string | undefined {
+  if (!commitSha) {
+    return undefined;
+  }
+
+  return commitSha.slice(0, Math.max(1, length));
+}
+
+function getRequiredProofWave(manifest: Wave10CertificationManifest): number {
+  return manifest.freshnessPolicy.requiredProofWave ?? manifest.wave;
+}
+
+function getRequiredCommitPrefixLength(manifest: Wave10CertificationManifest): number {
+  return manifest.freshnessPolicy.requiredCommitPrefixLength ?? 12;
+}
+
+function getExpectedBundlePrefix(manifest: Wave10CertificationManifest): string {
+  return `wave-${getRequiredProofWave(manifest)}-`;
+}
+
+function hasCommitShapedSuffix(bundleId: string, expectedPrefix: string, expectedLength: number): boolean {
+  const suffix = bundleId.slice(expectedPrefix.length);
+  const pattern = new RegExp(`^[0-9a-f]{${Math.max(1, expectedLength)}}$`, "i");
+  return pattern.test(suffix);
+}
+
+function getArtifactFreshnessReasons(input: {
+  manifest: Wave10CertificationManifest;
+  repoState: RepoFreshnessState;
+  source: HarnessSourceRecord;
+  sourceArtifact: Wave10SourceRunArtifact;
+}): string[] {
+  const reasons: string[] = [];
+  const { manifest, repoState, sourceArtifact, source } = input;
+  const requiredProofWave = getRequiredProofWave(manifest);
+
+  if (sourceArtifact.proofContext.proofWave !== requiredProofWave) {
+    reasons.push(
+      `${source.fixtureId ?? source.scenarioId ?? source.sourceId} artifact targets proof wave ${sourceArtifact.proofContext.proofWave}, not Wave ${requiredProofWave}.`,
+    );
+  }
+
+  const expectedBundlePrefix = getExpectedBundlePrefix(manifest);
+  const bundleId = sourceArtifact.proofContext.bundleId.trim();
+
+  if (!bundleId.startsWith(expectedBundlePrefix)) {
+    reasons.push(
+      `${source.fixtureId ?? source.scenarioId ?? source.sourceId} artifact bundle ${bundleId} does not use the required ${expectedBundlePrefix}* lineage.`,
+    );
+  }
+
+  const expectedCommitPrefix = getCommitPrefix(
+    repoState.repoCommitSha,
+    getRequiredCommitPrefixLength(manifest),
+  );
+
+  if (
+    manifest.freshnessPolicy.requireRepoCommit &&
+    expectedCommitPrefix &&
+    hasCommitShapedSuffix(
+      bundleId,
+      expectedBundlePrefix,
+      getRequiredCommitPrefixLength(manifest),
+    ) &&
+    bundleId !== `${expectedBundlePrefix}${expectedCommitPrefix}`
+  ) {
+    reasons.push(
+      `${source.fixtureId ?? source.scenarioId ?? source.sourceId} artifact bundle ${bundleId} does not match commit ${expectedCommitPrefix}.`,
+    );
+  }
+
+  return reasons;
+}
+
+function matchCertificationRecord(
+  records: ManualCertificationRecord[],
+  sourceArtifact: Wave10SourceRunArtifact | undefined,
+  surface: "word-desktop" | "word-web",
+): Wave10ManualSurfaceCoverage {
+  const required = Boolean(sourceArtifact);
+
+  if (!sourceArtifact) {
+    return buildMissingSurface(required);
+  }
+
+  const matches = records.filter((record) => {
+    if (record.surface !== surface) {
+      return false;
+    }
+
+    return (
+      record.runId === sourceArtifact.runStory.runId ||
+      record.exportId === sourceArtifact.exportRecord?.exportId ||
+      record.targetId === sourceArtifact.validationRun?.runId ||
+      record.targetId === sourceArtifact.exportRecord?.exportId
+    );
+  });
+
+  const latest = matches.sort((a, b) => b.observedAt.localeCompare(a.observedAt))[0];
+
+  if (!latest) {
+    return {
+      required,
+      status: "not-reviewed",
+    };
+  }
+
+  return {
+    required,
+    status: latest.outcome,
+    certificationId: latest.certificationId,
+    observedAt: latest.observedAt,
+    operator: latest.operator,
+    targetType: latest.targetType,
+    targetId: latest.targetId,
+  };
+}
+
+function buildCoverageEntry(input: {
+  manifest: Wave10CertificationManifest;
+  repoState: RepoFreshnessState;
+  source: HarnessSourceRecord;
+  sourceKey: string;
+  requiredManualReview: boolean;
+  expectedBlockedBeforeExport: boolean;
+  sourceArtifact?: Wave10SourceRunArtifact;
+  certifications: ManualCertificationRecord[];
+}): Wave10CoverageEntry {
+  const {
+    manifest,
+    repoState,
+    source,
+    sourceKey,
+    requiredManualReview,
+    expectedBlockedBeforeExport,
+    sourceArtifact,
+    certifications,
+  } = input;
+  const artifactRelativePath = getSourceArtifactRelativePath(sourceKey);
+  const wordDesktop = matchCertificationRecord(certifications, sourceArtifact, "word-desktop");
+  const wordWeb = matchCertificationRecord(certifications, sourceArtifact, "word-web");
+
+  if (!sourceArtifact) {
+    return {
+      sourceKey,
+      sourceId: source.sourceId,
+      sourceKind: source.sourceKind,
+      sourceLabel: source.sourceLabel,
+      featureClassFocus: source.featureClassFocus,
+      requiredManualReview,
+      artifactRelativePath,
+      status: "missing",
+      detail: "Wave 10 run artifact missing for this source.",
+      freshness: {
+        status: "missing",
+        reasons: ["Wave 10 run artifact missing for this source."],
+      },
+      validator: {
+        present: false,
+      },
+      compatibility: undefined,
+      manualReviews: {
+        wordDesktop,
+        wordWeb,
+      },
+    };
+  }
+
+  let status: Wave10CoverageEntry["status"] = "passed";
+  let detail = "Fresh Wave 10 artifact present.";
+  const freshnessReasons = getArtifactFreshnessReasons({
+    manifest,
+    repoState,
+    source,
+    sourceArtifact,
+  });
+
+  if (freshnessReasons.length > 0) {
+    status = "failed";
+    detail = freshnessReasons[0];
+  }
+
+  if (status === "passed" && source.featureClassFocus === "unsupported-fatal") {
+    if (
+      sourceArtifact.executionOutcome.state !== "blocked-before-export" ||
+      !sourceArtifact.compatibilitySummary.blockExport ||
+      sourceArtifact.exportRecord
+    ) {
+      status = "failed";
+      detail = "Malformed-package fixture did not fail closed before export.";
+    } else {
+      detail = sourceArtifact.executionOutcome.reason;
+    }
+  } else if (status === "passed" && sourceArtifact.executionOutcome.state === "blocked-before-export") {
+    if (expectedBlockedBeforeExport) {
+      detail =
+        "Scenario blocked before export as declared by the bounded v1 contract. Fail-closed export protection remains the expected outcome for this path.";
+    } else {
+      status = "blocked";
+      detail = sourceArtifact.executionOutcome.reason;
+    }
+  } else if (status === "passed" && !sourceArtifact.validationRun) {
+    status = "failed";
+    detail = "Wave 10 run exported but did not persist a validator result.";
+  } else if (
+    status === "passed" &&
+    source.sourceKind === "fixture" &&
+    source.featureClassFocus === "supported-roundtrip" &&
+    !sourceArtifact.validationRun.summary.isValid
+  ) {
+    status = "failed";
+    detail = "Supported-roundtrip fixture export recorded validator findings.";
+  } else if (
+    status === "passed" &&
+    source.sourceKind === "scenario" &&
+    typeof sourceArtifact.validationDeltaFromSource?.packageFindingDelta === "number" &&
+    typeof sourceArtifact.validationDeltaFromSource?.sdkFindingDelta === "number" &&
+    (sourceArtifact.validationDeltaFromSource.packageFindingDelta > 0 ||
+      sourceArtifact.validationDeltaFromSource.sdkFindingDelta > 0)
+  ) {
+    status = "failed";
+    detail = "Scenario export regressed validator findings compared to its recorded source baseline.";
+  } else if (
+    status === "passed" &&
+    requiredManualReview &&
+    (wordDesktop.status !== "passed" || wordWeb.status !== "passed")
+  ) {
+    status = "blocked";
+    detail = "Machine-backed run is fresh, but required manual Word certification is not complete.";
+  }
+
+  return {
+    sourceKey,
+    sourceId: source.sourceId,
+    sourceKind: source.sourceKind,
+    sourceLabel: source.sourceLabel,
+    featureClassFocus: source.featureClassFocus,
+    requiredManualReview,
+    artifactRelativePath,
+    status,
+    detail,
+    freshness: {
+      status: freshnessReasons.length === 0 ? "fresh" : "stale",
+      bundleId: sourceArtifact.proofContext.bundleId,
+      reasons: freshnessReasons,
+    },
+    runId: sourceArtifact.runStory.runId,
+    executionOutcome: sourceArtifact.executionOutcome.state,
+    proofWave: sourceArtifact.proofContext.proofWave,
+    bundleId: sourceArtifact.proofContext.bundleId,
+    validator: {
+      present: Boolean(sourceArtifact.validationRun),
+      isValid: sourceArtifact.validationRun?.summary.isValid,
+      packageFindingCount: sourceArtifact.validationRun?.summary.packageFindingCount,
+      sdkFindingCount: sourceArtifact.validationRun?.summary.sdkFindingCount,
+      packageFindingDelta: sourceArtifact.validationDeltaFromSource?.packageFindingDelta,
+      sdkFindingDelta: sourceArtifact.validationDeltaFromSource?.sdkFindingDelta,
+    },
+    compatibility: sourceArtifact.compatibilitySummary,
+    manualReviews: {
+      wordDesktop,
+      wordWeb,
+    },
+  };
+}
+
+export async function loadWave10CertificationManifest(): Promise<Wave10CertificationManifest> {
+  const raw = await readFile(wave10CertificationManifestPath, "utf8");
+  return JSON.parse(raw) as Wave10CertificationManifest;
+}
+
+export async function resolveRepoFreshnessState(): Promise<RepoFreshnessState> {
+  try {
+    const [{ stdout: commitStdout }, { stdout: dirtyStdout }] = await Promise.all([
+      execFile("git", ["rev-parse", "HEAD"], { cwd: repoRootDir }),
+      execFile("git", ["status", "--porcelain"], { cwd: repoRootDir }),
+    ]);
+
+    return {
+      repoCommitSha: commitStdout.trim(),
+      workingTreeDirty: dirtyStdout.trim().length > 0,
+      gitAvailable: true,
+    };
+  } catch {
+    return {
+      repoCommitSha: undefined,
+      workingTreeDirty: true,
+      gitAvailable: false,
+    };
+  }
+}
+
+export async function ensureWave10BundleLayout(): Promise<void> {
+  await mkdir(wave10BundleRootDir, { recursive: true });
+}
+
+export async function writeWave10SourceRunArtifact(
+  artifact: Wave10SourceRunArtifact,
+): Promise<string> {
+  await ensureWave10BundleLayout();
+  const relativePath = getSourceArtifactRelativePath(artifact.sourceKey);
+  const absolutePath = path.join(wave10BundleRootDir, relativePath);
+  await writeJsonAtomic(absolutePath, artifact);
+  return absolutePath;
+}
+
+export async function readWave10SourceRunArtifact(
+  sourceKey: string,
+): Promise<Wave10SourceRunArtifact | undefined> {
+  return readJsonFile<Wave10SourceRunArtifact>(
+    path.join(wave10BundleRootDir, getSourceArtifactRelativePath(sourceKey)),
+  );
+}
+
+export async function ensureWave10PendingSignoffArtifacts(input: {
+  repoState: RepoFreshnessState;
+  bundleId: string;
+}): Promise<void> {
+  await ensureWave10BundleLayout();
+
+  const header = [
+    `wave: 10`,
+    `bundleId: ${input.bundleId}`,
+    `commit: ${input.repoState.repoCommitSha ?? "unknown"}`,
+    `status: pending`,
+    `generatedAt: ${new Date().toISOString()}`,
+    "",
+    "Fresh operator signoff is still required for this Wave 10 bundle.",
+    "",
+  ].join("\n");
+
+  const textArtifacts = [
+    "accessibility-signoff.md",
+    "design-conformance.md",
+    "word-desktop-certification.md",
+    "word-web-certification.md",
+  ];
+
+  for (const relativePath of textArtifacts) {
+    const absolutePath = path.join(wave10BundleRootDir, relativePath);
+
+    if (!(await fileExists(absolutePath))) {
+      await writeFile(absolutePath, header);
+    }
+  }
+
+  const jsonArtifacts = [
+    {
+      relativePath: "performance-budget.json",
+      schemaVersion: "wave-10-performance-budget/1",
+    },
+    {
+      relativePath: "large-doc-smoke.json",
+      schemaVersion: "wave-10-large-doc-smoke/1",
+    },
+  ];
+
+  for (const artifact of jsonArtifacts) {
+    const absolutePath = path.join(wave10BundleRootDir, artifact.relativePath);
+
+    if (!(await fileExists(absolutePath))) {
+      await writeJsonAtomic(absolutePath, {
+        schemaVersion: artifact.schemaVersion,
+        wave: 10,
+        bundleId: input.bundleId,
+        commit: input.repoState.repoCommitSha ?? "unknown",
+        status: "pending",
+        generatedAt: new Date().toISOString(),
+        note: "Fresh operator-generated evidence has not been captured yet.",
+      });
+    }
+  }
+}
+
+export function buildWave10ReportModel(input: {
+  manifest: Wave10CertificationManifest;
+  repoState: RepoFreshnessState;
+  releaseGateFixtures: Array<{
+    source: HarnessSourceRecord;
+    artifact?: Wave10SourceRunArtifact;
+  }>;
+  representativeScenarios: Array<{
+    source: HarnessSourceRecord;
+    artifact?: Wave10SourceRunArtifact;
+  }>;
+  certifications: ManualCertificationRecord[];
+  requiredArtifactStatuses: Wave10SignoffArtifactStatus[];
+}): Wave10ReportModel {
+  const releaseGateFixtures = input.releaseGateFixtures.map(({ source, artifact }) =>
+    buildCoverageEntry({
+      manifest: input.manifest,
+      repoState: input.repoState,
+      source,
+      sourceKey: source.fixtureId || source.sourceId,
+      requiredManualReview: input.manifest.manualReviewFixtures.includes(source.fixtureId || ""),
+      expectedBlockedBeforeExport: false,
+      sourceArtifact: artifact,
+      certifications: input.certifications,
+    }),
+  );
+  const representativeScenarios = input.representativeScenarios.map(({ source, artifact }) =>
+    buildCoverageEntry({
+      manifest: input.manifest,
+      repoState: input.repoState,
+      source,
+      sourceKey: source.scenarioId || source.sourceId,
+      requiredManualReview: input.manifest.manualReviewScenarios.includes(source.scenarioId || ""),
+      expectedBlockedBeforeExport: input.manifest.expectedBlockedScenarios?.includes(source.scenarioId || "") || false,
+      sourceArtifact: artifact,
+      certifications: input.certifications,
+    }),
+  );
+
+  const blockingReasons: string[] = [];
+
+  if (input.manifest.freshnessPolicy.requireRepoCommit && !input.repoState.repoCommitSha) {
+    blockingReasons.push("Git commit SHA could not be resolved for this Wave 10 bundle.");
+  }
+
+  if (input.manifest.freshnessPolicy.requireCleanWorkingTree && input.repoState.workingTreeDirty) {
+    blockingReasons.push("Working tree is dirty, so the Wave 10 bundle is not commit-fresh.");
+  }
+
+  const ignoredLegacyRoots = input.manifest.freshnessPolicy.rejectLegacyRoots.map((relativePath) => ({
+    relativePath,
+    exists: false,
+  }));
+
+  for (const artifact of input.requiredArtifactStatuses) {
+    if (!artifact.exists) {
+      blockingReasons.push(`Required Wave 10 artifact missing: ${artifact.relativePath}`);
+    } else if (artifact.status !== "passed") {
+      blockingReasons.push(
+        `Wave 10 artifact ${artifact.relativePath} is present but not signed off (status ${artifact.status}).`,
+      );
+    }
+  }
+
+  for (const entry of [...releaseGateFixtures, ...representativeScenarios]) {
+    if (entry.status !== "passed") {
+      blockingReasons.push(`${entry.sourceKey} is ${entry.status}: ${entry.detail}`);
+    }
+  }
+
+  const coverage: Wave10FixtureCoverageManifest = {
+    schemaVersion: "wave-10-fixture-coverage/1",
+    generatedAt: new Date().toISOString(),
+    bundleRoot: wave10BundleRootDir,
+    repoState: input.repoState,
+    releaseGateFixtures,
+    representativeScenarios,
+    summary: {
+      releaseGateFixtures: releaseGateFixtures.length,
+      scenarios: representativeScenarios.length,
+      passedFixtures: releaseGateFixtures.filter((entry) => entry.status === "passed").length,
+      blockedFixtures: releaseGateFixtures.filter((entry) => entry.status !== "passed").length,
+      passedScenarios: representativeScenarios.filter((entry) => entry.status === "passed").length,
+      blockedScenarios: representativeScenarios.filter((entry) => entry.status !== "passed").length,
+    },
+  };
+
+  const requiredManualCoverage = [...releaseGateFixtures, ...representativeScenarios]
+    .filter((entry) => entry.requiredManualReview)
+    .map((entry) => ({
+      sourceKey: entry.sourceKey,
+      wordDesktop: entry.manualReviews.wordDesktop,
+      wordWeb: entry.manualReviews.wordWeb,
+    }));
+
+  const freshness: Wave10CertificationFreshnessManifest = {
+    schemaVersion: "wave-10-certification-freshness/1",
+    generatedAt: new Date().toISOString(),
+    bundleRoot: wave10BundleRootDir,
+    repoState: input.repoState,
+    overallStatus: blockingReasons.length === 0 ? "ready" : "blocked",
+    blockingReasons,
+    ignoredLegacyRoots,
+    requiredArtifacts: input.requiredArtifactStatuses,
+    requiredManualCoverage,
+  };
+
+  const requiredManualSurfaces = requiredManualCoverage.flatMap((entry) => [
+    entry.wordDesktop,
+    entry.wordWeb,
+  ]);
+
+  const regression: Wave10RegressionReport = {
+    schemaVersion: "wave-10-regression-report/1",
+    generatedAt: new Date().toISOString(),
+    bundleRoot: wave10BundleRootDir,
+    repoState: input.repoState,
+    overallStatus: blockingReasons.length === 0 ? "ready" : "blocked",
+    blockingReasons,
+    summary: {
+      releaseGateFixturesPassed: coverage.summary.passedFixtures,
+      releaseGateFixturesTotal: coverage.summary.releaseGateFixtures,
+      representativeScenariosPassed: coverage.summary.passedScenarios,
+      representativeScenariosTotal: coverage.summary.scenarios,
+      requiredArtifactsPassed: input.requiredArtifactStatuses.filter(
+        (artifact) => artifact.exists && artifact.status === "passed",
+      ).length,
+      requiredArtifactsTotal: input.requiredArtifactStatuses.length,
+      requiredManualSurfacesPassed: requiredManualSurfaces.filter(
+        (surface) => surface.status === "passed",
+      ).length,
+      requiredManualSurfacesTotal: requiredManualSurfaces.length,
+    },
+  };
+
+  return {
+    coverage,
+    freshness,
+    regression,
+  };
+}
+
+export async function generateWave10RegressionArtifacts(input: {
+  repoState?: RepoFreshnessState;
+} = {}): Promise<Wave10ReportModel> {
+  const [{ listManualCertifications }, { getHarnessSource }] = await Promise.all([
+    import("./certification-store.ts"),
+    import("./storage.ts"),
+  ]);
+  const manifest = await loadWave10CertificationManifest();
+  const repoState = input.repoState ?? (await resolveRepoFreshnessState());
+  const certifications = await listManualCertifications();
+  const [releaseGateFixtures, representativeScenarios] = await Promise.all([
+    Promise.all(
+      manifest.releaseGateFixtures.map(async (fixtureId) => ({
+        source: await getHarnessSource(`fixture:${fixtureId}`),
+        artifact: await readWave10SourceRunArtifact(fixtureId),
+      })),
+    ),
+    Promise.all(
+      manifest.representativeScenarios.map(async (scenarioId) => ({
+        source: await getHarnessSource(`scenario:${scenarioId}`),
+        artifact: await readWave10SourceRunArtifact(scenarioId),
+      })),
+    ),
+  ]);
+
+  const missingSources = [...releaseGateFixtures, ...representativeScenarios].filter(
+    (entry): entry is { source: undefined; artifact?: Wave10SourceRunArtifact } => !entry.source,
+  );
+
+  if (missingSources.length > 0) {
+    throw new Error(
+      `Wave 10 report cannot resolve sources for ${missingSources.length} manifest entries.`,
+    );
+  }
+
+  const requiredArtifactStatuses = await Promise.all(
+    manifest.requiredArtifacts.map((relativePath) => readSignoffArtifactStatus(relativePath)),
+  );
+  const ignoredLegacyRoots = await Promise.all(
+    manifest.freshnessPolicy.rejectLegacyRoots.map(async (relativePath) => ({
+      relativePath,
+      exists: await fileExists(path.join(repoRootDir, relativePath)),
+    })),
+  );
+
+  const model = buildWave10ReportModel({
+    manifest,
+    repoState,
+    releaseGateFixtures: releaseGateFixtures as Array<{
+      source: HarnessSourceRecord;
+      artifact?: Wave10SourceRunArtifact;
+    }>,
+    representativeScenarios: representativeScenarios as Array<{
+      source: HarnessSourceRecord;
+      artifact?: Wave10SourceRunArtifact;
+    }>,
+    certifications,
+    requiredArtifactStatuses,
+  });
+
+  model.freshness.ignoredLegacyRoots = ignoredLegacyRoots;
+
+  await ensureWave10BundleLayout();
+  await writeJsonAtomic(fixtureCoveragePath, model.coverage);
+  await writeJsonAtomic(certificationFreshnessPath, model.freshness);
+  await writeJsonAtomic(regressionReportPath, model.regression);
+
+  return model;
+}
+
+export function getWave10ArtifactPaths() {
+  return {
+    wave10BundleRootDir,
+    regressionReportPath,
+    fixtureCoveragePath,
+    certificationFreshnessPath,
+  };
+}