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

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

@@ -0,0 +1,110 @@
+/**
+ * Engine budget accounting — the PURE home for all concurrency + judge-cost math.
+ *
+ * `planJudgeBudget` decides how many pairwise comparisons each leg can afford
+ * under an `EngineBudget`, and `mapWithConcurrency` runs independent async work
+ * with a bounded in-flight pool. Both are deterministic and IO/LLM-free so the
+ * orchestrator and the adapters stay thin — no module re-derives "how many calls
+ * can we afford" or hand-rolls a worker pool.
+ *
+ * Cost model (the single invariant every consumer relies on): one pairwise
+ * comparison is judged in BOTH slot orders (A/B then B/A) to debias position, so
+ * each comparison costs `2` judge calls per repetition. The total judge calls a
+ * plan implies is therefore:
+ *
+ *     (directionPairs + qualityPairs) × 2 × reps   ≤   budget.maxJudgeCalls
+ *
+ * `qualityPairs` folds in the per-`Dimension` expansion of the absolute quality
+ * leg: judging each of the `k` exemplars across `qualityDimensions` dimensions is
+ * `k × qualityDimensions` comparisons (or `k` overall-only comparisons when no
+ * dimension budget is affordable). When the full dimension set doesn't fit, the
+ * plan drops `qualityDimensions` to 0 — an honest overall-only leg — rather than
+ * fabricating per-dimension win-rates the budget never paid for.
+ */
+/** Both slot orders are judged per repetition to neutralise position bias. */
+const SLOT_ORDERS_PER_REP = 2;
+/** Unique unordered pairs over `n` items: C(n, 2). */
+function pairCount(n) {
+    if (!Number.isFinite(n) || n < 2)
+        return 0;
+    const k = Math.floor(n);
+    return (k * (k - 1)) / 2;
+}
+function nonNegInt(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    return Math.floor(n);
+}
+/**
+ * Plan the judge budget for one engine run.
+ *
+ * Preference order (richest → leanest), stopping at the first plan that fits
+ * `budget.maxJudgeCalls`:
+ *   1. full per-`Dimension` quality leg at the configured `judgeReps`,
+ *   2. overall-only quality leg at `judgeReps`, then walking reps down to 1.
+ * Dimensions are dropped before reps because a dimension-scoped leg is opt-in,
+ * whereas repetitions buy debiasing on every comparison. If even the leanest
+ * plan overflows (a pathologically small `maxJudgeCalls`), the pairs themselves
+ * are capped — direction pairs first (winner selection is the core artifact),
+ * then the overall quality pairs — so the returned plan never exceeds budget.
+ */
+export function planJudgeBudget(directionCount, k, budget, dimensions) {
+    const maxCalls = nonNegInt(budget.maxJudgeCalls);
+    const directionPairs = pairCount(directionCount);
+    const kk = nonNegInt(k);
+    const requestedDims = nonNegInt(dimensions ?? 0);
+    const repsFull = Math.max(1, nonNegInt(budget.judgeReps) || 1);
+    const qualityPairsFor = (qDims) => (qDims > 0 ? kk * qDims : kk);
+    const callsFor = (qDims, reps) => (directionPairs + qualityPairsFor(qDims)) * SLOT_ORDERS_PER_REP * reps;
+    // Candidate plans in strict preference order.
+    const candidates = [];
+    if (requestedDims > 0)
+        candidates.push({ qDims: requestedDims, reps: repsFull });
+    for (let reps = repsFull; reps >= 1; reps--)
+        candidates.push({ qDims: 0, reps });
+    for (const c of candidates) {
+        if (callsFor(c.qDims, c.reps) <= maxCalls) {
+            return {
+                directionPairs,
+                qualityPairs: qualityPairsFor(c.qDims),
+                reps: c.reps,
+                qualityDimensions: c.qDims,
+            };
+        }
+    }
+    // Nothing fits even at reps=1, overall-only: cap the pairs to whatever the
+    // budget allows, prioritising the direction (winner-selection) leg.
+    const affordablePairs = Math.floor(maxCalls / SLOT_ORDERS_PER_REP);
+    const cappedDirectionPairs = Math.min(directionPairs, affordablePairs);
+    const cappedQualityPairs = Math.min(kk, affordablePairs - cappedDirectionPairs);
+    return {
+        directionPairs: cappedDirectionPairs,
+        qualityPairs: cappedQualityPairs,
+        reps: 1,
+        qualityDimensions: 0,
+    };
+}
+/**
+ * Map `fn` over `items` with at most `n` calls in flight at once, preserving
+ * input order in the output. The first rejection propagates (in-flight siblings
+ * are not cancelled, mirroring `Promise.all`). A non-positive / non-finite `n`
+ * is treated as 1; concurrency never exceeds `items.length`.
+ */
+export async function mapWithConcurrency(items, n, fn) {
+    const results = new Array(items.length);
+    if (items.length === 0)
+        return results;
+    const limit = Math.max(1, Math.min(nonNegInt(n) || 1, items.length));
+    let next = 0;
+    async function worker() {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    }
+    await Promise.all(Array.from({ length: limit }, () => worker()));
+    return results;
+}
+//# sourceMappingURL=budget.js.map

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

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

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

