@pixel-point/toolcraft 0.0.14 → 0.0.15

package/templates/starter/scripts/toolcraft-verification-receipt.mjs

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  assertToolcraftVerificationInputsUnchanged,
+  collectToolcraftVerificationInputs,
+  createToolcraftVerificationSourceHash,
+} from "./toolcraft-verification-inventory.mjs";
+
+export {
+  assertToolcraftVerificationInputsUnchanged,
+  collectToolcraftVerificationInputs,
+};
+
+export const TOOLCRAFT_PERFORMANCE_RECEIPT_VERSION = 1;
+export const TOOLCRAFT_PERFORMANCE_EXEMPTION_REASON =
+  "post-first-working-non-performance";
+
+const acceptedRunners = new Set(["playwright-fallback"]);
+const performanceExemptionBlockedRootFiles = new Set([
+  "index.html",
+  "npm-shrinkwrap.json",
+  "package-lock.json",
+  "package.json",
+  "playwright.config.ts",
+  "pnpm-lock.yaml",
+  "tsconfig.json",
+  "vite.config.ts",
+]);
+const performanceSensitivePathPattern =
+  /(?:^|[/_.-])(?:animation|canvas|exports?|images?|keyframes?|layers?|media|outputs?|performance|renders?|renderers?|rendering|shaders?|timeline|uploads?|videos?|viewport|webgl|workers?)(?=$|[/_.-])/u;
+
+function compareCodeUnits(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function toPosixPath(value) {
+  return value.split(path.sep).join("/");
+}
+
+export function getToolcraftPerformanceReceiptPath(rootDir) {
+  return path.join(
+    path.resolve(rootDir),
+    ".toolcraft",
+    "verification",
+    "performance.json",
+  );
+}
+
+async function writeReceipt(rootDir, receipt) {
+  const receiptPath = getToolcraftPerformanceReceiptPath(rootDir);
+  await fs.mkdir(path.dirname(receiptPath), { recursive: true });
+  const temporaryPath = `${receiptPath}.${process.pid}.tmp`;
+  await fs.writeFile(temporaryPath, `${JSON.stringify(receipt, null, 2)}\n`);
+  await fs.rename(temporaryPath, receiptPath);
+  return receipt;
+}
+
+export async function clearToolcraftPerformanceReceipt(rootDir) {
+  await fs.rm(getToolcraftPerformanceReceiptPath(rootDir), { force: true });
+}
+
+function isReceiptFileEntry(value) {
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    typeof value.path !== "string" ||
+    typeof value.sha256 !== "string"
+  ) {
+    return false;
+  }
+  const pathSegments = value.path.split("/");
+  return (
+    value.path.length > 0 &&
+    !value.path.includes("\\") &&
+    !path.posix.isAbsolute(value.path) &&
+    !pathSegments.some(
+      (segment) => segment === "" || segment === "." || segment === "..",
+    ) &&
+    /^[a-f0-9]{64}$/u.test(value.sha256)
+  );
+}
+
+function getReceiptInventoryError(receipt) {
+  const uniquePaths = new Set(receipt.files.map((entry) => entry.path));
+  if (uniquePaths.size !== receipt.files.length) {
+    return "Toolcraft performance receipt file inventory contains duplicate paths.";
+  }
+  if (createToolcraftVerificationSourceHash(receipt.files) !== receipt.sourceHash) {
+    return "Toolcraft performance receipt file inventory does not produce its source hash.";
+  }
+  return undefined;
+}
+
+function getReceiptShapeError(receipt) {
+  if (
+    typeof receipt !== "object" ||
+    receipt === null ||
+    Array.isArray(receipt) ||
+    receipt.version !== TOOLCRAFT_PERFORMANCE_RECEIPT_VERSION ||
+    typeof receipt.sourceHash !== "string" ||
+    !Array.isArray(receipt.files) ||
+    !receipt.files.every(isReceiptFileEntry)
+  ) {
+    return "Toolcraft performance receipt is malformed or uses an unsupported version.";
+  }
+  if (receipt.status !== "passed" && receipt.status !== "not-required") {
+    return "Toolcraft performance receipt must record a passed checkpoint or typed not-required exemption.";
+  }
+  if (receipt.kind === "performance-checkpoint") {
+    if (receipt.status !== "passed" || !acceptedRunners.has(receipt.runner)) {
+      return "Toolcraft performance checkpoint receipt must be passed and name a supported runner.";
+    }
+    return getReceiptInventoryError(receipt);
+  }
+  if (receipt.kind === "performance-exemption") {
+    if (
+      receipt.status !== "not-required" ||
+      receipt.reasonCode !== TOOLCRAFT_PERFORMANCE_EXEMPTION_REASON ||
+      ![0, 1, 2].includes(receipt.verificationTier) ||
+      typeof receipt.baselineSourceHash !== "string" ||
+      !Array.isArray(receipt.changedFiles) ||
+      !receipt.changedFiles.every((item) => typeof item === "string")
+    ) {
+      return "Toolcraft performance exemption receipt is malformed.";
+    }
+    return getReceiptInventoryError(receipt);
+  }
+  return "Toolcraft performance receipt kind is unsupported.";
+}
+
+async function readReceipt(rootDir) {
+  const receiptPath = getToolcraftPerformanceReceiptPath(rootDir);
+  let source;
+  try {
+    source = await fs.readFile(receiptPath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return { missing: true };
+    throw error;
+  }
+  try {
+    return { receipt: JSON.parse(source) };
+  } catch {
+    return { malformed: true };
+  }
+}
+
+export async function validateToolcraftPerformanceReceipt({ rootDir }) {
+  const loaded = await readReceipt(rootDir);
+  if (loaded.missing) {
+    return [
+      "Toolcraft performance receipt is missing. Run the required browser performance checkpoint for the current sources.",
+    ];
+  }
+  if (loaded.malformed) {
+    return ["Toolcraft performance receipt is malformed JSON."];
+  }
+
+  const shapeError = getReceiptShapeError(loaded.receipt);
+  if (shapeError) return [shapeError];
+
+  const inventory = await collectToolcraftVerificationInputs(rootDir);
+  if (loaded.receipt.sourceHash !== inventory.sourceHash) {
+    return [
+      "Toolcraft performance receipt is stale because product or verification inputs changed after the recorded checkpoint.",
+    ];
+  }
+  return [];
+}
+
+function getChangedFiles(previousFiles, currentFiles) {
+  const previous = new Map(previousFiles.map((entry) => [entry.path, entry.sha256]));
+  const current = new Map(currentFiles.map((entry) => [entry.path, entry.sha256]));
+  return [...new Set([...previous.keys(), ...current.keys()])]
+    .filter((filePath) => previous.get(filePath) !== current.get(filePath))
+    .sort(compareCodeUnits);
+}
+
+function blocksToolcraftPerformanceExemption(filePath) {
+  const normalizedPath = toPosixPath(filePath).replace(/^\.\//u, "").toLowerCase();
+
+  return (
+    performanceExemptionBlockedRootFiles.has(normalizedPath) ||
+    normalizedPath.startsWith("public/") ||
+    normalizedPath.startsWith("scripts/") ||
+    normalizedPath.startsWith("src/toolcraft/") ||
+    /^src\/app\/app-composition\.[^/]+$/u.test(normalizedPath) ||
+    performanceSensitivePathPattern.test(normalizedPath)
+  );
+}
+
+export function getToolcraftPerformanceExemptionBlockedFiles(changedFiles) {
+  return [...new Set(changedFiles.filter(blocksToolcraftPerformanceExemption))].sort(
+    compareCodeUnits,
+  );
+}
+
+export async function writeToolcraftPerformanceExemption({
+  reasonCode,
+  rootDir,
+  verificationTier,
+}) {
+  if (reasonCode !== TOOLCRAFT_PERFORMANCE_EXEMPTION_REASON) {
+    throw new Error(
+      `Toolcraft performance exemption reason must be ${TOOLCRAFT_PERFORMANCE_EXEMPTION_REASON}.`,
+    );
+  }
+  if (![0, 1, 2].includes(verificationTier)) {
+    throw new Error("Toolcraft performance exemptions are limited to verification tiers 0, 1, or 2.");
+  }
+  const loaded = await readReceipt(rootDir);
+  const shapeError = loaded.receipt ? getReceiptShapeError(loaded.receipt) : undefined;
+  if (
+    !loaded.receipt ||
+    shapeError ||
+    loaded.receipt.kind !== "performance-checkpoint" ||
+    loaded.receipt.status !== "passed"
+  ) {
+    throw new Error(
+      "A typed performance exemption requires a prior passed performance checkpoint receipt.",
+    );
+  }
+
+  const inventory = await collectToolcraftVerificationInputs(rootDir);
+  const changedFiles = getChangedFiles(loaded.receipt.files, inventory.entries);
+  if (changedFiles.length === 0) {
+    throw new Error("A performance exemption requires at least one changed verification input.");
+  }
+  const blockedFiles = getToolcraftPerformanceExemptionBlockedFiles(changedFiles);
+  if (blockedFiles.length > 0) {
+    throw new Error(
+      `A performance exemption cannot cover Tier 3 or Tier 4 changes: ${blockedFiles.join(", ")}. Run pnpm verify:perf for the current sources.`,
+    );
+  }
+  return writeReceipt(rootDir, {
+    baselineSourceHash: loaded.receipt.sourceHash,
+    changedFiles,
+    completedAt: new Date().toISOString(),
+    files: inventory.entries,
+    kind: "performance-exemption",
+    reasonCode,
+    sourceHash: inventory.sourceHash,
+    status: "not-required",
+    verificationTier,
+    version: TOOLCRAFT_PERFORMANCE_RECEIPT_VERSION,
+  });
+}
+
+async function runCli() {
+  const projectDir = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+  );
+  const [command = "validate", ...args] = process.argv.slice(2);
+
+  if (command === "record-exemption") {
+    const tierArgument = args.find((argument) => argument.startsWith("--tier="));
+    const verificationTier = Number(tierArgument?.slice("--tier=".length));
+    await writeToolcraftPerformanceExemption({
+      reasonCode: TOOLCRAFT_PERFORMANCE_EXEMPTION_REASON,
+      rootDir: projectDir,
+      verificationTier,
+    });
+    console.log("Recorded current-source Toolcraft post-first-working performance exemption.");
+    return;
+  }
+  if (command !== "validate") {
+    throw new Error(`Unknown Toolcraft verification receipt command: ${command}.`);
+  }
+  const errors = await validateToolcraftPerformanceReceipt({ rootDir: projectDir });
+  if (errors.length > 0) {
+    throw new Error(errors.join("\n"));
+  }
+  console.log("Toolcraft performance receipt is current and valid.");
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  runCli().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+  });
+}

