harnery 0.38.0 → 0.40.0

package/dist/lib/browser/page-review-evidence.d.ts

@@ -0,0 +1,48 @@
+import type { CritiqueFinding, CritiqueTile } from "./critique.js";
+import { type PageReviewDecisionSlot, type PageReviewEvidenceContext, type PageReviewNativeEvidence, type PageReviewNativeTile, type PageReviewRect } from "./page-review-contracts.js";
+import { type PageReviewContextRecord, type PageReviewCritiqueRecord } from "./page-review-pack.js";
+import { type CritiqueReusePlan, type PersistedCritique } from "./qa-reuse.js";
+import { type QaSnapshotStoreOptions } from "./qa-snapshot.js";
+export declare const PAGE_REVIEW_CRITIQUE_CONTRACT_VERSION = 2;
+export declare const PAGE_REVIEW_CRITIQUE_SCHEMA = "harnery-page-review-critique/v2";
+export declare const packRubricDigest: (rubric: string) => string;
+export declare function machineEvidenceDigest(target: string, critique: PageReviewCritiqueRecord[] | null): string;
+export declare function nativePixelDigest(png: Buffer): string;
+export declare function evidenceContextKey(context: PageReviewEvidenceContext): string;
+export declare function nativeRectKey(rect: PageReviewRect): string;
+export declare function validateNativeEvidence(evidence: PageReviewNativeEvidence): boolean;
+export declare function buildPackNativeEvidence(record: PageReviewContextRecord, tiles: Array<CritiqueTile & {
+    id: string;
+}>, rubric: string): PageReviewNativeEvidence;
+/** A baseline finding forces review even when it was previously dismissed. */
+export declare function planNativeTileReuse(input: {
+    current: PageReviewNativeEvidence;
+    baseline?: PageReviewNativeEvidence;
+    critique?: PersistedCritique;
+    tiles: Array<CritiqueTile & {
+        id: string;
+    }>;
+    mismatchThreshold?: number;
+}): CritiqueReusePlan;
+export declare function machineFindingKey(context: PageReviewEvidenceContext, tile: Pick<PageReviewNativeTile, "rect" | "pixel_digest">, finding: Pick<CritiqueFinding, "severity" | "category" | "description">): string;
+export declare function applyPackReviewDecisions(input: {
+    target: string;
+    evidence: PageReviewNativeEvidence;
+    findings: Array<CritiqueFinding & {
+        tile_id: string;
+    }>;
+    slot: PageReviewDecisionSlot | null;
+    enabled: boolean;
+}): {
+    findings: Array<CritiqueFinding & {
+        tile_id: string;
+    }>;
+    applied: Array<{
+        finding_key: string;
+        target: string;
+        disposition: "artifact" | "not-a-defect";
+    }>;
+};
+/** Validate the complete submission and all native bindings before writing any slot. */
+export declare function persistPackReviewDecisions(packDir: string, store?: QaSnapshotStoreOptions): number;
+//# sourceMappingURL=page-review-evidence.d.ts.map

