@plune-ai/cairn 0.2.1

package/dist/eval/experiment.js

@@ -0,0 +1,66 @@
+import { designTestCases } from "../design/index.js";
+import { deterministicScores } from "./scorers.js";
+import { judgeTestCases } from "./judge.js";
+/**
+ * Run dataset × prompt versions through the design stage, average the metrics, and produce a verdict
+ * (B2 self-improvement). A verdict is produced only for two variants: baseline (first) vs candidate (second).
+ */
+export async function runExperiment(items, variants, deps, opts = {}) {
+    const perVariant = [];
+    for (const variant of variants) {
+        const collected = {};
+        for (const item of items) {
+            const verified = item.verified ?? item.study.elements.map((e) => ({ ...e, count: 1, verified: true }));
+            const testCases = await designTestCases({
+                study: item.study,
+                pageSemantics: item.pageSemantics,
+                elements: verified.filter((v) => v.verified),
+            }, { invoke: deps.designInvoke, prompts: variant.prompts });
+            const scores = deterministicScores({ study: item.study, verified, testCases });
+            if (deps.judgeInvoke) {
+                scores.push(...(await judgeTestCases(testCases, item.pageSemantics, deps.judgeInvoke, variant.prompts)));
+            }
+            for (const s of scores)
+                (collected[s.name] ??= []).push(s.value);
+        }
+        const meanScores = {};
+        for (const [name, vals] of Object.entries(collected)) {
+            meanScores[name] = vals.reduce((a, b) => a + b, 0) / vals.length;
+        }
+        perVariant.push({ label: variant.label, meanScores, itemCount: items.length });
+    }
+    let verdict;
+    const base = perVariant[0];
+    const cand = perVariant[1];
+    if (perVariant.length === 2 && base && cand) {
+        const target = opts.target ?? "grounding";
+        const threshold = opts.threshold ?? 0.05;
+        const tolerance = opts.tolerance ?? 0.02;
+        const guardrails = opts.guardrails ?? [
+            "grounding",
+            "test_case_quality",
+            "methodology_adherence",
+            "locator_quality",
+        ];
+        const delta = (cand.meanScores[target] ?? 0) - (base.meanScores[target] ?? 0);
+        const guardrailRegressions = guardrails.filter((g) => {
+            if (g === target)
+                return false;
+            const b = base.meanScores[g];
+            const c = cand.meanScores[g];
+            if (b === undefined || c === undefined)
+                return false;
+            return c < b - tolerance;
+        });
+        verdict = {
+            target,
+            baseline: base.label,
+            candidate: cand.label,
+            delta,
+            improved: delta >= threshold && guardrailRegressions.length === 0,
+            guardrailRegressions,
+        };
+    }
+    return { perVariant, verdict };
+}
+//# sourceMappingURL=experiment.js.map

package/dist/eval/experiment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiment.js","sourceRoot":"","sources":["../../src/eval/experiment.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAgD5C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAoB,EACpB,QAAmB,EACnB,IAAoB,EACpB,OAA0B,EAAE;IAE5B,MAAM,UAAU,GAAoB,EAAE,CAAC;IAEvC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,SAAS,GAA6B,EAAE,CAAC;QAC/C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,QAAQ,GACZ,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YACxF,MAAM,SAAS,GAAG,MAAM,eAAe,CACrC;gBACE,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,aAAa,EAAE,IAAI,CAAC,aAAa;gBACjC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;aAC7C,EACD,EAAE,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CACxD,CAAC;YACF,MAAM,MAAM,GAAG,mBAAmB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;YAC/E,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;gBACrB,MAAM,CAAC,IAAI,CACT,GAAG,CAAC,MAAM,cAAc,CAAC,SAAS,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAC5F,CAAC;YACJ,CAAC;YACD,KAAK,MAAM,CAAC,IAAI,MAAM;gBAAE,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACnE,CAAC;QAED,MAAM,UAAU,GAA2B,EAAE,CAAC;QAC9C,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YACrD,UAAU,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;QACnE,CAAC;QACD,UAAU,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACjF,CAAC;IAED,IAAI,OAAsC,CAAC;IAC3C,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAC3B,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,WAAW,CAAC;QAC1C,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC;QACzC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC;QACzC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI;YACpC,WAAW;YACX,mBAAmB;YACnB,uBAAuB;YACvB,iBAAiB;SAClB,CAAC;QACF,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9E,MAAM,oBAAoB,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;YACnD,IAAI,CAAC,KAAK,MAAM;gBAAE,OAAO,KAAK,CAAC;YAC/B,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YAC7B,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YAC7B,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,SAAS;gBAAE,OAAO,KAAK,CAAC;YACrD,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;QAC3B,CAAC,CAAC,CAAC;QACH,OAAO,GAAG;YACR,MAAM;YACN,QAAQ,EAAE,IAAI,CAAC,KAAK;YACpB,SAAS,EAAE,IAAI,CAAC,KAAK;YACrB,KAAK;YACL,QAAQ,EAAE,KAAK,IAAI,SAAS,IAAI,oBAAoB,CAAC,MAAM,KAAK,CAAC;YACjE,oBAAoB;SACrB,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AACjC,CAAC"}

