@tangle-network/browser-agent-driver 0.33.2 → 0.34.0

package/dist/design/audit/reference/engine/score-core.js

@@ -0,0 +1,134 @@
+/**
+ * Scoring core — the SINGLE scoring authority for the reference-grounded engine.
+ *
+ * Everything the pipeline scores derives from ONE `QualityAssessment` (the
+ * absolute leg: the page-under-audit's win-rate vs the retrieved world-class
+ * exemplars). This module turns that one assessment into three honest surfaces,
+ * eliminating the double-scoring the v1 path risked:
+ *
+ *  - `deriveHeadlineScore` → the 0-10 headline, monotonic in `overallWinRate`,
+ *    capped when deterministic measurements flag blocking issues (you cannot be
+ *    world-class with critical a11y/contrast failures).
+ *  - `toDimensionScores` → the rich 5-`Dimension` `Record<Dimension, DimensionScore>`
+ *    that IS stage-8's `precomputedScores` hook. Each dimension is scored ONLY
+ *    from a genuinely judge-resolved per-dimension win-rate; a dimension with no
+ *    signal is filled at `confidence:'low'` with an explicit "not assessed"
+ *    summary — never the overall number stamped across dimensions.
+ *  - `toDesignSystemScore` → the flat 8-axis `DesignSystemScore` back-compat
+ *    field, an HONESTLY coarse projection of `overallWinRate` (not a second
+ *    per-axis authority).
+ *
+ * Pure and deterministic: no IO, no LLM, no clock. Notably does NOT borrow
+ * `conservativeScore` — there are no per-pass page scores in this mode, so
+ * importing it would be scoring fiction.
+ */
+import { DIMENSIONS } from '../../score-types.js';
+// Headline runs on a 0-10 scale; dimension + design-system axes run on the
+// 1-10 scale the rest of the audit uses (see evaluate.ts / DimensionScore).
+const HEADLINE_MAX = 10;
+// A page with deterministic blocking issues (critical/serious a11y or contrast
+// failures, `MeasurementBundle.hasBlockingIssues`) cannot earn a top headline.
+// Mirrors the ethics gate's major-floor cap (6) — a measurement ceiling, not a
+// floor in the colloquial sense.
+const BLOCKING_ISSUE_HEADLINE_CAP = 6;
+// Neutral placeholder for a dimension the budget never judged. NOT derived from
+// `overallWinRate`; paired with `confidence:'low'` + a full [1,10] range so it
+// reads as "unassessed", never as a real per-dimension verdict.
+const UNASSESSED_DIMENSION_SCORE = 5;
+// Per-dimension confidence tiers keyed off how many comparisons backed the
+// quality leg. More comparisons ⇒ higher confidence ⇒ a tighter range.
+const HIGH_CONFIDENCE_COMPARISONS = 8;
+const MEDIUM_CONFIDENCE_COMPARISONS = 4;
+const clamp01 = (n) => Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : 0;
+const round1 = (n) => Math.round(n * 10) / 10;
+/** Map a 0-1 win-rate onto the 1-10 dimension/design-system scale. */
+function winRateToScore(winRate) {
+    return Math.max(1, Math.min(10, Math.round(clamp01(winRate) * 10)));
+}
+/**
+ * Derive the 0-10 headline from the absolute win-rate, capped when measurements
+ * flag blocking issues. Monotonic non-decreasing in `overallWinRate`: a higher
+ * win-rate never yields a lower headline.
+ */
+export function deriveHeadlineScore(quality, measurements) {
+    const raw = clamp01(quality.overallWinRate) * HEADLINE_MAX;
+    const capped = measurements.hasBlockingIssues
+        ? Math.min(raw, BLOCKING_ISSUE_HEADLINE_CAP)
+        : raw;
+    return round1(Math.min(HEADLINE_MAX, Math.max(0, capped)));
+}
+function confidenceFor(comparisons) {
+    if (comparisons >= HIGH_CONFIDENCE_COMPARISONS)
+        return 'high';
+    if (comparisons >= MEDIUM_CONFIDENCE_COMPARISONS)
+        return 'medium';
+    return 'low';
+}
+function rangeSpread(confidence) {
+    if (confidence === 'high')
+        return 1;
+    if (confidence === 'medium')
+        return 2;
+    return 3;
+}
+function judgedDimensionScore(dim, winRate, comparisons) {
+    const score = winRateToScore(winRate);
+    const confidence = confidenceFor(comparisons);
+    const spread = rangeSpread(confidence);
+    return {
+        score,
+        range: [Math.max(1, score - spread), Math.min(10, score + spread)],
+        confidence,
+        summary: `${dim}: ${Math.round(clamp01(winRate) * 100)}% win-rate vs world-class exemplars across ${comparisons} pairwise comparison(s).`,
+        primaryFindings: [],
+    };
+}
+function unassessedDimensionScore(dim) {
+    return {
+        score: UNASSESSED_DIMENSION_SCORE,
+        range: [1, 10],
+        confidence: 'low',
+        summary: `${dim}: not independently judged — no dimension-scoped comparison ran under this run's judge budget (overall-only leg). Placeholder, not derived from the overall win-rate.`,
+        primaryFindings: [],
+    };
+}
+/**
+ * Map the per-`Dimension` win-rates onto the rich `Record<Dimension, DimensionScore>`
+ * stage-8 consumes as `precomputedScores`. Every one of the 5 dimensions is
+ * present. Dimensions with a real per-dimension win-rate are scored from it
+ * (win-rate → score, comparison count → range + confidence); dimensions with no
+ * win-rate are filled as explicit, low-confidence placeholders so the absence of
+ * a dimension-scoped leg is honest rather than fabricated.
+ */
+export function toDimensionScores(quality) {
+    const rates = quality.dimensionWinRates ?? {};
+    const out = {};
+    for (const dim of DIMENSIONS) {
+        const winRate = rates[dim];
+        out[dim] =
+            winRate === undefined
+                ? unassessedDimensionScore(dim)
+                : judgedDimensionScore(dim, winRate, quality.comparisons);
+    }
+    return out;
+}
+/**
+ * Project `overallWinRate` onto the flat 8-axis `DesignSystemScore` back-compat
+ * field. Every axis carries the same overall-derived 1-10 number — this is an
+ * honest coarse projection, NOT a second per-axis scoring authority (the judge
+ * resolves the 5 product dimensions, not these 8 design-system axes).
+ */
+export function toDesignSystemScore(quality) {
+    const s = winRateToScore(quality.overallWinRate);
+    return {
+        layout: s,
+        typography: s,
+        color: s,
+        spacing: s,
+        components: s,
+        interactions: s,
+        accessibility: s,
+        polish: s,
+    };
+}
+//# sourceMappingURL=score-core.js.map