package/dist/lib/browser/page-review-evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-review-evidence.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/page-review-evidence.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAO9B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,iBAAiB,EAEtB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,sBAAsB,EAAuB,MAAM,kBAAkB,CAAC;AAEpF,eAAO,MAAM,qCAAqC,IAAI,CAAC;AACvD,eAAO,MAAM,2BAA2B,oCAAoC,CAAC;AAE7E,eAAO,MAAM,gBAAgB,GAAI,QAAQ,MAAM,KAAG,MAAsB,CAAC;AAEzE,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,wBAAwB,EAAE,GAAG,IAAI,GAC1C,MAAM,CAcR;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErD;AASD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,MAAM,CAY7E;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAE1D;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,OAAO,CAwClF;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,uBAAuB,EAC/B,KAAK,EAAE,KAAK,CAAC,YAAY,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,EAC3C,MAAM,EAAE,MAAM,GACb,wBAAwB,CA6B1B;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,OAAO,EAAE,wBAAwB,CAAC;IAClC,QAAQ,CAAC,EAAE,wBAAwB,CAAC;IACpC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,KAAK,EAAE,KAAK,CAAC,YAAY,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5C,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,GAAG,iBAAiB,CA+EpB;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,yBAAyB,EAClC,IAAI,EAAE,IAAI,CAAC,oBAAoB,EAAE,MAAM,GAAG,cAAc,CAAC,EACzD,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,UAAU,GAAG,UAAU,GAAG,aAAa,CAAC,GACtE,MAAM,CAYR;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,wBAAwB,CAAC;IACnC,QAAQ,EAAE,KAAK,CAAC,eAAe,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,IAAI,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACpC,OAAO,EAAE,OAAO,CAAC;CAClB,GAAG;IACF,QAAQ,EAAE,KAAK,CAAC,eAAe,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,OAAO,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,UAAU,GAAG,cAAc,CAAA;KAAE,CAAC,CAAC;CACnG,CA+CA;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,sBAA2B,GACjC,MAAM,CAoIR"}

package/dist/lib/browser/page-review-evidence.js

