@tangle-network/browser-agent-driver 0.33.3 → 0.35.0

package/dist/design/audit/reference/judge/quality.js

@@ -0,0 +1,62 @@
+/**
+ * Absolute quality assessment — the single honest scoring leg.
+ *
+ * `assessPageQuality` judges the page-under-audit against the retrieved
+ * world-class exemplars with the same position-swapped `judgePair` debias, and
+ * reports the page's win-rate. This — NOT the relative direction ranking — is
+ * what `score-core` turns into the headline 0-10 and the per-`Dimension` scores.
+ *
+ * Overall leg: one debiased comparison per exemplar → `overallWinRate`.
+ * Optional per-dimension leg (`opts.dimensions`): one dimension-scoped
+ * comparison SET per `Dimension`, so each `dimensionWinRates` entry is genuinely
+ * judge-resolved (the judge narrows its rubric to that dimension), never the
+ * overall number stamped across dims. A dimension with no decisive comparison is
+ * OMITTED — callers must not fabricate a per-dim score from `overallWinRate`.
+ *
+ * Pure¹: the `TasteJudge` is injected, so this unit-tests with a stub judge and
+ * no live model. Comparisons run sequentially for deterministic accounting;
+ * concurrency/budget is the orchestrator's concern, not this leg's.
+ */
+import { judgePair } from './pairwise.js';
+const round4 = (n) => Math.round(n * 10000) / 10000;
+/** Neutral rate when no decisive (non-tie) comparison backed a leg. */
+const ON_PAR = 0.5;
+async function pageWinRate(judge, page, exemplars, dimension) {
+    let wins = 0;
+    let comparisons = 0;
+    for (const exemplar of exemplars) {
+        const verdict = await judgePair(judge, { a: page, b: exemplar, dimension });
+        if (verdict.winner === 'tie')
+            continue;
+        comparisons++;
+        if (verdict.winner === page.id)
+            wins++;
+    }
+    return { rate: comparisons > 0 ? round4(wins / comparisons) : ON_PAR, comparisons };
+}
+/**
+ * Assess the absolute quality of `page` against `exemplars` → a `win-rate`-keyed
+ * `QualityAssessment`.
+ */
+export async function assessPageQuality(judge, page, exemplars, opts = {}) {
+    const overall = await pageWinRate(judge, page, exemplars);
+    let dimensionWinRates;
+    const dimensions = opts.dimensions ?? [];
+    if (dimensions.length > 0 && exemplars.length > 0) {
+        const collected = {};
+        for (const dimension of dimensions) {
+            const dim = await pageWinRate(judge, page, exemplars, dimension);
+            // Omit a dimension with no decisive signal rather than stamp a fake rate.
+            if (dim.comparisons > 0)
+                collected[dimension] = dim.rate;
+        }
+        if (Object.keys(collected).length > 0)
+            dimensionWinRates = collected;
+    }
+    return {
+        overallWinRate: overall.rate,
+        dimensionWinRates,
+        comparisons: overall.comparisons,
+    };
+}
+//# sourceMappingURL=quality.js.map

package/dist/design/audit/reference/judge/quality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality.js","sourceRoot":"","sources":["../../../../../src/design/audit/reference/judge/quality.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAEzC,MAAM,MAAM,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAA;AAEnE,uEAAuE;AACvE,MAAM,MAAM,GAAG,GAAG,CAAA;AASlB,KAAK,UAAU,WAAW,CACxB,KAAiB,EACjB,IAAkB,EAClB,SAAyB,EACzB,SAAqB;IAErB,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,IAAI,WAAW,GAAG,CAAC,CAAA;IACnB,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAA;QAC3E,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK;YAAE,SAAQ;QACtC,WAAW,EAAE,CAAA;QACb,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,EAAE;YAAE,IAAI,EAAE,CAAA;IACxC,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,CAAA;AACrF,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAiB,EACjB,IAAkB,EAClB,SAAyB,EACzB,OAAqC,EAAE;IAEvC,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;IAEzD,IAAI,iBAAiE,CAAA;IACrE,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,EAAE,CAAA;IACxC,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,MAAM,SAAS,GAAuC,EAAE,CAAA;QACxD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,CAAC,CAAA;YAChE,0EAA0E;YAC1E,IAAI,GAAG,CAAC,WAAW,GAAG,CAAC;gBAAE,SAAS,CAAC,SAAS,CAAC,GAAG,GAAG,CAAC,IAAI,CAAA;QAC1D,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC;YAAE,iBAAiB,GAAG,SAAS,CAAA;IACtE,CAAC;IAED,OAAO;QACL,cAAc,EAAE,OAAO,CAAC,IAAI;QAC5B,iBAAiB;QACjB,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAA;AACH,CAAC"}