package/dist/eval/judge.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import type { StructuredInvoke } from "../llm/structured.js";
+import type { PromptRegistry } from "../prompts/index.js";
+import type { TestCase } from "../design/index.js";
+import type { Score } from "./scorers.js";
+export declare const JudgeSchema: z.ZodObject<{
+    test_case_quality: z.ZodNumber;
+    methodology_adherence: z.ZodNumber;
+    comment: z.ZodString;
+}, z.core.$strip>;
+/**
+ * LLM-as-judge (SDK-side, cheap tier) — subjective evaluation of cases (ADR-0006).
+ * The prompt is versioned in the registry ("judge-test-cases"), like the methodology prompts.
+ */
+export declare function judgeTestCases(testCases: TestCase[], pageSemantics: string, invoke: StructuredInvoke, prompts: PromptRegistry): Promise<Score[]>;
+export declare const ChecklistCoverageSchema: z.ZodObject<{
+    coverage: z.ZodNumber;
+    uncovered: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Semantic coverage of the checklist by the cases (LLM judge) — understands meaning regardless of LANGUAGE.
+ * The prompt is versioned in the registry ("judge-checklist-coverage").
+ */
+export declare function judgeChecklistCoverage(checklistItems: {
+    text: string;
+}[], testCases: TestCase[], invoke: StructuredInvoke, prompts: PromptRegistry): Promise<{
+    value: number;
+    comment: string;
+}>;
+//# sourceMappingURL=judge.d.ts.map

package/dist/eval/judge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"judge.d.ts","sourceRoot":"","sources":["../../src/eval/judge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,eAAO,MAAM,WAAW;;;;iBAItB,CAAC;AAEH;;;GAGG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,QAAQ,EAAE,EACrB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,KAAK,EAAE,CAAC,CAWlB;AAED,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAC;AAEH;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,cAAc,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,EAClC,SAAS,EAAE,QAAQ,EAAE,EACrB,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAY7C"}

package/dist/eval/judge.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { HumanMessage } from "@langchain/core/messages";
+export const JudgeSchema = z.object({
+    test_case_quality: z.number().min(0).max(1),
+    methodology_adherence: z.number().min(0).max(1),
+    comment: z.string(),
+});
+/**
+ * LLM-as-judge (SDK-side, cheap tier) — subjective evaluation of cases (ADR-0006).
+ * The prompt is versioned in the registry ("judge-test-cases"), like the methodology prompts.
+ */
+export async function judgeTestCases(testCases, pageSemantics, invoke, prompts) {
+    if (testCases.length === 0)
+        return [];
+    const cases = testCases
+        .map((tc) => `- [${tc.technique}] ${tc.title}: ${tc.steps.join("; ")} ⇒ ${tc.expected}`)
+        .join("\n");
+    const prompt = await prompts.getPrompt("judge-test-cases", { pageSemantics, cases });
+    const r = await invoke(JudgeSchema, [new HumanMessage(prompt.text)]);
+    return [
+        { name: "test_case_quality", value: r.test_case_quality, comment: r.comment },
+        { name: "methodology_adherence", value: r.methodology_adherence },
+    ];
+}
+export const ChecklistCoverageSchema = z.object({
+    coverage: z.number().min(0).max(1),
+    uncovered: z.array(z.string()).default([]),
+});
+/**
+ * Semantic coverage of the checklist by the cases (LLM judge) — understands meaning regardless of LANGUAGE.
+ * The prompt is versioned in the registry ("judge-checklist-coverage").
+ */
+export async function judgeChecklistCoverage(checklistItems, testCases, invoke, prompts) {
+    if (checklistItems.length === 0)
+        return { value: 0, comment: "" };
+    const items = checklistItems.map((i, n) => `${n + 1}. ${i.text}`).join("\n");
+    const cases = testCases
+        .map((tc) => `- ${tc.title}: ${tc.steps.join("; ")} ⇒ ${tc.expected}`)
+        .join("\n");
+    const prompt = await prompts.getPrompt("judge-checklist-coverage", { items, cases });
+    const r = await invoke(ChecklistCoverageSchema, [new HumanMessage(prompt.text)]);
+    return {
+        value: r.coverage,
+        comment: r.uncovered.length > 0 ? `uncovered: ${r.uncovered.join("; ")}` : "full coverage",
+    };
+}
+//# sourceMappingURL=judge.js.map

package/dist/eval/judge.js.map

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

package/dist/eval/pilot.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import type { StructuredInvoke } from "../llm/structured.js";
+import type { PromptRegistry } from "../prompts/index.js";
+import type { TestCase } from "../design/index.js";
+import type { ValidationReport } from "../validate/index.js";
+export declare const PilotSchema: z.ZodObject<{
+    verdict: z.ZodEnum<{
+        pass: "pass";
+        "needs-work": "needs-work";
+        fail: "fail";
+    }>;
+    reason: z.ZodString;
+    guidance: z.ZodString;
+}, z.core.$strip>;
+export type PilotVerdict = z.infer<typeof PilotSchema>;
+/**
+ * Pilot supervisor (idea from explorbot): a holistic run verdict (pass/needs-work/fail) + guidance.
+ * Complements the per-metric judge with a single decision on "whether the run is good enough".
+ */
+export declare function pilotReview(pageSemantics: string, validation: ValidationReport | undefined, testCases: TestCase[], invoke: StructuredInvoke, prompts: PromptRegistry): Promise<PilotVerdict>;
+//# sourceMappingURL=pilot.d.ts.map

package/dist/eval/pilot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pilot.d.ts","sourceRoot":"","sources":["../../src/eval/pilot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,eAAO,MAAM,WAAW;;;;;;;;iBAItB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEvD;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,gBAAgB,GAAG,SAAS,EACxC,SAAS,EAAE,QAAQ,EAAE,EACrB,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,YAAY,CAAC,CAWvB"}

package/dist/eval/pilot.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { HumanMessage } from "@langchain/core/messages";
+export const PilotSchema = z.object({
+    verdict: z.enum(["pass", "needs-work", "fail"]),
+    reason: z.string(),
+    guidance: z.string(),
+});
+/**
+ * Pilot supervisor (idea from explorbot): a holistic run verdict (pass/needs-work/fail) + guidance.
+ * Complements the per-metric judge with a single decision on "whether the run is good enough".
+ */
+export async function pilotReview(pageSemantics, validation, testCases, invoke, prompts) {
+    const validationText = validation
+        ? `${Math.round(validation.greenRatio * 100)}% green (${validation.results.length} tests, flaky: ${validation.flakyCount})`
+        : "(no validation — case design only)";
+    const cases = testCases.map((tc) => `- [${tc.type}/${tc.priority}] ${tc.title}`).join("\n");
+    const prompt = await prompts.getPrompt("pilot-review", {
+        pageSemantics,
+        validation: validationText,
+        cases,
+    });
+    return invoke(PilotSchema, [new HumanMessage(prompt.text)]);
+}
+//# sourceMappingURL=pilot.js.map

package/dist/eval/pilot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pilot.js","sourceRoot":"","sources":["../../src/eval/pilot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAMxD,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IAC/C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;CACrB,CAAC,CAAC;AAGH;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,aAAqB,EACrB,UAAwC,EACxC,SAAqB,EACrB,MAAwB,EACxB,OAAuB;IAEvB,MAAM,cAAc,GAAG,UAAU;QAC/B,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,GAAG,GAAG,CAAC,YAAY,UAAU,CAAC,OAAO,CAAC,MAAM,kBAAkB,UAAU,CAAC,UAAU,GAAG;QAC3H,CAAC,CAAC,oCAAoC,CAAC;IACzC,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,QAAQ,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5F,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,cAAc,EAAE;QACrD,aAAa;QACb,UAAU,EAAE,cAAc;QAC1B,KAAK;KACN,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC,IAAI,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC"}

package/dist/eval/scorers.d.ts

@@ -0,0 +1,23 @@
+import type { PageStudy } from "../observe/index.js";
+import type { TestCase } from "../design/index.js";
+import type { GeneratedSuite } from "../codegen/index.js";
+import type { ValidationReport } from "../validate/index.js";
+import type { VerifiedElement } from "../browser/types.js";
+export interface Score {
+    name: string;
+    value: number;
+    comment?: string;
+}
+export interface ScoreInput {
+    study: PageStudy;
+    verified: VerifiedElement[];
+    testCases: TestCase[];
+    suite?: GeneratedSuite;
+    validation?: ValidationReport;
+}
+/**
+ * Deterministic (objective) scorers — computed from run data without an LLM or network.
+ * Foundation of the self-improvement loop: a measurable signal for every run (ADR-0006).
+ */
+export declare function deterministicScores(input: ScoreInput): Score[];
+//# sourceMappingURL=scorers.d.ts.map

package/dist/eval/scorers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scorers.d.ts","sourceRoot":"","sources":["../../src/eval/scorers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,KAAK,EAAE,CAsC9D"}

package/dist/eval/scorers.js

@@ -0,0 +1,38 @@
+/**
+ * Deterministic (objective) scorers — computed from run data without an LLM or network.
+ * Foundation of the self-improvement loop: a measurable signal for every run (ADR-0006).
+ */
+export function deterministicScores(input) {
+    const scores = [];
+    if (input.validation) {
+        scores.push({ name: "runs_green", value: input.validation.greenRatio });
+        if (input.validation.results.length > 0) {
+            scores.push({
+                name: "flaky_ratio",
+                value: input.validation.flakyCount / input.validation.results.length,
+            });
+        }
+    }
+    if (input.verified.length > 0) {
+        const ok = input.verified.filter((v) => v.verified).length;
+        scores.push({ name: "verified_ratio", value: ok / input.verified.length });
+    }
+    // grounding: share of cases whose elementRefs all point to REAL elements (count≥1),
+    // including duplicated ones (.first()). verified_ratio separately measures uniqueness (count===1).
+    const realRefs = new Set(input.verified.filter((v) => v.count >= 1).map((v) => v.ref));
+    if (input.testCases.length > 0) {
+        const grounded = input.testCases.filter((tc) => tc.elementRefs.length > 0 && tc.elementRefs.every((r) => realRefs.has(r))).length;
+        scores.push({ name: "grounding", value: grounded / input.testCases.length });
+    }
+    // locator_quality: share of user-facing locators vs CSS/testid in the generated code.
+    if (input.suite) {
+        const code = input.suite.files.map((f) => f.content).join("\n");
+        const userFacing = (code.match(/getBy(Role|Label|Text|Placeholder|AltText|Title)/g) ?? []).length;
+        const fragile = (code.match(/\.locator\(|getByTestId|page\.\$/g) ?? []).length;
+        const total = userFacing + fragile;
+        if (total > 0)
+            scores.push({ name: "locator_quality", value: userFacing / total });
+    }
+    return scores;
+}
+//# sourceMappingURL=scorers.js.map

package/dist/eval/scorers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scorers.js","sourceRoot":"","sources":["../../src/eval/scorers.ts"],"names":[],"mappings":"AAoBA;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAiB;IACnD,MAAM,MAAM,GAAY,EAAE,CAAC;IAE3B,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACrB,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC;QACxE,IAAI,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxC,MAAM,CAAC,IAAI,CAAC;gBACV,IAAI,EAAE,aAAa;gBACnB,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM;aACrE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC;QAC3D,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED,oFAAoF;IACpF,mGAAmG;IACnG,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACvF,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CACrC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAClF,CAAC,MAAM,CAAC;QACT,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,sFAAsF;IACtF,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChE,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,mDAAmD,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QAClG,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,mCAAmC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QAC/E,MAAM,KAAK,GAAG,UAAU,GAAG,OAAO,CAAC;QACnC,IAAI,KAAK,GAAG,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,UAAU,GAAG,KAAK,EAAE,CAAC,CAAC;IACrF,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * QA Explorer Bot — public library API (Sprint 6: frozen for embedding).
+ *
+ * Example: import { runDesign, runAutomate, runExploration } from "@plune-ai/cairn";
+ * Three entry points: explore (everything), design (cases only), automate (code from cases).
+ */
+export declare const BOT_NAME: "@plune-ai/cairn";
+export declare const BOT_VERSION: "0.1.0";
+export { runExploration, runDesign, runAutomate, buildExploreGraph, ExploreState } from "./agent/index.js";
+export type { ExploreInput, ExploreResult, DesignResult, AutomateResult, ExploreDeps, } from "./agent/index.js";
+export { loadConfig } from "./config/index.js";
+export type { AppConfig } from "./config/index.js";
+export type { TestCase, DesignedCase } from "./design/index.js";
+export type { PageStudy } from "./observe/index.js";
+export type { GeneratedSuite } from "./codegen/index.js";
+export type { Score } from "./eval/scorers.js";
+export type { PilotVerdict } from "./eval/pilot.js";
+export type { ValidationReport } from "./validate/index.js";
+export type { ChecklistItem } from "./checklist/index.js";
+export type { ElementRef, VerifiedElement, StorageState, BackendKind } from "./browser/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,QAAQ,EAAG,iBAA0B,CAAC;AACnD,eAAO,MAAM,WAAW,EAAG,OAAgB,CAAC;AAG5C,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC3G,YAAY,EACV,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,cAAc,EACd,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAGnD,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAChE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * QA Explorer Bot — public library API (Sprint 6: frozen for embedding).
+ *
+ * Example: import { runDesign, runAutomate, runExploration } from "@plune-ai/cairn";
+ * Three entry points: explore (everything), design (cases only), automate (code from cases).
+ */
+export const BOT_NAME = "@plune-ai/cairn";
+export const BOT_VERSION = "0.1.0";
+// Entry points.
+export { runExploration, runDesign, runAutomate, buildExploreGraph, ExploreState } from "./agent/index.js";
+// Config.
+export { loadConfig } from "./config/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG,iBAA0B,CAAC;AACnD,MAAM,CAAC,MAAM,WAAW,GAAG,OAAgB,CAAC;AAE5C,gBAAgB;AAChB,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAS3G,UAAU;AACV,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/knowledge/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Load domain knowledge (.md with credentials/validation rules/notes), URL-matched (idea from explorbot).
+ * A file without `url:` is global (always applied); with `url:` only when the pattern is contained in the page URL.
+ * Injected into the design prompt → the bot knows facts not visible in the snapshot (reduces the oracle gap).
+ */
+export declare function loadKnowledge(dir: string, url: string): Promise<string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/knowledge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/knowledge/index.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB7E"}

package/dist/knowledge/index.js

@@ -0,0 +1,39 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+/** url pattern from frontmatter (the `url: ...` line), if present. */
+function frontmatterUrl(raw) {
+    const fm = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fm?.[1])
+        return undefined;
+    const line = fm[1].split(/\r?\n/).find((l) => /^url:/.test(l.trim()));
+    return line ? line.replace(/^\s*url:\s*/, "").trim() : undefined;
+}
+function stripFrontmatter(raw) {
+    return raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "").trim();
+}
+/**
+ * Load domain knowledge (.md with credentials/validation rules/notes), URL-matched (idea from explorbot).
+ * A file without `url:` is global (always applied); with `url:` only when the pattern is contained in the page URL.
+ * Injected into the design prompt → the bot knows facts not visible in the snapshot (reduces the oracle gap).
+ */
+export async function loadKnowledge(dir, url) {
+    let files = [];
+    try {
+        files = (await readdir(dir)).filter((f) => f.endsWith(".md"));
+    }
+    catch {
+        return "";
+    }
+    const parts = [];
+    for (const f of files) {
+        const raw = await readFile(join(dir, f), "utf8");
+        const pattern = frontmatterUrl(raw);
+        if (!pattern || url.includes(pattern)) {
+            const body = stripFrontmatter(raw);
+            if (body.length > 0)
+                parts.push(body);
+        }
+    }
+    return parts.join("\n\n");
+}
+//# sourceMappingURL=index.js.map

