harnery 0.38.0 → 0.40.0

package/src/lib/browser/qa-snapshot.ts

@@ -13,6 +13,7 @@
 // target, a subdirectory per context, atomic writes (tmp + rename) so a
 // crashed writer never leaves a half-baseline the next run would trust.
 
+import { randomUUID } from "node:crypto";
 import {
   existsSync,
   mkdirSync,
@@ -24,6 +25,12 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import {
+  PAGE_REVIEW_DECISIONS_SCHEMA,
+  type PageReviewDecisionSlot,
+  type PageReviewNativeEvidence,
+} from "./page-review-contracts.js";
+import { machineFindingKey, validateNativeEvidence } from "./page-review-evidence.js";
 import { fnv1a32, type QaContext, type QaSignature } from "./qa-plan.js";
 import type { PersistedCritique } from "./qa-reuse.js";
 
@@ -43,6 +50,7 @@ export interface StoredQaSnapshot {
   /** Critique results persisted with the snapshot (full-coverage runs only) —
    * what the band-diff reuse layer replays for provably-unchanged regions. */
   critique?: PersistedCritique;
+  tileEvidence?: PageReviewNativeEvidence;
 }
 
 /** Filesystem-safe key for a target URL/file + render context. The digest
@@ -75,6 +83,159 @@ function snapshotDir(target: string, context: QaContext, opts: QaSnapshotStoreOp
   return resolve(opts.root ?? SNAPSHOT_DIR, qaSnapshotKey(target), contextDirName(context));
 }
 
+/** Serialize both owned slots across processes. A stuck writer fails closed. */
+function withStoreLock<T>(dir: string, operation: () => T): T {
+  mkdirSync(dir, { recursive: true });
+  const lock = resolve(dir, ".write-lock");
+  const deadline = Date.now() + 5_000;
+  while (true) {
+    try {
+      mkdirSync(lock);
+      break;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      if (Date.now() >= deadline) throw new Error(`Snapshot writer lock busy: ${dir}`);
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  }
+  try {
+    return operation();
+  } finally {
+    rmSync(lock, { recursive: true, force: true });
+  }
+}
+
+function validateDecisionSlot(
+  target: string,
+  context: QaContext,
+  slot: PageReviewDecisionSlot,
+): void {
+  const only = (value: object, keys: string[]) =>
+    Object.keys(value).every((key) => keys.includes(key));
+  if (
+    slot.schema !== PAGE_REVIEW_DECISIONS_SCHEMA ||
+    slot.complete !== true ||
+    slot.target !== target ||
+    slot.context.viewport !== context.viewport ||
+    slot.context.theme !== context.theme ||
+    slot.context.state !== context.state ||
+    slot.context.critique_contract_version !== 2 ||
+    ![slot.context.viewport_width, slot.context.viewport_height, slot.context.dpr].every(
+      (n) => Number.isFinite(n) && n > 0,
+    ) ||
+    !/^[a-f0-9]{64}$/.test(slot.context.rubric_digest) ||
+    !slot.context.recipe_version ||
+    !only(slot, [
+      "schema",
+      "complete",
+      "target",
+      "context",
+      "source_run",
+      "source_revision",
+      "reviewer",
+      "reviewed_at",
+      "decisions",
+    ]) ||
+    !only(slot.context, [
+      "viewport",
+      "viewport_width",
+      "viewport_height",
+      "theme",
+      "state",
+      "dpr",
+      "recipe_version",
+      "rubric_digest",
+      "critique_contract_version",
+    ]) ||
+    !slot.reviewer?.trim() ||
+    !Number.isFinite(Date.parse(slot.reviewed_at)) ||
+    !slot.source_run ||
+    !Array.isArray(slot.decisions)
+  )
+    throw new Error("Invalid durable review decision slot");
+  const keys = new Set<string>();
+  for (const decision of slot.decisions) {
+    if (
+      !decision.reviewer?.trim() ||
+      !Number.isFinite(Date.parse(decision.at)) ||
+      keys.has(decision.finding_key) ||
+      !/^[a-f0-9]{64}$/.test(decision.tile_pixel_digest) ||
+      !only(decision, [
+        "finding_key",
+        "tile_pixel_digest",
+        "rect",
+        "finding",
+        "disposition",
+        "reviewer",
+        "at",
+        "note",
+      ]) ||
+      !only(decision.finding, ["severity", "category", "description"]) ||
+      !only(decision.rect, ["x", "y", "width", "height"]) ||
+      ![decision.rect.x, decision.rect.y, decision.rect.width, decision.rect.height].every(
+        Number.isInteger,
+      ) ||
+      decision.rect.x < 0 ||
+      decision.rect.y < 0 ||
+      decision.rect.width < 1 ||
+      decision.rect.height < 1 ||
+      !["artifact", "not-a-defect", "confirmed", "duplicate-of-gate"].includes(
+        decision.disposition,
+      ) ||
+      decision.finding.category === "provider-error" ||
+      machineFindingKey(
+        slot.context,
+        { rect: decision.rect, pixel_digest: decision.tile_pixel_digest },
+        decision.finding,
+      ) !== decision.finding_key
+    ) {
+      throw new Error("Invalid durable review finding identity");
+    }
+    keys.add(decision.finding_key);
+  }
+}
+
+export function loadReviewDecisions(
+  target: string,
+  context: QaContext,
+  opts: QaSnapshotStoreOptions = {},
+): PageReviewDecisionSlot | null {
+  const dir = snapshotDir(target, context, opts);
+  if (!existsSync(dir)) return null;
+  try {
+    return withStoreLock(dir, () => {
+      const slot = JSON.parse(
+        readFileSync(resolve(dir, "review-decisions.json"), "utf8"),
+      ) as PageReviewDecisionSlot;
+      validateDecisionSlot(target, context, slot);
+      return slot;
+    });
+  } catch {
+    return null;
+  }
+}
+
+/** Decisions contain text and digests only; replacing a baseline cannot touch this slot. */
+export function saveReviewDecisions(
+  target: string,
+  context: QaContext,
+  slot: PageReviewDecisionSlot,
+  opts: QaSnapshotStoreOptions = {},
+): void {
+  validateDecisionSlot(target, context, slot);
+  const dir = snapshotDir(target, context, opts);
+  withStoreLock(dir, () => {
+    const path = resolve(dir, "review-decisions.json");
+    const temp = `${path}.tmp-${randomUUID()}`;
+    try {
+      writeFileSync(temp, `${JSON.stringify(slot)}\n`);
+      renameSync(temp, path);
+    } finally {
+      rmSync(temp, { force: true });
+    }
+  });
+}
+
 /**
  * Persist a QA snapshot atomically. The whole context directory is staged as
  * `<dir>.tmp-<pid>` and renamed into place, replacing any prior snapshot for
@@ -88,33 +249,77 @@ export function saveQaSnapshot(
     domHtml?: string;
     screenshotPng?: Buffer;
     critique?: PersistedCritique;
+    tileEvidence?: PageReviewNativeEvidence;
   },
   opts: QaSnapshotStoreOptions = {},
 ): StoredQaSnapshot {
-  const dir = snapshotDir(target, context, opts);
-  const staging = `${dir}.tmp-${process.pid}`;
-  rmSync(staging, { recursive: true, force: true });
-  mkdirSync(staging, { recursive: true });
-  writeFileSync(resolve(staging, "signature.json"), `${JSON.stringify(content.signature)}\n`);
-  if (content.domHtml !== undefined) {
-    writeFileSync(resolve(staging, "dom.html"), content.domHtml);
-  }
-  if (content.screenshotPng !== undefined) {
-    writeFileSync(resolve(staging, "screenshot.png"), content.screenshotPng);
-  }
-  if (content.critique !== undefined) {
-    writeFileSync(resolve(staging, "critique.json"), `${JSON.stringify(content.critique)}\n`);
-  }
-  rmSync(dir, { recursive: true, force: true });
-  renameSync(staging, dir);
-  return {
-    signature: content.signature,
-    path: dir,
-    ...(content.domHtml !== undefined ? { domHtmlPath: resolve(dir, "dom.html") } : {}),
-    ...(content.screenshotPng !== undefined
-      ? { screenshotPath: resolve(dir, "screenshot.png") }
-      : {}),
-  };
+  const container = snapshotDir(target, context, opts);
+  return withStoreLock(container, () => {
+    const dir = resolve(container, "baseline");
+    const staging = `${dir}.tmp-${randomUUID()}`;
+    const previous = `${dir}.previous`;
+    if (content.tileEvidence && content.screenshotPng)
+      throw new Error("A pack native-tile baseline must not retain a full-page image");
+    if (content.tileEvidence && !validateNativeEvidence(content.tileEvidence))
+      throw new Error("Invalid native tile baseline evidence");
+    mkdirSync(staging, { recursive: true });
+    try {
+      writeFileSync(resolve(staging, "signature.json"), `${JSON.stringify(content.signature)}\n`);
+      if (content.domHtml !== undefined) {
+        writeFileSync(resolve(staging, "dom.html"), content.domHtml);
+      }
+      if (content.screenshotPng !== undefined) {
+        writeFileSync(resolve(staging, "screenshot.png"), content.screenshotPng);
+      }
+      if (content.critique !== undefined) {
+        writeFileSync(resolve(staging, "critique.json"), `${JSON.stringify(content.critique)}\n`);
+      }
+      if (content.tileEvidence) {
+        const tiles = content.tileEvidence.tiles.map(({ png, ...tile }, i) => {
+          const file = `tile-${i}.png`;
+          writeFileSync(resolve(staging, file), png);
+          return { ...tile, file };
+        });
+        writeFileSync(
+          resolve(staging, "native-evidence.json"),
+          JSON.stringify({ ...content.tileEvidence, tiles }),
+        );
+      }
+      // Recovery of a writer interrupted after moving its old baseline.
+      if (!existsSync(dir) && existsSync(previous)) renameSync(previous, dir);
+      rmSync(previous, { recursive: true, force: true });
+      if (existsSync(dir)) renameSync(dir, previous);
+      try {
+        renameSync(staging, dir);
+      } catch (error) {
+        if (existsSync(previous)) renameSync(previous, dir);
+        throw error;
+      }
+      rmSync(previous, { recursive: true, force: true });
+      // Remove superseded legacy baseline files, never the independent decision slot.
+      for (const name of [
+        "signature.json",
+        "dom.html",
+        "screenshot.png",
+        "critique.json",
+        "native-evidence.json",
+      ]) {
+        rmSync(resolve(container, name), { force: true });
+      }
+      return {
+        signature: content.signature,
+        path: dir,
+        ...(content.domHtml !== undefined ? { domHtmlPath: resolve(dir, "dom.html") } : {}),
+        ...(content.screenshotPng !== undefined
+          ? { screenshotPath: resolve(dir, "screenshot.png") }
+          : {}),
+        ...(content.critique ? { critique: content.critique } : {}),
+        ...(content.tileEvidence ? { tileEvidence: content.tileEvidence } : {}),
+      };
+    } finally {
+      rmSync(staging, { recursive: true, force: true });
+    }
+  });
 }
 
 /** Load the persisted snapshot for a target + context, or null. A corrupt
@@ -125,35 +330,71 @@ export function loadQaSnapshot(
   context: QaContext,
   opts: QaSnapshotStoreOptions = {},
 ): StoredQaSnapshot | null {
-  const dir = snapshotDir(target, context, opts);
-  const sigPath = resolve(dir, "signature.json");
-  if (!existsSync(sigPath)) return null;
+  const container = snapshotDir(target, context, opts);
+  if (!existsSync(container)) return null;
   try {
-    const signature = JSON.parse(readFileSync(sigPath, "utf8")) as QaSignature;
-    if (!signature || !Array.isArray(signature.nodes) || !Array.isArray(signature.stylesheets)) {
-      return null;
-    }
-    const domHtmlPath = resolve(dir, "dom.html");
-    const screenshotPath = resolve(dir, "screenshot.png");
-    const critiquePath = resolve(dir, "critique.json");
-    let critique: PersistedCritique | undefined;
-    if (existsSync(critiquePath)) {
+    return withStoreLock(container, () => {
+      const baseline = resolve(container, "baseline");
+      const dir = existsSync(baseline)
+        ? baseline
+        : existsSync(`${baseline}.previous`)
+          ? `${baseline}.previous`
+          : container;
+      const sigPath = resolve(dir, "signature.json");
+      if (!existsSync(sigPath)) return null;
       try {
-        const parsed = JSON.parse(readFileSync(critiquePath, "utf8")) as PersistedCritique;
-        if (parsed && typeof parsed.contract_version === "number" && Array.isArray(parsed.tiles)) {
-          critique = parsed;
+        const signature = JSON.parse(readFileSync(sigPath, "utf8")) as QaSignature;
+        if (
+          !signature ||
+          !Array.isArray(signature.nodes) ||
+          !Array.isArray(signature.stylesheets)
+        ) {
+          return null;
         }
+        const domHtmlPath = resolve(dir, "dom.html");
+        const screenshotPath = resolve(dir, "screenshot.png");
+        const critiquePath = resolve(dir, "critique.json");
+        let critique: PersistedCritique | undefined;
+        let tileEvidence: PageReviewNativeEvidence | undefined;
+        try {
+          const raw = JSON.parse(readFileSync(resolve(dir, "native-evidence.json"), "utf8"));
+          const candidate = {
+            ...raw,
+            tiles: raw.tiles.map((tile: { file: string }) => {
+              if (!/^tile-\d+\.png$/.test(tile.file)) throw new Error("Invalid native tile path");
+              return { ...tile, png: readFileSync(resolve(dir, tile.file)) };
+            }),
+          } as PageReviewNativeEvidence;
+          if (validateNativeEvidence(candidate)) tileEvidence = candidate;
+        } catch {
+          /* Missing or corrupt evidence is a cache miss. */
+        }
+        if (existsSync(critiquePath)) {
+          try {
+            const parsed = JSON.parse(readFileSync(critiquePath, "utf8")) as PersistedCritique;
+            if (
+              parsed &&
+              typeof parsed.contract_version === "number" &&
+              Array.isArray(parsed.tiles)
+            ) {
+              critique = parsed;
+            }
+          } catch {
+            // corrupt critique.json degrades to a reuse miss, never an error
+          }
+        }
+        return {
+          signature,
+          path: dir,
+          ...(existsSync(domHtmlPath) ? { domHtmlPath } : {}),
+          ...(existsSync(screenshotPath) ? { screenshotPath } : {}),
+          ...(critique ? { critique } : {}),
+          ...(tileEvidence ? { tileEvidence } : {}),
+        };
       } catch {
-        // corrupt critique.json degrades to a reuse miss, never an error
+        return null;
       }