@@ -0,0 +1,340 @@
+// Native pixels are the evidence. Overviews and PNG encodings are not identity.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+import { PAGE_REVIEW_DECISIONS_SCHEMA, PAGE_REVIEW_NATIVE_EVIDENCE_SCHEMA, } from "./page-review-contracts.js";
+import { buildInspectionPlan, machineFindingTargets, packPaths, readPackFindings, readPackManifest, readPackTiles, resolvePackVerdict, validateFindingsDocument, } from "./page-review-pack.js";
+import { DEFAULT_REUSE_MISMATCH_RATIO, } from "./qa-reuse.js";
+import { saveReviewDecisions } from "./qa-snapshot.js";
+export const PAGE_REVIEW_CRITIQUE_CONTRACT_VERSION = 2;
+export const PAGE_REVIEW_CRITIQUE_SCHEMA = "harnery-page-review-critique/v2";
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+export const packRubricDigest = (rubric) => hash(rubric);
+export function machineEvidenceDigest(target, critique) {
+    return hash(JSON.stringify({
+        target,
+        contexts: critique?.map((row) => ({
+            context_id: row.context_id,
+            outcome: row.outcome,
+            findings: row.findings,
+            evidence: row.evidence ?? null,
+            coverage: row.coverage,
+        })) ?? null,
+    }));
+}
+export function nativePixelDigest(png) {
+    return decodedPixelDigest(PNG.sync.read(png));
+}
+function decodedPixelDigest(decoded) {
+    const dimensions = Buffer.alloc(8);
+    dimensions.writeUInt32BE(decoded.width, 0);
+    dimensions.writeUInt32BE(decoded.height, 4);
+    return createHash("sha256").update(dimensions).update(decoded.data).digest("hex");
+}
+export function evidenceContextKey(context) {
+    return JSON.stringify([
+        context.viewport,
+        context.viewport_width,
+        context.viewport_height,
+        context.theme,
+        context.state,
+        context.dpr,
+        context.recipe_version,
+        context.rubric_digest,
+        context.critique_contract_version,
+    ]);
+}
+export function nativeRectKey(rect) {
+    return JSON.stringify([rect.x, rect.y, rect.width, rect.height]);
+}
+export function validateNativeEvidence(evidence) {
+    try {
+        const ctx = evidence.context;
+        if (evidence.schema !== PAGE_REVIEW_NATIVE_EVIDENCE_SCHEMA ||
+            ctx.critique_contract_version !== PAGE_REVIEW_CRITIQUE_CONTRACT_VERSION ||
+            ![ctx.viewport_width, ctx.viewport_height, ctx.dpr].every((n) => Number.isFinite(n) && n > 0) ||
+            !ctx.recipe_version ||
+            !ctx.rubric_digest ||
+            !ctx.viewport ||
+            !ctx.state ||
+            !["light", "dark"].includes(ctx.theme) ||
+            !Array.isArray(evidence.tiles))
+            return false;
+        const ids = new Set();
+        return evidence.tiles.every((tile) => {
+            if (!tile.tile_id || ids.has(tile.tile_id))
+                return false;
+            ids.add(tile.tile_id);
+            const { x, y, width, height } = tile.rect;
+            if (![x, y, width, height].every(Number.isInteger) ||
+                x < 0 ||
+                y < 0 ||
+                width < 1 ||
+                height < 1)
+                return false;
+            const decoded = PNG.sync.read(tile.png);
+            return (decoded.width === width &&
+                decoded.height === height &&
+                decodedPixelDigest(decoded) === tile.pixel_digest);
+        });
+    }
+    catch {
+        return false;
+    }
+}
+export function buildPackNativeEvidence(record, tiles, rubric) {
+    const evidence = {
+        schema: PAGE_REVIEW_NATIVE_EVIDENCE_SCHEMA,
+        context: {
+            viewport: record.viewport,
+            viewport_width: record.viewport_size.width,
+            viewport_height: record.viewport_size.height,
+            theme: record.theme,
+            state: record.state,
+            dpr: record.dpr,
+            recipe_version: `${record.recipe_version};source=${record.capture_fidelity?.source ?? "full-page"}`,
+            rubric_digest: packRubricDigest(rubric),
+            critique_contract_version: PAGE_REVIEW_CRITIQUE_CONTRACT_VERSION,
+        },
+        tiles: tiles.map((tile) => {
+            const png = Buffer.from(tile.pngBase64, "base64");
+            return {
+                tile_id: tile.id,
+                index: tile.index,
+                label: tile.label,
+                rect: { x: tile.x ?? 0, y: tile.scrollY, width: tile.width, height: tile.height },
+                pixel_digest: nativePixelDigest(png),
+                png,
+            };
+        }),
+    };
+    if (!validateNativeEvidence(evidence))
+        throw new Error("Native tile evidence has invalid geometry or pixels; recapture this context.");
+    return evidence;
+}
+/** A baseline finding forces review even when it was previously dismissed. */
+export function planNativeTileReuse(input) {
+    const threshold = input.mismatchThreshold ?? DEFAULT_REUSE_MISMATCH_RATIO;
+    const { current, baseline, critique } = input;
+    const validCritique = critique &&
+        ["pass", "fail"].includes(critique.outcome) &&
+        Array.isArray(critique.findings) &&
+        Array.isArray(critique.tiles) &&
+        critique.findings.every((f) => Number.isInteger(f.tile) &&
+            typeof f.description === "string" &&
+            typeof f.category === "string" &&
+            ["high", "medium", "low"].includes(f.severity));
+    const invalidation = !baseline || !critique
+        ? "native-evidence-missing"
+        : !validCritique
+            ? "native-critique-invalid"
+            : !validateNativeEvidence(baseline) || !validateNativeEvidence(current)
+                ? "native-evidence-invalid"
+                : critique.contract_version !== PAGE_REVIEW_CRITIQUE_CONTRACT_VERSION ||
+                    critique.rubric_digest !== current.context.rubric_digest ||
+                    evidenceContextKey(current.context) !== evidenceContextKey(baseline.context)
+                    ? "native-evidence-contract-changed"
+                    : undefined;
+    const decisions = input.tiles.map((tile) => {
+        const cur = current.tiles.find((t) => t.tile_id === tile.id);
+        const prior = cur && baseline?.tiles.find((t) => nativeRectKey(t.rect) === nativeRectKey(cur.rect));
+        let reason = invalidation;
+        let ratio;
+        if (!reason && (!cur || !prior))
+            reason = "native-tile-missing";
+        if (!reason && prior && critique) {
+            const affected = critique.findings.some((finding) => {
+                const found = baseline?.tiles.filter((t) => t.index === finding.tile);
+                if (!found?.length)
+                    return true;
+                return found.some((t) => t.rect.x < prior.rect.x + prior.rect.width &&
+                    t.rect.x + t.rect.width > prior.rect.x &&
+                    t.rect.y < prior.rect.y + prior.rect.height &&
+                    t.rect.y + t.rect.height > prior.rect.y);
+            });
+            if (affected)
+                reason = "baseline-finding";
+        }
+        if (!reason && cur && prior) {
+            const a = PNG.sync.read(prior.png);
+            const b = PNG.sync.read(cur.png);
+            ratio =
+                pixelmatch(a.data, b.data, undefined, a.width, a.height, {
+                    threshold: 0.1,
+                    includeAA: false,
+                }) /
+                    (a.width * a.height);
+            if (ratio > threshold)
+                reason = "pixels-changed";
+        }
+        return {
+            index: tile.index,
+            label: tile.label,
+            reuse: !reason,
+            reason: reason ?? "unchanged-clean-native-tile",
+            ...(ratio === undefined ? {} : { mismatch_ratio: ratio }),
+        };
+    });
+    const review = input.tiles.filter((_, i) => !decisions[i]?.reuse);
+    return {
+        mode: "band-diff",
+        review,
+        decisions,
+        tiles_total: input.tiles.length,
+        tiles_reviewed: review.length,
+        tiles_reused: input.tiles.length - review.length,
+        provider_calls_avoided: input.tiles.length - review.length,
+        mismatch_threshold: threshold,
+        ...(invalidation ? { invalidation } : {}),
+    };
+}
+export function machineFindingKey(context, tile, finding) {
+    const normalize = (value) => value.replace(/\s+/g, " ").trim();
+    return hash(JSON.stringify([
+        evidenceContextKey(context),
+        nativeRectKey(tile.rect),
+        tile.pixel_digest,
+        normalize(finding.severity),
+        normalize(finding.category),
+        normalize(finding.description),
+    ]));
+}
+export function applyPackReviewDecisions(input) {
+    const applied = [];
+    const { slot, evidence } = input;
+    if (!input.enabled ||
+        !slot?.complete ||
+        slot.target !== input.target ||
+        evidenceContextKey(slot.context) !== evidenceContextKey(evidence.context) ||
+        !validateNativeEvidence(evidence))
+        return { findings: [...input.findings], applied };
+    const ordinals = new Map();
+    const findings = input.findings.filter((finding) => {
+        const ordinal = ordinals.get(finding.tile_id) ?? 0;
+        ordinals.set(finding.tile_id, ordinal + 1);
+        if (finding.category === "provider-error")
+            return true;
+        const tile = evidence.tiles.find((t) => t.tile_id === finding.tile_id);
+        if (!tile)
+            return true;
+        const key = machineFindingKey(evidence.context, tile, finding);
+        const decision = slot.decisions.find((d) => d.finding_key === key &&
+            d.tile_pixel_digest === tile.pixel_digest &&
+            nativeRectKey(d.rect) === nativeRectKey(tile.rect) &&
+            machineFindingKey(slot.context, { rect: d.rect, pixel_digest: d.tile_pixel_digest }, d.finding) === key);
+        if (!decision ||
+            (decision.disposition !== "artifact" && decision.disposition !== "not-a-defect"))
+            return true;
+        applied.push({
+            finding_key: key,
+            target: `${finding.tile_id}#${ordinal}`,
+            disposition: decision.disposition,
+        });
+        return false;
+    });
+    return { findings, applied };
+}
+/** Validate the complete submission and all native bindings before writing any slot. */
+export function persistPackReviewDecisions(packDir, store = {}) {
+    const manifest = readPackManifest(packDir);
+    const doc = readPackFindings(packDir);
+    const errors = validateFindingsDocument(doc);
+    if (errors.length)
+        throw new Error(`Invalid findings document: ${errors.join("; ")}`);
+    if (doc.machine_evidence_digest !== machineEvidenceDigest(manifest.target, manifest.critique)) {
+        throw new Error("Reviewer submission belongs to different machine evidence; review the current findings again");
+    }
+    if (doc.target !== manifest.target || !doc.reviewer?.trim() || !doc.reviewed_at)
+        throw new Error("Review target or reviewer identity is missing or mismatched");
+    // Recompute required coverage from machine evidence, rather than trusting an edited plan.
+    const plan = buildInspectionPlan(manifest.contexts, manifest.critique, manifest.gates);
+    const verdict = resolvePackVerdict(manifest, plan, doc);
+    if (!manifest.critique?.length ||
+        verdict.uncovered_primary_tiles.length ||
+        verdict.primary_tiles_total === 0 ||
+        doc.delegated_reviews.some((r) => r.status !== "complete" || r.completed_tiles.length !== r.assigned_tiles.length) ||
+        manifest.contexts.some((c) => c.capture_incomplete ||
+            c.coverage.capped ||
+            c.coverage.reviewed_height_px < c.coverage.page_height_px ||
+            c.allocation_coverage?.omitted_scopes.length ||
+            c.allocation_coverage?.uncovered_intervals.length) ||
+        manifest.critique.some((c) => c.outcome === "incomplete" ||
+            c.outcome === "skipped" ||
+            c.tiles_reviewed + c.tiles_reused !== c.tiles_total)) {
+        throw new Error("Durable decisions require complete delegated review and complete native capture/judging");
+    }
+    const machineFile = JSON.parse(readFileSync(packPaths(packDir).critique, "utf8"));
+    if (machineFile.schema !== PAGE_REVIEW_CRITIQUE_SCHEMA ||
+        JSON.stringify(machineFile.contexts) !== JSON.stringify(manifest.critique))
+        throw new Error("Machine critique binding mismatch; recapture and judge this pack");
+    const targets = machineFindingTargets(manifest.critique);
+    if (verdict.unmatched_dispositions.length)
+        throw new Error("Disposition names an absent machine finding");
+    const primary = new Set(plan.contexts.flatMap((c) => c.primary_tiles.map((t) => `${c.context_id}/${t.id}`)));
+    if (doc.delegated_reviews.some((r) => r.assigned_tiles.some((t) => !primary.has(t))))
+        throw new Error("Delegated review refers to an unknown primary tile");
+    for (const finding of doc.findings) {
+        const ctx = manifest.contexts.find((c) => c.id === finding.context_id);
+        if (!ctx ||
+            finding.evidence.some((ref) => !ctx.tiles.some((t) => ref === t.id || ref === t.file || ref === `${ctx.id}/${t.id}`)))
+            throw new Error("Reviewer finding has an invalid evidence binding");
+    }
+    const slots = manifest.contexts.map((record) => {
+        const row = manifest.critique?.find((c) => c.context_id === record.id);
+        if (!row?.evidence || row.evidence.schema !== PAGE_REVIEW_CRITIQUE_SCHEMA)
+            throw new Error("Missing v2 machine evidence; rejudge this pack");
+        const tiles = readPackTiles(packDir, record);
+        const evidence = buildPackNativeEvidence(record, tiles, "");
+        evidence.context.rubric_digest = row.evidence.context.rubric_digest;
+        if (evidenceContextKey(evidence.context) !== evidenceContextKey(row.evidence.context) ||
+            row.evidence.tiles.length !== evidence.tiles.length ||
+            row.evidence.tiles.some((tile) => !evidence.tiles.some((cur) => cur.tile_id === tile.tile_id &&
+                cur.pixel_digest === tile.pixel_digest &&
+                nativeRectKey(cur.rect) === nativeRectKey(tile.rect)))) {
+            throw new Error("Native tile binding changed after judging; recapture and rejudge");
+        }
+        if (row.findings.some((f) => !evidence.tiles.some((tile) => tile.tile_id === f.tile_id && tile.index === f.tile)))
+            throw new Error("Machine finding names an absent native tile");
+        const decisions = new Map();
+        for (const disposition of doc.dispositions ?? []) {
+            const finding = targets.get(disposition.target);
+            if (!finding || finding.context_id !== record.id)
+                continue;
+            if (finding.category === "provider-error")
+                throw new Error("Provider errors cannot receive durable dispositions");
+            const tile = evidence.tiles.find((t) => t.tile_id === finding.tile_id);
+            if (!tile)
+                throw new Error("Disposition tile binding is absent");
+            const key = machineFindingKey(evidence.context, tile, finding);
+            decisions.set(key, {
+                finding_key: key,
+                tile_pixel_digest: tile.pixel_digest,
+                rect: tile.rect,
+                finding: {
+                    severity: finding.severity,
+                    category: finding.category,
+                    description: finding.description,
+                },
+                disposition: disposition.disposition,
+                reviewer: disposition.by?.trim() || doc.reviewer,
+                at: disposition.at ?? doc.reviewed_at,
+                ...(disposition.note === undefined ? {} : { note: disposition.note }),
+            });
+        }
+        return {
+            schema: PAGE_REVIEW_DECISIONS_SCHEMA,
+            target: manifest.target,
+            context: evidence.context,
+            source_run: manifest.created_at,
+            source_revision: manifest.tested_revision ?? null,
+            reviewer: doc.reviewer,
+            reviewed_at: doc.reviewed_at,
+            complete: true,
+            decisions: [...decisions.values()],
+        };
+    });
+    for (const slot of slots)
+        saveReviewDecisions(manifest.target, slot.context, slot, store);
+    return slots.length;
+}