package/dist/knowledge/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/knowledge/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,sEAAsE;AACtE,SAAS,cAAc,CAAC,GAAW;IACjC,MAAM,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACpD,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/B,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACtE,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACnE,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAW;IACnC,OAAO,GAAG,CAAC,OAAO,CAAC,iCAAiC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAW,EAAE,GAAW;IAC1D,IAAI,KAAK,GAAa,EAAE,CAAC;IACzB,IAAI,CAAC;QACH,KAAK,GAAG,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,OAAO,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;YACnC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC"}

package/dist/llm/factory.d.ts

@@ -0,0 +1,31 @@
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import type { ModelTier } from "../config/index.js";
+/** OpenRouter — OpenAI-compatible API; we connect via the ChatOpenAI baseURL (ADR-0002). */
+export declare const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+export interface ProviderKeys {
+    anthropicApiKey?: string;
+    openrouterApiKey?: string;
+}
+/** Resolved model specification (pure result, no side effects). */
+export type ModelSpec = {
+    provider: "anthropic";
+    model: string;
+    apiKey: string;
+    temperature?: number;
+    supportsVision: boolean;
+} | {
+    provider: "openrouter";
+    model: string;
+    apiKey: string;
+    baseURL: string;
+    temperature?: number;
+    supportsVision: boolean;
+};
+/**
+ * Pure function: tier + keys → ModelSpec. Throws if the required provider's key is missing.
+ * Separated from instantiation so it is fully testable without the SDK.
+ */
+export declare function resolveModelSpec(tier: ModelTier, keys: ProviderKeys): ModelSpec;
+/** Provider-agnostic factory: returns a LangChain `BaseChatModel` for the tier. */
+export declare function makeModel(tier: ModelTier, keys: ProviderKeys): BaseChatModel;
+//# sourceMappingURL=factory.d.ts.map