package/dist/design/audit/reference/engine/score-core.js.map

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

package/dist/design/audit/reference/engine/wiring.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Composition root — the ONE place concrete adapters meet. ORCH, zero domain
+ * logic.
+ *
+ * `buildDefaultDeps` assembles the `ReferenceEngineDeps` bundle `engine/core`
+ * depends on, picking each concrete implementation of the seven narrow boundary
+ * interfaces: the page→DNA extractor, the file corpus store (exposed as its
+ * read-only half), the embedding provider, the pure matcher, the brain-backed
+ * generator, the default text judge, and the pure ranker. The core never sees a
+ * concrete — it receives only these interfaces — and this module never imports
+ * `engine/core`, so the two L3 siblings have no edge between them.
+ *
+ * The model is injected through the narrow `ReferenceBrain` seam (exactly
+ * `brain.complete`'s shape, shared by the generator + judge adapters). The real
+ * `Brain` satisfies it structurally, so the L4 entrypoints pass `brain`
+ * unchanged while tests inject a deterministic stub with no live model.
+ */
+import type { ReferenceEngineDeps, ReferenceGroundedConfig } from '../contracts.js';
+import { type GenerationModel } from '../generate/generator.js';
+import { type JudgeModel } from '../judge/text-judge.js';
+/**
+ * The model seam the default wiring needs. The generator and the default text
+ * judge both reduce to `brain.complete`, so a single narrow interface satisfies
+ * both adapters; the concrete `Brain` is assignable to it.
+ */
+export interface ReferenceBrain extends GenerationModel, JudgeModel {
+}
+/**
+ * Assemble the default dependency bundle for {@link runRedesignCore}. The corpus
+ * store is created here but only its `CorpusReader` half reaches the core
+ * (`ReferenceEngineDeps.store` is typed `CorpusReader`), so the audit hot path
+ * can never touch the authoring mutators.
+ */
+export declare function buildDefaultDeps(brain: ReferenceBrain, config: ReferenceGroundedConfig): ReferenceEngineDeps;
+//# sourceMappingURL=wiring.d.ts.map

package/dist/design/audit/reference/engine/wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiring.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/engine/wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,uBAAuB,EAKxB,MAAM,iBAAiB,CAAA;AAMxB,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,0BAA0B,CAAA;AACrF,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAKzE;;;;GAIG;AACH,MAAM,WAAW,cAAe,SAAQ,eAAe,EAAE,UAAU;CAAG;AAsCtE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,uBAAuB,GAC9B,mBAAmB,CAarB"}

package/dist/design/audit/reference/engine/wiring.js

@@ -0,0 +1,80 @@
+/**
+ * Composition root — the ONE place concrete adapters meet. ORCH, zero domain
+ * logic.
+ *
+ * `buildDefaultDeps` assembles the `ReferenceEngineDeps` bundle `engine/core`
+ * depends on, picking each concrete implementation of the seven narrow boundary
+ * interfaces: the page→DNA extractor, the file corpus store (exposed as its
+ * read-only half), the embedding provider, the pure matcher, the brain-backed
+ * generator, the default text judge, and the pure ranker. The core never sees a
+ * concrete — it receives only these interfaces — and this module never imports
+ * `engine/core`, so the two L3 siblings have no edge between them.
+ *
+ * The model is injected through the narrow `ReferenceBrain` seam (exactly
+ * `brain.complete`'s shape, shared by the generator + judge adapters). The real
+ * `Brain` satisfies it structurally, so the L4 entrypoints pass `brain`
+ * unchanged while tests inject a deterministic stub with no live model.
+ */
+import { createPageDnaExtractor } from '../dna/page-adapter.js';
+import { createFileCorpusStore } from '../corpus/store.js';
+import { resolveEmbeddingProvider } from '../retrieval/embedding-openai.js';
+import { HashEmbeddingProvider } from '../retrieval/embedding-hash.js';
+import { retrieve } from '../retrieval/matcher.js';
+import { createBrainGenerator } from '../generate/generator.js';
+import { createTextJudge } from '../judge/text-judge.js';
+import { createVisionJudge } from '../judge/vision-judge.js';
+import { buildVisionModels } from '../judge/vision-model.js';
+import { rankDirections } from '../judge/rank.js';
+/**
+ * Pick the concrete embedding provider for the config:
+ *  - `'deterministic'` → the literally-pure offline hash embedder (zero network);
+ *  - `'provider'`      → the network provider when a key resolves, else the hash
+ *    embedder (fail-safe: a missing key yields a working offline run, not an error).
+ */
+function selectEmbedder(config) {
+    return config.embedder === 'provider' ? resolveEmbeddingProvider() : HashEmbeddingProvider;
+}
+/**
+ * Pick the concrete taste judge. `'text'` is the shipped default (judges from DNA
+ * summaries via `brain.complete`). `'vision'` builds the screenshot-grounded
+ * ensemble from `config.visionModels`: ONE Brain per `{ provider, model }` ref
+ * (each with its own provider key, constructed in `buildVisionModels`), wrapped
+ * in the pure `createVisionJudge`. The injected text `brain` is reused as the
+ * fallback for screenshot-less subjects (the direction-ranking leg), so the
+ * vision judge stays a single drop-in for both legs. Fails closed: an empty
+ * `visionModels` list throws rather than silently degrading to text.
+ *
+ * This is the composition root, so constructing concrete vision Brains here is by
+ * design — the engine core only ever sees the narrow `TasteJudge`. Unit tests
+ * inject `deps.judge` (or call `createVisionJudge` with stub models) and never
+ * reach this Brain construction.
+ */
+function selectJudge(brain, config) {
+    if (config.judge !== 'vision')
+        return createTextJudge(brain);
+    const refs = config.visionModels ?? [];
+    if (refs.length === 0) {
+        throw new Error('reference engine: judge "vision" requires at least one visionModels ref — none resolved');
+    }
+    return createVisionJudge(buildVisionModels(refs), { textFallback: createTextJudge(brain) });
+}
+/**
+ * Assemble the default dependency bundle for {@link runRedesignCore}. The corpus
+ * store is created here but only its `CorpusReader` half reaches the core
+ * (`ReferenceEngineDeps.store` is typed `CorpusReader`), so the audit hot path
+ * can never touch the authoring mutators.
+ */
+export function buildDefaultDeps(brain, config) {
+    const matcher = { retrieve };
+    const ranker = { rank: rankDirections };
+    return {
+        extractor: createPageDnaExtractor(),
+        store: createFileCorpusStore(config.corpusDir),
+        embedder: selectEmbedder(config),
+        matcher,
+        generator: createBrainGenerator(brain, { count: config.directionCount }),
+        judge: selectJudge(brain, config),
+        ranker,
+    };
+}
+//# sourceMappingURL=wiring.js.map

package/dist/design/audit/reference/engine/wiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiring.js","sourceRoot":"","sources":["../../../../../src/design/audit/reference/engine/wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAUH,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAC1D,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAA;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAA;AACtE,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAClD,OAAO,EAAE,oBAAoB,EAAwB,MAAM,0BAA0B,CAAA;AACrF,OAAO,EAAE,eAAe,EAAmB,MAAM,wBAAwB,CAAA;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AASjD;;;;;GAKG;AACH,SAAS,cAAc,CAAC,MAA+B;IACrD,OAAO,MAAM,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,wBAAwB,EAAE,CAAC,CAAC,CAAC,qBAAqB,CAAA;AAC5F,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,WAAW,CAAC,KAAqB,EAAE,MAA+B;IACzE,IAAI,MAAM,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,eAAe,CAAC,KAAK,CAAC,CAAA;IAC5D,MAAM,IAAI,GAAG,MAAM,CAAC,YAAY,IAAI,EAAE,CAAA;IACtC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,yFAAyF,CAC1F,CAAA;IACH,CAAC;IACD,OAAO,iBAAiB,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,EAAE,YAAY,EAAE,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;AAC7F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAqB,EACrB,MAA+B;IAE/B,MAAM,OAAO,GAAoB,EAAE,QAAQ,EAAE,CAAA;IAC7C,MAAM,MAAM,GAAoB,EAAE,IAAI,EAAE,cAAc,EAAE,CAAA;IAExD,OAAO;QACL,SAAS,EAAE,sBAAsB,EAAE;QACnC,KAAK,EAAE,qBAAqB,CAAC,MAAM,CAAC,SAAS,CAAC;QAC9C,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC;QAChC,OAAO;QACP,SAAS,EAAE,oBAAoB,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC;QACxE,KAAK,EAAE,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC;QACjC,MAAM;KACP,CAAA;AACH,CAAC"}

package/dist/design/audit/reference/eval/taste-core.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Taste-eval cores — the PURE bridge from debiased `TasteVerdict`s to the
+ * bench-layer taste metrics. Given verdicts (and the corpus ground-truth labels
+ * that produced them), these functions report how trustworthy the taste judge is
+ * and how the generated directions stack up against the operator reference.
+ *
+ * Everything here is pure and deterministic: NO IO, NO model, NO bench framework.
+ * The win-rate CIs (`wilsonInterval` / `bootstrapDiff95`) are computed at the
+ * bench layer from the raw counts these functions return — never re-implemented
+ * here — so this module stays a thin, framework-free numeric core.
+ *
+ * Tie-handling is uniform with the rest of the engine (`assessPageQuality`,
+ * `calibrateAgainstVotes`): a tie is never a win and never inflates a
+ * denominator, so every rate is a clean decisive proportion with integer
+ * `successes`/`n` the bench layer can hand straight to `wilsonInterval`.
+ */
+import type { RawVerdict, TasteAgreementResult, TasteMetrics, TastePair, TasteVerdict } from '../contracts.js';
+export { calibrateAgainstVotes } from '../judge/rank.js';
+/**
+ * One position-swapped comparison: the two slot-order raw verdicts for a single
+ * unordered pair. `ab` presented `aId`→SLOT A and `bId`→SLOT B; `ba` is the swap
+ * (`bId`→SLOT A, `aId`→SLOT B). This mirrors the two `judge.compare` calls
+ * `judgePair` issues per repetition, so a bench harness can record both raw
+ * verdicts and feed them here to diagnose slot bias the reconciled
+ * `TasteVerdict` has already absorbed.
+ */
+export interface SwappedRun {
+    aId: string;
+    bId: string;
+    ab: RawVerdict;
+    ba: RawVerdict;
+}
+/** Judge position-bias diagnosis over a set of swapped runs. */
+export interface PositionBiasResult {
+    /**
+     * Fraction of DECISIVE swapped runs (both orders named a winner) whose winning
+     * id flipped with the slot — i.e. the judge tracked the physical position, not
+     * the design. 0 = no measurable slot bias; 1 = pure slot bias.
+     */
+    biasRate: number;
+    /** Number of swapped runs where BOTH orders were decisive (the denominator). */
+    n: number;
+}
+/**
+ * Judge-vs-label agreement over corpus-vs-corpus taste pairs. Each `TastePair`
+ * carries a known-stronger / known-weaker member (the ground-truth label); the
+ * judge agrees when its debiased verdict for that pair picks the stronger id.
+ * Ties (judge said tie) and pairs the judge never compared are excluded from
+ * `n`. Empty → `{ agreementRate: 0, n: 0 }`, never NaN.
+ *
+ * Reuses `calibrateAgainstVotes`: a corpus label IS exactly a human vote for the
+ * stronger id, so the same agreement walk applies — pair lookup is unordered, so
+ * a verdict recorded in either slot order resolves correctly.
+ */
+export declare function tasteAgreement(pairs: TastePair[], verdicts: TasteVerdict[]): TasteAgreementResult;
+/**
+ * Generated-vs-reference metrics: how often a generated direction beats the
+ * single operator reference. `winsVsReference` counts the decisive comparisons
+ * the generated side won; `comparisons` counts the decisive comparisons that
+ * backed it. Ties, self-pairs, and verdicts not involving `referenceId` are
+ * excluded from `comparisons`, so the bench layer can form a clean Wilson
+ * interval `wilsonInterval(winsVsReference, comparisons)`. `corpusOrderAgreement`
+ * is intentionally left undefined here — it is a DIFFERENT verdict set
+ * (corpus-vs-corpus); the caller folds it in from `tasteAgreement`. Empty → 0
+ * wins / 0 comparisons, never NaN.
+ */
+export declare function tasteMetricsFromVerdicts(referenceId: string, verdicts: TasteVerdict[]): TasteMetrics;
+/**
+ * Position-bias rate from swapped runs. A run is DECISIVE when both slot orders
+ * named a winner; among decisive runs, the judge is position-biased on that run
+ * when the winning id flips with the slot (it picked the same physical slot both
+ * times — exactly the `reconcileVerdicts` "position bias → tie" branch, measured
+ * here as a rate). Runs where either order tied are excluded from `n`. Empty →
+ * `{ biasRate: 0, n: 0 }`, never NaN.
+ */
+export declare function positionBiasRate(runs: SwappedRun[]): PositionBiasResult;
+//# sourceMappingURL=taste-core.d.ts.map

package/dist/design/audit/reference/eval/taste-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"taste-core.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/eval/taste-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAEV,UAAU,EACV,oBAAoB,EACpB,YAAY,EACZ,SAAS,EACT,YAAY,EACb,MAAM,iBAAiB,CAAA;AAMxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAUxD;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,EAAE,EAAE,UAAU,CAAA;IACd,EAAE,EAAE,UAAU,CAAA;CACf;AAED,gEAAgE;AAChE,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,gFAAgF;IAChF,CAAC,EAAE,MAAM,CAAA;CACV;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,oBAAoB,CAIjG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,YAAY,CAWpG;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,kBAAkB,CAWvE"}

