@cavelang/cli 0.27.14 → 0.29.1

package/dist/internal/connect/template.js

@@ -0,0 +1,221 @@
+/**
+ * Mapping templates (spec §23.1) — an ordinary CAVE document whose `?field`
+ * variables stand for record fields.
+ *
+ * Top-level blocks (a line plus its indented children) split by whether they
+ * contain a variable: variable-free blocks form the **prelude** (verb
+ * declarations, static claims — appended once per run), blocks with
+ * variables are **record templates**, instantiated once per record.
+ *
+ * A variable is a whole whitespace-delimited token beginning with `?`;
+ * tokens inside `"…"` and `` `…` `` literals are never substituted. A claim
+ * line whose record lacks a referenced field is dropped together with its
+ * indented children — optional fields simply yield fewer claims.
+ */
+import { Value, Verb } from '@cavelang/core';
+import { parseDocument, Token } from '@cavelang/parser';
+const isVariable = (token) => token.kind === 'word' && token.text.startsWith('?') && token.text.length > 1;
+const indentOf = (line) => line.length - line.trimStart().length;
+const isStructural = (line) => {
+    const body = line.trim();
+    return body !== '' && !body.startsWith(';');
+};
+const lineVariables = (line) => Token.tokenize(Token.splitComment(line).head)
+    .filter(isVariable)
+    .map(token => token.text.slice(1));
+/**
+ * Parses a mapping document: lints it (variables parse as ordinary terms, so
+ * diagnostics are real syntax problems), rejects variables in attribute
+ * position (`?attr: …` would silently name an attribute `?attr`), and splits
+ * top-level blocks into prelude and record templates.
+ */
+export const parse = (text) => {
+    const problems = [];
+    const document = parseDocument(text);
+    for (const diagnostic of document.diagnostics) {
+        problems.push(`mapping line ${diagnostic.line}: ${diagnostic.message}`);
+    }
+    const rawLines = text.split(/\r?\n/);
+    rawLines.forEach((line, at) => {
+        for (const token of Token.tokenize(Token.splitComment(line).head)) {
+            if (token.kind === 'word' && /^\?.+:$/.test(token.text)) {
+                problems.push(`mapping line ${at + 1}: variables cannot name attributes (${token.text})`);
+            }
+        }
+    });
+    if (problems.length > 0) {
+        return { problems };
+    }
+    const blocks = [];
+    const preamble = [];
+    for (const line of rawLines) {
+        if (isStructural(line) && indentOf(line) === 0) {
+            blocks.push([line]);
+        }
+        else if (blocks.length === 0) {
+            preamble.push(line);
+        }
+        else {
+            blocks[blocks.length - 1].push(line);
+        }
+    }
+    const preludeParts = [...preamble];
+    const templates = [];
+    const variables = new Set();
+    for (const block of blocks) {
+        const names = block.flatMap(lineVariables);
+        if (names.length === 0) {
+            preludeParts.push(...block);
+        }
+        else {
+            names.forEach(name => variables.add(name));
+            templates.push(block);
+        }
+    }
+    return {
+        mapping: {
+            prelude: preludeParts.join('\n').trim() === '' ? '' : `${preludeParts.join('\n').trimEnd()}\n`,
+            templates,
+            variables: [...variables].sort()
+        },
+        problems
+    };
+};
+const safeAtomRe = /^[A-Za-z0-9][A-Za-z0-9._/+-]*$/;
+/**
+ * Formats one field value for one template slot (spec §23.1). Deterministic
+ * and exact — values insert verbatim when already token-safe, or as quoted
+ * literals; formatting never invents names (no slugification).
+ */
+export const formatValue = (value, position) => {
+    if (value === undefined || value === null) {
+        return { kind: 'missing' };
+    }
+    if (typeof value === 'number') {
+        // Plain decimal, never String's exponent notation — `1e-7` is not a
+        // CAVE number (spec §16) and would round-trip as an atom.
+        return Number.isFinite(value) ?
+            { kind: 'ok', text: Value.formatNumber(value) } :
+            { kind: 'problem', message: 'non-finite number' };
+    }
+    if (typeof value === 'boolean') {
+        return { kind: 'ok', text: value ? 'true' : 'false' };
+    }
+    if (typeof value !== 'string') {
+        return { kind: 'problem', message: `unsupported field type (${Array.isArray(value) ? 'array' : typeof value})` };
+    }
+    const text = value.replace(/[\r\n]+/g, ' ').trim();
+    if (text === '') {
+        return { kind: 'missing' };
+    }
+    if (safeAtomRe.test(text) && !Verb.isVerbToken(text)) {
+        return { kind: 'ok', text };
+    }
+    if (position === 'payload') {
+        const parsed = Value.parse(text);
+        if (parsed.kind === 'number' || parsed.kind === 'date' || parsed.kind === 'trajectory') {
+            return { kind: 'ok', text };
+        }
+    }
+    if (!text.includes('"')) {
+        return { kind: 'ok', text: `"${text}"` };
+    }
+    if (!text.includes('`')) {
+        return { kind: 'ok', text: `\`${text}\`` };
+    }
+    return { kind: 'problem', message: 'value contains both " and ` — cannot quote' };
+};
+/**
+ * Resolves a field by name: exact key first, then a dot path into nested
+ * JSON (`address.city`, `items.0.sku`).
+ */
+export const fieldOf = (record, name) => {
+    if (record !== null && typeof record === 'object' && name in record) {
+        return record[name];
+    }
+    let current = record;
+    for (const part of name.split('.')) {
+        if (current === null || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+};
+const formatToken = (token) => {
+    switch (token.kind) {
+        case 'text':
+            return `"${token.text}"`;
+        case 'code':
+            return `\`${token.text}\``;
+        default:
+            return token.text;
+    }
+};
+const substituteLine = (line, lookup) => {
+    const indent = line.slice(0, indentOf(line));
+    const { head, comment } = Token.splitComment(line);
+    const tokens = Token.tokenize(head);
+    const parts = [];
+    for (const [at, token] of tokens.entries()) {
+        if (!isVariable(token)) {
+            parts.push(formatToken(token));
+            continue;
+        }
+        const name = token.text.slice(1);
+        const formatted = formatValue(lookup(name), at === 0 ? 'subject' : 'payload');
+        switch (formatted.kind) {
+            case 'missing':
+                return { kind: 'dropped' };
+            case 'problem':
+                return { kind: 'problem', message: `?${name}: ${formatted.message}` };
+            default:
+                parts.push(formatted.text);
+        }
+    }
+    return { kind: 'ok', line: `${indent}${parts.join(' ')}${comment === undefined ? '' : ` ; ${comment}`}` };
+};
+/**
+ * Instantiates every template block for one record. Lines without variables
+ * pass through verbatim; a dropped line takes its indented children with it.
+ */
+export const instantiate = (templates, lookup) => {
+    const out = [];
+    const problems = [];
+    let dropped = 0;
+    for (const block of templates) {
+        let skipDeeperThan;
+        for (const line of block) {
+            if (!isStructural(line)) {
+                out.push(line);
+                continue;
+            }
+            const indent = indentOf(line);
+            if (skipDeeperThan !== undefined && indent > skipDeeperThan) {
+                dropped += 1;
+                continue;
+            }
+            skipDeeperThan = undefined;
+            if (lineVariables(line).length === 0) {
+                out.push(line);
+                continue;
+            }
+            const substituted = substituteLine(line, lookup);
+            switch (substituted.kind) {
+                case 'dropped':
+                    dropped += 1;
+                    skipDeeperThan = indent;
+                    break;
+                case 'problem':
+                    problems.push(substituted.message);
+                    skipDeeperThan = indent;
+                    break;
+                default:
+                    out.push(substituted.line);
+            }
+        }
+    }
+    const body = out.join('\n').trim();
+    return { text: body === '' ? '' : `${out.join('\n').trimEnd()}\n`, dropped, problems };
+};
+//# sourceMappingURL=template.js.map

package/dist/internal/connect/template.js.map

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

package/dist/internal/eval/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@cavelang/cli/eval` — golden-fixture extraction and query evals
+ * and reconstruction policy evaluation.
+ *
+ * ```sh
+ * cave eval suite/ --agent 'claude -p --mcp-config {mcp-config} --allowedTools "mcp__cave__*"'
+ * ```
+ *
+ * Library API for SDK scripts (agents and judges may be functions):
+ *
+ * ```ts
+ * import { run } from '@cavelang/cli/eval'
+ *
+ * const report = await run({
+ *   suites: ['suite/'], mode: 'stdout', runs: 3,
+ *   agent: async prompt => callYourSdk(prompt)   // returns CAVE text
+ * })
+ * ```
+ */
+export * as Suite from './suite.ts';
+export * as Score from './score.ts';
+export * as Queries from './queries.ts';
+export * as Loop from './loop.ts';
+export { judgePrompt, parsePairs } from './judge.ts';
+export { fixtureCount, run } from './run.ts';
+export type { Agent, CaseReport, Judge, Mean, Options, Report, RunReport } from './run.ts';
+export { meetsMin, render, runEval } from './main.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/internal/eval/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AACjC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAC5C,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAC1F,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA"}

package/dist/internal/eval/index.js

@@ -0,0 +1,27 @@
+/**
+ * `@cavelang/cli/eval` — golden-fixture extraction and query evals
+ * and reconstruction policy evaluation.
+ *
+ * ```sh
+ * cave eval suite/ --agent 'claude -p --mcp-config {mcp-config} --allowedTools "mcp__cave__*"'
+ * ```
+ *
+ * Library API for SDK scripts (agents and judges may be functions):
+ *
+ * ```ts
+ * import { run } from '@cavelang/cli/eval'
+ *
+ * const report = await run({
+ *   suites: ['suite/'], mode: 'stdout', runs: 3,
+ *   agent: async prompt => callYourSdk(prompt)   // returns CAVE text
+ * })
+ * ```
+ */
+export * as Suite from "./suite.js";
+export * as Score from "./score.js";
+export * as Queries from "./queries.js";
+export * as Loop from "./loop.js";
+export { judgePrompt, parsePairs } from "./judge.js";
+export { fixtureCount, run } from "./run.js";
+export { meetsMin, render, runEval } from "./main.js";
+//# sourceMappingURL=index.js.map

package/dist/internal/eval/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AACjC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA"}

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

@@ -0,0 +1,30 @@
+/**
+ * The optional LLM judge — semantic-equivalence pairing
+ * of what claim-key scoring could not match.
+ *
+ * Exact keys are deliberately strict: `grandma-maria` and `maria` are
+ * different entities to the scorer even when a human sees one person.
+ * The judge closes that gap without loosening the metric — after strict
+ * matching, the unmatched golden claims and unmatched produced claims go
+ * to a judge agent that pairs the ones stating the same fact. Judged
+ * pairs never overwrite the strict scores; they produce a second,
+ * *judged* precision/recall/F1 reported alongside.
+ *
+ * The protocol is the same as extraction agents (`@cavelang/cli/ingest`): a
+ * shell template (prompt on stdin and `{prompt-file}`) or an injected
+ * function. The judge replies with one JSON array of `[G, P]` 1-based
+ * index pairs — anything around it (prose, a code fence) is tolerated,
+ * only the last well-formed array counts, out-of-range or duplicate
+ * indices are dropped.
+ */
+import type { Fact } from './score.ts';
+/** @returns the judge prompt for unmatched golden/produced claims. */
+export declare const judgePrompt: (misses: readonly Fact[], extras: readonly Fact[]) => string;
+/**
+ * Parses the judge's reply into validated 0-based `[miss, extra]` pairs.
+ * The *last* well-formed JSON array wins (agents often think aloud before
+ * answering); malformed entries, out-of-range indices and reused indices
+ * are dropped rather than failing the run.
+ */
+export declare const parsePairs: (output: string, misses: number, extras: number) => [number, number][];
+//# sourceMappingURL=judge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"judge.d.ts","sourceRoot":"","sources":["../../src/judge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC,sEAAsE;AACtE,eAAO,MAAM,WAAW,GAAI,QAAQ,SAAS,IAAI,EAAE,EAAE,QAAQ,SAAS,IAAI,EAAE,KAAG,MAmBnE,CAAA;AAEZ;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,EAAE,QAAQ,MAAM,EAAE,QAAQ,MAAM,KAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAkD3F,CAAA"}

package/dist/internal/eval/judge.js

@@ -0,0 +1,101 @@
+/**
+ * The optional LLM judge — semantic-equivalence pairing
+ * of what claim-key scoring could not match.
+ *
+ * Exact keys are deliberately strict: `grandma-maria` and `maria` are
+ * different entities to the scorer even when a human sees one person.
+ * The judge closes that gap without loosening the metric — after strict
+ * matching, the unmatched golden claims and unmatched produced claims go
+ * to a judge agent that pairs the ones stating the same fact. Judged
+ * pairs never overwrite the strict scores; they produce a second,
+ * *judged* precision/recall/F1 reported alongside.
+ *
+ * The protocol is the same as extraction agents (`@cavelang/cli/ingest`): a
+ * shell template (prompt on stdin and `{prompt-file}`) or an injected
+ * function. The judge replies with one JSON array of `[G, P]` 1-based
+ * index pairs — anything around it (prose, a code fence) is tolerated,
+ * only the last well-formed array counts, out-of-range or duplicate
+ * indices are dropped.
+ */
+import { lineOf } from "./score.js";
+/** @returns the judge prompt for unmatched golden/produced claims. */
+export const judgePrompt = (misses, extras) => [
+    'You are judging a knowledge-extraction eval written in CAVE — one atomic claim per line:',
+    'subject VERB object, or subject HAS attribute: value, with optional @context, #tag and @ N% confidence.',
+    '',
+    'The golden claims below were expected but not produced verbatim; the produced claims were',
+    'extracted but match no golden claim. Pair every golden claim with a produced claim ONLY when',
+    'both state the same fact about the same real-world entity — tolerate naming, spelling and',
+    'phrasing variation (grandma-maria vs maria), but never pair claims that disagree in meaning,',
+    'direction or value. Judge conservatively: when unsure, do not pair. Each index may appear in',
+    'at most one pair.',
+    '',
+    'Golden claims not produced:',
+    ...misses.map((fact, index) => `G${index + 1}: ${lineOf(fact)}`),
+    '',
+    'Produced claims matching no golden claim:',
+    ...extras.map((fact, index) => `P${index + 1}: ${lineOf(fact)}`),
+    '',
+    'Reply with ONLY a JSON array of [golden, produced] index pairs, e.g. [[1, 2], [3, 1]].',
+    'Reply [] when nothing is equivalent.'
+].join('\n');
+/**
+ * Parses the judge's reply into validated 0-based `[miss, extra]` pairs.
+ * The *last* well-formed JSON array wins (agents often think aloud before
+ * answering); malformed entries, out-of-range indices and reused indices
+ * are dropped rather than failing the run.
+ */
+export const parsePairs = (output, misses, extras) => {
+    // Balanced-bracket scan: each candidate runs from a `[` to its matching
+    // `]`; a span that parses is consumed whole (inner arrays are not
+    // re-considered), one that does not is re-entered at the next `[` — so
+    // prose brackets before the answer cannot swallow it.
+    let parsed;
+    let at = output.indexOf('[');
+    while (at !== -1) {
+        let depth = 0;
+        let end = -1;
+        for (let scan = at; scan < output.length; scan += 1) {
+            if (output[scan] === '[') {
+                depth += 1;
+            }
+            else if (output[scan] === ']' && --depth === 0) {
+                end = scan;
+                break;
+            }
+        }
+        if (end === -1) {
+            break;
+        }
+        try {
+            parsed = JSON.parse(output.slice(at, end + 1));
+            at = output.indexOf('[', end + 1);
+        }
+        catch {
+            at = output.indexOf('[', at + 1);
+        }
+    }
+    if (!Array.isArray(parsed)) {
+        return [];
+    }
+    const pairs = [];
+    const usedMisses = new Set();
+    const usedExtras = new Set();
+    for (const entry of parsed) {
+        if (!Array.isArray(entry) || entry.length !== 2) {
+            continue;
+        }
+        const [golden, produced] = entry;
+        if (typeof golden !== 'number' || typeof produced !== 'number' ||
+            !Number.isInteger(golden) || !Number.isInteger(produced) ||
+            golden < 1 || golden > misses || produced < 1 || produced > extras ||
+            usedMisses.has(golden) || usedExtras.has(produced)) {
+            continue;
+        }
+        usedMisses.add(golden);
+        usedExtras.add(produced);
+        pairs.push([golden - 1, produced - 1]);
+    }
+    return pairs;
+};
+//# sourceMappingURL=judge.js.map

package/dist/internal/eval/judge.js.map

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

package/dist/internal/eval/loop.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Reconstruction (loop) cases — spec §18 evaluation.
+ *
+ * A case whose golden has a `<stem>.loop.cave` sibling evals the
+ * §18 reconstruction loop instead of extraction: the source is the
+ * *knowledge* (CAVE text), the loop file declares the seeds and budgets,
+ * and the golden is the claims a good reconstruction collects. Without an
+ * agent the deterministic heuristic policy runs — the baseline every LLM
+ * policy is measured against; with `--agent` the same seeds drive
+ * `llmPolicy` over the shell-agent template (one completion per step).
+ *
+ * The loop file is ordinary CAVE text about the entity `loop` — the
+ * existing parser, no new grammar:
+ *
+ * ```cave
+ * loop SEEDS reject-valid-tokens
+ * loop HAS query: `why are valid tokens rejected?`
+ * loop HAS steps: 12
+ * loop HAS claims: 40
+ * ```
+ *
+ * `SEEDS` claims keep file order (the initial frontier); `query`, `steps`
+ * and `claims` are attributes — several claims on one attribute follow
+ * belief semantics, the last wins. Anything else in the file is a fixture
+ * problem: a misspelled knob must scream, not silently default.
+ */
+import type { Registry } from '@cavelang/canonical';
+import type { Reconstruction } from '@cavelang/cli/loop';
+export type Spec = {
+    /** Seed entities, in file order — the initial frontier. */
+    readonly seeds: readonly string[];
+    /** Shown to the LLM policy each step; the heuristic ignores it. */
+    readonly query?: string;
+    /** Step budget for both policies (their shared default when absent). */
+    readonly maxSteps?: number;
+    /** Claim budget for both policies. */
+    readonly maxClaims?: number;
+};
+/**
+ * Parses and strictly validates a loop file. Problems are fixture
+ * problems — an unknown verb, subject or attribute fails the case
+ * instead of being skipped.
+ */
+export declare const parseSpec: (text: string, registry: Registry.t) => {
+    spec: Spec;
+    problems: readonly string[];
+};
+/** The agent contract of one reconstruction run: prompt in, reply out. */
+export type Complete = (prompt: string) => Promise<string>;
+export type RunOptions = {
+    /** Shell-agent template or completion function; absent = the heuristic baseline. */
+    readonly agent?: string | Complete;
+    readonly timeoutSeconds?: number;
+    readonly cwd?: string;
+};
+/**
+ * Runs one reconstruction over the knowledge: the heuristic baseline
+ * without an agent, `llmPolicy` over the agent otherwise. Both policies
+ * get the same budgets, so their scores compare like for like.
+ */
+export declare const runSpec: (knowledge: string, spec: Spec, registry: Registry.t, options?: RunOptions) => Promise<Reconstruction>;
+/** One-line expansion summary for run notes: `a → b → c`. */
+export declare const traceNote: (reconstruction: Reconstruction) => string;
+//# sourceMappingURL=loop.d.ts.map

package/dist/internal/eval/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAInD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpD,MAAM,MAAM,IAAI,GAAG;IACjB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,mEAAmE;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B,CAAA;AAMD;;;;GAIG;AACH,eAAO,MAAM,SAAS,GACpB,MAAM,MAAM,EACZ,UAAU,QAAQ,CAAC,CAAC,KACnB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAsD3C,CAAA;AAED,0EAA0E;AAC1E,MAAM,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;AAE1D,MAAM,MAAM,UAAU,GAAG;IACvB,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAClC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,OAAO,GAClB,WAAW,MAAM,EACjB,MAAM,IAAI,EACV,UAAU,QAAQ,CAAC,CAAC,EACpB,UAAS,UAAe,KACvB,OAAO,CAAC,cAAc,CAoBxB,CAAA;AAED,6DAA6D;AAC7D,eAAO,MAAM,SAAS,GAAI,gBAAgB,cAAc,KAAG,MAEmB,CAAA"}

package/dist/internal/eval/loop.js

@@ -0,0 +1,123 @@
+/**
+ * Reconstruction (loop) cases — spec §18 evaluation.
+ *
+ * A case whose golden has a `<stem>.loop.cave` sibling evals the
+ * §18 reconstruction loop instead of extraction: the source is the
+ * *knowledge* (CAVE text), the loop file declares the seeds and budgets,
+ * and the golden is the claims a good reconstruction collects. Without an
+ * agent the deterministic heuristic policy runs — the baseline every LLM
+ * policy is measured against; with `--agent` the same seeds drive
+ * `llmPolicy` over the shell-agent template (one completion per step).
+ *
+ * The loop file is ordinary CAVE text about the entity `loop` — the
+ * existing parser, no new grammar:
+ *
+ * ```cave
+ * loop SEEDS reject-valid-tokens
+ * loop HAS query: `why are valid tokens rejected?`
+ * loop HAS steps: 12
+ * loop HAS claims: 40
+ * ```
+ *
+ * `SEEDS` claims keep file order (the initial frontier); `query`, `steps`
+ * and `claims` are attributes — several claims on one attribute follow
+ * belief semantics, the last wins. Anything else in the file is a fixture
+ * problem: a misspelled knob must scream, not silently default.
+ */
+import { Claim } from '@cavelang/core';
+import { canonicalizeText } from '@cavelang/canonical';
+import { heuristicPolicy, llmPolicy, memoryStoreOfText, reconstruct, reconstructAsync, shellComplete } from '@cavelang/cli/loop';
+const subject = 'loop';
+const seedVerb = 'SEEDS';
+const budgetAttributes = ['steps', 'claims'];
+/**
+ * Parses and strictly validates a loop file. Problems are fixture
+ * problems — an unknown verb, subject or attribute fails the case
+ * instead of being skipped.
+ */
+export const parseSpec = (text, registry) => {
+    const result = canonicalizeText(text, registry);
+    const problems = result.problems.map(problem => `loop line ${problem.line}: ${problem.message}`);
+    const seeds = [];
+    let query;
+    const budgets = new Map();
+    for (const { claim, line } of result.claims) {
+        const problem = (message) => {
+            problems.push(`loop line ${line}: ${message}`);
+        };
+        if (Claim.formatTerm(claim.subject) !== subject) {
+            problem(`expected subject '${subject}', got '${Claim.formatTerm(claim.subject)}'`);
+            continue;
+        }
+        if (claim.verb === seedVerb && claim.payload.kind === 'relation') {
+            const seed = Claim.formatTerm(claim.payload.object);
+            if (!seeds.includes(seed)) {
+                seeds.push(seed);
+            }
+            continue;
+        }
+        if (claim.verb === 'HAS' && claim.payload.kind === 'attribute') {
+            const { attribute, value } = claim.payload;
+            if (attribute === 'query') {
+                query = value.raw;
+                continue;
+            }
+            if (budgetAttributes.includes(attribute)) {
+                if (value.num === undefined || !Number.isInteger(value.num) || value.num < 1) {
+                    problem(`${attribute} must be a positive integer, got '${value.raw}'`);
+                }
+                else {
+                    budgets.set(attribute, value.num);
+                }
+                continue;
+            }
+            problem(`unknown attribute '${attribute}' — expected query, steps or claims`);
+            continue;
+        }
+        problem(`expected '${subject} ${seedVerb} <entity>' or '${subject} HAS query|steps|claims: …'`);
+    }
+    if (seeds.length === 0) {
+        problems.push(`loop file declares no seeds — at least one '${subject} ${seedVerb} <entity>' line is required`);
+    }
+    const steps = budgets.get('steps');
+    const claims = budgets.get('claims');
+    return {
+        spec: {
+            seeds,
+            ...query === undefined ? {} : { query },
+            ...steps === undefined ? {} : { maxSteps: steps },
+            ...claims === undefined ? {} : { maxClaims: claims }
+        },
+        problems
+    };
+};
+/**
+ * Runs one reconstruction over the knowledge: the heuristic baseline
+ * without an agent, `llmPolicy` over the agent otherwise. Both policies
+ * get the same budgets, so their scores compare like for like.
+ */
+export const runSpec = (knowledge, spec, registry, options = {}) => {
+    const store = memoryStoreOfText(knowledge, registry);
+    const budgets = {
+        ...spec.maxSteps === undefined ? {} : { maxSteps: spec.maxSteps },
+        ...spec.maxClaims === undefined ? {} : { maxClaims: spec.maxClaims }
+    };
+    if (options.agent === undefined) {
+        return Promise.resolve(reconstruct(store, heuristicPolicy(budgets), spec.seeds));
+    }
+    const complete = typeof options.agent === 'function' ?
+        options.agent :
+        shellComplete(options.agent, {
+            ...options.timeoutSeconds === undefined ? {} : { timeoutSeconds: options.timeoutSeconds },
+            ...options.cwd === undefined ? {} : { cwd: options.cwd }
+        });
+    const policy = llmPolicy(complete, {
+        ...spec.query === undefined ? {} : { query: spec.query },
+        ...budgets
+    });
+    return reconstructAsync(store, policy, spec.seeds);
+};
+/** One-line expansion summary for run notes: `a → b → c`. */
+export const traceNote = (reconstruction) => `expanded ${reconstruction.trace.length} cue(s): ` +
+    `${reconstruction.trace.map(step => step.cue.entity).join(' → ') || 'none'}`;
+//# sourceMappingURL=loop.js.map

package/dist/internal/eval/loop.js.map

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