package/dist/llm/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/llm/factory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,4FAA4F;AAC5F,eAAO,MAAM,mBAAmB,iCAAiC,CAAC;AAElE,MAAM,WAAW,YAAY;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,mEAAmE;AACnE,MAAM,MAAM,SAAS,GACjB;IACE,QAAQ,EAAE,WAAW,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;CACzB,GACD;IACE,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;CACzB,CAAC;AAEN;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,SAAS,CAwB/E;AAED,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAa5E"}

package/dist/llm/factory.js

@@ -0,0 +1,48 @@
+import { ChatAnthropic } from "@langchain/anthropic";
+import { ChatOpenAI } from "@langchain/openai";
+/** OpenRouter — OpenAI-compatible API; we connect via the ChatOpenAI baseURL (ADR-0002). */
+export const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+/**
+ * Pure function: tier + keys → ModelSpec. Throws if the required provider's key is missing.
+ * Separated from instantiation so it is fully testable without the SDK.
+ */
+export function resolveModelSpec(tier, keys) {
+    if (tier.provider === "anthropic") {
+        if (!keys.anthropicApiKey) {
+            throw new Error(`Tier '${tier.model}' requires Anthropic, but ANTHROPIC_API_KEY is not set.`);
+        }
+        return {
+            provider: "anthropic",
+            model: tier.model,
+            apiKey: keys.anthropicApiKey,
+            temperature: tier.temperature,
+            supportsVision: tier.supportsVision,
+        };
+    }
+    if (!keys.openrouterApiKey) {
+        throw new Error(`Tier '${tier.model}' requires OpenRouter, but OPENROUTER_API_KEY is not set.`);
+    }
+    return {
+        provider: "openrouter",
+        model: tier.model,
+        apiKey: keys.openrouterApiKey,
+        baseURL: OPENROUTER_BASE_URL,
+        temperature: tier.temperature,
+        supportsVision: tier.supportsVision,
+    };
+}
+/** Provider-agnostic factory: returns a LangChain `BaseChatModel` for the tier. */
+export function makeModel(tier, keys) {
+    const spec = resolveModelSpec(tier, keys);
+    const temperature = spec.temperature !== undefined ? { temperature: spec.temperature } : {};
+    if (spec.provider === "anthropic") {
+        return new ChatAnthropic({ model: spec.model, apiKey: spec.apiKey, ...temperature });
+    }
+    return new ChatOpenAI({
+        model: spec.model,
+        apiKey: spec.apiKey,
+        configuration: { baseURL: spec.baseURL },
+        ...temperature,
+    });
+}
+//# sourceMappingURL=factory.js.map