@@ -0,0 +1,32 @@
+/**
+ * The single reference-grounded sequencer — ORCH, no domain logic of its own.
+ *
+ * `runRedesignCore` threads one page through the locked data flow (ARCHITECTURE
+ * §2): extract DNA → embed → retrieve → guard → generate → judge (absolute
+ * quality + relative direction legs) → rank → score → assemble artifact →
+ * project findings. EVERY decision is delegated to a pure core (`guard`,
+ * `budget`, `score-core`, `artifact/*`, `judge/*`, `dna/*`) or an injected
+ * boundary on `deps`; this file only orders the stages and shapes the inputs
+ * each stage already expects. It imports NO concrete IO/LLM adapter — those are
+ * supplied by `engine/wiring` at the composition root and arrive as the narrow
+ * `ReferenceEngineDeps` interfaces.
+ *
+ * Fail-closed, never fake-success:
+ *  - the `guard` aborts (throws its reason) when there is nothing to ground
+ *    against, so an ungrounded run can never masquerade as reference-grounded;
+ *  - a generator that yields zero directions throws rather than emitting an
+ *    empty artifact;
+ *  - `buildRedesignArtifact` throws on fabricated provenance.
+ *
+ * Acquire-once: the core retrieves against the pre-loaded `input.corpus` and
+ * NEVER calls `store.load()` — loading the corpus once per run is the
+ * entrypoint's job (it protects the ±0.5 reproducibility gate across pages/reps).
+ */
+import type { ReferenceEngineDeps, RedesignCoreInput, RedesignRunResult } from '../contracts.js';
+/**
+ * Run one page through the reference-grounded engine. Pure-ish: every impure
+ * boundary (browser extract, embed, LLM generate/judge, corpus disk) is reached
+ * only through the injected `deps`, so the whole sequencer unit-tests with fakes.
+ */
+export declare function runRedesignCore(deps: ReferenceEngineDeps, input: RedesignCoreInput): Promise<RedesignRunResult>;
+//# sourceMappingURL=core.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/engine/core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EAclB,MAAM,iBAAiB,CAAA;AA0BxB;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,mBAAmB,EACzB,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAoI5B"}

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