package/dist/design/audit/reference/judge/rank.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Direction ranking — the PURE Bradley-Terry / Elo rollup. Folds many debiased
+ * `TasteVerdict`s into a single `RankResult`. No IO, no model: deterministic for
+ * a fixed verdict set, so `rankDirections` IS the `DirectionRanker`
+ * implementation (`{ rank: rankDirections }` at the wiring root).
+ *
+ * Two complementary solvers, both reported:
+ *  - Bradley-Terry strengths via minorization-maximization (the maximum-
+ *    likelihood stationary ranking; order-independent, sum-normalised).
+ *  - Elo via sequential `updateElo` (cheap, online, conserves total rating).
+ *
+ * The published order is by Bradley-Terry strength, with Elo then id as
+ * deterministic tie-breaks. `calibrateAgainstVotes` scores judge-vs-human
+ * agreement so the taste judge can be validated against ground-truth votes.
+ */
+import type { CalibrationResult, HumanVote, RankResult, TasteVerdict } from '../contracts.js';
+/**
+ * One Elo update for a single game. `outcome` is the score for the FIRST player
+ * (1 win, 0.5 tie, 0 loss). Total rating is conserved (the two deltas cancel),
+ * and the update is symmetric under swapping players + complementing the outcome.
+ */
+export declare function updateElo(ra: number, rb: number, outcome: number, k?: number): [number, number];
+/**
+ * Bradley-Terry strengths per id, sum-normalised. A win counts as one game won;
+ * a tie splits the game half-and-half. Returns `{}` for no verdicts and a
+ * uniform distribution when ids exist but no games were played.
+ */
+export declare function bradleyTerry(verdicts: TasteVerdict[]): Record<string, number>;
+/**
+ * Roll a set of pairwise verdicts up into a ranking. `ids` seeds the population
+ * (so a direction with no verdicts still appears, ranked last). Order is by
+ * Bradley-Terry strength, tie-broken by Elo then id for determinism.
+ */
+export declare function rankDirections(ids: string[], verdicts: TasteVerdict[]): RankResult;
+/**
+ * Judge-vs-human agreement over a set of votes. Ties (on either side) and pairs
+ * the judge never compared are excluded from `n`. Empty → `{ agreement: 0, n: 0 }`,
+ * never NaN.
+ */
+export declare function calibrateAgainstVotes(verdicts: TasteVerdict[], votes: HumanVote[]): CalibrationResult;
+//# sourceMappingURL=rank.d.ts.map

package/dist/design/audit/reference/judge/rank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rank.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/judge/rank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAoB7F;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,GAAE,MAAc,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAOtG;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmD7E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,UAAU,CAwDlF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,iBAAiB,CAerG"}

package/dist/design/audit/reference/judge/rank.js