package/dist/llm/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/llm/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI/C,4FAA4F;AAC5F,MAAM,CAAC,MAAM,mBAAmB,GAAG,8BAA8B,CAAC;AAyBlE;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAe,EAAE,IAAkB;IAClE,IAAI,IAAI,CAAC,QAAQ,KAAK,WAAW,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,SAAS,IAAI,CAAC,KAAK,yDAAyD,CAAC,CAAC;QAChG,CAAC;QACD,OAAO;YACL,QAAQ,EAAE,WAAW;YACrB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,IAAI,CAAC,eAAe;YAC5B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,cAAc,EAAE,IAAI,CAAC,cAAc;SACpC,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,SAAS,IAAI,CAAC,KAAK,2DAA2D,CAAC,CAAC;IAClG,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,YAAY;QACtB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM,EAAE,IAAI,CAAC,gBAAgB;QAC7B,OAAO,EAAE,mBAAmB;QAC5B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,cAAc,EAAE,IAAI,CAAC,cAAc;KACpC,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,SAAS,CAAC,IAAe,EAAE,IAAkB;IAC3D,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1C,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAE5F,IAAI,IAAI,CAAC,QAAQ,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,IAAI,aAAa,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,WAAW,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,IAAI,UAAU,CAAC;QACpB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,aAAa,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE;QACxC,GAAG,WAAW;KACf,CAAC,CAAC;AACL,CAAC"}