package/dist/lib/browser/page-review-judge.d.ts

@@ -1,6 +1,6 @@
 import type { CritiqueProvider } from "./critique.js";
 import { type PageReviewContextRecord, type PageReviewCritiqueRecord } from "./page-review-pack.js";
-import { type CritiqueReusePlan } from "./qa-reuse.js";
+import type { CritiqueReusePlan } from "./qa-reuse.js";
 import { type QaSnapshotStoreOptions } from "./qa-snapshot.js";
 export interface JudgePageReviewPackOptions {
     packDir: string;

package/dist/lib/browser/page-review-judge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"page-review-judge.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/page-review-judge.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAmB,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AACrF,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAI9B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,KAAK,iBAAiB,EAAqB,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAkB,KAAK,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE/E,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,QAAQ,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf;kCAC8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,qEAAqE;IACrE,KAAK,CAAC,EAAE;QACN,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;QAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF;2EACuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,aAAc,SAAQ,wBAAwB;IAC7D,MAAM,EAAE,uBAAuB,CAAC;IAChC,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,IAAI,CACV,iBAAiB,EACjB,aAAa,GAAG,cAAc,GAAG,gBAAgB,GAAG,cAAc,GAAG,oBAAoB,CAC1F,CAAC;CACH;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAUD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,uBAAuB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CA2E1F;AAaD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CA4KpC;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,yBAAyB,GAAG,wBAAwB,EAAE,CAI/F"}
+{"version":3,"file":"page-review-judge.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/page-review-judge.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAmB,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AAOrF,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAG9B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAkB,KAAK,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE/E,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,QAAQ,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf;kCAC8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,qEAAqE;IACrE,KAAK,CAAC,EAAE;QACN,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;QAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF;2EACuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,aAAc,SAAQ,wBAAwB;IAC7D,MAAM,EAAE,uBAAuB,CAAC;IAChC,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,IAAI,CACV,iBAAiB,EACjB,aAAa,GAAG,cAAc,GAAG,gBAAgB,GAAG,cAAc,GAAG,oBAAoB,CAC1F,CAAC;CACH;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAUD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,uBAAuB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CA+E1F;AAaD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CAoLpC;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,yBAAyB,GAAG,wBAAwB,EAAE,CAI/F"}