-    }
-    return {
-      signature,
-      path: dir,
-      ...(existsSync(domHtmlPath) ? { domHtmlPath } : {}),
-      ...(existsSync(screenshotPath) ? { screenshotPath } : {}),
-      ...(critique ? { critique } : {}),
-    };
+    });
   } catch {
     return null;
   }

package/src/lib/browser/review-capture-transaction.ts

@@ -0,0 +1,106 @@
+import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+  allocateTileBudget,
+  capturePlanDigest,
+  validatePageReviewAllocation,
+} from "./page-review-budget.ts";
+import type {
+  PageReviewCapturePlan,
+  PageReviewContextAllocation,
+} from "./page-review-contracts.ts";
+import { packPaths } from "./page-review-pack.ts";
+
+/** Publish a complete context atomically; failed writes stay outside discoverable contexts. */
+export function writeCaptureTransaction<T>(
+  packDir: string,
+  contextId: string,
+  write: (stage: string) => T,
+): T {
+  mkdirSync(packDir, { recursive: true, mode: 0o700 });
+  const stage = mkdtempSync(join(packDir, ".pending-capture-"));
+  try {
+    const result = write(stage);
+    const destination = packPaths(packDir).contextDir(contextId);
+    mkdirSync(dirname(destination), { recursive: true });
+    if (existsSync(destination))
+      throw new Error("Capture context already exists; refusing to replace prior evidence.");
+    renameSync(packPaths(stage).contextDir(contextId), destination);
+    rmSync(stage, { recursive: true });
+    return result;
+  } catch (error) {
+    if (error instanceof Error) error.message += ` Incomplete capture retained at ${stage}.`;
+    throw error;
+  }
+}
+
+/** A preliminary allocation reserves pixels; it never supplies current source evidence. */
+export function allocateCaptureReservation(
+  reservation: PageReviewContextAllocation,
+  current: PageReviewCapturePlan,
+): PageReviewContextAllocation {
+  validatePageReviewAllocation(reservation, reservation.plan);
+  for (const key of [
+    "context_id",
+    "viewport",
+    "viewport_width",
+    "viewport_height",
+    "theme",
+    "state",
+    "dpr",
+    "recipe_version",
+  ] as const) {
+    if (reservation.plan[key] !== current[key])
+      throw new Error(`Capture reservation changed ${key}.`);
+  }
+  if (reservation.plan.required_scopes.some((scope) => !current.required_scopes.includes(scope)))
+    throw new Error("Capture reservation lost a required scope.");
+  // Reservations sum to the original global allocation, even when its per-context
+  // ceiling was higher than the number of tiles actually assigned to that context.
+  const ceiling = reservation.selected_ids.length;
+  const allocation = allocateTileBudget([current], ceiling, { [current.context_id]: ceiling })
+    .contexts[0];
+  if (
+    allocation.coverage.capped ||
+    allocation.coverage.omitted_scopes.length ||
+    allocation.coverage.uncovered_intervals.length
+  )
+    throw new Error("Fresh native capture coverage exceeds the reserved tile budget.");
+  return validatePageReviewAllocation(allocation, current);
+}
+
+export class CaptureSourceChanged extends Error {
+  constructor(message = "Page source changed during the gate and capture transaction.") {
+    super(message);
+    this.name = "CaptureSourceChanged";
+  }
+}
+
+/** Gate-hit annotations may change, but source and every native rectangle must stay fixed. */
+export function assertGatePlanStable(
+  before: PageReviewCapturePlan,
+  after: PageReviewCapturePlan,
+): void {
+  if (capturePlanDigest(before) !== capturePlanDigest(after))
+    throw new CaptureSourceChanged(
+      "Page source or geometry changed while deterministic gates were running.",
+    );
+}
+
+/** One retry recollects every gate and allocation; no previous green result survives. */
+export async function runCaptureTransaction<T>(
+  collectAndAllocate: (attempt: number) => Promise<void>,
+  capture: () => Promise<T>,
+  recordFailure: (attempt: number, error: unknown) => void,
+): Promise<T> {
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    try {
+      await collectAndAllocate(attempt);
+      return await capture();
+    } catch (error) {
+      recordFailure(attempt, error);
+      if (!(error instanceof CaptureSourceChanged) || attempt === 2) throw error;
+    }
+  }
+  throw new Error("Capture transaction did not complete.");
+}

package/src/lib/browser/standalone-html.ts

@@ -73,7 +73,9 @@ export function buildStandaloneHtmlScript(): (
       if (cached !== undefined) return cached;
       let result: string | null = null;
       try {
-        const res = await fetch(url, { credentials: "include" });
+        // Retain access to authenticated same-origin assets without imposing
+        // credentialed CORS on public assets served by another origin.
+        const res = await fetch(url, { credentials: "same-origin" });
         if (res.ok) {
           const buf = await res.arrayBuffer();
           const fits =
@@ -169,7 +171,7 @@ export function buildStandaloneHtmlScript(): (
       }
       let css: string | null = null;
       try {
-        const res = await fetch(url, { credentials: "include" });
+        const res = await fetch(url, { credentials: "same-origin" });
         if (res.ok) css = await res.text();
       } catch {
         css = null;