@@ -0,0 +1,196 @@
+/**
+ * Direction ranking — the PURE Bradley-Terry / Elo rollup. Folds many debiased
+ * `TasteVerdict`s into a single `RankResult`. No IO, no model: deterministic for
+ * a fixed verdict set, so `rankDirections` IS the `DirectionRanker`
+ * implementation (`{ rank: rankDirections }` at the wiring root).
+ *
+ * Two complementary solvers, both reported:
+ *  - Bradley-Terry strengths via minorization-maximization (the maximum-
+ *    likelihood stationary ranking; order-independent, sum-normalised).
+ *  - Elo via sequential `updateElo` (cheap, online, conserves total rating).
+ *
+ * The published order is by Bradley-Terry strength, with Elo then id as
+ * deterministic tie-breaks. `calibrateAgainstVotes` scores judge-vs-human
+ * agreement so the taste judge can be validated against ground-truth votes.
+ */
+const ELO_START = 1500;
+const ELO_K = 32;
+const BT_ITERATIONS = 200;
+const round2 = (n) => Math.round(n * 100) / 100;
+const round4 = (n) => Math.round(n * 10000) / 10000;
+const round6 = (n) => Math.round(n * 1e6) / 1e6;
+const clamp01 = (n) => (n < 0 ? 0 : n > 1 ? 1 : n);
+function collectIds(seed, verdicts) {
+    const set = new Set(seed);
+    for (const v of verdicts) {
+        set.add(v.aId);
+        set.add(v.bId);
+    }
+    return [...set];
+}
+/**
+ * One Elo update for a single game. `outcome` is the score for the FIRST player
+ * (1 win, 0.5 tie, 0 loss). Total rating is conserved (the two deltas cancel),
+ * and the update is symmetric under swapping players + complementing the outcome.
+ */
+export function updateElo(ra, rb, outcome, k = ELO_K) {
+    const expectedA = 1 / (1 + Math.pow(10, (rb - ra) / 400));
+    const expectedB = 1 - expectedA;
+    const o = clamp01(outcome);
+    const ra2 = ra + k * (o - expectedA);
+    const rb2 = rb + k * (1 - o - expectedB);
+    return [ra2, rb2];
+}
+/**
+ * Bradley-Terry strengths per id, sum-normalised. A win counts as one game won;
+ * a tie splits the game half-and-half. Returns `{}` for no verdicts and a
+ * uniform distribution when ids exist but no games were played.
+ */
+export function bradleyTerry(verdicts) {
+    const ids = collectIds([], verdicts);
+    if (ids.length === 0)
+        return {};
+    const wins = {};
+    const games = {};
+    for (const id of ids) {
+        wins[id] = 0;
+        games[id] = {};
+        for (const other of ids)
+            games[id][other] = 0;
+    }
+    let totalGames = 0;
+    for (const v of verdicts) {
+        if (v.aId === v.bId)
+            continue;
+        games[v.aId][v.bId] += 1;
+        games[v.bId][v.aId] += 1;
+        totalGames += 1;
+        if (v.winner === v.aId)
+            wins[v.aId] += 1;
+        else if (v.winner === v.bId)
+            wins[v.bId] += 1;
+        else {
+            wins[v.aId] += 0.5;
+            wins[v.bId] += 0.5;
+        }
+    }
+    if (totalGames === 0) {
+        const uniform = 1 / ids.length;
+        return Object.fromEntries(ids.map((id) => [id, uniform]));
+    }
+    let p = Object.fromEntries(ids.map((id) => [id, 1]));
+    for (let iter = 0; iter < BT_ITERATIONS; iter++) {
+        const next = {};
+        for (const i of ids) {
+            let denom = 0;
+            for (const j of ids) {
+                if (i === j)
+                    continue;
+                const nij = games[i][j];
+                if (nij === 0)
+                    continue;
+                denom += nij / (p[i] + p[j]);
+            }
+            next[i] = denom > 0 ? wins[i] / denom : 0;
+        }
+        const sum = ids.reduce((s, id) => s + next[id], 0);
+        p = sum > 0 ? Object.fromEntries(ids.map((id) => [id, next[id] / sum])) : next;
+    }
+    const sum = ids.reduce((s, id) => s + p[id], 0);
+    if (sum <= 0)
+        return p;
+    return Object.fromEntries(ids.map((id) => [id, round6(p[id] / sum)]));
+}
+/**
+ * Roll a set of pairwise verdicts up into a ranking. `ids` seeds the population
+ * (so a direction with no verdicts still appears, ranked last). Order is by
+ * Bradley-Terry strength, tie-broken by Elo then id for determinism.
+ */
+export function rankDirections(ids, verdicts) {
+    const population = collectIds(ids, verdicts);
+    const bt = bradleyTerry(verdicts);
+    const bradleyTerryMap = {};
+    for (const id of population)
+        bradleyTerryMap[id] = bt[id] ?? 0;
+    // No evidence at all over the whole population ⇒ uniform priors (sum-normalised
+    // to 1, per contract), not a row of zeros.
+    const btSum = population.reduce((s, id) => s + bradleyTerryMap[id], 0);
+    if (population.length > 0 && btSum <= 1e-12) {
+        const uniform = round6(1 / population.length);
+        for (const id of population)
+            bradleyTerryMap[id] = uniform;
+    }
+    // Games played per id — a seeded-but-unjudged direction (0 games) must sink
+    // below any direction that was actually compared, even a loser, since we have
+    // no evidence to surface it.
+    const games = {};
+    for (const id of population)
+        games[id] = 0;
+    for (const v of verdicts) {
+        if (v.aId === v.bId)
+            continue;
+        games[v.aId] = (games[v.aId] ?? 0) + 1;
+        games[v.bId] = (games[v.bId] ?? 0) + 1;
+    }
+    const elo = {};
+    for (const id of population)
+        elo[id] = ELO_START;
+    for (const v of verdicts) {
+        if (v.aId === v.bId)
+            continue;
+        if (!(v.aId in elo))
+            elo[v.aId] = ELO_START;
+        if (!(v.bId in elo))
+            elo[v.bId] = ELO_START;
+        const outcome = v.winner === v.aId ? 1 : v.winner === v.bId ? 0 : 0.5;
+        const [ra, rb] = updateElo(elo[v.aId], elo[v.bId], outcome);
+        elo[v.aId] = ra;
+        elo[v.bId] = rb;
+    }
+    const order = [...population].sort((x, y) => {
+        const db = bradleyTerryMap[y] - bradleyTerryMap[x];
+        if (Math.abs(db) > 1e-9)
+            return db;
+        const dg = games[y] - games[x];
+        if (dg !== 0)
+            return dg;
+        const de = elo[y] - elo[x];
+        if (Math.abs(de) > 1e-9)
+            return de;
+        return x < y ? -1 : x > y ? 1 : 0;
+    });
+    const eloRounded = {};
+    for (const id of population)
+        eloRounded[id] = round2(elo[id]);
+    return {
+        order,
+        winnerId: order[0] ?? '',
+        bradleyTerry: bradleyTerryMap,
+        elo: eloRounded,
+    };
+}
+/**
+ * Judge-vs-human agreement over a set of votes. Ties (on either side) and pairs
+ * the judge never compared are excluded from `n`. Empty → `{ agreement: 0, n: 0 }`,
+ * never NaN.
+ */
+export function calibrateAgainstVotes(verdicts, votes) {
+    const key = (a, b) => (a < b ? `${a}|${b}` : `${b}|${a}`);
+    const judgeByPair = new Map();
+    for (const v of verdicts)
+        judgeByPair.set(key(v.aId, v.bId), v.winner);
+    let n = 0;
+    let agree = 0;
+    for (const vote of votes) {
+        if (vote.winner === 'tie')
+            continue;
+        const judged = judgeByPair.get(key(vote.aId, vote.bId));
+        if (judged === undefined || judged === 'tie')
+            continue;
+        n++;
+        if (judged === vote.winner)
+            agree++;
+    }
+    return { agreement: n > 0 ? round4(agree / n) : 0, n };
+}
+//# sourceMappingURL=rank.js.map