package/dist/llm/index.d.ts

@@ -0,0 +1,5 @@
+export { OPENROUTER_BASE_URL, resolveModelSpec, makeModel } from "./factory.js";
+export type { ModelSpec, ProviderKeys } from "./factory.js";
+export { imageBlock } from "./vision.js";
+export type { ImageBlock } from "./vision.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/llm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAChF,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/llm/index.js

@@ -0,0 +1,3 @@
+export { OPENROUTER_BASE_URL, resolveModelSpec, makeModel } from "./factory.js";
+export { imageBlock } from "./vision.js";
+//# sourceMappingURL=index.js.map

package/dist/llm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEhF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/llm/structured.d.ts

@@ -0,0 +1,30 @@
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import type { BaseMessageLike } from "@langchain/core/messages";
+import type { ZodType } from "zod";
+/**
+ * Structured-call seam: (schema, messages) → typed result.
+ * Decouples domain logic (design/analyze) from the concrete model — a fake is injected in tests.
+ */
+export type StructuredInvoke = <T>(schema: ZodType<T>, messages: BaseMessageLike[]) => Promise<T>;
+/** Real implementation on top of LangChain `withStructuredOutput`. */
+export declare function structuredInvoker(model: BaseChatModel): StructuredInvoke;
+export interface RetryOptions {
+    retries?: number;
+    baseDelayMs?: number;
+}
+/**
+ * Retry wrapper (Sprint 6 robustness): retries the call on TRANSIENT errors (429/5xx/overloaded)
+ * with exponential backoff. Non-transient errors (schema validation, 4xx) are thrown immediately.
+ */
+export declare function retryInvoke(inner: StructuredInvoke, opts?: RetryOptions): StructuredInvoke;
+/** Cost-guardrail (Sprint 6): shared LLM-call counter per run — a safeguard against runaway cost. */
+export declare class CallBudget {
+    private readonly max;
+    private n;
+    constructor(max: number);
+    charge(): void;
+    get spent(): number;
+}
+/** Cost-guardrail wrapper: counts the call against the shared CallBudget (throws when exceeded). */
+export declare function cappedInvoke(inner: StructuredInvoke, budget: CallBudget): StructuredInvoke;
+//# sourceMappingURL=structured.d.ts.map