package/templates/starter/scripts/toolcraft-verification-receipt.test.mjs

@@ -0,0 +1,282 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  TOOLCRAFT_PERFORMANCE_RECEIPT_VERSION,
+  collectToolcraftVerificationInputs,
+  getToolcraftPerformanceExemptionBlockedFiles,
+  getToolcraftPerformanceReceiptPath,
+  validateToolcraftPerformanceReceipt,
+  writeToolcraftPerformanceExemption,
+} from "./toolcraft-verification-receipt.mjs";
+import * as receiptModule from "./toolcraft-verification-receipt.mjs";
+
+async function createFixture() {
+  const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-receipt-"));
+  await fs.mkdir(path.join(rootDir, "src", "app"), { recursive: true });
+  await fs.mkdir(path.join(rootDir, "e2e"), { recursive: true });
+  await fs.writeFile(
+    path.join(rootDir, "src", "app", "app-schema.ts"),
+    'export const schema = { mode: "initial" };\n',
+  );
+  await fs.writeFile(
+    path.join(rootDir, "e2e", "app-performance.spec.ts"),
+    'export const scenario = "heavy";\n',
+  );
+  await fs.writeFile(
+    path.join(rootDir, "package.json"),
+    JSON.stringify({ name: "receipt-fixture", private: true }),
+  );
+  return rootDir;
+}
+
+async function writePassedCheckpointFixture(
+  rootDir,
+  { runner = "playwright-fallback" } = {},
+) {
+  const inventory = await collectToolcraftVerificationInputs(rootDir);
+  const receiptPath = getToolcraftPerformanceReceiptPath(rootDir);
+  await fs.mkdir(path.dirname(receiptPath), { recursive: true });
+  await fs.writeFile(
+    receiptPath,
+    `${JSON.stringify(
+      {
+        completedAt: new Date().toISOString(),
+        files: inventory.entries,
+        kind: "performance-checkpoint",
+        runner,
+        sourceHash: inventory.sourceHash,
+        status: "passed",
+        version: TOOLCRAFT_PERFORMANCE_RECEIPT_VERSION,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+
+test("does not expose a reusable passed-checkpoint writer", () => {
+  assert.equal("writeToolcraftPerformanceReceipt" in receiptModule, false);
+});
+
+test("rejects verification inputs that change during a protected checkpoint", () => {
+  const assertStable = receiptModule.assertToolcraftVerificationInputsUnchanged;
+  assert.equal(typeof assertStable, "function");
+  assert.doesNotThrow(() =>
+    assertStable({
+      baseline: { entries: [], sourceHash: "same" },
+      current: { entries: [], sourceHash: "same" },
+      phase: "after build",
+    }),
+  );
+  assert.throws(
+    () =>
+      assertStable({
+        baseline: { entries: [], sourceHash: "before" },
+        current: { entries: [], sourceHash: "after" },
+        phase: "after Playwright",
+      }),
+    /verification inputs changed.*after Playwright/iu,
+  );
+});
+
+test("classifies obvious Tier 3 and Tier 4 paths without blocking ordinary Tier 0-2 files", () => {
+  assert.deepEqual(
+    getToolcraftPerformanceExemptionBlockedFiles([
+      "src/app/app-schema.ts",
+      "src/app/app-acceptance-data.ts",
+      "src/app/app-schema.test.ts",
+      "src/product/control-mapping.ts",
+      "e2e/app-controls.spec.ts",
+      "src/styles/panel.module.css",
+      "package-lock.json",
+      "public/source.png",
+      "scripts/check.mjs",
+      "src/toolcraft/runtime.ts",
+      "src/app/app-composition.tsx",
+      "src/app/app-performance.ts",
+      "src/product/product-output.ts",
+      "src/product/renderer.ts",
+      "src/product/canvas-worker.ts",
+      "src/product/viewport.ts",
+    ]),
+    [
+      "package-lock.json",
+      "public/source.png",
+      "scripts/check.mjs",
+      "src/app/app-composition.tsx",
+      "src/app/app-performance.ts",
+      "src/product/canvas-worker.ts",
+      "src/product/product-output.ts",
+      "src/product/renderer.ts",
+      "src/product/viewport.ts",
+      "src/toolcraft/runtime.ts",
+    ],
+  );
+});
+
+test("requires a structured receipt instead of prose-only performance claims", async (t) => {
+  const rootDir = await createFixture();
+  t.after(() => fs.rm(rootDir, { force: true, recursive: true }));
+  await fs.mkdir(path.join(rootDir, "docs", "toolcraft"), { recursive: true });
+  await fs.writeFile(
+    path.join(rootDir, "docs", "toolcraft", "agent-worklog.md"),
+    "- Run: pnpm verify:perf passed\n",
+  );
+
+  const errors = await validateToolcraftPerformanceReceipt({ rootDir });
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /performance receipt is missing/iu);
+});
+
+test("accepts a passed receipt only while its source inventory is current", async (t) => {
+  const rootDir = await createFixture();
+  t.after(() => fs.rm(rootDir, { force: true, recursive: true }));
+  await writePassedCheckpointFixture(rootDir);
+
+  assert.deepEqual(await validateToolcraftPerformanceReceipt({ rootDir }), []);
+
+  await fs.writeFile(
+    path.join(rootDir, "src", "app", "app-schema.ts"),
+    'export const schema = { mode: "changed" };\n',
+  );
+  const staleErrors = await validateToolcraftPerformanceReceipt({ rootDir });
+  assert.equal(staleErrors.length, 1);
+  assert.match(staleErrors[0], /stale/iu);
+});
+
+test("rejects manual agent-browser receipts without automated runner proof", async (t) => {
+  const rootDir = await createFixture();
+  t.after(() => fs.rm(rootDir, { force: true, recursive: true }));
+  await writePassedCheckpointFixture(rootDir, { runner: "agent-browser" });
+
+  assert.match(
+    (await validateToolcraftPerformanceReceipt({ rootDir }))[0],
+    /supported runner/iu,
+  );
+});
+
+test("rejects a receipt whose file inventory does not produce its source hash", async (t) => {
+  const rootDir = await createFixture();
+  t.after(() => fs.rm(rootDir, { force: true, recursive: true }));
+  const inventory = await collectToolcraftVerificationInputs(rootDir);
+  const receiptPath = getToolcraftPerformanceReceiptPath(rootDir);
+  await fs.mkdir(path.dirname(receiptPath), { recursive: true });
+  await fs.writeFile(
+    receiptPath,
+    `${JSON.stringify(
+      {
+        completedAt: new Date().toISOString(),
+        files: [],
+        kind: "performance-checkpoint",
+        runner: "playwright-fallback",
+        sourceHash: inventory.sourceHash,
+        status: "passed",
+        version: TOOLCRAFT_PERFORMANCE_RECEIPT_VERSION,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+
+  assert.match(
+    (await validateToolcraftPerformanceReceipt({ rootDir }))[0],
+    /file inventory.*source hash/iu,
+  );
+});
+
+test("invalidates a checkpoint when the npm dependency graph changes", async (t) => {
+  const rootDir = await createFixture();
+  t.after(() => fs.rm(rootDir, { force: true, recursive: true }));
+  const packageLockPath = path.join(rootDir, "package-lock.json");
+  await fs.writeFile(
+    packageLockPath,
+    JSON.stringify({ lockfileVersion: 3, packages: {} }),
+  );
+  await writePassedCheckpointFixture(rootDir);
+
+  await fs.writeFile(
+    packageLockPath,
+    JSON.stringify({
+      lockfileVersion: 3,
+      packages: { "node_modules/example": { version: "2.0.0" } },
+    }),
+  );
+
+  assert.match(
+    (await validateToolcraftPerformanceReceipt({ rootDir }))[0],
+    /stale/iu,
+  );
+});
+
+test("rejects malformed and non-passed receipts", async (t) => {
+  const rootDir = await createFixture();
+  t.after(() => fs.rm(rootDir, { force: true, recursive: true }));
+  const receiptPath = getToolcraftPerformanceReceiptPath(rootDir);
+  await fs.mkdir(path.dirname(receiptPath), { recursive: true });
+  await fs.writeFile(receiptPath, "not json");
+  const malformedErrors = await validateToolcraftPerformanceReceipt({ rootDir });
+  assert.equal(malformedErrors.length, 1);
+  assert.match(malformedErrors[0], /malformed/iu);
+
+  await fs.writeFile(
+    receiptPath,
+    JSON.stringify({
+      kind: "performance-checkpoint",
+      files: [],
+      runner: "playwright-fallback",
+      sourceHash: "invalid",
+      status: "failed",
+      version: 1,
+    }),
+  );
+  const failedErrors = await validateToolcraftPerformanceReceipt({ rootDir });
+  assert.equal(failedErrors.length, 1);
+  assert.match(failedErrors[0], /passed/iu);
+});
+
+test("permits only a current typed post-first-working exemption backed by a prior pass", async (t) => {
+  const rootDir = await createFixture();
+  t.after(() => fs.rm(rootDir, { force: true, recursive: true }));
+  await writePassedCheckpointFixture(rootDir);
+  await fs.writeFile(
+    path.join(rootDir, "src", "app", "app-schema.ts"),
+    'export const schema = { mode: "non-performance-feature" };\n',
+  );
+  await writeToolcraftPerformanceExemption({
+    reasonCode: "post-first-working-non-performance",
+    rootDir,
+    verificationTier: 2,
+  });
+
+  assert.deepEqual(await validateToolcraftPerformanceReceipt({ rootDir }), []);
+
+  await fs.writeFile(
+    path.join(rootDir, "e2e", "app-performance.spec.ts"),
+    'export const scenario = "changed-after-exemption";\n',
+  );
+  const staleErrors = await validateToolcraftPerformanceReceipt({ rootDir });
+  assert.equal(staleErrors.length, 1);
+  assert.match(staleErrors[0], /stale/iu);
+});
+
+test("rejects exemptions for obvious Tier 3 renderer changes", async (t) => {
+  const rootDir = await createFixture();
+  t.after(() => fs.rm(rootDir, { force: true, recursive: true }));
+  const rendererPath = path.join(rootDir, "src", "product-renderer.ts");
+  await fs.writeFile(rendererPath, "export const render = () => 1;\n");
+  await writePassedCheckpointFixture(rootDir);
+  await fs.writeFile(rendererPath, "export const render = () => 2;\n");
+
+  await assert.rejects(
+    writeToolcraftPerformanceExemption({
+      reasonCode: "post-first-working-non-performance",
+      rootDir,
+      verificationTier: 2,
+    }),
+    /product-renderer\.ts.*pnpm verify:perf/iu,
+  );
+});

package/templates/starter/scripts/toolcraft-vitest-runtime-contract.d.mts

@@ -0,0 +1,32 @@
+export type ToolcraftVitestRuntimeRequirement = {
+  kind: "acceptance" | "performance";
+  requirementId: string;
+  testName: string;
+};
+
+export type ToolcraftVitestRuntimeTest = {
+  expectedFailure: boolean;
+  filePath: string;
+  name: string;
+  owner: "framework" | "product";
+  state: "failed" | "passed" | "pending" | "skipped";
+};
+
+export const TOOLCRAFT_VITEST_RUNTIME_EVIDENCE_VERSION: 1;
+export const TOOLCRAFT_VITEST_RUNTIME_REQUIREMENTS_ANNOTATION_TYPE: string;
+export const TOOLCRAFT_VITEST_RUNTIME_MARKER_TEST_NAME: string;
+export const TOOLCRAFT_VITEST_RUNTIME_MARKER_FILE_NAMES: readonly string[];
+
+export function serializeToolcraftVitestRuntimeRequirements(
+  requirements: readonly ToolcraftVitestRuntimeRequirement[],
+): string;
+
+export function parseToolcraftVitestRuntimeRequirements(annotation: {
+  message: string;
+  type: string;
+}): ToolcraftVitestRuntimeRequirement[] | undefined;
+
+export function evaluateToolcraftVitestRuntimeEvidence(input: {
+  requirements: readonly ToolcraftVitestRuntimeRequirement[];
+  tests: readonly ToolcraftVitestRuntimeTest[];
+}): string[];

package/templates/starter/scripts/toolcraft-vitest-runtime-contract.mjs

@@ -0,0 +1,88 @@
+export const TOOLCRAFT_VITEST_RUNTIME_EVIDENCE_VERSION = 1;
+export const TOOLCRAFT_VITEST_RUNTIME_REQUIREMENTS_ANNOTATION_TYPE =
+  "toolcraft.automated-runtime-requirements";
+export const TOOLCRAFT_VITEST_RUNTIME_MARKER_TEST_NAME =
+  "toolcraft: validate complete automated runtime coverage";
+export const TOOLCRAFT_VITEST_RUNTIME_MARKER_FILE_NAMES = Object.freeze([
+  "starter-automated-runtime-evidence.test.ts",
+  "app-automated-runtime-evidence.test.ts",
+]);
+
+export function serializeToolcraftVitestRuntimeRequirements(requirements) {
+  return JSON.stringify({
+    requirements,
+    version: TOOLCRAFT_VITEST_RUNTIME_EVIDENCE_VERSION,
+  });
+}
+
+export function parseToolcraftVitestRuntimeRequirements(annotation) {
+  if (
+    !annotation ||
+    annotation.type !== TOOLCRAFT_VITEST_RUNTIME_REQUIREMENTS_ANNOTATION_TYPE
+  ) {
+    return undefined;
+  }
+
+  try {
+    const payload = JSON.parse(annotation.message);
+    if (
+      payload?.version !== TOOLCRAFT_VITEST_RUNTIME_EVIDENCE_VERSION ||
+      !Array.isArray(payload.requirements) ||
+      payload.requirements.some(
+        (requirement) =>
+          !requirement ||
+          !["acceptance", "performance"].includes(requirement.kind) ||
+          typeof requirement.requirementId !== "string" ||
+          !requirement.requirementId.trim() ||
+          typeof requirement.testName !== "string" ||
+          !requirement.testName.trim(),
+      )
+    ) {
+      return undefined;
+    }
+
+    return payload.requirements;
+  } catch {
+    return undefined;
+  }
+}
+
+export function evaluateToolcraftVitestRuntimeEvidence({ requirements, tests }) {
+  const errors = [];
+
+  for (const requirement of requirements) {
+    const matchingTests = tests.filter(
+      (test) =>
+        test.owner === "product" && test.name === requirement.testName,
+    );
+
+    if (matchingTests.length === 0) {
+      errors.push(
+        `Missing required automated test "${requirement.testName}" for ${requirement.kind} requirement "${requirement.requirementId}".`,
+      );
+      continue;
+    }
+
+    if (matchingTests.length > 1) {
+      errors.push(
+        `Duplicate required automated test "${requirement.testName}" for ${requirement.kind} requirement "${requirement.requirementId}". Each requirement needs one product-owned test.`,
+      );
+      continue;
+    }
+
+    const [test] = matchingTests;
+    if (test.expectedFailure) {
+      errors.push(
+        `Required automated test "${requirement.testName}" must not use expected-failure mode in ${test.filePath}.`,
+      );
+      continue;
+    }
+    if (test.state !== "passed") {
+      errors.push(
+        `Required automated test "${requirement.testName}" must finish with status "passed"; received "${test.state}" in ${test.filePath}.`,
+      );
+    }
+  }
+
+  return errors;
+}