package/dist/design/audit/reference/eval/taste-core.js

@@ -0,0 +1,95 @@
+/**
+ * Taste-eval cores — the PURE bridge from debiased `TasteVerdict`s to the
+ * bench-layer taste metrics. Given verdicts (and the corpus ground-truth labels
+ * that produced them), these functions report how trustworthy the taste judge is
+ * and how the generated directions stack up against the operator reference.
+ *
+ * Everything here is pure and deterministic: NO IO, NO model, NO bench framework.
+ * The win-rate CIs (`wilsonInterval` / `bootstrapDiff95`) are computed at the
+ * bench layer from the raw counts these functions return — never re-implemented
+ * here — so this module stays a thin, framework-free numeric core.
+ *
+ * Tie-handling is uniform with the rest of the engine (`assessPageQuality`,
+ * `calibrateAgainstVotes`): a tie is never a win and never inflates a
+ * denominator, so every rate is a clean decisive proportion with integer
+ * `successes`/`n` the bench layer can hand straight to `wilsonInterval`.
+ */
+import { calibrateAgainstVotes } from '../judge/rank.js';
+// Re-export the human-vote calibration hook so the taste eval has a single
+// import surface. The implementation lives in judge/rank — one solver, no
+// duplicated agreement math.
+export { calibrateAgainstVotes } from '../judge/rank.js';
+const round4 = (n) => Math.round(n * 10000) / 10000;
+function slotToId(slot, idForSlotA, idForSlotB) {
+    if (slot === 'A')
+        return idForSlotA;
+    if (slot === 'B')
+        return idForSlotB;
+    return 'tie';
+}
+/**
+ * Judge-vs-label agreement over corpus-vs-corpus taste pairs. Each `TastePair`
+ * carries a known-stronger / known-weaker member (the ground-truth label); the
+ * judge agrees when its debiased verdict for that pair picks the stronger id.
+ * Ties (judge said tie) and pairs the judge never compared are excluded from
+ * `n`. Empty → `{ agreementRate: 0, n: 0 }`, never NaN.
+ *
+ * Reuses `calibrateAgainstVotes`: a corpus label IS exactly a human vote for the
+ * stronger id, so the same agreement walk applies — pair lookup is unordered, so
+ * a verdict recorded in either slot order resolves correctly.
+ */
+export function tasteAgreement(pairs, verdicts) {
+    const votes = pairs.map((p) => ({ aId: p.strongId, bId: p.weakId, winner: p.strongId }));
+    const { agreement, n } = calibrateAgainstVotes(verdicts, votes);
+    return { agreementRate: agreement, n };
+}
+/**
+ * Generated-vs-reference metrics: how often a generated direction beats the
+ * single operator reference. `winsVsReference` counts the decisive comparisons
+ * the generated side won; `comparisons` counts the decisive comparisons that
+ * backed it. Ties, self-pairs, and verdicts not involving `referenceId` are
+ * excluded from `comparisons`, so the bench layer can form a clean Wilson
+ * interval `wilsonInterval(winsVsReference, comparisons)`. `corpusOrderAgreement`
+ * is intentionally left undefined here — it is a DIFFERENT verdict set
+ * (corpus-vs-corpus); the caller folds it in from `tasteAgreement`. Empty → 0
+ * wins / 0 comparisons, never NaN.
+ */
+export function tasteMetricsFromVerdicts(referenceId, verdicts) {
+    let winsVsReference = 0;
+    let comparisons = 0;
+    for (const v of verdicts) {
+        if (v.aId === v.bId)
+            continue;
+        if (v.aId !== referenceId && v.bId !== referenceId)
+            continue;
+        if (v.winner === 'tie')
+            continue;
+        comparisons += 1;
+        if (v.winner !== referenceId)
+            winsVsReference += 1;
+    }
+    return { winsVsReference, comparisons };
+}
+/**
+ * Position-bias rate from swapped runs. A run is DECISIVE when both slot orders
+ * named a winner; among decisive runs, the judge is position-biased on that run
+ * when the winning id flips with the slot (it picked the same physical slot both
+ * times — exactly the `reconcileVerdicts` "position bias → tie" branch, measured
+ * here as a rate). Runs where either order tied are excluded from `n`. Empty →
+ * `{ biasRate: 0, n: 0 }`, never NaN.
+ */
+export function positionBiasRate(runs) {
+    let n = 0;
+    let biased = 0;
+    for (const run of runs) {
+        const w1 = slotToId(run.ab.winnerSlot, run.aId, run.bId);
+        const w2 = slotToId(run.ba.winnerSlot, run.bId, run.aId);
+        if (w1 === 'tie' || w2 === 'tie')
+            continue;
+        n += 1;
+        if (w1 !== w2)
+            biased += 1;
+    }
+    return { biasRate: n > 0 ? round4(biased / n) : 0, n };
+}
+//# sourceMappingURL=taste-core.js.map

