daftari 1.15.0 → 1.17.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"subgraph.d.ts","sourceRoot":"","sources":["../../src/eval/subgraph.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC,CA6D5C"}

package/dist/eval/subgraph.js

@@ -0,0 +1,214 @@
+// Deterministic subgraph sampling for the cortex quality metric.
+//
+// Given a vault and a seed string, derive a small connected subgraph rooted at
+// one "seed doc". The seed→doc mapping is stratified by collection so a vault
+// with one dense collection cannot dominate every sample. From the seed we hop
+// along four edge kinds — frontmatter `sources`, in-body markdown links, logged
+// tensions, and `superseded_by` revision links — collecting neighbours until a
+// node cap is reached. In Daftari's data model `sources:` holds external
+// citation slugs (not in-vault paths), so the real in-vault doc→doc revision
+// edge lives in `superseded_by:`, walked bidirectionally below.
+//
+// Pure given (vault state + seed): the same inputs always yield the same
+// subgraph. All randomness is replaced by SHA-256 indexing over sorted inputs.
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { listTensions } from "../curation/tension.js";
+import { parseDocument } from "../frontmatter/parser.js";
+import { err, ok } from "../frontmatter/types.js";
+import { openIndexForActiveProvider } from "../tools/search.js";
+export async function sampleSubgraph(vaultRoot, seed, opts = {}) {
+    const maxNodes = opts.maxNodes ?? 5;
+    const indexRes = openIndexForActiveProvider(vaultRoot);
+    if (!indexRes.ok) {
+        return err({ kind: "runtime", message: `vault index unavailable: ${indexRes.error.message}` });
+    }
+    const db = indexRes.value;
+    let docs;
+    try {
+        docs = db.prepare("SELECT path, superseded_by FROM documents").all();
+    }
+    finally {
+        db.close();
+    }
+    if (docs.length === 0) {
+        return err({ kind: "runtime", message: "vault has no indexed documents" });
+    }
+    const strata = stratifyByCollection(docs.map((d) => d.path));
+    const stratumNames = [...strata.keys()].sort();
+    const stratumIdx = hashToIndex(`${seed}:stratum`, stratumNames.length);
+    const stratumName = stratumNames[stratumIdx];
+    const stratumDocs = [...(strata.get(stratumName) ?? [])].sort();
+    const seedIdx = hashToIndex(`${seed}:doc`, stratumDocs.length);
+    const seedDoc = stratumDocs[seedIdx];
+    const visited = new Map();
+    const edges = [];
+    const tensionsByDoc = await loadTensionEdges(vaultRoot);
+    // Bidirectional supersede map, built from the already-materialized SQL rows
+    // (no extra file reads). Bidirectional so a seed landing on EITHER the old or
+    // the new doc reaches its counterpart.
+    const supersededByDoc = new Map();
+    for (const d of docs) {
+        if (typeof d.superseded_by === "string" && d.superseded_by.length > 0) {
+            pushTo(supersededByDoc, d.path, { other: d.superseded_by });
+            pushTo(supersededByDoc, d.superseded_by, { other: d.path });
+        }
+    }
+    await loadNode(vaultRoot, seedDoc, visited);
+    await walkHop(vaultRoot, seedDoc, visited, edges, tensionsByDoc, supersededByDoc);
+    const firstHopNeighbors = [...visited.keys()].filter((p) => p !== seedDoc);
+    for (const n of firstHopNeighbors) {
+        if (visited.size >= maxNodes)
+            break;
+        await walkHop(vaultRoot, n, visited, edges, tensionsByDoc, supersededByDoc);
+    }
+    const nodes = trimToCap(seedDoc, visited, edges, maxNodes);
+    const nodePaths = new Set(nodes.map((n) => n.path));
+    return ok({
+        seed_doc: seedDoc,
+        nodes,
+        edges: edges.filter((e) => keepEdge(e, nodePaths)),
+    });
+}
+// An edge is kept when its `from` survived the node cap, and:
+//  - for `link`/`tension`/`superseded` edges, the `to` is also a retained
+//    in-vault node — these reference other vault documents, so a dangling
+//    target means the neighbour was trimmed or never existed and the edge is
+//    meaningless.
+//  - for `sources` edges, the `to` is a provenance citation that is, by the
+//    vault's frontmatter convention, an external source slug rather than an
+//    in-vault `.md` path. Such an edge records real provenance off the seed
+//    doc and is retained even though the cited source is not itself a node.
+function keepEdge(e, nodePaths) {
+    if (!nodePaths.has(e.from))
+        return false;
+    if (e.kind === "sources")
+        return true;
+    return nodePaths.has(e.to);
+}
+async function loadTensionEdges(vaultRoot) {
+    const tensionsByDoc = new Map();
+    const tensionsRes = await listTensions(vaultRoot);
+    if (!tensionsRes.ok)
+        return tensionsByDoc;
+    for (const t of tensionsRes.value) {
+        pushTo(tensionsByDoc, t.sourceA, { other: t.sourceB });
+        pushTo(tensionsByDoc, t.sourceB, { other: t.sourceA });
+    }
+    return tensionsByDoc;
+}
+function stratifyByCollection(paths) {
+    const m = new Map();
+    for (const p of paths) {
+        const collection = p.split("/")[0] || "_root";
+        pushTo(m, collection, p);
+    }
+    return m;
+}
+// Appends `value` to the array at `key`, creating the array on first use.
+// Replaces the `map.get(key)!.push(...)` non-null-assertion idiom that biome's
+// lint/style/noNonNullAssertion rule forbids.
+function pushTo(m, key, value) {
+    const arr = m.get(key);
+    if (arr)
+        arr.push(value);
+    else
+        m.set(key, [value]);
+}
+function hashToIndex(input, mod) {
+    if (mod <= 0)
+        throw new Error("mod must be positive");
+    const h = createHash("sha256").update(input).digest();
+    const n = h.readUInt32BE(0);
+    return n % mod;
+}
+// Loads a document's frontmatter + body into `visited`. Uses the project's
+// canonical parser; on malformed YAML it falls back to empty frontmatter so the
+// walk continues. A missing file is silently skipped.
+async function loadNode(vaultRoot, path, visited) {
+    if (visited.has(path))
+        return;
+    let raw;
+    try {
+        raw = await readFile(resolve(vaultRoot, path), "utf8");
+    }
+    catch {
+        return; // Missing doc — silently skip.
+    }
+    const parsed = parseDocument(raw);
+    if (parsed.ok) {
+        visited.set(path, { path, body: parsed.value.content, frontmatter: parsed.value.raw });
+    }
+    else {
+        visited.set(path, { path, body: raw, frontmatter: {} });
+    }
+}
+async function walkHop(vaultRoot, from, visited, edges, tensionsByDoc, supersededByDoc) {
+    const node = visited.get(from);
+    if (!node)
+        return;
+    const sources = Array.isArray(node.frontmatter.sources)
+        ? node.frontmatter.sources
+        : [];
+    for (const s of sources) {
+        if (typeof s !== "string")
+            continue;
+        edges.push({ from, to: s, kind: "sources" });
+        await loadNode(vaultRoot, s, visited);
+    }
+    const links = extractInVaultLinks(node.body);
+    for (const l of links) {
+        edges.push({ from, to: l, kind: "link" });
+        await loadNode(vaultRoot, l, visited);
+    }
+    const tensions = tensionsByDoc.get(from) ?? [];
+    for (const t of tensions) {
+        edges.push({ from, to: t.other, kind: "tension" });
+        await loadNode(vaultRoot, t.other, visited);
+    }
+    const superseded = supersededByDoc.get(from) ?? [];
+    for (const s of superseded) {
+        edges.push({ from, to: s.other, kind: "superseded" });
+        await loadNode(vaultRoot, s.other, visited);
+    }
+}
+function trimToCap(seed, visited, edges, cap) {
+    if (visited.size <= cap)
+        return [...visited.values()];
+    const degree = new Map();
+    for (const e of edges) {
+        degree.set(e.from, (degree.get(e.from) ?? 0) + 1);
+        degree.set(e.to, (degree.get(e.to) ?? 0) + 1);
+    }
+    const ranked = [...visited.entries()]
+        .map(([path, node]) => ({ path, node, degree: degree.get(path) ?? 0 }))
+        .sort((a, b) => {
+        if (a.path === seed)
+            return -1;
+        if (b.path === seed)
+            return 1;
+        // Higher degree wins; path tiebreak keeps the cut deterministic
+        // independent of engine sort stability.
+        return b.degree - a.degree || a.path.localeCompare(b.path);
+    });
+    return ranked.slice(0, cap).map((r) => r.node);
+}
+// Deliberately matches only standard markdown links to in-vault `.md` files —
+// `[text](path.md)` / `[text](path.md#anchor)`, skipping web/mailto and
+// absolute-rooted hrefs. Wiki-style `[[links]]` are not a Daftari vault
+// convention and are intentionally unsupported.
+function extractInVaultLinks(body) {
+    const out = [];
+    const re = /\[[^\]]*\]\(([^)]+\.md)(?:#[^)]*)?\)/g;
+    for (const m of body.matchAll(re)) {
+        const href = m[1];
+        if (/^https?:|^mailto:/i.test(href))
+            continue;
+        if (href.startsWith("/"))
+            continue;
+        out.push(href);
+    }
+    return out;
+}
+//# sourceMappingURL=subgraph.js.map