@@ -0,0 +1,261 @@
+/**
+ * The single reference-grounded sequencer — ORCH, no domain logic of its own.
+ *
+ * `runRedesignCore` threads one page through the locked data flow (ARCHITECTURE
+ * §2): extract DNA → embed → retrieve → guard → generate → judge (absolute
+ * quality + relative direction legs) → rank → score → assemble artifact →
+ * project findings. EVERY decision is delegated to a pure core (`guard`,
+ * `budget`, `score-core`, `artifact/*`, `judge/*`, `dna/*`) or an injected
+ * boundary on `deps`; this file only orders the stages and shapes the inputs
+ * each stage already expects. It imports NO concrete IO/LLM adapter — those are
+ * supplied by `engine/wiring` at the composition root and arrive as the narrow
+ * `ReferenceEngineDeps` interfaces.
+ *
+ * Fail-closed, never fake-success:
+ *  - the `guard` aborts (throws its reason) when there is nothing to ground
+ *    against, so an ungrounded run can never masquerade as reference-grounded;
+ *  - a generator that yields zero directions throws rather than emitting an
+ *    empty artifact;
+ *  - `buildRedesignArtifact` throws on fabricated provenance.
+ *
+ * Acquire-once: the core retrieves against the pre-loaded `input.corpus` and
+ * NEVER calls `store.load()` — loading the corpus once per run is the
+ * entrypoint's job (it protects the ±0.5 reproducibility gate across pages/reps).
+ */
+import { summarizeDNA } from '../dna/derive.js';
+import { aestheticDescriptor, structuralFeatures } from '../dna/descriptor.js';
+import { dnaDelta } from '../dna/delta.js';
+import { DEFAULT_RETRIEVE_WEIGHTS } from '../config.js';
+import { DIMENSIONS } from '../../score-types.js';
+import { planJudgeBudget, mapWithConcurrency } from './budget.js';
+import { decideProceed } from './guard.js';
+import { deriveHeadlineScore, toDimensionScores, toDesignSystemScore } from './score-core.js';
+import { assessPageQuality } from '../judge/quality.js';
+import { judgePair } from '../judge/pairwise.js';
+import { buildRedesignArtifact } from '../artifact/build.js';
+import { directionToFindings } from '../artifact/to-findings.js';
+// Stable id + seed rating for the synthetic exemplar minted from an operator
+// `--reference`. The reference "stands in for (or augments) corpus retrieval"
+// (contracts `ReferenceContext`): wrapping it as a `RetrievalResult` lets the
+// generator ground in it, the absolute quality leg compare against it, and the
+// artifact cite it — through the SAME shapes the corpus path already uses, so no
+// stage needs a reference-only code branch. `1500` mirrors the corpus seed elo
+// (corpus/build.SEED_ELO) without importing that L2 adapter into the core.
+const REFERENCE_EXEMPLAR_ID = 'reference';
+const REFERENCE_SEED_ELO = 1500;
+// Budget for the direction subject's spec dump fed to the judge.
+const DIRECTION_SUMMARY_MAX_CHARS = 1200;
+/**
+ * Run one page through the reference-grounded engine. Pure-ish: every impure
+ * boundary (browser extract, embed, LLM generate/judge, corpus disk) is reached
+ * only through the injected `deps`, so the whole sequencer unit-tests with fakes.
+ */
+export async function runRedesignCore(deps, input) {
+    const { config } = input;
+    // Token accounting: both LLM legs report their cost. The judge boundary
+    // surfaces `RawVerdict.tokensUsed` per comparison — wrap it once so every
+    // debias / quality call funnels into one counter. `RedesignGenerator.generate`
+    // surfaces the summed generation tokens (folded in below). Adding the two
+    // yields a COMPLETE `tokensUsed` (generation + judging), never a judge-only
+    // undercount.
+    let judgeTokens = 0;
+    const judge = {
+        id: deps.judge.id,
+        async compare(judgeInput) {
+            const verdict = await deps.judge.compare(judgeInput);
+            judgeTokens += verdict.tokensUsed ?? 0;
+            return verdict;
+        },
+    };
+    // 1. Page → DesignDNA (folds in the already-gathered measurement signals).
+    const { dna } = await deps.extractor.extract({ url: input.url, measurements: input.measurements });
+    // 2. DNA → authoritative aesthetic vector (embedded ONCE) + structural vector.
+    const vectors = await deps.embedder.embed([aestheticDescriptor(dna)]);
+    const aestheticVector = vectors[0] ?? [];
+    const query = {
+        pageType: input.classification.type,
+        jobToBeDone: input.classification.intent,
+        aestheticVector,
+        structuralVector: structuralFeatures(dna),
+    };
+    // 3. Retrieve k nearest exemplars; an operator reference is prepended as an
+    //    always-included grounding signal that augments the corpus hits.
+    const corpusHits = deps.matcher.retrieve(query, input.corpus, DEFAULT_RETRIEVE_WEIGHTS).slice(0, config.k);
+    const hits = config.reference
+        ? [referenceHit(config.reference, input.classification), ...corpusHits]
+        : corpusHits;
+    // 4. Fail-closed gate: nothing to ground against ⇒ abort with the reason.
+    const decision = decideProceed({
+        corpusSize: input.corpus.length,
+        retrieved: hits.length,
+        ...(config.reference ? { reference: config.reference } : {}),
+    });
+    if (!decision.ok)
+        throw new Error(decision.reason);
+    // 5. Generate the grounded redesign directions (concurrent inside the adapter).
+    const ctx = {
+        url: input.url,
+        classification: input.classification,
+        dna,
+        measurements: input.measurements,
+    };
+    const { directions, tokensUsed: generationTokens } = await deps.generator.generate(ctx, hits, {
+        count: config.directionCount,
+    });
+    if (directions.length === 0) {
+        throw new Error('reference engine: generator produced no redesign directions (all generation calls failed); ' +
+            'refusing to emit an empty reference-grounded artifact');
+    }
+    // Plan both judging legs from the ACTUAL direction count + retrieved exemplars.
+    const plan = planJudgeBudget(directions.length, hits.length, config.budget, DIMENSIONS.length);
+    const dimensions = plan.qualityDimensions > 0 ? DIMENSIONS.slice(0, plan.qualityDimensions) : [];
+    // 6. Judge legs run with overlap: the absolute quality leg (page vs exemplars)
+    //    and the relative direction-ranking leg are independent.
+    const pageSubject = {
+        id: 'page',
+        dnaSummary: summarizeDNA(dna),
+        ...(input.screenshotPath ? { screenshotPath: input.screenshotPath } : {}),
+    };
+    const exemplarSubjects = hits.map((hit) => exemplarSubject(hit, (e) => deps.store.resolveScreenshot(e)));
+    // Bound the quality leg to the exemplar count the budget actually paid for
+    // (qualityPairs already folds in the per-dimension expansion).
+    const qualityExemplarCount = Math.floor(plan.qualityPairs / Math.max(1, plan.qualityDimensions));
+    const qualityExemplars = exemplarSubjects.slice(0, Math.max(0, qualityExemplarCount));
+    const [quality, verdicts] = await Promise.all([
+        assessPageQuality(judge, pageSubject, qualityExemplars, dimensions.length > 0 ? { dimensions } : {}),
+        judgeDirectionLeg(judge, directions, plan.directionPairs, plan.reps, config.budget.concurrency, config.reference),
+    ]);
+    // Complete cost: judge tokens funnelled through the wrapped boundary above plus
+    // the generation tokens the generator summed. Both surfaces (artifact + result)
+    // report this total so neither undercounts to judge-only.
+    const tokensUsed = judgeTokens + generationTokens;
+    // 7. Roll the relative verdicts up into a winner.
+    const ranking = deps.ranker.rank(directions.map((d) => d.id), verdicts);
+    // 8. Single scoring authority: every surface derives from `quality`.
+    const headlineScore = deriveHeadlineScore(quality, input.measurements);
+    const dimensionScores = toDimensionScores(quality);
+    const designSystemScore = toDesignSystemScore(quality);
+    // 9. Assemble the rich artifact (winner first) + project the v1 findings.
+    const referenceId = config.reference ? REFERENCE_EXEMPLAR_ID : undefined;
+    const artifact = buildRedesignArtifact({
+        url: input.url,
+        directions,
+        ranking,
+        retrieval: hits,
+        verdicts,
+        tokensUsed,
+        ...(referenceId ? { referenceId } : {}),
+    });
+    const winner = artifact.directions[0];
+    if (!winner)
+        throw new Error('reference engine: ranking produced no winning direction');
+    const gapTarget = resolveGapTarget(config.reference, winner, hits, dna);
+    const findings = directionToFindings(winner, dnaDelta(dna, gapTarget), input.measurements, dna, hits);
+    return {
+        artifact,
+        quality,
+        headlineScore,
+        dimensionScores,
+        designSystemScore,
+        findings,
+        classification: input.classification,
+        measurements: input.measurements,
+        tokensUsed,
+    };
+}
+/**
+ * The relative leg: judge unique direction pairs (bounded by the budget plan)
+ * against the named reference, position-debiased, run with bounded concurrency.
+ */
+async function judgeDirectionLeg(judge, directions, maxPairs, reps, concurrency, reference) {
+    const subjects = directions.map(directionSubject);
+    const pairs = [];
+    for (let i = 0; i < directions.length; i++) {
+        for (let j = i + 1; j < directions.length; j++)
+            pairs.push([i, j]);
+    }
+    const planned = pairs.slice(0, Math.max(0, maxPairs));
+    return mapWithConcurrency(planned, concurrency, ([i, j]) => judgePair(judge, {
+        a: subjects[i],
+        b: subjects[j],
+        ...(reference ? { reference } : {}),
+    }, reps));
+}
+/**
+ * A retrieved exemplar as a judge subject (DNA spec dump, optional screenshot).
+ * The corpus stores `screenshotPath` RELATIVE to the corpus dir, so it is resolved
+ * to an absolute path through the store before reaching a vision judge that reads
+ * it off disk; the reference hit's already-absolute path passes through unchanged.
+ * Byte-neutral for the text judge, which never reads the field.
+ */
+function exemplarSubject(hit, resolveScreenshot) {
+    const screenshotPath = resolveScreenshot(hit.exemplar);
+    return {
+        id: hit.exemplar.id,
+        dnaSummary: summarizeDNA(hit.exemplar.dna),
+        ...(screenshotPath ? { screenshotPath } : {}),
+    };
+}
+/**
+ * A generated direction as a judge subject: evocative headline + spec dump. NO
+ * `screenshotPath` — directions are unrendered specs, so the direction-ranking
+ * leg stays text-only (a vision judge falls back to text here). Future lever:
+ * render each direction to a screenshot to make this leg vision-judgeable too.
+ */
+function directionSubject(direction) {
+    return {
+        id: direction.id,
+        directionSummary: `${direction.name} — ${direction.rationale}`,
+        dnaSummary: summarizeDirectionSpec(direction),
+    };
+}
+/**
+ * A compact, budget-bounded summary of a direction's PROPOSED systems for the
+ * judge. Renders the spec (type/colour/motion/hierarchy) the direction defines —
+ * NOT an extracted DNA, which a not-yet-built redesign has none of.
+ */
+function summarizeDirectionSpec(d) {
+    const t = d.typeSystem;
+    const c = d.colorSystem;
+    const m = d.motionSpec;
+    const lines = [
+        `type: families ${t.families.join(' ') || 'system'}; scale ${t.scalePx.join('/') || 'n/a'}px; ratio ~${t.ratio}×`,
+        `colour: primary ${c.primary}${c.accent ? `, accent ${c.accent}` : ''}, background ${c.background}, neutrals ${c.neutrals.join(' ') || 'n/a'}`,
+        `motion: ${m.durationsMs.join('/') || 'none'}ms ${m.easings.join(' ') || 'no-easing'}${m.cues.length ? `; ${m.cues.join('; ')}` : ''}`,
+        `hierarchy: ${d.hierarchy.join(' → ') || 'n/a'}`,
+    ];
+    const body = lines.join('\n');
+    return body.length > DIRECTION_SUMMARY_MAX_CHARS ? `${body.slice(0, DIRECTION_SUMMARY_MAX_CHARS - 1)}…` : body;
+}
+/**
+ * The DNA the winner is measured AGAINST when minting the gap findings. Prefers
+ * the explicit operator reference, then the winner's first grounding exemplar,
+ * then the top retrieved exemplar, and finally the page itself (a zero delta) so
+ * a finding set is always produced rather than a crash.
+ */
+function resolveGapTarget(reference, winner, hits, current) {
+    if (reference)
+        return reference.dna;
+    const groundedId = winner.groundedInExemplarIds[0];
+    const grounded = groundedId ? hits.find((h) => h.exemplar.id === groundedId) : undefined;
+    return grounded?.exemplar.dna ?? hits[0]?.exemplar.dna ?? current;
+}
+/**
+ * Wrap an operator reference as a synthetic `RetrievalResult` so it flows through
+ * the same generate / judge / artifact stages as a corpus exemplar.
+ */
+function referenceHit(reference, classification) {
+    const exemplar = {
+        id: REFERENCE_EXEMPLAR_ID,
+        source: 'manual',
+        url: reference.dna.url,
+        pageType: classification.type,
+        jobToBeDone: classification.intent,
+        dna: reference.dna,
+        screenshotPath: reference.screenshotPath ?? '',
+        aestheticVector: [],
+        eloRating: REFERENCE_SEED_ELO,
+    };
+    return { exemplar, score: 1, reasons: [`operator reference (${reference.kind})`] };
+}
+//# sourceMappingURL=core.js.map

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

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

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