package/dist/design/audit/reference/eval/taste-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"taste-core.js","sourceRoot":"","sources":["../../../../../src/design/audit/reference/eval/taste-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAUH,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAExD,2EAA2E;AAC3E,0EAA0E;AAC1E,6BAA6B;AAC7B,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAExD,MAAM,MAAM,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAA;AAEnE,SAAS,QAAQ,CAAC,IAA8B,EAAE,UAAkB,EAAE,UAAkB;IACtF,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,UAAU,CAAA;IACnC,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,UAAU,CAAA;IACnC,OAAO,KAAK,CAAA;AACd,CAAC;AA6BD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,KAAkB,EAAE,QAAwB;IACzE,MAAM,KAAK,GAAgB,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAA;IACrG,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,GAAG,qBAAqB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;IAC/D,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC,EAAE,CAAA;AACxC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CAAC,WAAmB,EAAE,QAAwB;IACpF,IAAI,eAAe,GAAG,CAAC,CAAA;IACvB,IAAI,WAAW,GAAG,CAAC,CAAA;IACnB,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG;YAAE,SAAQ;QAC7B,IAAI,CAAC,CAAC,GAAG,KAAK,WAAW,IAAI,CAAC,CAAC,GAAG,KAAK,WAAW;YAAE,SAAQ;QAC5D,IAAI,CAAC,CAAC,MAAM,KAAK,KAAK;YAAE,SAAQ;QAChC,WAAW,IAAI,CAAC,CAAA;QAChB,IAAI,CAAC,CAAC,MAAM,KAAK,WAAW;YAAE,eAAe,IAAI,CAAC,CAAA;IACpD,CAAC;IACD,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,CAAA;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAkB;IACjD,IAAI,CAAC,GAAG,CAAC,CAAA;IACT,IAAI,MAAM,GAAG,CAAC,CAAA;IACd,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,UAAU,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAA;QACxD,MAAM,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,UAAU,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAA;QACxD,IAAI,EAAE,KAAK,KAAK,IAAI,EAAE,KAAK,KAAK;YAAE,SAAQ;QAC1C,CAAC,IAAI,CAAC,CAAA;QACN,IAAI,EAAE,KAAK,EAAE;YAAE,MAAM,IAAI,CAAC,CAAA;IAC5B,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;AACxD,CAAC"}