package/dist/eval/subgraph.js.map

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

package/dist/eval/tool-surface.d.ts

@@ -0,0 +1,7 @@
+import type { ToolDef } from "./llm.js";
+export interface ToolSurface {
+    defs: ToolDef[];
+    handler: (name: string, input: unknown) => Promise<unknown>;
+}
+export declare function buildToolSurface(vaultRoot: string): ToolSurface;
+//# sourceMappingURL=tool-surface.d.ts.map

package/dist/eval/tool-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-surface.d.ts","sourceRoot":"","sources":["../../src/eval/tool-surface.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7D;AAiID,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAyB/D"}

package/dist/eval/tool-surface.js

@@ -0,0 +1,160 @@
+// src/eval/tool-surface.ts
+// In-process MCP tool surface for the answerer LLM. A thin adapter over the
+// existing src/tools/* handlers — no MCP serialization, no transport, no
+// stdio. The answerer calls these directly via the LlmClient tool loop.
+//
+// vault_tension_log is INTENTIONALLY EXCLUDED: it is a write tool, and the
+// answerer is strictly read-only. Exposing a write tool to the answerer would
+// let it mutate the vault mid-eval, which would corrupt the measurement.
+//
+// access is passed as `undefined` to every handler, which bypasses RBAC. This
+// is intended: eval runs locally against a snapshot, there is no user identity.
+import { vaultLint, vaultTensionBlast, vaultTensionClusters } from "../tools/curation.js";
+import { vaultRead } from "../tools/read.js";
+import { vaultSearch, vaultSearchRelated } from "../tools/search.js";
+import { vaultThemes } from "../tools/themes.js";
+// Awaits a tool handler's Result and flattens it to either the value or a
+// `{ tool_error }` envelope. Never throws — a rejected promise still surfaces
+// as a tool_error so the answerer can react instead of crashing the run.
+async function unwrap(p) {
+    try {
+        const r = await p;
+        return r.ok ? r.value : { tool_error: r.error.message };
+    }
+    catch (e) {
+        return { tool_error: e instanceof Error ? e.message : String(e) };
+    }
+}
+const TOOL_DEFS = [
+    {
+        name: "vault_read",
+        description: "Read a single vault document. Returns its markdown body, parsed " +
+            "frontmatter, and metadata. Path is relative to the vault root.",
+        input_schema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Vault-relative path to the markdown file, e.g. competitive-intel/foo.md",
+                },
+            },
+            required: ["path"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "vault_search",
+        description: "Hybrid search across the vault: BM25 lexical ranking combined with " +
+            "vector semantic similarity. Returns ranked documents with snippets.",
+        input_schema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Free-text search query" },
+                limit: { type: "number", description: "Maximum results to return (default 10, max 50)" },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "vault_search_related",
+        description: "Find documents related to a given vault document. Uses that document's " +
+            "own text and embeddings as the query; the document itself is excluded. " +
+            "Path is relative to the vault root.",
+        input_schema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Vault-relative path of the reference document" },
+                limit: { type: "number", description: "Maximum results to return (default 10, max 50)" },
+            },
+            required: ["path"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "vault_themes",
+        description: "Surface thematic clusters across the vault using k-means over " +
+            "document-pooled embeddings. Each theme reports a label, coherence " +
+            "score, representative documents, and frequent tags.",
+        input_schema: {
+            type: "object",
+            properties: {
+                k: { type: "integer", description: "Optional explicit cluster count.", minimum: 1 },
+                collection: {
+                    type: "string",
+                    description: "Restrict clustering to documents in this collection.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "vault_lint",
+        description: "Run the advisory curation checks across the vault: stale files, " +
+            "orphans, old drafts, stagnant low-confidence files, deprecated files " +
+            "still linked, unanswered questions, and tension health. Reports " +
+            "problems; never auto-fixes. Optionally filter to a single check.",
+        input_schema: {
+            type: "object",
+            properties: {
+                filter: { type: "string", description: "Restrict the report to a single check" },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "vault_tension_blast",
+        description: "Compute the transitive closure of downstream documents that cite or " +
+            "link a contested document — or the union over a contested cluster. " +
+            "Accepts exactly one of 'document' (vault-relative path) or 'cluster_id'.",
+        input_schema: {
+            type: "object",
+            properties: {
+                document: { type: "string", description: "Vault-relative path of a contested document" },
+                cluster_id: {
+                    type: "string",
+                    description: "A content-addressed cluster id from vault_tension_clusters",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "vault_tension_clusters",
+        description: "Compute connected components of the tension graph: groups of vault " +
+            "documents joined transitively by unresolved tensions. Each cluster " +
+            "reports its members, in-scope tension count, tally by kind, and age " +
+            "range. Read-only.",
+        input_schema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+    },
+];
+export function buildToolSurface(vaultRoot) {
+    // biome-ignore lint/suspicious/noExplicitAny: tool inputs are structural JSON from the LLM
+    const handler = async (name, input) => {
+        const inp = input ?? {};
+        switch (name) {
+            case "vault_read":
+                return unwrap(vaultRead(vaultRoot, String(inp.path ?? ""), undefined));
+            case "vault_search":
+                return unwrap(vaultSearch(vaultRoot, inp, undefined));
+            case "vault_search_related":
+                return unwrap(vaultSearchRelated(vaultRoot, inp, undefined));
+            case "vault_themes":
+                return unwrap(vaultThemes(vaultRoot, inp, undefined));
+            case "vault_lint":
+                return unwrap(vaultLint(vaultRoot, inp, undefined));
+            case "vault_tension_blast":
+                return unwrap(vaultTensionBlast(vaultRoot, inp, undefined));
+            case "vault_tension_clusters":
+                return unwrap(vaultTensionClusters(vaultRoot, inp, undefined));
+            default:
+                return { tool_error: `unknown tool: ${name}` };
+        }
+    };
+    return { defs: TOOL_DEFS, handler };
+}
+//# sourceMappingURL=tool-surface.js.map

package/dist/eval/tool-surface.js.map

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

package/dist/eval/types.d.ts

@@ -0,0 +1,173 @@
+import type { Result } from "../frontmatter/types.js";
+export declare const TIERS: readonly ["retrieval", "cross_reference", "contradiction"];
+export type Tier = (typeof TIERS)[number];
+export declare const TIER_WEIGHT: Record<Tier, number>;
+export interface Question {
+    id: string;
+    tier: Tier;
+    question: string;
+    expected_answer: string;
+    expected_sources: string[];
+    origin: "generated" | "augmented";
+}
+export interface QuestionSet {
+    id: string;
+    vault_hash: string;
+    seed: string;
+    timestamp: string;
+    subgraph: {
+        seed_doc: string;
+        nodes: string[];
+        edges: SubgraphEdge[];
+    };
+    questions: Question[];
+    generator_model: string;
+    prompt_version: number;
+    tier_counts_requested: Record<Tier, number>;
+    tier_counts_produced: Record<Tier, number>;
+}
+export interface SubgraphEdge {
+    from: string;
+    to: string;
+    kind: "sources" | "link" | "tension" | "superseded";
+}
+export interface Trace {
+    tool_calls: ToolCall[];
+    final_answer: string;
+    total_tool_calls: number;
+    input_tokens: number;
+    output_tokens: number;
+    wall_ms: number;
+    stop_reason: string;
+}
+export interface ToolCall {
+    tool: string;
+    input: unknown;
+    output: unknown;
+    latency_ms: number;
+}
+export type RunStatus = "complete" | "incomplete";
+interface PerRunResultBase {
+    question_id: string;
+    question_index: number;
+    k_index: number;
+}
+export type PerRunResult = (PerRunResultBase & {
+    status: "complete";
+    trace: Trace;
+}) | (PerRunResultBase & {
+    status: "incomplete";
+    trace: null;
+});
+export interface EvalRun {
+    id: string;
+    questions_id: string;
+    answerer_model: string;
+    prompt_version: number;
+    timestamp: string;
+    k: number;
+    runs: Record<string, PerRunResult>;
+}
+export type GradeVerdict = "yes" | "partial" | "no" | "ungraded";
+export interface Grade {
+    question_id: string;
+    question_index: number;
+    k_index: number;
+    verdict: GradeVerdict;
+    reasoning: string;
+    grader_model: string;
+}
+export interface TierScore {
+    mean: number;
+    std: number;
+    n: number;
+    trace_efficiency: number;
+}
+export interface Score {
+    score: number;
+    score_std: number;
+    by_tier: Record<Tier, TierScore>;
+    models: {
+        generator: string;
+        answerer: string;
+        grader: string;
+    };
+    prompt_version: number;
+    spec_version: number;
+    questions_id: string;
+    results_id: string;
+    vault_hash: string;
+    k: number;
+    n: number;
+    timestamp: string;
+}
+export interface HistoryEntry {
+    score_id: string;
+    score: number;
+    score_std: number;
+    by_tier: Record<Tier, number>;
+    vault_hash: string;
+    timestamp: string;
+    n: number;
+    k: number;
+    models: {
+        generator: string;
+        answerer: string;
+        grader: string;
+    };
+    prompt_version: number;
+    spec_version: number;
+}
+export interface HistoryFile {
+    version: 1;
+    runs: HistoryEntry[];
+}
+export declare const HISTORY_RETENTION = 50;
+export declare const SPEC_VERSION = 1;
+export type CortexEvalError = {
+    kind: "config";
+    message: string;
+} | {
+    kind: "runtime";
+    message: string;
+} | {
+    kind: "llm";
+    message: string;
+    retryable: boolean;
+};
+export declare const QuestionSetSchema: {
+    readonly type: "object";
+    readonly required: readonly ["questions"];
+    readonly properties: {
+        readonly questions: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["tier", "question", "expected_answer", "expected_sources"];
+                readonly properties: {
+                    readonly tier: {
+                        readonly enum: readonly ["retrieval", "cross_reference", "contradiction"];
+                    };
+                    readonly question: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly expected_answer: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly expected_sources: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly minItems: 1;
+                    };
+                };
+            };
+        };
+    };
+};
+export type { Result };
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/eval/types.js

@@ -0,0 +1,44 @@
+// src/eval/types.ts
+// Shared types for the cortex quality metric. Pure data shapes; no logic.
+// See docs/superpowers/specs/2026-05-31-cortex-quality-metric-design.md.
+// --- Tiers ---
+export const TIERS = ["retrieval", "cross_reference", "contradiction"];
+// Tier weight for the aggregate score formula.
+export const TIER_WEIGHT = {
+    retrieval: 1,
+    cross_reference: 2,
+    contradiction: 3,
+};
+export const HISTORY_RETENTION = 50;
+export const SPEC_VERSION = 1;
+// --- JSON Schema for generator output ---
+// The generator LLM is asked to return JSON matching this schema. Embedded
+// here so the prompt, runtime validator, and types share one source of truth.
+// NOTE: kept in sync MANUALLY with the `Question` interface above — there is no
+// codegen between them. When you add/rename a Question field that the generator
+// produces, update both this schema and `Question` in the same edit. (`id` and
+// `origin` are assigned post-generation, so they are intentionally absent here.)
+export const QuestionSetSchema = {
+    type: "object",
+    required: ["questions"],
+    properties: {
+        questions: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["tier", "question", "expected_answer", "expected_sources"],
+                properties: {
+                    tier: { enum: TIERS },
+                    question: { type: "string", minLength: 1 },
+                    expected_answer: { type: "string", minLength: 1 },
+                    expected_sources: {
+                        type: "array",
+                        items: { type: "string", minLength: 1 },
+                        minItems: 1,
+                    },
+                },
+            },
+        },
+    },
+};
+//# sourceMappingURL=types.js.map

package/dist/eval/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/eval/types.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB,0EAA0E;AAC1E,yEAAyE;AAIzE,gBAAgB;AAEhB,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,WAAW,EAAE,iBAAiB,EAAE,eAAe,CAAU,CAAC;AAGhF,+CAA+C;AAC/C,MAAM,CAAC,MAAM,WAAW,GAAyB;IAC/C,SAAS,EAAE,CAAC;IACZ,eAAe,EAAE,CAAC;IAClB,aAAa,EAAE,CAAC;CACjB,CAAC;AAyIF,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AACpC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC;AAa9B,2CAA2C;AAC3C,2EAA2E;AAC3E,8EAA8E;AAC9E,gFAAgF;AAChF,gFAAgF;AAChF,+EAA+E;AAC/E,iFAAiF;AAEjF,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,IAAI,EAAE,QAAQ;IACd,QAAQ,EAAE,CAAC,WAAW,CAAC;IACvB,UAAU,EAAE;QACV,SAAS,EAAE;YACT,IAAI,EAAE,OAAO;YACb,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,iBAAiB,EAAE,kBAAkB,CAAC;gBACrE,UAAU,EAAE;oBACV,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE;oBACrB,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;oBAC1C,eAAe,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;oBACjD,gBAAgB,EAAE;wBAChB,IAAI,EAAE,OAAO;wBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;wBACvC,QAAQ,EAAE,CAAC;qBACZ;iBACF;aACF;SACF;KACF;CACO,CAAC"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAuCA,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASrE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAE3D;AAED,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CA4HhF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwCA,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASrE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAE3D;AAED,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAuIhF"}