@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/starter/scripts/toolcraft-product-evidence-boundary-ast.mjs

@@ -3,54 +3,121 @@ import ts from "typescript";
 import {
   isNestedToolcraftStringComposition,
   isToolcraftStringCompositionNode,
-  createToolcraftStaticStringResolver,
 } from "./toolcraft-static-string.mjs";
-import {
-  createSourceFile,
-  getNodeLocation,
-} from "./toolcraft-product-boundary-ast-utils.mjs";
+
+const RESERVED_PIPELINE_BRIDGE_ATTRIBUTE =
+  "data-toolcraft-pipeline-evidence";
+const RESERVED_PIPELINE_BRIDGE_PATTERN =
+  /(?:^|[^\p{L}\p{N}_-])data-toolcraft-pipeline-evidence(?:$|[^\p{L}\p{N}_-])/u;
+const RESERVED_UNAVAILABLE_RESOURCE_FIXTURE_ATTRIBUTE =
+  "data-toolcraft-unavailable-resource-evidence";
+const RESERVED_UNAVAILABLE_RESOURCE_FIXTURE_PATTERN =
+  /(?:^|[^\p{L}\p{N}_.-])(?:data-toolcraft-unavailable-resource-evidence|toolcraft\.browser-proof\.unavailable-resource-request)(?:$|[^\p{L}\p{N}_.-])/u;
+const RESERVED_EVIDENCE_MESSAGE =
+  "Product-owned source must use protected observable, export, fixture, interaction, budget, and pipeline helpers; it must not import, bridge, or forge reserved browser evidence channels.";
+
+function referencesReservedPipelineBridge(staticValue) {
+  return (
+    typeof staticValue === "string" &&
+    RESERVED_PIPELINE_BRIDGE_PATTERN.test(staticValue)
+  );
+}
+
+function referencesReservedUnavailableResourceFixture(staticValue) {
+  return (
+    typeof staticValue === "string" &&
+    RESERVED_UNAVAILABLE_RESOURCE_FIXTURE_PATTERN.test(staticValue)
+  );
+}
 
 export function inspectToolcraftReservedEvidenceAccess({
-  absolutePath,
-  rawSource,
+  getNodeLocation,
   repoPath,
+  resolveStaticString,
+  sourceFile,
 }) {
-  const sourceFile = createSourceFile(absolutePath, rawSource);
-  const resolveStaticString = createToolcraftStaticStringResolver(sourceFile);
   const violations = [];
   const reportedLocations = new Set();
 
+  function reportReservedEvidence(node) {
+    const locationKey = `${node.getStart(sourceFile)}:${node.end}`;
+    if (reportedLocations.has(locationKey)) return;
+
+    reportedLocations.add(locationKey);
+    violations.push({
+      ...getNodeLocation(sourceFile, node),
+      kind: "reserved-runtime-evidence",
+      message: RESERVED_EVIDENCE_MESSAGE,
+      repoPath,
+    });
+  }
+
   function visit(node) {
     if (
       isToolcraftStringCompositionNode(node) &&
       !isNestedToolcraftStringComposition(node)
     ) {
       const staticValue = resolveStaticString(node);
+      const staticModuleValue =
+        typeof staticValue === "string"
+          ? staticValue.replace(/[?#].*$/u, "")
+          : undefined;
       const isReservedModule =
-        typeof staticValue === "string" &&
-        (/(?:^|\/)browser-runtime-evidence(?:\.[cm]?[jt]s)?$/u.test(staticValue) ||
-          /(?:^|\/)test-evidence\/browser-runtime-contract(?:\.[cm]?[jt]s)?$/u.test(
-            staticValue,
+        staticModuleValue !== undefined &&
+        (/(?:^|\/)browser-(?:runtime|performance)-evidence(?:\.[cm]?[jt]s)?$/u.test(
+          staticModuleValue,
+        ) ||
+          /(?:^|\/)browser-performance-measurement-(?:evidence|report)(?:\.[cm]?[jt]s)?$/u.test(
+            staticModuleValue,
+          ) ||
+          /(?:^|\/)browser-performance-report(?:\.[cm]?[jt]s)?$/u.test(
+            staticModuleValue,
+          ) ||
+          /(?:^|\/)performance-(?:checkpoint-report|environment-evidence|measurement-evidence)(?:\.[cm]?[jt]s)?$/u.test(
+            staticModuleValue,
+          ) ||
+          /(?:^|\/)performance-path-helpers(?:\.[cm]?[jt]s)?$/u.test(
+            staticModuleValue,
+          ) ||
+          /(?:^|\/)performance-pipeline-(?:evidence(?:-test-fixtures)?|invariants)(?:\.[cm]?[jt]s)?$/u.test(
+            staticModuleValue,
+          ) ||
+          /(?:^|\/)test-evidence\/browser-(?:runtime|performance|performance-measurement)-contract(?:\.[cm]?[jt]s)?$/u.test(
+            staticModuleValue,
+          ) ||
+          /(?:^|\/)toolcraft-(?:targeted-performance-report|kernel-benchmark-receipt)(?:\.[cm]?[jt]s)?$/u.test(
+            staticModuleValue,
           ));
       const isReservedPayload =
         staticValue === "toolcraft.browser-runtime-evidence" ||
+        staticValue === "toolcraft.browser-performance-evidence" ||
+        staticValue === "toolcraft.browser-performance-measurement" ||
+        staticValue === "toolcraft.performance-environment" ||
+        staticValue ===
+          "application/vnd.toolcraft.browser-runtime-evidence+json" ||
+        staticValue ===
+          "application/vnd.toolcraft.browser-performance-evidence+json" ||
+        staticValue ===
+          "application/vnd.toolcraft.browser-performance-measurement+json" ||
         staticValue ===
-          "application/vnd.toolcraft.browser-runtime-evidence+json";
-      const locationKey = `${node.getStart(sourceFile)}:${node.end}`;
-      if (
-        (isReservedModule || isReservedPayload) &&
-        !reportedLocations.has(locationKey)
-      ) {
-        reportedLocations.add(locationKey);
-        violations.push({
-          ...getNodeLocation(sourceFile, node),
-          kind: "reserved-runtime-evidence",
-          message:
-            "Product-owned source must use protected observable, export, fixture, interaction, and budget helpers; it must not import, bridge, or forge the reserved runtime evidence channel.",
-          repoPath,
-        });
+          "application/vnd.toolcraft.performance-environment+json" ||
+        referencesReservedPipelineBridge(staticValue) ||
+        referencesReservedUnavailableResourceFixture(staticValue) ||
+        staticValue === "toolcraft.renderer-pipeline-evidence.snapshot";
+      if (isReservedModule || isReservedPayload) {
+        reportReservedEvidence(node);
       }
     }
+    if (
+      ts.isJsxAttribute(node) &&
+      (
+        node.name.getText(sourceFile) === RESERVED_PIPELINE_BRIDGE_ATTRIBUTE ||
+        node.name.getText(sourceFile) ===
+          RESERVED_UNAVAILABLE_RESOURCE_FIXTURE_ATTRIBUTE
+      )
+    ) {
+      reportReservedEvidence(node);
+    }
     ts.forEachChild(node, visit);
   }
 
@@ -59,12 +126,11 @@ export function inspectToolcraftReservedEvidenceAccess({
 }
 
 export function inspectToolcraftModuleLoading({
-  absolutePath,
-  rawSource,
+  getNodeLocation,
   repoPath,
+  resolveStaticString,
+  sourceFile,
 }) {
-  const sourceFile = createSourceFile(absolutePath, rawSource);
-  const resolveStaticString = createToolcraftStaticStringResolver(sourceFile);
   const violations = [];
 
   function visit(node) {

package/templates/starter/scripts/toolcraft-product-evidence-boundary.test.mjs

@@ -22,7 +22,11 @@ test("protects every starter helper that writes reserved runtime evidence", asyn
 
   for (const helperPath of helperPaths) {
     const source = await fs.readFile(path.join(starterRoot, helperPath), "utf8");
-    if (/from\s+["']\.\/browser-runtime-evidence["']/u.test(source)) {
+    if (
+      /from\s+["']\.\/browser-(?:runtime|performance|performance-measurement)-evidence["']/u.test(
+        source,
+      )
+    ) {
       evidenceWriterPaths.push(helperPath);
     }
   }
@@ -34,6 +38,27 @@ test("protects every starter helper that writes reserved runtime evidence", asyn
     evidenceWriterPaths.filter((helperPath) => !protectedPathSet.has(helperPath)),
     [],
   );
+  assert.ok(evidenceWriterPaths.includes("e2e/performance-pipeline-evidence.ts"));
+  for (const protectedEvidencePath of [
+    "e2e/browser-performance-evidence.ts",
+    "e2e/browser-performance-measurement-evidence.ts",
+    "e2e/browser-performance-measurement-report.ts",
+    "e2e/browser-performance-report.ts",
+    "e2e/browser-runtime-evidence.ts",
+    "e2e/performance-checkpoint-report.ts",
+    "e2e/performance-environment-evidence.ts",
+    "e2e/performance-measurement-evidence.ts",
+    "e2e/performance-pipeline-evidence.ts",
+    "e2e/performance-pipeline-evidence-test-fixtures.ts",
+    "e2e/performance-pipeline-invariants.ts",
+    "src/app/test-evidence/browser-performance-contract.ts",
+    "src/app/test-evidence/browser-performance-measurement-contract.ts",
+  ]) {
+    assert.ok(
+      protectedPathSet.has(protectedEvidencePath),
+      `${protectedEvidencePath} must remain framework-owned.`,
+    );
+  }
 });
 
 test("rejects product tests that import or forge reserved runtime evidence", async (context) => {
@@ -66,6 +91,184 @@ test("rejects product tests that import or forge reserved runtime evidence", asy
   );
 });
 
+test("rejects product code that imports or forges rich performance evidence", async (context) => {
+  const rootDir = await createFixture(context, {
+    "e2e/app-controls.spec.ts": `
+      import { attachToolcraftBrowserPerformanceEvidence } from "./browser-performance-evidence";
+      import { attachToolcraftPerformanceMeasurementEvidence } from "./browser-performance-measurement-evidence";
+      import { evaluateToolcraftPerformanceMeasurements } from "./browser-performance-measurement-report";
+      import { evaluateToolcraftBrowserPerformanceEvidence } from "./browser-performance-report";
+      import { createToolcraftPerformanceCheckpointReport } from "./performance-checkpoint-report";
+      import { attachToolcraftPerformanceEnvironmentEvidence } from "./performance-environment-evidence";
+      import { finalizeToolcraftMeasurement } from "./performance-measurement-evidence";
+      import { expectToolcraftPipelineInvariant as internalPipelineHelper } from "./performance-pipeline-evidence";
+      import pipelineHelperSource from "./performance-pipeline-evidence.ts?raw";
+      import { pipelineEvidence } from "./performance-pipeline-evidence-test-fixtures";
+      import { getPipelineObservationInvariantErrors } from "./performance-pipeline-invariants";
+      import { runToolcraftPerformancePath } from "./performance-path-helpers";
+      import { serializeToolcraftBrowserPerformanceEvidence } from "../src/app/test-evidence/browser-performance-contract";
+      import { serializeToolcraftPerformanceMeasurement } from "../src/app/test-evidence/browser-performance-measurement-contract";
+      const forgedName = "toolcraft.browser-performance-" + "evidence";
+      const forgedContentType =
+        "application/vnd.toolcraft.browser-performance-" + "evidence+json";
+      const forgedMeasurementName =
+        "toolcraft.browser-performance-" + "measurement";
+      const forgedEnvironmentContentType =
+        "application/vnd.toolcraft.performance-" + "environment+json";
+      const bridgeAttribute = "data-toolcraft-pipeline-" + "evidence";
+      const bridgeSymbol =
+        "toolcraft.renderer-pipeline-evidence." + "snapshot";
+      void attachToolcraftBrowserPerformanceEvidence;
+      void attachToolcraftPerformanceMeasurementEvidence;
+      void evaluateToolcraftPerformanceMeasurements;
+      void evaluateToolcraftBrowserPerformanceEvidence;
+      void createToolcraftPerformanceCheckpointReport;
+      void attachToolcraftPerformanceEnvironmentEvidence;
+      void finalizeToolcraftMeasurement;
+      void internalPipelineHelper;
+      void pipelineHelperSource;
+      void pipelineEvidence;
+      void getPipelineObservationInvariantErrors;
+      void runToolcraftPerformancePath;
+      void serializeToolcraftBrowserPerformanceEvidence;
+      void serializeToolcraftPerformanceMeasurement;
+      void forgedName;
+      void forgedContentType;
+      void forgedMeasurementName;
+      void forgedEnvironmentContentType;
+      void bridgeAttribute;
+      void bridgeSymbol;
+    `,
+  });
+
+  const result = await evaluateToolcraftProductBoundary({ rootDir });
+
+  assert.equal(result.violations.length, 20);
+  assert.ok(
+    result.violations.every(
+      (violation) => violation.kind === "reserved-runtime-evidence",
+    ),
+  );
+});
+
+test("allows product adapters to import only the inert performance path contract", async (context) => {
+  const rootDir = await createFixture(context, {
+    "e2e/app-performance-path-adapters.ts": `
+      import type { ToolcraftPerformancePathAdapter } from "./performance-path-adapter-contract";
+      export const adapters = [] as const satisfies readonly ToolcraftPerformancePathAdapter[];
+    `,
+  });
+
+  const result = await evaluateToolcraftProductBoundary({ rootDir });
+
+  assert.deepEqual(result.violations, []);
+});
+
+test("allows product layer specs to use the public proof facade without reserved evidence imports", async (context) => {
+  const rootDir = await createFixture(context, {
+    "e2e/app-layers.spec.ts": `
+      import { expectToolcraftLayerReorder } from "./browser-layer-evidence-helpers";
+      import { createToolcraftBrowserProofSession } from "./browser-proof-session";
+      export async function proveLayerOrder(page: unknown) {
+        const session = await createToolcraftBrowserProofSession(page);
+        const action = session.targetAction("layers.order", async () => {});
+        void action;
+        void expectToolcraftLayerReorder;
+      }
+    `,
+    "e2e/browser-layer-evidence-helpers.ts": `
+      export async function expectToolcraftLayerReorder() {}
+    `,
+    "e2e/browser-proof-session.ts": `
+      export async function createToolcraftBrowserProofSession() {
+        return {
+          targetAction(target: string, run: () => Promise<void>) {
+            return { run, target };
+          },
+        };
+      }
+    `,
+  });
+
+  const result = await evaluateToolcraftProductBoundary({
+    protectedFilePaths: [
+      "e2e/browser-layer-evidence-helpers.ts",
+      "e2e/browser-proof-session.ts",
+    ],
+    rootDir,
+  });
+
+  assert.deepEqual(result.violations, []);
+});
+
+test("allows product specs to use the unavailable-resource facade but rejects its reserved bridge", async (context) => {
+  const allowedRoot = await createFixture(context, {
+    "e2e/app-canvas.spec.ts": `
+      import {
+        createToolcraftUnavailableImageResourceFixture,
+        expectToolcraftInfinityCanvasUnavailableImageExportEvidence,
+      } from "./browser-infinity-canvas-evidence";
+      void createToolcraftUnavailableImageResourceFixture;
+      void expectToolcraftInfinityCanvasUnavailableImageExportEvidence;
+    `,
+    "e2e/browser-infinity-canvas-evidence.ts": `
+      export function createToolcraftUnavailableImageResourceFixture() {}
+      export async function expectToolcraftInfinityCanvasUnavailableImageExportEvidence() {}
+    `,
+  });
+  const allowed = await evaluateToolcraftProductBoundary({
+    protectedFilePaths: ["e2e/browser-infinity-canvas-evidence.ts"],
+    rootDir: allowedRoot,
+  });
+  assert.deepEqual(allowed.violations, []);
+
+  const rejectedRoot = await createFixture(context, {
+    "e2e/app-canvas.spec.ts": `
+      const fixtureEvent =
+        "toolcraft.browser-proof.unavailable-resource-" + "request";
+      const fixtureAttribute =
+        "data-toolcraft-unavailable-resource-" + "evidence";
+      void fixtureEvent;
+      void fixtureAttribute;
+    `,
+    "src/product/unavailable-resource-bridge.tsx": `
+      export const ReservedBridge = () => (
+        <output data-toolcraft-unavailable-resource-evidence />
+      );
+    `,
+  });
+  const rejected = await evaluateToolcraftProductBoundary({
+    rootDir: rejectedRoot,
+  });
+  assert.deepEqual(
+    rejected.violations.map((violation) => violation.kind),
+    [
+      "reserved-runtime-evidence",
+      "reserved-runtime-evidence",
+      "reserved-runtime-evidence",
+    ],
+  );
+});
+
+test("rejects product selectors and JSX attributes that access the pipeline evidence bridge", async (context) => {
+  const rootDir = await createFixture(context, {
+    "src/product/pipeline-bridge.tsx": `
+      export const pipelineBridgeSelector =
+        "[data-toolcraft-pipeline-" + "evidence]";
+      export const PipelineBridge = () => (
+        <output data-toolcraft-pipeline-evidence />
+      );
+    `,
+  });
+
+  const result = await evaluateToolcraftProductBoundary({ rootDir });
+
+  assert.deepEqual(
+    result.violations.map((violation) => violation.kind),
+    ["reserved-runtime-evidence", "reserved-runtime-evidence"],
+  );
+});
+
 test("rejects reserved runtime evidence bridged through product production source", async (context) => {
   const rootDir = await createFixture(context, {
     "e2e/browser-runtime-evidence.ts": `

package/templates/starter/scripts/toolcraft-product-model-presentation-boundary.test.mjs

@@ -0,0 +1,49 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { evaluateToolcraftProductBoundary } from "./toolcraft-product-boundary.mjs";
+import { createToolcraftProductBoundaryFixture as createFixture } from "./toolcraft-product-boundary-test-fixtures.mjs";
+
+test("allows the checked presentation consumer without opening model internals", async (context) => {
+  const rootDir = await createFixture(context, {
+    "src/features/model-canvas.tsx": `
+      import { useToolcraftModelPresentationConsumer } from "@/toolcraft/runtime/react";
+      export function ModelCanvas() {
+        const consumer = useToolcraftModelPresentationConsumer({
+          id: "product-model",
+          sourceTarget: "source.model",
+        });
+        void consumer;
+        return <canvas data-product-model-canvas="source.model" />;
+      }
+    `,
+    "src/features/model-loader.ts": `
+      import { useToolcraftModelRenderHost } from "@/toolcraft/runtime/react";
+      import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+      import { createModelSourceBundle } from "@/toolcraft/runtime/model-import/model-source-bundle";
+      import { createToolcraftModelPresentationResourceManager } from "@/toolcraft/runtime/react/model-rendering/model-presentation-resource-manager";
+      void useToolcraftModelRenderHost;
+      void GLTFLoader;
+      void createModelSourceBundle;
+      void createToolcraftModelPresentationResourceManager;
+    `,
+  });
+
+  const result = await evaluateToolcraftProductBoundary({ rootDir });
+
+  assert.deepEqual(
+    result.violations.map((violation) => violation.kind).sort(),
+    [
+      "runtime-model-import-ownership",
+      "runtime-model-import-ownership",
+      "runtime-model-presentation-ownership",
+      "runtime-model-presentation-ownership",
+    ],
+  );
+  assert.equal(
+    result.violations.some((violation) =>
+      violation.repoPath.endsWith("model-canvas.tsx"),
+    ),
+    false,
+  );
+});

package/templates/starter/scripts/toolcraft-product-observable-facade.test.mjs

@@ -0,0 +1,223 @@
+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 { pathToFileURL } from "node:url";
+
+import ts from "typescript";
+
+const starterRoot = path.resolve(import.meta.dirname, "..");
+const helperPath = path.join(starterRoot, "e2e/product-observable-helpers.ts");
+
+async function loadProductObservableFacade(context) {
+  const outputDir = await fs.mkdtemp(
+    path.join(os.tmpdir(), "toolcraft-product-observable-"),
+  );
+  context.after(() => fs.rm(outputDir, { force: true, recursive: true }));
+  const outputPath = path.join(outputDir, "product-observable-helpers.mjs");
+  const source = (await fs.readFile(helperPath, "utf8"))
+    .replaceAll('"@playwright/test"', '"./playwright.mjs"')
+    .replaceAll('"./browser-runtime-evidence"', '"./evidence.mjs"')
+    .replaceAll('"./browser-proof-session"', '"./proof-session.mjs"')
+    .replaceAll('"./stable-outcome-helpers"', '"./stable-outcome.mjs"');
+  const { outputText } = ts.transpileModule(source, {
+    compilerOptions: {
+      module: ts.ModuleKind.ESNext,
+      target: ts.ScriptTarget.ES2022,
+    },
+    fileName: helperPath,
+  });
+
+  await Promise.all([
+    fs.writeFile(outputPath, outputText),
+    fs.writeFile(
+      path.join(outputDir, "playwright.mjs"),
+      `
+        export function expect(actual, message = "Expectation failed") {
+          return {
+            async toBeVisible() {
+              if (!actual?.visible) throw new Error(message);
+            },
+          };
+        }
+      `,
+    ),
+    fs.writeFile(
+      path.join(outputDir, "evidence.mjs"),
+      `
+        export async function attachToolcraftBrowserRuntimeEvidence(evidence) {
+          globalThis.__toolcraftProductObservableAttachments.push(evidence);
+        }
+      `,
+    ),
+    fs.writeFile(
+      path.join(outputDir, "proof-session.mjs"),
+      `
+        export function assertToolcraftBrowserActionForSession(session, action) {
+          if (action.session !== session) throw new Error("wrong proof session");
+        }
+        export function getToolcraftBrowserActionTarget(action) {
+          return action.target;
+        }
+        export async function getToolcraftBrowserProofPage(session) {
+          return session.page;
+        }
+        export function isToolcraftBrowserAction(action) {
+          return action?.kind === "action";
+        }
+        export function isToolcraftBrowserProofSession(session) {
+          return session?.kind === "session";
+        }
+        export async function runToolcraftBrowserAction(action) {
+          await action.run();
+        }
+      `,
+    ),
+    fs.writeFile(
+      path.join(outputDir, "stable-outcome.mjs"),
+      `
+        export async function expectToolcraftPersistentOutcomeAfterAction(
+          observe,
+          action,
+          options,
+        ) {
+          const before = await observe();
+          await action();
+          const after = await observe();
+          if (after === before) {
+            throw new Error(options.message);
+          }
+        }
+      `,
+    ),
+  ]);
+
+  return import(`${pathToFileURL(outputPath).href}?test=${Date.now()}`);
+}
+
+function createPage({
+  height = 100,
+  raster = [137, 80, 78, 71],
+  width = 160,
+} = {}) {
+  const state = {
+    height,
+    metadata: {
+      ariaLabel: "before",
+      className: "before",
+      hiddenContent: "before",
+      href: "/before",
+      role: "img",
+    },
+    raster: [...raster],
+    rasterEvaluations: 0,
+    screenshotCalls: 0,
+    width,
+  };
+  const locator = {
+    visible: true,
+    async boundingBox() {
+      return { height: state.height, width: state.width, x: 8, y: 12 };
+    },
+    first() {
+      return this;
+    },
+    async screenshot(options) {
+      assert.deepEqual(options, {
+        animations: "disabled",
+        caret: "hide",
+        scale: "css",
+        type: "png",
+      });
+      state.screenshotCalls += 1;
+      return Uint8Array.from(state.raster);
+    },
+  };
+
+  return {
+    page: {
+      async evaluate(_reader, input) {
+        if (input === undefined) return undefined;
+        state.rasterEvaluations += 1;
+        let hash = 2166136261;
+        for (const byte of state.raster) {
+          hash ^= byte;
+          hash = Math.imul(hash, 16777619);
+        }
+        return {
+          height: state.height,
+          rasterHash: (hash >>> 0).toString(16),
+          width: state.width,
+        };
+      },
+      locator() {
+        return locator;
+      },
+    },
+    state,
+  };
+}
+
+test("product observable proof rejects metadata-only and hidden bookkeeping changes", async (context) => {
+  const facade = await loadProductObservableFacade(context);
+  globalThis.__toolcraftProductObservableAttachments = [];
+  const { page, state } = createPage();
+
+  await assert.rejects(
+    facade.expectToolcraftProductObservableToChange(page, async () => {
+      state.metadata = {
+        ariaLabel: "after",
+        className: "after",
+        hiddenContent: "after",
+        href: "/after",
+        role: "presentation",
+      };
+    }),
+    /Product output should change/u,
+  );
+
+  assert.equal(state.screenshotCalls, 3);
+  assert.equal(state.rasterEvaluations, 2);
+  assert.deepEqual(globalThis.__toolcraftProductObservableAttachments, []);
+});
+
+test("product observable proof detects a visible raster change and attaches exact evidence", async (context) => {
+  const facade = await loadProductObservableFacade(context);
+  globalThis.__toolcraftProductObservableAttachments = [];
+  const { page, state } = createPage();
+  const session = { kind: "session", page };
+  const action = {
+    kind: "action",
+    run: async () => {
+      state.raster = [137, 80, 78, 71, 1];
+    },
+    session,
+    target: "material.chocolate",
+  };
+
+  await facade.expectToolcraftProductObservableToChange(session, action, {
+    requirementId: "material.chocolate",
+  });
+
+  assert.equal(state.screenshotCalls, 3);
+  assert.equal(state.rasterEvaluations, 2);
+  assert.deepEqual(globalThis.__toolcraftProductObservableAttachments, [
+    {
+      evidenceType: "product-observable-change",
+      requirementId: "material.chocolate",
+      target: "material.chocolate",
+    },
+  ]);
+});
+
+test("product observable proof fails closed before capturing an oversized surface", async (context) => {
+  const facade = await loadProductObservableFacade(context);
+  const { page, state } = createPage({ height: 2200, width: 4096 });
+
+  await assert.rejects(
+    facade.getToolcraftProductObservableSnapshot(page),
+    /exceeds the bounded visual proof limit/u,
+  );
+  assert.equal(state.screenshotCalls, 0);
+});