package/dist/design/audit/reference/generate/generator.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Reference-grounded redesign generator — the LLM ADAPTER of the generative
+ * layer. Implements the `RedesignGenerator` contract.
+ *
+ * Responsibility is thin: for the top `count` retrieved exemplars it fans out
+ * one model call each (built by the pure `buildDirectionPrompt`), parses every
+ * response with the pure fail-closed `parseDirection`, streams each accepted
+ * direction through `onDirection`, and returns the directions in stable slot
+ * order. All grounding/prompt/parse decisions live in the pure cores; this file
+ * owns only the IO orchestration.
+ *
+ * Dependency injection: the model is supplied as a narrow `GenerationModel`
+ * callable, so the real `Brain` (which structurally satisfies it) is wired at
+ * the composition root while tests inject a deterministic mock — no model id is
+ * hard-coded here.
+ *
+ * Fan-out width is the direction `count` (2-3, budget-capped upstream by
+ * `engine/budget.planJudgeBudget`/`config.directionCount`), so the calls run
+ * fully in parallel via `Promise.allSettled` — no separate concurrency limiter
+ * is needed at this small, bounded width. A single failed or malformed call is
+ * dropped, never fatal and never fabricated.
+ */
+import type { RedesignGenerator } from '../contracts.js';
+/**
+ * The narrow model boundary this adapter depends on — exactly `Brain.complete`'s
+ * shape, so the concrete `Brain` is assignable and a stub is trivial to inject.
+ */
+export interface GenerationModel {
+    complete(system: string, user: string, options?: {
+        maxOutputTokens?: number;
+    }): Promise<{
+        text: string;
+        tokensUsed?: number;
+    }>;
+}
+/** Construction-time defaults for the generator adapter. */
+export interface BrainGeneratorOptions {
+    /** Default direction count when `generate` is called without one. */
+    count?: number;
+    /** Output-token cap per generation call (a full direction is large). */
+    maxOutputTokens?: number;
+    /** Forwarded to `buildDirectionPrompt` to bound injected DNA. */
+    maxRefChars?: number;
+}
+/**
+ * Build a `RedesignGenerator` backed by an injected `GenerationModel`.
+ */
+export declare function createBrainGenerator(brain: GenerationModel, opts?: BrainGeneratorOptions): RedesignGenerator;
+//# sourceMappingURL=generator.d.ts.map

