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

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

@@ -0,0 +1,110 @@
+/**
+ * Brain-backed vision-model adapter — the IO half of the vision judge stack.
+ *
+ * The vision ensemble depends only on the narrow `VisionJudgeModel` seam
+ * (contracts): a model bound to ONE `{ provider, model }` ref that takes a system
+ * prompt + a user prompt + the compared subjects' screenshots and returns raw
+ * text. This module is the concrete, Brain-backed implementation of that seam.
+ * It is the ONLY impure part of the vision judge (disk read + a live model call);
+ * the aggregation in `vision-judge.ts` stays pure and unit-tests with stubs.
+ *
+ * Two responsibilities, both thin:
+ *  - `createBrainVisionModel`: wrap one Brain as a `VisionJudgeModel` — resolve
+ *    each `VisionImageRef` to encoded bytes (disk read for `screenshotPath`,
+ *    mediaType from the file extension; passthrough for in-memory base64) and
+ *    route them through `brain.completeVision`. The `id` is the ref rendered as
+ *    `provider:model`, so an ensemble keys/aggregates per model.
+ *  - `buildVisionModels`: construct the ensemble from a `ModelRef[]` — ONE Brain
+ *    per ref, each with its OWN provider key. A single Brain CANNOT serve a mixed
+ *    ensemble: `Brain.getModel` resolves the key via
+ *    `resolveProviderApiKey(provider, this.explicitApiKey)`, so an explicit key
+ *    set for one provider would leak to the others. Per-ref Brains give each ref
+ *    the correct provider key (resolved from the environment).
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { Brain } from '../../../../brain/index.js';
+import { clampPngLongestEdge } from './image-clamp.js';
+import { resolveDefaultProvider, resolveProviderApiKey, resolveProviderModelName, } from '../../../../provider-defaults.js';
+/** Render a `ModelRef` as the stable `provider:model` id the ensemble keys on. */
+export function refToId(ref) {
+    return `${ref.provider ?? resolveDefaultProvider()}:${ref.model}`;
+}
+/** Infer an image mediaType from a screenshot file extension (PNG default). */
+function mediaTypeForPath(p) {
+    const ext = path.extname(p).toLowerCase();
+    if (ext === '.jpg' || ext === '.jpeg')
+        return 'image/jpeg';
+    if (ext === '.webp')
+        return 'image/webp';
+    if (ext === '.gif')
+        return 'image/gif';
+    return 'image/png';
+}
+/**
+ * Resolve a `VisionImageRef` to encoded bytes (disk read for on-disk paths).
+ * Full-page PNG captures are clamped to the vision API's longest-edge limit first
+ * (see {@link clampPngLongestEdge}) — without it, a tall exemplar screenshot trips
+ * Anthropic's 8000px hard limit and the whole comparison fails. The clamp is a
+ * no-op for in-bounds images and for non-PNG bytes, so it never alters a small
+ * screenshot.
+ */
+async function resolveImage(ref) {
+    if ('base64' in ref) {
+        if (ref.mediaType !== 'image/png')
+            return { image: ref.base64, mediaType: ref.mediaType };
+        const clamped = clampPngLongestEdge(Buffer.from(ref.base64, 'base64'));
+        return { image: clamped.toString('base64'), mediaType: ref.mediaType };
+    }
+    const mediaType = mediaTypeForPath(ref.screenshotPath);
+    const buf = await readFile(ref.screenshotPath);
+    const bytes = mediaType === 'image/png' ? clampPngLongestEdge(buf) : buf;
+    return { image: bytes.toString('base64'), mediaType };
+}
+/**
+ * Wrap one Brain (already bound to a `{ provider, model }`) as a
+ * `VisionJudgeModel`. The disk read + mediaType inference happen here so the
+ * pure ensemble never touches the filesystem; a failed read or model call
+ * propagates as a rejection, which the ensemble treats as a DROPPED model.
+ */
+export function createBrainVisionModel(brain, ref) {
+    return {
+        id: refToId(ref),
+        async completeVision(system, user, images, options) {
+            const encoded = await Promise.all(images.map(resolveImage));
+            return brain.completeVision(system, user, encoded, options);
+        },
+    };
+}
+/**
+ * Construct the vision ensemble: ONE Brain per `ModelRef`, each resolving its own
+ * provider/model/api-key through `provider-defaults` (so a mixed
+ * openai+anthropic+google ensemble each gets the right env key). `vision: true`
+ * is set for clarity; `completeVision` builds its own multimodal message and does
+ * not depend on the Brain's vision strategy.
+ *
+ * Future lever: explicit per-vision-model `--api-key`/`--base-url` (today each ref
+ * resolves its key from the environment by provider; the audit's own brain still
+ * honours an explicit `--api-key`).
+ */
+export function buildVisionModels(refs) {
+    return refs.map((ref) => {
+        const provider = ref.provider ?? resolveDefaultProvider();
+        const model = resolveProviderModelName(provider, ref.model);
+        const brain = new Brain({
+            provider,
+            model,
+            apiKey: resolveProviderApiKey(provider),
+            vision: true,
+            // The Claude Code SDK drops image parts unless streaming input is on; these
+            // Brains exist only to send screenshots, so force it. No-op for every other
+            // provider, so a mixed ensemble is unaffected.
+            claudeCodeStreamingInput: true,
+            // Opt-in per-call provider logging for diagnosing dropped vision verdicts.
+            debug: process.env.BAD_VISION_JUDGE_DEBUG === '1',
+            llmTimeoutMs: 120_000,
+        });
+        return createBrainVisionModel(brain, { provider, model });
+    });
+}
+//# sourceMappingURL=vision-model.js.map

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

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