package/dist/llm/structured.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured.d.ts","sourceRoot":"","sources":["../../src/llm/structured.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,eAAe,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAElG,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,CAKxE;AAMD,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,GAAE,YAAiB,GAAG,gBAAgB,CAiB9F;AAED,qGAAqG;AACrG,qBAAa,UAAU;IAET,OAAO,CAAC,QAAQ,CAAC,GAAG;IADhC,OAAO,CAAC,CAAC,CAAK;gBACe,GAAG,EAAE,MAAM;IACxC,MAAM,IAAI,IAAI;IAQd,IAAI,KAAK,IAAI,MAAM,CAElB;CACF;AAED,oGAAoG;AACpG,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,UAAU,GAAG,gBAAgB,CAK1F"}

package/dist/llm/structured.js

@@ -0,0 +1,58 @@
+/** Real implementation on top of LangChain `withStructuredOutput`. */
+export function structuredInvoker(model) {
+    return async (schema, messages) => {
+        const structured = model.withStructuredOutput(schema);
+        return (await structured.invoke(messages));
+    };
+}
+/** Transient provider errors worth retrying (rate limit / overload / 5xx / timeout). */
+const TRANSIENT = /\b429\b|rate.?limit|overloaded|temporarily|timeout|ETIMEDOUT|ECONNRESET|\b50\d\b|service unavailable/i;
+/**
+ * Retry wrapper (Sprint 6 robustness): retries the call on TRANSIENT errors (429/5xx/overloaded)
+ * with exponential backoff. Non-transient errors (schema validation, 4xx) are thrown immediately.
+ */
+export function retryInvoke(inner, opts = {}) {
+    const retries = opts.retries ?? 3;
+    const baseDelayMs = opts.baseDelayMs ?? 800;
+    return async (schema, messages) => {
+        let lastErr;
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                return await inner(schema, messages);
+            }
+            catch (e) {
+                lastErr = e;
+                const msg = e instanceof Error ? e.message : String(e);
+                if (attempt === retries || !TRANSIENT.test(msg))
+                    throw e;
+                await new Promise((r) => setTimeout(r, baseDelayMs * 2 ** attempt));
+            }
+        }
+        throw lastErr;
+    };
+}
+/** Cost-guardrail (Sprint 6): shared LLM-call counter per run — a safeguard against runaway cost. */
+export class CallBudget {
+    max;
+    n = 0;
+    constructor(max) {
+        this.max = max;
+    }
+    charge() {
+        this.n += 1;
+        if (this.n > this.max) {
+            throw new Error(`LLM-call limit per run exceeded (${this.max}) — cost-guardrail. Increase maxLlmCalls or check the loop.`);
+        }
+    }
+    get spent() {
+        return this.n;
+    }
+}
+/** Cost-guardrail wrapper: counts the call against the shared CallBudget (throws when exceeded). */
+export function cappedInvoke(inner, budget) {
+    return async (schema, messages) => {
+        budget.charge();
+        return inner(schema, messages);
+    };
+}
+//# sourceMappingURL=structured.js.map