@@ -0,0 +1,43 @@
+/**
+ * Fail-closed proceed/abort guard — the PURE gate that keeps the engine from
+ * shipping a default-looking run mislabelled as reference-grounded.
+ *
+ * A reference-grounded run is only meaningful when it has something concrete to
+ * ground against: at least one retrieved exemplar, OR an operator-supplied
+ * `--reference`. With neither, `decideProceed` returns an explicit abort reason
+ * instead of letting the engine emit an ungrounded artifact that pretends to be
+ * reference-grounded. There is no fabricated success path here — an absent
+ * signal is treated as a blocker, never silently as "passed".
+ *
+ * Pure and deterministic: no IO, no LLM, no clock.
+ */
+import type { ReferenceContext } from '../contracts.js';
+/** Inputs to the proceed decision. All counts are post-retrieval. */
+export interface GuardInput {
+    /** Number of exemplars loaded into the in-memory corpus for this run. */
+    corpusSize: number;
+    /** Number of exemplars the matcher actually retrieved for this page. */
+    retrieved: number;
+    /** Operator-supplied reference, resolved once; stands in for the corpus. */
+    reference?: ReferenceContext;
+}
+/**
+ * Discriminated result: proceed, or abort with a human-readable reason. The
+ * reason is surfaced to the operator and recorded — never swallowed.
+ */
+export type ProceedDecision = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Decide whether a reference-grounded run may proceed.
+ *
+ * An operator reference short-circuits to `ok` (it is itself the grounding
+ * target, so an empty corpus is fine). Otherwise both a non-empty corpus AND a
+ * non-empty retrieval are required; either being empty is a terminal blocker
+ * with a distinct reason so the operator knows which precondition failed.
+ */
+export declare function decideProceed(input: GuardInput): ProceedDecision;
+//# sourceMappingURL=guard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/engine/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAEvD,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAA;IAClB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAA;IACjB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,gBAAgB,CAAA;CAC7B;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAO1E;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,eAAe,CAoBhE"}

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