package/dist/design/audit/reference/judge/rank.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rank.js","sourceRoot":"","sources":["../../../../../src/design/audit/reference/judge/rank.ts"],"names":[],"mappings":"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"}

package/dist/design/audit/reference/judge/text-judge.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Text taste judge — the default `TasteJudge` adapter. The ONLY impure piece of
+ * the judge stack: one `brain.complete` per comparison over budget-bounded DNA /
+ * direction summaries, parsed by the pure `parseRawVerdict`. All debiasing,
+ * aggregation, and ranking live in the pure cores around it (`pairwise`,
+ * `quality`, `rank`).
+ *
+ * The model dependency is injected through the narrow `JudgeModel` seam — the
+ * real `Brain` satisfies it structurally, so the wiring root passes `brain`
+ * unchanged while unit tests inject a deterministic mock with no live model.
+ *
+ * `brain.auditDesign` is deliberately NOT used: overloading the page-audit seam
+ * for taste comparison is the contract abuse the architecture forbids. A vision
+ * judge is a future drop-in implementing this same `TasteJudge` interface once a
+ * clean visual-compare seam exists.
+ */
+import type { TasteJudge } from '../contracts.js';
+/**
+ * The narrow model seam the text judge needs. `Brain` is assignable to this, so
+ * `createTextJudge(brain)` compiles at the wiring root while tests supply a stub.
+ */
+export interface JudgeModel {
+    complete(system: string, user: string, options?: {
+        maxOutputTokens?: number;
+    }): Promise<{
+        text: string;
+        tokensUsed?: number;
+    }>;
+}
+export declare function createTextJudge(brain: JudgeModel): TasteJudge;
+//# sourceMappingURL=text-judge.d.ts.map