package/dist/design/audit/reference/generate/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/generate/generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EAKlB,MAAM,iBAAiB,CAAA;AAIxB;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,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;AAED,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AA+CD;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,eAAe,EACtB,IAAI,GAAE,qBAA0B,GAC/B,iBAAiB,CA0CnB"}

package/dist/design/audit/reference/generate/generator.js

@@ -0,0 +1,94 @@
+/**
+ * Reference-grounded redesign generator — the LLM ADAPTER of the generative
+ * layer. Implements the `RedesignGenerator` contract.
+ *
+ * Responsibility is thin: for the top `count` retrieved exemplars it fans out
+ * one model call each (built by the pure `buildDirectionPrompt`), parses every
+ * response with the pure fail-closed `parseDirection`, streams each accepted
+ * direction through `onDirection`, and returns the directions in stable slot
+ * order. All grounding/prompt/parse decisions live in the pure cores; this file
+ * owns only the IO orchestration.
+ *
+ * Dependency injection: the model is supplied as a narrow `GenerationModel`
+ * callable, so the real `Brain` (which structurally satisfies it) is wired at
+ * the composition root while tests inject a deterministic mock — no model id is
+ * hard-coded here.
+ *
+ * Fan-out width is the direction `count` (2-3, budget-capped upstream by
+ * `engine/budget.planJudgeBudget`/`config.directionCount`), so the calls run
+ * fully in parallel via `Promise.allSettled` — no separate concurrency limiter
+ * is needed at this small, bounded width. A single failed or malformed call is
+ * dropped, never fatal and never fabricated.
+ */
+import { buildDirectionPrompt } from './prompt.js';
+import { parseDirection } from './parse.js';
+const DEFAULT_MAX_OUTPUT_TOKENS = 2200;
+const clampCount = (requested, available) => Math.max(0, Math.min(Math.floor(requested), available));
+async function generateOne(model, ctx, hit, slot, allowedIds, opts, reasons, onDirection) {
+    try {
+        const { system, user } = buildDirectionPrompt(ctx, hit, { maxRefChars: opts.maxRefChars });
+        const { text, tokensUsed } = await model.complete(system, user, {
+            maxOutputTokens: opts.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
+        });
+        // The call's tokens count toward cost even when its response fails to parse —
+        // a malformed completion still billed. Only a thrown call (caught below)
+        // reports nothing, because it never produced a usage figure.
+        const tokens = tokensUsed ?? 0;
+        const parsed = parseDirection(text, allowedIds);
+        if (!parsed.ok) {
+            reasons.push(`slot ${slot} parse failed (len=${text.length})`);
+            if (process.env.BAD_DEBUG_REFGEN)
+                console.error(`[refgen] slot ${slot} parse failed: ${JSON.stringify(parsed)} | len=${text.length} head=${JSON.stringify(text.slice(0, 240))}`);
+            return { direction: null, tokensUsed: tokens };
+        }
+        // Normalise the id to a deterministic, collision-free slot id — parallel
+        // calls share a prompt skeleton and may echo the same example id. The
+        // model's evocative `name` and grounding are preserved.
+        const direction = { ...parsed.direction, id: `direction-${slot + 1}` };
+        onDirection?.(direction);
+        return { direction, tokensUsed: tokens };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        reasons.push(`slot ${slot} call failed: ${message}`);
+        if (process.env.BAD_DEBUG_REFGEN)
+            console.error(`[refgen] slot ${slot} call failed: ${message}`);
+        return { direction: null, tokensUsed: 0 };
+    }
+}
+/**
+ * Build a `RedesignGenerator` backed by an injected `GenerationModel`.
+ */
+export function createBrainGenerator(brain, opts = {}) {
+    return {
+        async generate(ctx, exemplars, genOpts) {
+            const count = clampCount(genOpts?.count ?? opts.count ?? exemplars.length, exemplars.length);
+            const selected = exemplars.slice(0, count);
+            // Grounding is validated against the FULL retrieved set, so a direction may
+            // legitimately cite any retrieved exemplar, not only the one it was seeded
+            // with.
+            const allowedIds = exemplars.map((r) => r.exemplar.id);
+            // Per-call failure reasons collected here so a total wipeout reports WHY
+            // (e.g. an auth error) instead of a silent empty result downstream.
+            const reasons = [];
+            const settled = await Promise.allSettled(selected.map((hit, slot) => generateOne(brain, ctx, hit, slot, allowedIds, opts, reasons, genOpts?.onDirection)));
+            // Stable slot order; dropped (errored/rejected) calls simply leave a gap.
+            // Tokens accrue from EVERY completed call (parsed or not) so the cost the
+            // engine reports reflects what generation actually spent.
+            const directions = [];
+            let tokensUsed = 0;
+            for (const r of settled) {
+                if (r.status === 'fulfilled') {
+                    tokensUsed += r.value.tokensUsed;
+                    if (r.value.direction)
+                        directions.push(r.value.direction);
+                }
+            }
+            if (directions.length === 0 && selected.length > 0 && reasons.length > 0) {
+                console.warn(`[reference] all ${selected.length} redesign generation call(s) failed — first reason: ${reasons[0]}`);
+            }
+            return { directions, tokensUsed };
+        },
+    };
+}
+//# sourceMappingURL=generator.js.map