@@ -0,0 +1,43 @@
+/**
+ * Fail-closed proceed/abort guard — the PURE gate that keeps the engine from
+ * shipping a default-looking run mislabelled as reference-grounded.
+ *
+ * A reference-grounded run is only meaningful when it has something concrete to
+ * ground against: at least one retrieved exemplar, OR an operator-supplied
+ * `--reference`. With neither, `decideProceed` returns an explicit abort reason
+ * instead of letting the engine emit an ungrounded artifact that pretends to be
+ * reference-grounded. There is no fabricated success path here — an absent
+ * signal is treated as a blocker, never silently as "passed".
+ *
+ * Pure and deterministic: no IO, no LLM, no clock.
+ */
+/** A finite, strictly-positive count. Non-finite / negative ⇒ treated as zero. */
+function positive(n) {
+    return Number.isFinite(n) && n > 0;
+}
+/**
+ * Decide whether a reference-grounded run may proceed.
+ *
+ * An operator reference short-circuits to `ok` (it is itself the grounding
+ * target, so an empty corpus is fine). Otherwise both a non-empty corpus AND a
+ * non-empty retrieval are required; either being empty is a terminal blocker
+ * with a distinct reason so the operator knows which precondition failed.
+ */
+export function decideProceed(input) {
+    if (input.reference)
+        return { ok: true };
+    if (!positive(input.corpusSize)) {
+        return {
+            ok: false,
+            reason: 'reference-grounded run requires a non-empty exemplar corpus or a --reference; the corpus is empty',
+        };
+    }
+    if (!positive(input.retrieved)) {
+        return {
+            ok: false,
+            reason: 'reference-grounded run retrieved 0 exemplars for this page type and no --reference was supplied; nothing to ground against',
+        };
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=guard.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../../../../../src/design/audit/reference/engine/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAoBH,kFAAkF;AAClF,SAAS,QAAQ,CAAC,CAAS;IACzB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,IAAI,KAAK,CAAC,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;IAExC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;QAChC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,mGAAmG;SACtG,CAAA;IACH,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QAC/B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,4HAA4H;SAC/H,CAAA;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;AACrB,CAAC"}

package/dist/design/audit/reference/engine/score-core.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 type { QualityAssessment, MeasurementBundle, Dimension, DimensionScore, DesignSystemScore } from '../contracts.js';
+/**
+ * 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 declare function deriveHeadlineScore(quality: QualityAssessment, measurements: MeasurementBundle): number;
+/**
+ * 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 declare function toDimensionScores(quality: QualityAssessment): Record<Dimension, DimensionScore>;
+/**
+ * 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 declare function toDesignSystemScore(quality: QualityAssessment): DesignSystemScore;
+//# sourceMappingURL=score-core.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"score-core.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/engine/score-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EACT,cAAc,EACd,iBAAiB,EAClB,MAAM,iBAAiB,CAAA;AA8BxB;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,iBAAiB,EAC1B,YAAY,EAAE,iBAAiB,GAC9B,MAAM,CAMR;AAyCD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,iBAAiB,GACzB,MAAM,CAAC,SAAS,EAAE,cAAc,CAAC,CAWnC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,iBAAiB,CAYjF"}