package/dist/design/audit/reference/pipeline/evaluate-reference.d.ts

@@ -0,0 +1,68 @@
+/**
+ * L4 entrypoint — the flagged STAGE-6 replacement. ORCH: it runs the ONE shared
+ * core and maps its result onto the EXISTING `PageAuditResult` contract so the
+ * reference-grounded path drops into the v1 pipeline and stages 7-9 run unchanged.
+ *
+ * It is the sibling of `run.ts`: the SAME `engine/core.runRedesignCore`, a
+ * different return-shaping. Where `run.ts` surfaces the rich `RedesignArtifact`,
+ * this maps `RedesignRunResult` → `PageAuditResult` via the pure
+ * `artifact/to-findings.toReferencePageAuditResult` — never a second scoring pass.
+ *
+ * Acquire-once is honoured by the CALLER: the pipeline loads the corpus and
+ * resolves the reference ONCE above the page/rep loops and threads them in
+ * (`input.corpus`, `input.reference`), so this entry never reads the corpus from
+ * disk and the core never calls `store.load()`.
+ */
+import type { PageClassification, MeasurementBundle, ReferenceContext, ReferenceGroundedConfig, PageAuditResult, Exemplar, ReferenceEngineDeps, Dimension, DimensionScore, RedesignArtifact } from '../contracts.js';
+import { type ReferenceBrain } from '../engine/wiring.js';
+/**
+ * Per-page input for {@link evaluateReferenceGrounded}. `corpus` and `config` are
+ * the once-acquired values threaded down from the pipeline; `reference` is the
+ * once-resolved operator reference (when one was supplied).
+ */
+export interface EvaluateReferenceInput {
+    url: string;
+    classification: PageClassification;
+    measurements: MeasurementBundle;
+    /** Page screenshot, carried onto the result and reserved for a future vision judge. */
+    screenshotPath?: string;
+    /** Operator reference resolved once upstream; folded into `config.reference`. */
+    reference?: ReferenceContext;
+    /** The exemplar corpus, loaded ONCE per run by the pipeline and reused across pages/reps. */
+    corpus: Exemplar[];
+    /** The resolved engine config (the pipeline supplies a fully-resolved bundle). */
+    config: ReferenceGroundedConfig;
+}
+/**
+ * The result of one reference-grounded page evaluation.
+ *
+ * `result` is the `PageAuditResult` stages 7-9 consume; its `score` is the single
+ * headline authority. `dimensionScores` is the engine's per-`Dimension` surface,
+ * surfaced HERE so the pipeline can hand it to stage-8's `buildAuditResult` as
+ * `precomputedScores` — skipping the redundant `brain.auditDesign` scoring pass so
+ * there is exactly ONE scoring authority and no second multidim LLM call.
+ */
+export interface ReferenceEvaluation {
+    result: PageAuditResult;
+    dimensionScores: Record<Dimension, DimensionScore>;
+    /**
+     * The rich engine output (all ranked directions with ASCII layout, type/colour/
+     * motion systems, hierarchy, copy). Carried here so the CLI can surface the full
+     * redesign brief instead of the lossy `DesignFinding` projection. The lossy
+     * `PageAuditResult.findings` projection alone cannot represent it.
+     */
+    artifact: RedesignArtifact;
+}
+/**
+ * Evaluate one page in reference-grounded mode. Returns a `ReferenceEvaluation`:
+ * the `PageAuditResult` (whose `score`, `summary`, `strengths`, `findings`, and
+ * `designSystemScore` come from the single quality authority via
+ * `toReferencePageAuditResult`) plus the engine's `dimensionScores` for the
+ * stage-8 `precomputedScores` hook.
+ *
+ * `deps` defaults to the production composition root (`buildDefaultDeps`); it is
+ * injectable only so the wiring unit-tests with deterministic fakes (no browser,
+ * no live LLM). The pipeline never passes it.
+ */
+export declare function evaluateReferenceGrounded(brain: ReferenceBrain, input: EvaluateReferenceInput, deps?: ReferenceEngineDeps): Promise<ReferenceEvaluation>;
+//# sourceMappingURL=evaluate-reference.d.ts.map