package/dist/lib/browser/page-review-judge.js

@@ -8,9 +8,8 @@
 // finding (false reviews are allowed, false passes never).
 //
 // Toolkit tier: this module must not import src/core (layering check).
-import { readFileSync } from "node:fs";
-import { listPackContexts, readPackContext, readPackFullPage, readPackTiles, } from "./page-review-pack.js";
-import { planCritiqueReuse } from "./qa-reuse.js";
+import { buildPackNativeEvidence, PAGE_REVIEW_CRITIQUE_SCHEMA, planNativeTileReuse, } from "./page-review-evidence.js";
+import { listPackContexts, readPackContext, readPackTiles, } from "./page-review-pack.js";
 import { loadQaSnapshot } from "./qa-snapshot.js";
 /**
  * Orientation the provider reads before the rubric: which band this tile is,
@@ -39,7 +38,7 @@ export function tileRubricPreamble(record, tileId) {
             .sort((a, b) => a.scrollY - b.scrollY || a.index - b.index);
         const n = bands.findIndex((entry) => entry.id === tile.id);
         const capped = record.coverage.capped
-            ? ` (the page has ${record.coverage.bands_total} bands; those past the cap are not in this pack)`
+            ? ` (the page has ${record.coverage.bands_total} bands; unselected bands are not in this pack)`
             : "";
         lines.push(`Tile ${tile.id}: band ${n + 1} of ${bands.length}${capped}, ` +
             `document y ${top}-${bottom} px of a ${pageHeight} px tall page.`);
@@ -50,13 +49,17 @@ export function tileRubricPreamble(record, tileId) {
             const above = Math.max(0, prev.scrollY + prev.height - top);
             overlaps.push(above > 0
                 ? `its top ${above} px repeat the bottom of ${prev.id}`
-                : `it starts where ${prev.id} ends, with no overlap`);
+                : prev.scrollY + prev.height === top
+                    ? `it starts where ${prev.id} ends, with no overlap`
+                    : `an unreviewed gap of ${top - prev.scrollY - prev.height} px separates it from ${prev.id}`);
         }
         if (next) {
             const below = Math.max(0, bottom - next.scrollY);
             overlaps.push(below > 0
                 ? `its bottom ${below} px repeat the top of ${next.id}`
-                : `it ends where ${next.id} starts, with no overlap`);
+                : bottom === next.scrollY
+                    ? `it ends where ${next.id} starts, with no overlap`
+                    : `an unreviewed gap of ${next.scrollY - bottom} px separates it from ${next.id}`);
         }
         if (overlaps.length > 0) {
             const joined = overlaps.join("; ");
@@ -69,13 +72,13 @@ export function tileRubricPreamble(record, tileId) {
         lines.push("This tile covers the whole page height.");
     }
     else if (touchesTop) {
-        lines.push("This tile touches the page top; content cut at its bottom edge continues in the next band.");
+        lines.push("This tile touches the page top; the capture continues below its bottom edge, which alone does not prove clipping.");
     }
     else if (touchesBottom) {
-        lines.push("This tile touches the page bottom; content cut at its top edge continues in the previous band.");
+        lines.push("This tile touches the page bottom; the capture continues above its top edge, which alone does not prove clipping.");
     }
     else {
-        lines.push("This tile is interior: content cut at its top and bottom edges continues in the neighbouring bands.");
+        lines.push("This tile is interior: the page continues beyond both edges. Use document positions to distinguish overlapping bands from unreviewed gaps.");
     }
     const source = record.capture_fidelity?.source ?? "full-page";
     lines.push(source === "scrolled-bands"
@@ -114,41 +117,41 @@ export async function judgePageReviewPack(options) {
         const tiles = readPackTiles(packDir, record);
         let review = tiles;
         let reuse;
-        // Reuse only for unscoped captures: scope tiles share tiler indices with
-        // the bands, and a mixed set would mis-associate baseline findings.
-        // Never for a scrolled-bands context: its tiles were cut from scrolled
-        // viewport captures, not from the full-page PNG the band diff compares.
-        const scrolled = record.capture_fidelity?.source === "scrolled-bands";
-        if (options.reuse && provider && scrolled) {
-            log(`judge ${record.id}: band-diff reuse skipped (tiles came from scrolled bands)`);
-        }
-        if (options.reuse && provider && record.scopes.length === 0 && !scrolled) {
+        const evidence = buildPackNativeEvidence(record, tiles, rubric);
+        record.evidence_context = evidence.context;
+        if (options.reuse &&
+            provider &&
+            record.scopes.length === 0 &&
+            !record.capture_incomplete &&
+            !record.coverage.capped) {
             const context = {
                 viewport: record.viewport,
                 theme: record.theme,
                 state: record.state,
             };
             const stored = loadQaSnapshot(options.reuse.target, context, options.reuse.store ?? {});
-            if (stored?.screenshotPath && stored.critique) {
-                reuse = planCritiqueReuse({
-                    baselineScreenshot: readFileSync(stored.screenshotPath),
-                    baselineCritique: stored.critique,
-                    currentScreenshot: readPackFullPage(packDir, record),
-                    tiles,
-                    rubric,
-                    ...(options.reuse.mismatchThreshold !== undefined
-                        ? { mismatchThreshold: options.reuse.mismatchThreshold }
-                        : {}),
-                });
-                const keep = new Set(reuse.review.map((tile) => tile.index));
-                // planCritiqueReuse returns CritiqueTile objects; re-attach ids by
-                // tiler index so the pool cites the pack's stable tile ids.
-                review = tiles.filter((tile) => keep.has(tile.index));
-                log(`judge ${record.id}: ${reuse.tiles_reused}/${reuse.tiles_total} tiles reused (band-diff)` +
-                    (reuse.invalidation ? ` — ${reuse.invalidation}` : ""));
-            }
+            reuse = planNativeTileReuse({
+                current: evidence,
+                baseline: stored?.tileEvidence,
+                critique: stored?.critique,
+                tiles,
+                ...(options.reuse.mismatchThreshold !== undefined
+                    ? { mismatchThreshold: options.reuse.mismatchThreshold }
+                    : {}),
+            });
+            review = tiles.filter((_, i) => !reuse?.decisions[i]?.reuse);
+            log(`judge ${record.id}: ${reuse.tiles_reused}/${reuse.tiles_total} tiles reused (band-diff)` +
+                (reuse.invalidation ? ` — ${reuse.invalidation}` : ""));
         }
-        return { record, tiles, review, ...(reuse ? { reuse } : {}), findings: [], judged: new Set() };
+        return {
+            record,
+            tiles,
+            review,
+            evidence,
+            ...(reuse ? { reuse } : {}),
+            findings: [],
+            judged: new Set(),
+        };
     });
     const work = [];
     perContext.forEach((entry, contextIndex) => {
@@ -212,7 +215,7 @@ export async function judgePageReviewPack(options) {
             ? "skipped"
             : findings.some((f) => f.severity === "high")
                 ? "fail"
-                : unjudged > 0
+                : unjudged > 0 || entry.record.capture_incomplete
                     ? "incomplete"
                     : "pass";
         return {
@@ -231,6 +234,11 @@ export async function judgePageReviewPack(options) {
                     error: "no critiqueProvider injected by the host (see HarneryProgramContext.critiqueProvider)",
                 }),
             record: entry.record,
+            evidence: {
+                schema: PAGE_REVIEW_CRITIQUE_SCHEMA,
+                context: entry.evidence.context,
+                tiles: entry.evidence.tiles.map(({ png: _png, ...tile }) => tile),
+            },
             ...(entry.reuse
                 ? {
                     reuse: {