package/dist/design/audit/reference/judge/text-judge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-judge.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/judge/text-judge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAA8B,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAI7E;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,GACrC,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAClD;AAKD,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAuB7D"}

package/dist/design/audit/reference/judge/text-judge.js

@@ -0,0 +1,43 @@
+/**
+ * Text taste judge — the default `TasteJudge` adapter. The ONLY impure piece of
+ * the judge stack: one `brain.complete` per comparison over budget-bounded DNA /
+ * direction summaries, parsed by the pure `parseRawVerdict`. All debiasing,
+ * aggregation, and ranking live in the pure cores around it (`pairwise`,
+ * `quality`, `rank`).
+ *
+ * The model dependency is injected through the narrow `JudgeModel` seam — the
+ * real `Brain` satisfies it structurally, so the wiring root passes `brain`
+ * unchanged while unit tests inject a deterministic mock with no live model.
+ *
+ * `brain.auditDesign` is deliberately NOT used: overloading the page-audit seam
+ * for taste comparison is the contract abuse the architecture forbids. A vision
+ * judge is a future drop-in implementing this same `TasteJudge` interface once a
+ * clean visual-compare seam exists.
+ */
+import { buildPairwisePrompt, buildQualityPrompt } from './prompt.js';
+import { parseRawVerdict } from './parse.js';
+// Verdict JSON is tiny; cap output so a runaway judge response can't blow budget.
+const JUDGE_MAX_OUTPUT_TOKENS = 400;
+export function createTextJudge(brain) {
+    return {
+        id: 'text-judge',
+        async compare(input) {
+            // Direction-vs-direction comparisons carry a directionSummary; page-vs-
+            // exemplar (absolute quality) comparisons carry only DNA. Choose the
+            // matching prompt; the debias core supplies the slot order via input a/b.
+            const usesDirections = Boolean(input.a.directionSummary || input.b.directionSummary);
+            const { system, user } = usesDirections
+                ? buildPairwisePrompt(input, 'AB')
+                : buildQualityPrompt(input, 'AB');
+            const { text, tokensUsed } = await brain.complete(system, user, {
+                maxOutputTokens: JUDGE_MAX_OUTPUT_TOKENS,
+            });
+            const verdict = parseRawVerdict(text);
+            // Echo the dimension scope so the quality leg can bucket per-dimension.
+            return input.dimension !== undefined
+                ? { ...verdict, dimension: input.dimension, tokensUsed }
+                : { ...verdict, tokensUsed };
+        },
+    };
+}
+//# sourceMappingURL=text-judge.js.map