package/dist/design/audit/reference/pipeline/evaluate-reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate-reference.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/pipeline/evaluate-reference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,QAAQ,EACR,mBAAmB,EACnB,SAAS,EACT,cAAc,EACd,gBAAgB,EACjB,MAAM,iBAAiB,CAAA;AAExB,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAI3E;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,cAAc,EAAE,kBAAkB,CAAA;IAClC,YAAY,EAAE,iBAAiB,CAAA;IAC/B,uFAAuF;IACvF,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,iFAAiF;IACjF,SAAS,CAAC,EAAE,gBAAgB,CAAA;IAC5B,6FAA6F;IAC7F,MAAM,EAAE,QAAQ,EAAE,CAAA;IAClB,kFAAkF;IAClF,MAAM,EAAE,uBAAuB,CAAA;CAChC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,eAAe,CAAA;IACvB,eAAe,EAAE,MAAM,CAAC,SAAS,EAAE,cAAc,CAAC,CAAA;IAClD;;;;;OAKG;IACH,QAAQ,EAAE,gBAAgB,CAAA;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,sBAAsB,EAC7B,IAAI,CAAC,EAAE,mBAAmB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAuB9B"}

package/dist/design/audit/reference/pipeline/evaluate-reference.js

@@ -0,0 +1,52 @@
+/**
+ * L4 entrypoint — the flagged STAGE-6 replacement. ORCH: it runs the ONE shared
+ * core and maps its result onto the EXISTING `PageAuditResult` contract so the
+ * reference-grounded path drops into the v1 pipeline and stages 7-9 run unchanged.
+ *
+ * It is the sibling of `run.ts`: the SAME `engine/core.runRedesignCore`, a
+ * different return-shaping. Where `run.ts` surfaces the rich `RedesignArtifact`,
+ * this maps `RedesignRunResult` → `PageAuditResult` via the pure
+ * `artifact/to-findings.toReferencePageAuditResult` — never a second scoring pass.
+ *
+ * Acquire-once is honoured by the CALLER: the pipeline loads the corpus and
+ * resolves the reference ONCE above the page/rep loops and threads them in
+ * (`input.corpus`, `input.reference`), so this entry never reads the corpus from
+ * disk and the core never calls `store.load()`.
+ */
+import { runRedesignCore } from '../engine/core.js';
+import { buildDefaultDeps } from '../engine/wiring.js';
+import { toReferencePageAuditResult } from '../artifact/to-findings.js';
+import { writeArtifact } from '../artifact/render.js';
+/**
+ * Evaluate one page in reference-grounded mode. Returns a `ReferenceEvaluation`:
+ * the `PageAuditResult` (whose `score`, `summary`, `strengths`, `findings`, and
+ * `designSystemScore` come from the single quality authority via
+ * `toReferencePageAuditResult`) plus the engine's `dimensionScores` for the
+ * stage-8 `precomputedScores` hook.
+ *
+ * `deps` defaults to the production composition root (`buildDefaultDeps`); it is
+ * injectable only so the wiring unit-tests with deterministic fakes (no browser,
+ * no live LLM). The pipeline never passes it.
+ */
+export async function evaluateReferenceGrounded(brain, input, deps) {
+    // The core grounds against `config.reference`, never a separate field, so fold
+    // the once-resolved reference into the config the core reads.
+    const config = input.reference
+        ? { ...input.config, reference: input.reference }
+        : input.config;
+    const resolvedDeps = deps ?? buildDefaultDeps(brain, config);
+    const result = await runRedesignCore(resolvedDeps, {
+        url: input.url,
+        classification: input.classification,
+        measurements: input.measurements,
+        ...(input.screenshotPath ? { screenshotPath: input.screenshotPath } : {}),
+        corpus: input.corpus,
+        config,
+    });
+    if (config.artifactDir)
+        await writeArtifact(result.artifact, config.artifactDir);
+    const audit = toReferencePageAuditResult(result);
+    const withShot = input.screenshotPath ? { ...audit, screenshotPath: input.screenshotPath } : audit;
+    return { result: withShot, dimensionScores: result.dimensionScores, artifact: result.artifact };
+}
+//# sourceMappingURL=evaluate-reference.js.map