package/dist/design/audit/reference/generate/generator.js.map

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

package/dist/design/audit/reference/generate/parse.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Redesign-direction parser — a PURE core of the generative layer.
+ *
+ * `parseDirection` turns one raw model response into a typed `RedesignDirection`
+ * or a typed `DirectionParseError`. It is FAIL-CLOSED by construction: malformed
+ * JSON, a missing/ill-typed field, an ungrounded direction, or a hallucinated
+ * exemplar id all yield an explicit error — never a fabricated or half-built
+ * direction. The generator drops errored calls rather than inventing content.
+ *
+ * Hostile-input safe: the response is parsed with `JSON.parse` only (no eval),
+ * and the returned direction is assembled FIELD-BY-FIELD from validated values,
+ * so unexpected keys (including `__proto__`) never leak into the result and no
+ * prototype is mutated.
+ *
+ * No IO, no LLM, no browser — unit-tested on string fixtures alone.
+ */
+import type { RedesignDirection, DirectionParseResult } from '../contracts.js';
+/**
+ * Ids in `d.groundedInExemplarIds` that are NOT in `allowedIds` (the retrieved
+ * set). Empty ⇒ the direction is grounded only in real, retrieved exemplars.
+ */
+export declare function validateGrounding(d: RedesignDirection, allowedIds: string[]): string[];
+/**
+ * Parse one model response into a `RedesignDirection`. Fail-closed: any defect
+ * returns a `DirectionParseError`, never a partial or invented direction.
+ */
+export declare function parseDirection(raw: string, allowedIds: string[]): DirectionParseResult;
+//# sourceMappingURL=parse.d.ts.map

package/dist/design/audit/reference/generate/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/generate/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,oBAAoB,EAKrB,MAAM,iBAAiB,CAAA;AAgFxB;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAGtF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,oBAAoB,CAwDtF"}