package/dist/design/audit/reference/judge/text-judge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-judge.js","sourceRoot":"","sources":["../../../../../src/design/audit/reference/judge/text-judge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAc5C,kFAAkF;AAClF,MAAM,uBAAuB,GAAG,GAAG,CAAA;AAEnC,MAAM,UAAU,eAAe,CAAC,KAAiB;IAC/C,OAAO;QACL,EAAE,EAAE,YAAY;QAChB,KAAK,CAAC,OAAO,CAAC,KAAqB;YACjC,wEAAwE;YACxE,qEAAqE;YACrE,0EAA0E;YAC1E,MAAM,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB,IAAI,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAA;YACpF,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,cAAc;gBACrC,CAAC,CAAC,mBAAmB,CAAC,KAAK,EAAE,IAAI,CAAC;gBAClC,CAAC,CAAC,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;YAEnC,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE;gBAC9D,eAAe,EAAE,uBAAuB;aACzC,CAAC,CAAA;YACF,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,CAAA;YAErC,wEAAwE;YACxE,OAAO,KAAK,CAAC,SAAS,KAAK,SAAS;gBAClC,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,UAAU,EAAE;gBACxD,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,UAAU,EAAE,CAAA;QAChC,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/design/audit/reference/judge/vision-judge.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Vision taste judge — a screenshot-grounded `TasteJudge` that is a drop-in for
+ * the default text judge. PURE given its injected models: it imports no Brain and
+ * does no IO, so it unit-tests with deterministic `VisionJudgeModel` stubs and no
+ * live model. The disk read + provider round-trip live behind the injected seam
+ * (`judge/vision-model.createBrainVisionModel`).
+ *
+ * What it adds over the text judge: it judges from the subjects' SCREENSHOTS (the
+ * audited page and the corpus exemplars), not just their DNA text — so the
+ * absolute-quality leg (`judge/quality.assessPageQuality`) becomes a genuine
+ * visual page-vs-exemplar comparison. It reuses the text judge's pure prompt
+ * cores (`buildQualityPrompt`/`buildPairwisePrompt`) and parser
+ * (`parseVerdictOrNull`) verbatim — vision adds images, not new prompt logic.
+ *
+ * TWO layered debiases, kept separate so neither is double-applied:
+ *  - POSITION-SWAP (A-vs-B and B-vs-A) is NOT done here. The surrounding pure
+ *    debias core (`judge/pairwise.judgePair`) already calls `compare` twice and
+ *    reconciles, so one `compare` is ONE slot order. Re-swapping internally would
+ *    double the model calls and break that core's accounting.
+ *  - The ENSEMBLE (across MODELS) IS done here: every model runs in parallel on
+ *    the given slot order, then aggregates to a majority winner with an honest
+ *    agreement-fraction confidence (see `aggregateVerdicts`). With one model it
+ *    degrades to a single judge; with many it is robust to single-model bias.
+ *
+ * Fail-closed: a model that throws or returns no parseable winner is DROPPED; if
+ * every model is dropped, `compare` throws rather than fabricating a tie. An empty
+ * model list is rejected at construction.
+ *
+ * SCOPE: only subjects that HAVE a screenshot are vision-judged. Unrendered
+ * `RedesignDirection` specs carry none, so a comparison with a screenshot-less
+ * side delegates to the injected text fallback — keeping this a single drop-in
+ * judge for BOTH the quality leg (vision) and the direction-ranking leg (text).
+ */
+import type { RawVerdict, TasteJudge, VisionJudgeModel } from '../contracts.js';
+/**
+ * Collapse the surviving per-model verdicts into one ensemble `RawVerdict` body
+ * (winnerSlot + honest confidence + merged reasons). PURE. Throws on an empty set
+ * — an all-dropped ensemble is an explicit error, never a fabricated tie.
+ *
+ * The bucket (A/B/tie) with the STRICT maximum vote count wins; a genuine `tie`
+ * vote counts in its own bucket. `confidence` is that bucket's vote share
+ * (agreement fraction). A split — two or more buckets sharing the top count —
+ * is undecided ⇒ tie at confidence 0.
+ */
+export declare function aggregateVerdicts(verdicts: RawVerdict[]): {
+    winnerSlot: RawVerdict['winnerSlot'];
+    confidence: number;
+    reasons: string[];
+};
+/**
+ * Build a vision `TasteJudge` over a non-empty list of `VisionJudgeModel`s. One
+ * model ⇒ a single judge; many ⇒ the cross-model ensemble. `textFallback` (the
+ * default text judge, injected by the wiring) handles comparisons whose subjects
+ * lack screenshots; omit it only in tests that never exercise that path.
+ */
+export declare function createVisionJudge(models: VisionJudgeModel[], opts?: {
+    textFallback?: TasteJudge;
+}): TasteJudge;
+//# sourceMappingURL=vision-judge.d.ts.map

package/dist/design/audit/reference/judge/vision-judge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision-judge.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/judge/vision-judge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAEV,UAAU,EACV,UAAU,EAEV,gBAAgB,EACjB,MAAM,iBAAiB,CAAA;AAqBxB;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG;IACzD,UAAU,EAAE,UAAU,CAAC,YAAY,CAAC,CAAA;IACpC,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB,CAqBA;AA6BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,gBAAgB,EAAE,EAC1B,IAAI,GAAE;IAAE,YAAY,CAAC,EAAE,UAAU,CAAA;CAAO,GACvC,UAAU,CAsDZ"}

package/dist/design/audit/reference/judge/vision-judge.js