package/dist/design/audit/reference/pipeline/evaluate-reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate-reference.js","sourceRoot":"","sources":["../../../../../src/design/audit/reference/pipeline/evaluate-reference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAcH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,gBAAgB,EAAuB,MAAM,qBAAqB,CAAA;AAC3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAA;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AA0CrD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,KAAqB,EACrB,KAA6B,EAC7B,IAA0B;IAE1B,+EAA+E;IAC/E,8DAA8D;IAC9D,MAAM,MAAM,GAA4B,KAAK,CAAC,SAAS;QACrD,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE;QACjD,CAAC,CAAC,KAAK,CAAC,MAAM,CAAA;IAEhB,MAAM,YAAY,GAAG,IAAI,IAAI,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAE5D,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,YAAY,EAAE;QACjD,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,GAAG,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzE,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,MAAM;KACP,CAAC,CAAA;IAEF,IAAI,MAAM,CAAC,WAAW;QAAE,MAAM,aAAa,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,WAAW,CAAC,CAAA;IAEhF,MAAM,KAAK,GAAG,0BAA0B,CAAC,MAAM,CAAC,CAAA;IAChD,MAAM,QAAQ,GAAG,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,KAAK,CAAA;IAClG,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,CAAC,eAAe,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAA;AACjG,CAAC"}

package/dist/design/audit/reference/reference-context.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Reference resolution adapter — turn the operator's `--reference <url|path>`
+ * into a resolved `ReferenceContext` ONCE, fail-closed.
+ *
+ * It owns the SINGLE IO seam (a live URL or a ripped local copy → `DesignDNA`)
+ * by delegating to an injected `DesignDnaExtractor`; it adds zero extraction
+ * logic of its own and the DNA→summary fold reuses the pure `summarizeDNA`, so
+ * it unit-tests against a deterministic fake extractor with no live browser or
+ * network. Per ARCHITECTURE §9 D3 it lives in its own small module — not the fat
+ * orchestrator — so both the CLI plumbing and tests reach it directly.
+ *
+ * Fail-closed: an unresolvable reference throws an explicit error rather than
+ * degrading to a fabricated "neutral" reference that would silently mis-ground.
+ */
+import type { DesignDnaExtractor, ReferenceContext } from './contracts.js';
+/** The single dependency the resolver injects — the page→DNA extractor seam. */
+export interface ResolveReferenceDeps {
+    extractor: DesignDnaExtractor;
+}
+/** Browser/IO knobs forwarded to the extractor for the reference capture. */
+export interface ResolveReferenceOptions {
+    headless?: boolean;
+    outputDir?: string;
+}
+/**
+ * Resolve `--reference` into a `ReferenceContext` exactly once. Returns
+ * `undefined` when no reference was supplied (the engine then grounds against
+ * the corpus alone); throws when a supplied reference cannot be captured.
+ */
+export declare function resolveReferenceContext(ref: string | undefined, deps: ResolveReferenceDeps, opts?: ResolveReferenceOptions): Promise<ReferenceContext | undefined>;
+//# sourceMappingURL=reference-context.d.ts.map

package/dist/design/audit/reference/reference-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-context.d.ts","sourceRoot":"","sources":["../../../../src/design/audit/reference/reference-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAiB,MAAM,gBAAgB,CAAA;AAGzF,gFAAgF;AAChF,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,kBAAkB,CAAA;CAC9B;AAED,6EAA6E;AAC7E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA6BD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,IAAI,EAAE,oBAAoB,EAC1B,IAAI,GAAE,uBAA4B,GACjC,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAoBvC"}

package/dist/design/audit/reference/reference-context.js