package/dist/llm/structured.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured.js","sourceRoot":"","sources":["../../src/llm/structured.ts"],"names":[],"mappings":"AAUA,sEAAsE;AACtE,MAAM,UAAU,iBAAiB,CAAC,KAAoB;IACpD,OAAO,KAAK,EAAK,MAAkB,EAAE,QAA2B,EAAc,EAAE;QAC9E,MAAM,UAAU,GAAG,KAAK,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;QACtD,OAAO,CAAC,MAAM,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAM,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC;AAED,wFAAwF;AACxF,MAAM,SAAS,GACb,uGAAuG,CAAC;AAO1G;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAuB,EAAE,OAAqB,EAAE;IAC1E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;IAClC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,GAAG,CAAC;IAC5C,OAAO,KAAK,EAAK,MAAkB,EAAE,QAA2B,EAAc,EAAE;QAC9E,IAAI,OAAgB,CAAC;QACrB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;YACpD,IAAI,CAAC;gBACH,OAAO,MAAM,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YACvC,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,OAAO,GAAG,CAAC,CAAC;gBACZ,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBACvD,IAAI,OAAO,KAAK,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC;oBAAE,MAAM,CAAC,CAAC;gBACzD,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,WAAW,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC;YACtE,CAAC;QACH,CAAC;QACD,MAAM,OAAO,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAED,qGAAqG;AACrG,MAAM,OAAO,UAAU;IAEQ;IADrB,CAAC,GAAG,CAAC,CAAC;IACd,YAA6B,GAAW;QAAX,QAAG,GAAH,GAAG,CAAQ;IAAG,CAAC;IAC5C,MAAM;QACJ,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,oCAAoC,IAAI,CAAC,GAAG,6DAA6D,CAC1G,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,CAAC,CAAC;IAChB,CAAC;CACF;AAED,oGAAoG;AACpG,MAAM,UAAU,YAAY,CAAC,KAAuB,EAAE,MAAkB;IACtE,OAAO,KAAK,EAAK,MAAkB,EAAE,QAA2B,EAAc,EAAE;QAC9E,MAAM,CAAC,MAAM,EAAE,CAAC;QAChB,OAAO,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACjC,CAAC,CAAC;AACJ,CAAC"}

package/dist/llm/vision.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Cross-provider image content block for HumanMessage.
+ *
+ * The `image_url` form with a data-URL is accepted by both ChatAnthropic (via LangChain coercion)
+ * and ChatOpenAI/OpenRouter. The exact working form for Anthropic Opus is confirmed by Spike S2 —
+ * if needed, a per-provider branch will live here.
+ */
+export interface ImageBlock {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+    [key: string]: unknown;
+}
+export declare function imageBlock(dataB64: string, mediaType?: string): ImageBlock;
+//# sourceMappingURL=vision.d.ts.map