@@ -0,0 +1,150 @@
+/**
+ * Vision taste judge — a screenshot-grounded `TasteJudge` that is a drop-in for
+ * the default text judge. PURE given its injected models: it imports no Brain and
+ * does no IO, so it unit-tests with deterministic `VisionJudgeModel` stubs and no
+ * live model. The disk read + provider round-trip live behind the injected seam
+ * (`judge/vision-model.createBrainVisionModel`).
+ *
+ * What it adds over the text judge: it judges from the subjects' SCREENSHOTS (the
+ * audited page and the corpus exemplars), not just their DNA text — so the
+ * absolute-quality leg (`judge/quality.assessPageQuality`) becomes a genuine
+ * visual page-vs-exemplar comparison. It reuses the text judge's pure prompt
+ * cores (`buildQualityPrompt`/`buildPairwisePrompt`) and parser
+ * (`parseVerdictOrNull`) verbatim — vision adds images, not new prompt logic.
+ *
+ * TWO layered debiases, kept separate so neither is double-applied:
+ *  - POSITION-SWAP (A-vs-B and B-vs-A) is NOT done here. The surrounding pure
+ *    debias core (`judge/pairwise.judgePair`) already calls `compare` twice and
+ *    reconciles, so one `compare` is ONE slot order. Re-swapping internally would
+ *    double the model calls and break that core's accounting.
+ *  - The ENSEMBLE (across MODELS) IS done here: every model runs in parallel on
+ *    the given slot order, then aggregates to a majority winner with an honest
+ *    agreement-fraction confidence (see `aggregateVerdicts`). With one model it
+ *    degrades to a single judge; with many it is robust to single-model bias.
+ *
+ * Fail-closed: a model that throws or returns no parseable winner is DROPPED; if
+ * every model is dropped, `compare` throws rather than fabricating a tie. An empty
+ * model list is rejected at construction.
+ *
+ * SCOPE: only subjects that HAVE a screenshot are vision-judged. Unrendered
+ * `RedesignDirection` specs carry none, so a comparison with a screenshot-less
+ * side delegates to the injected text fallback — keeping this a single drop-in
+ * judge for BOTH the quality leg (vision) and the direction-ranking leg (text).
+ */
+import { buildPairwisePrompt, buildQualityPrompt } from './prompt.js';
+import { parseVerdictOrNull } from './parse.js';
+// Verdict JSON is tiny; cap output so a runaway response can't blow budget. Same
+// ceiling as the text judge (`text-judge.JUDGE_MAX_OUTPUT_TOKENS`).
+const JUDGE_MAX_OUTPUT_TOKENS = 400;
+// Merged-reason ceiling on the aggregated verdict, so an N-model ensemble cannot
+// bloat one `RawVerdict` with N× the reasons.
+const REASON_CAP = 8;
+// Prepended to the reused text prompt so the model maps images→slots. The images
+// are attached in slot order ([slot A, slot B]); `compare` always renders the
+// input on slot order 'AB', and the outer `judgePair` supplies the swapped order.
+const VISION_PREAMBLE = 'Two screenshots are attached. The FIRST image is SLOT A; the SECOND image is SLOT B. ' +
+    'Judge primarily from the screenshots — the text below is a secondary DNA summary of each design.';
+const round4 = (n) => Math.round(n * 10000) / 10000;
+/**
+ * Collapse the surviving per-model verdicts into one ensemble `RawVerdict` body
+ * (winnerSlot + honest confidence + merged reasons). PURE. Throws on an empty set
+ * — an all-dropped ensemble is an explicit error, never a fabricated tie.
+ *
+ * The bucket (A/B/tie) with the STRICT maximum vote count wins; a genuine `tie`
+ * vote counts in its own bucket. `confidence` is that bucket's vote share
+ * (agreement fraction). A split — two or more buckets sharing the top count —
+ * is undecided ⇒ tie at confidence 0.
+ */
+export function aggregateVerdicts(verdicts) {
+    if (verdicts.length === 0) {
+        throw new Error('vision judge: cannot aggregate an empty set of verdicts');
+    }
+    const counts = { A: 0, B: 0, tie: 0 };
+    for (const v of verdicts)
+        counts[v.winnerSlot]++;
+    const total = verdicts.length;
+    const top = Math.max(counts.A, counts.B, counts.tie);
+    const leaders = ['A', 'B', 'tie'].filter((slot) => counts[slot] === top);
+    const decided = leaders.length === 1;
+    const winnerSlot = decided ? leaders[0] : 'tie';
+    const confidence = decided ? round4(top / total) : 0;
+    const reasons = [
+        `ensemble: A=${counts.A} B=${counts.B} tie=${counts.tie} over ${total} model${total === 1 ? '' : 's'}`,
+    ];
+    for (const v of verdicts) {
+        for (const r of v.reasons)
+            if (!reasons.includes(r))
+                reasons.push(r);
+    }
+    return { winnerSlot, confidence, reasons: reasons.slice(0, REASON_CAP) };
+}
+/** Run one model on a single slot order; a throw/unparseable result is a drop. */
+async function runModel(model, system, user, images) {
+    try {
+        const { text, tokensUsed } = await model.completeVision(system, user, images, {
+            maxOutputTokens: JUDGE_MAX_OUTPUT_TOKENS,
+        });
+        const verdict = parseVerdictOrNull(text);
+        if (!verdict && process.env.BAD_VISION_JUDGE_DEBUG === '1')
+            console.error(`[vision ${model.id}] parse-failed | len=${text.length} head=${JSON.stringify(text.slice(0, 240))}`);
+        return { verdict, tokens: tokensUsed ?? 0 };
+    }
+    catch (err) {
+        if (process.env.BAD_VISION_JUDGE_DEBUG === '1')
+            console.error(`[vision ${model.id}] call-failed: ${err instanceof Error ? err.message : String(err)}`);
+        return { verdict: null, tokens: 0 };
+    }
+}
+/**
+ * Build a vision `TasteJudge` over a non-empty list of `VisionJudgeModel`s. One
+ * model ⇒ a single judge; many ⇒ the cross-model ensemble. `textFallback` (the
+ * default text judge, injected by the wiring) handles comparisons whose subjects
+ * lack screenshots; omit it only in tests that never exercise that path.
+ */
+export function createVisionJudge(models, opts = {}) {
+    if (models.length === 0) {
+        throw new Error('vision judge: at least one vision model is required (empty ensemble)');
+    }
+    const { textFallback } = opts;
+    const id = `vision-judge[${models.map((m) => m.id).join('+')}]`;
+    return {
+        id,
+        async compare(input) {
+            const { a, b } = input;
+            // Vision needs an image on BOTH sides. Screenshot-less subjects (unrendered
+            // directions) delegate to the injected text judge, so one instance serves
+            // the vision quality leg AND the text direction leg.
+            if (!a.screenshotPath || !b.screenshotPath) {
+                if (!textFallback) {
+                    throw new Error(`vision judge: subjects ${a.id}/${b.id} lack screenshots and no text fallback was injected`);
+                }
+                return textFallback.compare(input);
+            }
+            // Mirror the text judge's prompt selection; both subjects carry screenshots
+            // here, so this is the absolute-quality leg in practice.
+            const usesDirections = Boolean(a.directionSummary || b.directionSummary);
+            const { system, user } = usesDirections
+                ? buildPairwisePrompt(input, 'AB')
+                : buildQualityPrompt(input, 'AB');
+            const userWithImages = `${VISION_PREAMBLE}\n\n${user}`;
+            const images = [
+                { screenshotPath: a.screenshotPath },
+                { screenshotPath: b.screenshotPath },
+            ];
+            const outcomes = await Promise.all(models.map((m) => runModel(m, system, userWithImages, images)));
+            const survivors = outcomes
+                .map((o) => o.verdict)
+                .filter((v) => v !== null);
+            const tokensUsed = outcomes.reduce((sum, o) => sum + o.tokens, 0);
+            if (survivors.length === 0) {
+                throw new Error(`vision judge: every model in the ensemble (${models.length}) failed to return a usable ` +
+                    'verdict; refusing to fabricate a tie');
+            }
+            const agg = aggregateVerdicts(survivors);
+            const verdict = { winnerSlot: agg.winnerSlot, confidence: agg.confidence, reasons: agg.reasons };
+            const withTokens = tokensUsed > 0 ? { ...verdict, tokensUsed } : verdict;
+            return input.dimension !== undefined ? { ...withTokens, dimension: input.dimension } : withTokens;
+        },
+    };
+}
+//# sourceMappingURL=vision-judge.js.map

package/dist/design/audit/reference/judge/vision-judge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision-judge.js","sourceRoot":"","sources":["../../../../../src/design/audit/reference/judge/vision-judge.ts"],"names":[],"mappings":"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"}