@@ -0,0 +1,73 @@
+/**
+ * Reference resolution adapter — turn the operator's `--reference <url|path>`
+ * into a resolved `ReferenceContext` ONCE, fail-closed.
+ *
+ * It owns the SINGLE IO seam (a live URL or a ripped local copy → `DesignDNA`)
+ * by delegating to an injected `DesignDnaExtractor`; it adds zero extraction
+ * logic of its own and the DNA→summary fold reuses the pure `summarizeDNA`, so
+ * it unit-tests against a deterministic fake extractor with no live browser or
+ * network. Per ARCHITECTURE §9 D3 it lives in its own small module — not the fat
+ * orchestrator — so both the CLI plumbing and tests reach it directly.
+ *
+ * Fail-closed: an unresolvable reference throws an explicit error rather than
+ * degrading to a fabricated "neutral" reference that would silently mis-ground.
+ */
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { summarizeDNA } from './dna/derive.js';
+const HTTP_RE = /^https?:\/\//i;
+/**
+ * Classify a `--reference` argument into a `ReferenceKind` and the URL the
+ * extractor consumes. A live `http(s)` ref is a `url`; any other value is a
+ * `rip` (a previously ripped local copy) addressed as a `file://` URL so the
+ * same extractor handles both. A relative path is resolved against the cwd.
+ */
+function classifyReference(ref) {
+    if (HTTP_RE.test(ref))
+        return { kind: 'url', url: ref };
+    if (ref.startsWith('file://'))
+        return { kind: 'rip', url: ref };
+    const abs = path.isAbsolute(ref) ? ref : path.resolve(ref);
+    return { kind: 'rip', url: pathToFileURL(abs).href };
+}
+/**
+ * Prefer the desktop capture; otherwise any captured viewport, else none.
+ * Returned ABSOLUTE so a downstream consumer (e.g. the vision judge reading the
+ * screenshot off disk) resolves it independent of the process cwd — the
+ * extractor yields a path relative to its outputDir.
+ */
+function firstScreenshot(paths) {
+    const p = paths['desktop'] ?? Object.values(paths)[0];
+    if (!p)
+        return undefined;
+    return path.isAbsolute(p) ? p : path.resolve(p);
+}
+/**
+ * Resolve `--reference` into a `ReferenceContext` exactly once. Returns
+ * `undefined` when no reference was supplied (the engine then grounds against
+ * the corpus alone); throws when a supplied reference cannot be captured.
+ */
+export async function resolveReferenceContext(ref, deps, opts = {}) {
+    if (!ref)
+        return undefined;
+    const { kind, url } = classifyReference(ref);
+    let capture;
+    try {
+        capture = await deps.extractor.extract({
+            url,
+            ...(opts.headless !== undefined ? { headless: opts.headless } : {}),
+            ...(opts.outputDir ? { outputDir: opts.outputDir } : {}),
+        });
+    }
+    catch (err) {
+        throw new Error(`--reference could not be resolved (${ref}): ${err.message}`);
+    }
+    const screenshotPath = firstScreenshot(capture.screenshotPaths);
+    return {
+        kind,
+        dna: capture.dna,
+        summary: summarizeDNA(capture.dna),
+        ...(screenshotPath ? { screenshotPath } : {}),
+    };
+}
+//# sourceMappingURL=reference-context.js.map

package/dist/design/audit/reference/reference-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-context.js","sourceRoot":"","sources":["../../../../src/design/audit/reference/reference-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAa9C,MAAM,OAAO,GAAG,eAAe,CAAA;AAE/B;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,GAAW;IACpC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,CAAA;IACvD,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,CAAA;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC1D,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAA;AACtD,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAA6B;IACpD,MAAM,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IACrD,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAA;IACxB,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,GAAuB,EACvB,IAA0B,EAC1B,OAAgC,EAAE;IAElC,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAA;IAC1B,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAA;IAC5C,IAAI,OAAO,CAAA;IACX,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;YACrC,GAAG;YACH,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnE,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,sCAAsC,GAAG,MAAO,GAAa,CAAC,OAAO,EAAE,CAAC,CAAA;IAC1F,CAAC;IACD,MAAM,cAAc,GAAG,eAAe,CAAC,OAAO,CAAC,eAAe,CAAC,CAAA;IAC/D,OAAO;QACL,IAAI;QACJ,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC;QAClC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAA;AACH,CAAC"}

package/dist/design/audit/reference/retrieval/embedding-hash.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Deterministic hash embedder + cosine similarity — the LITERALLY PURE half of
+ * the embedding boundary (the offline/test default).
+ *
+ * `HashEmbeddingProvider` implements `EmbeddingProvider` with a feature-hashing
+ * trick: every word unigram and adjacent bigram of the input is hashed to a
+ * signed bucket in a fixed-dimension vector, which is then L2-normalised. No
+ * network, no dynamic import, no env — so retrieval works with zero provider and
+ * unit tests never touch the wire. Identical text always yields an identical,
+ * unit-length vector.
+ *
+ * `cosineSimilarity` is the only symbol `retrieval/matcher` imports from here,
+ * keeping the matcher inside the pure subgraph. The network-backed provider lives
+ * in the sibling `embedding-openai.ts` adapter so this module stays pure.
+ */
+import type { EmbeddingProvider } from '../contracts.js';
+/** Fixed embedding width. A corpus embedded with the hash provider is keyed to this. */
+export declare const HASH_EMBEDDING_DIMS = 256;
+/**
+ * The offline/test default embedder. Deterministic, normalised, zero-IO.
+ */
+export declare const HashEmbeddingProvider: EmbeddingProvider;
+/**
+ * Cosine similarity of two numeric vectors, in [-1, 1]. Symmetric. Returns 0 when
+ * either vector is all-zero or empty (a fail-closed "no signal", never NaN). When
+ * lengths differ it compares the common leading dimensions — the caller is
+ * responsible for keeping query/exemplar vectors in the same embedding space.
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+//# sourceMappingURL=embedding-hash.d.ts.map

package/dist/design/audit/reference/retrieval/embedding-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-hash.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/retrieval/embedding-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAmB,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAEzE,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,MAAM,CAAA;AAwCtC;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,iBAKnC,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAajE"}

package/dist/design/audit/reference/retrieval/embedding-hash.js

@@ -0,0 +1,87 @@
+/**
+ * Deterministic hash embedder + cosine similarity — the LITERALLY PURE half of
+ * the embedding boundary (the offline/test default).
+ *
+ * `HashEmbeddingProvider` implements `EmbeddingProvider` with a feature-hashing
+ * trick: every word unigram and adjacent bigram of the input is hashed to a
+ * signed bucket in a fixed-dimension vector, which is then L2-normalised. No
+ * network, no dynamic import, no env — so retrieval works with zero provider and
+ * unit tests never touch the wire. Identical text always yields an identical,
+ * unit-length vector.
+ *
+ * `cosineSimilarity` is the only symbol `retrieval/matcher` imports from here,
+ * keeping the matcher inside the pure subgraph. The network-backed provider lives
+ * in the sibling `embedding-openai.ts` adapter so this module stays pure.
+ */
+/** Fixed embedding width. A corpus embedded with the hash provider is keyed to this. */
+export const HASH_EMBEDDING_DIMS = 256;
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+/** 32-bit FNV-1a — a stable, dependency-free string hash. */
+function fnv1a(str) {
+    let h = FNV_OFFSET;
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        h = Math.imul(h, FNV_PRIME);
+    }
+    return h >>> 0;
+}
+/** Lowercase word unigrams + adjacent bigrams; deterministic and order-stable. */
+function tokenize(text) {
+    const words = text.toLowerCase().match(/[a-z0-9#]+/g) ?? [];
+    const tokens = [...words];
+    for (let i = 1; i < words.length; i++)
+        tokens.push(`${words[i - 1]}_${words[i]}`);
+    return tokens;
+}
+function hashEmbed(text) {
+    const vec = new Array(HASH_EMBEDDING_DIMS).fill(0);
+    for (const token of tokenize(text)) {
+        const h = fnv1a(token);
+        const bucket = h % HASH_EMBEDDING_DIMS;
+        // A second, independent hash bit picks the sign, decorrelating collisions.
+        const sign = (fnv1a(`${token}\0sign`) & 1) === 0 ? 1 : -1;
+        vec[bucket] += sign;
+    }
+    let norm = 0;
+    for (const v of vec)
+        norm += v * v;
+    if (norm === 0)
+        return vec;
+    const inv = 1 / Math.sqrt(norm);
+    for (let i = 0; i < vec.length; i++)
+        vec[i] *= inv;
+    return vec;
+}
+/**
+ * The offline/test default embedder. Deterministic, normalised, zero-IO.
+ */
+export const HashEmbeddingProvider = {
+    id: 'hash-v1',
+    async embed(texts) {
+        return texts.map(hashEmbed);
+    },
+};
+/**
+ * Cosine similarity of two numeric vectors, in [-1, 1]. Symmetric. Returns 0 when
+ * either vector is all-zero or empty (a fail-closed "no signal", never NaN). When
+ * lengths differ it compares the common leading dimensions — the caller is
+ * responsible for keeping query/exemplar vectors in the same embedding space.
+ */
+export function cosineSimilarity(a, b) {
+    const len = Math.min(a.length, b.length);
+    if (len === 0)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < len; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+//# sourceMappingURL=embedding-hash.js.map

package/dist/design/audit/reference/retrieval/embedding-hash.js.map

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

package/dist/design/audit/reference/retrieval/embedding-openai.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Network-backed embedder — the ADAPTER half of the embedding boundary.
+ *
+ * `OpenAiEmbeddingProvider` implements `EmbeddingProvider` over the OpenAI
+ * embeddings endpoint via a `dynamic import('openai')` (the import is confined to
+ * this one adapter so the sibling `embedding-hash.ts` stays literally pure and
+ * the `openai` dep is never loaded on the offline path). The API key is resolved
+ * through the existing `resolveProviderApiKey` provider abstraction — never a
+ * hand-rolled fetch and never a duplicated env lookup.
+ *
+ * `resolveEmbeddingProvider` is the swap point: it returns the OpenAI provider
+ * when a key is present and falls back to the deterministic `HashEmbeddingProvider`
+ * otherwise, so the engine and its unit tests run with zero provider by default.
+ */
+import type { EmbeddingProvider } from '../contracts.js';
+/** Small, cheap, 1536-dim default. A corpus must be embedded with the same model. */
+export declare const DEFAULT_OPENAI_EMBEDDING_MODEL = "text-embedding-3-small";
+/**
+ * The default network-backed provider. Reads `OPENAI_API_KEY` from the
+ * environment lazily on each `embed` call via the shared provider abstraction.
+ */
+export declare const OpenAiEmbeddingProvider: EmbeddingProvider;
+/** Options for selecting an embedding provider. */
+export interface ResolveEmbeddingOptions {
+    /** Explicit key, bypassing env resolution. */
+    apiKey?: string;
+    /** Env to resolve the key from (defaults to `process.env`). */
+    env?: NodeJS.ProcessEnv;
+    /** Override the embedding model (otherwise `DEFAULT_OPENAI_EMBEDDING_MODEL`). */
+    model?: string;
+}
+/**
+ * Pick a concrete embedder: the OpenAI provider when a key is resolvable, else the
+ * deterministic `HashEmbeddingProvider`. Fail-safe by construction — a missing key
+ * yields a working offline embedder rather than an error.
+ */
+export declare function resolveEmbeddingProvider(opts?: ResolveEmbeddingOptions): EmbeddingProvider;
+//# sourceMappingURL=embedding-openai.d.ts.map

package/dist/design/audit/reference/retrieval/embedding-openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-openai.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/retrieval/embedding-openai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAmB,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAIzE,qFAAqF;AACrF,eAAO,MAAM,8BAA8B,2BAA2B,CAAA;AAkCtE;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAErC,CAAA;AAED,mDAAmD;AACnD,MAAM,WAAW,uBAAuB;IACtC,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,GAAE,uBAA4B,GAAG,iBAAiB,CAQ9F"}

package/dist/design/audit/reference/retrieval/embedding-openai.js

@@ -0,0 +1,73 @@
+/**
+ * Network-backed embedder — the ADAPTER half of the embedding boundary.
+ *
+ * `OpenAiEmbeddingProvider` implements `EmbeddingProvider` over the OpenAI
+ * embeddings endpoint via a `dynamic import('openai')` (the import is confined to
+ * this one adapter so the sibling `embedding-hash.ts` stays literally pure and
+ * the `openai` dep is never loaded on the offline path). The API key is resolved
+ * through the existing `resolveProviderApiKey` provider abstraction — never a
+ * hand-rolled fetch and never a duplicated env lookup.
+ *
+ * `resolveEmbeddingProvider` is the swap point: it returns the OpenAI provider
+ * when a key is present and falls back to the deterministic `HashEmbeddingProvider`
+ * otherwise, so the engine and its unit tests run with zero provider by default.
+ */
+import { resolveProviderApiKey } from '../../../../provider-defaults.js';
+import { HashEmbeddingProvider } from './embedding-hash.js';
+/** Small, cheap, 1536-dim default. A corpus must be embedded with the same model. */
+export const DEFAULT_OPENAI_EMBEDDING_MODEL = 'text-embedding-3-small';
+/** L2-normalise so provider vectors are unit-length like the hash provider's. */
+function l2normalize(v) {
+    let norm = 0;
+    for (const x of v)
+        norm += x * x;
+    if (norm === 0)
+        return v.slice();
+    const inv = 1 / Math.sqrt(norm);
+    return v.map((x) => x * inv);
+}
+/**
+ * Build an OpenAI-backed `EmbeddingProvider` for `model`, resolving its key lazily
+ * (at `embed` time) through `getApiKey` so the provider can be a stable object.
+ */
+function createOpenAiProvider(model, getApiKey) {
+    return {
+        id: `openai:${model}`,
+        async embed(texts) {
+            if (texts.length === 0)
+                return [];
+            const apiKey = getApiKey();
+            if (!apiKey) {
+                throw new Error('OpenAiEmbeddingProvider: no OpenAI API key resolved (set OPENAI_API_KEY or pass apiKey)');
+            }
+            const { default: OpenAI } = await import('openai');
+            const client = new OpenAI({ apiKey });
+            const res = await client.embeddings.create({ model, input: texts });
+            const out = new Array(texts.length);
+            for (const item of res.data)
+                out[item.index] = l2normalize(item.embedding);
+            return out;
+        },
+    };
+}
+/**
+ * The default network-backed provider. Reads `OPENAI_API_KEY` from the
+ * environment lazily on each `embed` call via the shared provider abstraction.
+ */
+export const OpenAiEmbeddingProvider = createOpenAiProvider(DEFAULT_OPENAI_EMBEDDING_MODEL, () => resolveProviderApiKey('openai'));
+/**
+ * Pick a concrete embedder: the OpenAI provider when a key is resolvable, else the
+ * deterministic `HashEmbeddingProvider`. Fail-safe by construction — a missing key
+ * yields a working offline embedder rather than an error.
+ */
+export function resolveEmbeddingProvider(opts = {}) {
+    const apiKey = resolveProviderApiKey('openai', opts.apiKey, opts.env);
+    if (!apiKey)
+        return HashEmbeddingProvider;
+    const model = opts.model ?? DEFAULT_OPENAI_EMBEDDING_MODEL;
+    if (model === DEFAULT_OPENAI_EMBEDDING_MODEL && opts.apiKey === undefined && opts.env === undefined) {
+        return OpenAiEmbeddingProvider;
+    }
+    return createOpenAiProvider(model, () => resolveProviderApiKey('openai', opts.apiKey, opts.env));
+}
+//# sourceMappingURL=embedding-openai.js.map

package/dist/design/audit/reference/retrieval/embedding-openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-openai.js","sourceRoot":"","sources":["../../../../../src/design/audit/reference/retrieval/embedding-openai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAA;AACxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAE3D,qFAAqF;AACrF,MAAM,CAAC,MAAM,8BAA8B,GAAG,wBAAwB,CAAA;AAEtE,iFAAiF;AACjF,SAAS,WAAW,CAAC,CAAW;IAC9B,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,KAAK,MAAM,CAAC,IAAI,CAAC;QAAE,IAAI,IAAI,CAAC,GAAG,CAAC,CAAA;IAChC,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,KAAK,EAAE,CAAA;IAChC,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC/B,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAA;AAC9B,CAAC;AAED;;;GAGG;AACH,SAAS,oBAAoB,CAAC,KAAa,EAAE,SAAmC;IAC9E,OAAO;QACL,EAAE,EAAE,UAAU,KAAK,EAAE;QACrB,KAAK,CAAC,KAAK,CAAC,KAAe;YACzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,CAAA;YACjC,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;YAC1B,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,yFAAyF,CAAC,CAAA;YAC5G,CAAC;YACD,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAA;YAClD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;YACrC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;YACnE,MAAM,GAAG,GAAG,IAAI,KAAK,CAAkB,KAAK,CAAC,MAAM,CAAC,CAAA;YACpD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,IAAI;gBAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;YAC1E,OAAO,GAAG,CAAA;QACZ,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAsB,oBAAoB,CAAC,8BAA8B,EAAE,GAAG,EAAE,CAClH,qBAAqB,CAAC,QAAQ,CAAC,CAChC,CAAA;AAYD;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAgC,EAAE;IACzE,MAAM,MAAM,GAAG,qBAAqB,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IACrE,IAAI,CAAC,MAAM;QAAE,OAAO,qBAAqB,CAAA;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,8BAA8B,CAAA;IAC1D,IAAI,KAAK,KAAK,8BAA8B,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QACpG,OAAO,uBAAuB,CAAA;IAChC,CAAC;IACD,OAAO,oBAAoB,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,qBAAqB,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;AAClG,CAAC"}