@cavelang/cli 0.27.3 → 0.29.0

package/dist/internal/eval/score.js

@@ -0,0 +1,126 @@
+/**
+ * Claim scoring — the produced extraction against the golden (roadmap
+ * item 9).
+ *
+ * Both sides run through the same pipeline: parse → canonicalize → strip
+ * actor stamps → re-key → keep the last claim per key. Actor stamps are
+ * the `@src:` contexts appended by the engine itself under spec §9.5
+ * (`@src:cli`, `@src:agent/<name>`, `@src:ingest`) — which actor
+ * happened to write a claim must not shift its key away from the golden's,
+ * while *content* sources the fixture author wrote (`@src:maria`,
+ * `@src:notes.md`) stay part of claim identity: the golden decides which
+ * contexts extraction is expected to produce.
+ *
+ * A golden claim *matches* a produced claim when their normalized keys are
+ * equal and their values agree — numerically within a relative tolerance
+ * (units must agree; `~` approximation is metadata), textually otherwise.
+ * Relation and existence claims carry their object in the key, so the key
+ * alone decides. Confidence, tags, `+/-` uncertainty, importance and
+ * comments are metadata and never scored; a key that matches with a
+ * disagreeing value is counted separately (`valueOff`) — the right fact,
+ * the wrong value.
+ */
+import { Claim, Key, Value } from '@cavelang/core';
+import { canonicalizeText, emitClaim, standardRegistry } from '@cavelang/canonical';
+import { Files } from '@cavelang/cli/ingest';
+/** Actor-stamp sources appended by the engine (spec §9.5), ignored in scoring. */
+const actorStampRe = /^src:(?:cli$|agent\/|ingest$)/;
+/** @returns the claim without engine-appended actor stamps. */
+export const normalize = (claim) => {
+    const contexts = claim.contexts.filter(context => !actorStampRe.test(context));
+    return contexts.length === claim.contexts.length ? claim : { ...claim, contexts };
+};
+/** @returns the claim key of the normalized claim. */
+export const keyOf = (claim) => Key.of(normalize(claim));
+/**
+ * @returns one fact per normalized key, the last claim winning — the same
+ * latest-wins semantics the store gives a belief series (spec §9.1).
+ */
+export const factsOf = (claims) => {
+    const byKey = new Map();
+    for (const claim of claims) {
+        byKey.set(keyOf(claim), claim);
+    }
+    return [...byKey].map(([key, claim]) => ({ key, claim }));
+};
+/** Parses a golden document into facts; parse problems are fixture problems. */
+export const goldenFacts = (text, registry = standardRegistry) => {
+    const result = canonicalizeText(text, registry);
+    return {
+        facts: factsOf(result.claims.map(entry => entry.claim)),
+        problems: result.problems.map(problem => `golden line ${problem.line}: ${problem.message}`)
+    };
+};
+/**
+ * @returns the facts an extraction run produced — the store's current
+ * beliefs minus the orchestrator's own `ingest-digest` provenance claims
+ * (`@cavelang/cli/ingest` bookkeeping, not extracted knowledge).
+ */
+export const producedFacts = (store) => factsOf(store.currentBeliefs()
+    .filter(row => row.attribute !== Files.digestAttribute)
+    .map(row => store.toClaim(row)));
+const valueOf = (claim) => claim.payload.kind === 'attribute' ? claim.payload.value :
+    claim.payload.kind === 'metric' ? claim.payload.value :
+        undefined;
+/**
+ * @returns whether the produced value agrees with the golden's: equal
+ * numbers (within `tolerance`, relative to the golden) under equal units,
+ * or the exact same canonical text. Claims without a value (relations,
+ * existence) always agree — their key already carries the object.
+ */
+export const valueAgrees = (golden, produced, tolerance = 0) => {
+    const goldenValue = valueOf(golden);
+    const producedValue = valueOf(produced);
+    if (goldenValue === undefined || producedValue === undefined) {
+        return goldenValue === producedValue;
+    }
+    if (goldenValue.num !== undefined && producedValue.num !== undefined) {
+        if ((goldenValue.unit ?? '') !== (producedValue.unit ?? '')) {
+            return false;
+        }
+        return goldenValue.num === producedValue.num ||
+            Math.abs(producedValue.num - goldenValue.num) <= tolerance * Math.abs(goldenValue.num);
+    }
+    return Value.format(goldenValue) === Value.format(producedValue);
+};
+const ratio = (numerator, denominator) => denominator === 0 ? 0 : numerator / denominator;
+/** @returns the F1 of a precision/recall pair, 0 when both are 0. */
+export const f1Of = (precision, recall) => precision + recall === 0 ? 0 : (2 * precision * recall) / (precision + recall);
+/** Compares produced facts against golden facts. */
+export const compare = (golden, produced, options = {}) => {
+    const byKey = new Map(produced.map(fact => [fact.key, fact]));
+    const misses = [];
+    const matchedKeys = new Set();
+    let matched = 0;
+    let valueOff = 0;
+    for (const fact of golden) {
+        const candidate = byKey.get(fact.key);
+        if (candidate !== undefined && valueAgrees(fact.claim, candidate.claim, options.tolerance)) {
+            matched += 1;
+            matchedKeys.add(fact.key);
+        }
+        else {
+            if (candidate !== undefined) {
+                valueOff += 1;
+            }
+            misses.push(fact);
+        }
+    }
+    const extras = produced.filter(fact => !matchedKeys.has(fact.key));
+    const precision = ratio(matched, produced.length);
+    const recall = ratio(matched, golden.length);
+    return {
+        golden: golden.length,
+        produced: produced.length,
+        matched,
+        valueOff,
+        misses,
+        extras,
+        precision,
+        recall,
+        f1: f1Of(precision, recall)
+    };
+};
+/** @returns the canonical line of a fact, for reports and judge prompts. */
+export const lineOf = (fact) => emitClaim(normalize(fact.claim));
+//# sourceMappingURL=score.js.map

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

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

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

@@ -0,0 +1,66 @@
+/**
+ * Suite discovery — eval fixtures as plain files.
+ *
+ * A suite is any directory; a *case* is named by its golden file:
+ *
+ * ```
+ * suite/
+ *   instructions.md               (optional, shared by the suite)
+ *   family-history.md             the source the agent extracts from
+ *   family-history.golden.cave    the expected extraction
+ *   family-history.queries.cave   (optional) CAVE-Q behavioral checks
+ * ```
+ *
+ * For `<stem>.golden.cave` the source is the single sibling `<stem>.<ext>`
+ * whose extension has no further dots — so goldens, queries and
+ * instructions of this or other cases never masquerade as sources, while
+ * `design.notes.md` still pairs with `design.notes.golden.cave`. Zero or
+ * several candidates is a fixture problem, reported instead of guessed.
+ *
+ * A `<stem>.loop.cave` sibling makes the case a *reconstruction* case
+ * (spec §18): the source is the knowledge (CAVE text), the loop
+ * file declares seeds and budgets, and the golden is the expected
+ * reconstruction — see `loop.ts`.
+ *
+ * Instructions resolve nearest-first: an explicit path (CLI `--instructions`)
+ * beats `<stem>.instructions.md` beats the case directory's
+ * `instructions.md` beats the suite root's.
+ */
+export declare const goldenSuffix = ".golden.cave";
+export declare const queriesSuffix = ".queries.cave";
+export declare const loopSuffix = ".loop.cave";
+export declare const instructionsSuffix = ".instructions.md";
+/** Suite-shared instructions file name. */
+export declare const sharedInstructions = "instructions.md";
+export type Case = {
+    /** Display name — the golden's path relative to `cwd`, suffix dropped. */
+    readonly name: string;
+    /**
+     * Absolute source file: what the agent extracts from — or, for a
+     * reconstruction case, the knowledge the loop runs over.
+     */
+    readonly source: string;
+    /** Absolute golden `.cave` path. */
+    readonly golden: string;
+    /** Absolute queries file path, when the case has one. */
+    readonly queries?: string;
+    /** Absolute loop file path — present on reconstruction cases (item 10). */
+    readonly loop?: string;
+    /** Absolute instructions markdown path, when one resolves. */
+    readonly instructions?: string;
+};
+export type Suite = {
+    /** Discovered cases, sorted by name. */
+    readonly cases: readonly Case[];
+    /** Fixture problems — goldens that could not become cases. */
+    readonly problems: readonly string[];
+};
+/**
+ * Discovers the cases of one or more suites. Each root may be a directory
+ * (searched recursively for `*.golden.cave`) or a single golden file.
+ */
+export declare const discover: (roots: readonly string[], options?: {
+    instructions?: string;
+    cwd?: string;
+}) => Suite;
+//# sourceMappingURL=suite.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"suite.d.ts","sourceRoot":"","sources":["../../src/suite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH,eAAO,MAAM,YAAY,iBAAiB,CAAA;AAC1C,eAAO,MAAM,aAAa,kBAAkB,CAAA;AAC5C,eAAO,MAAM,UAAU,eAAe,CAAA;AACtC,eAAO,MAAM,kBAAkB,qBAAqB,CAAA;AAEpD,2CAA2C;AAC3C,eAAO,MAAM,kBAAkB,oBAAoB,CAAA;AAEnD,MAAM,MAAM,IAAI,GAAG;IACjB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,yDAAyD;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B,CAAA;AAED,MAAM,MAAM,KAAK,GAAG;IAClB,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC,CAAA;AAyDD;;;GAGG;AACH,eAAO,MAAM,QAAQ,GACnB,OAAO,SAAS,MAAM,EAAE,EACxB,UAAS;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,KACpD,KAuCF,CAAA"}

package/dist/internal/eval/suite.js

@@ -0,0 +1,130 @@
+/**
+ * Suite discovery — eval fixtures as plain files.
+ *
+ * A suite is any directory; a *case* is named by its golden file:
+ *
+ * ```
+ * suite/
+ *   instructions.md               (optional, shared by the suite)
+ *   family-history.md             the source the agent extracts from
+ *   family-history.golden.cave    the expected extraction
+ *   family-history.queries.cave   (optional) CAVE-Q behavioral checks
+ * ```
+ *
+ * For `<stem>.golden.cave` the source is the single sibling `<stem>.<ext>`
+ * whose extension has no further dots — so goldens, queries and
+ * instructions of this or other cases never masquerade as sources, while
+ * `design.notes.md` still pairs with `design.notes.golden.cave`. Zero or
+ * several candidates is a fixture problem, reported instead of guessed.
+ *
+ * A `<stem>.loop.cave` sibling makes the case a *reconstruction* case
+ * (spec §18): the source is the knowledge (CAVE text), the loop
+ * file declares seeds and budgets, and the golden is the expected
+ * reconstruction — see `loop.ts`.
+ *
+ * Instructions resolve nearest-first: an explicit path (CLI `--instructions`)
+ * beats `<stem>.instructions.md` beats the case directory's
+ * `instructions.md` beats the suite root's.
+ */
+import { existsSync, globSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+export const goldenSuffix = '.golden.cave';
+export const queriesSuffix = '.queries.cave';
+export const loopSuffix = '.loop.cave';
+export const instructionsSuffix = '.instructions.md';
+/** Suite-shared instructions file name. */
+export const sharedInstructions = 'instructions.md';
+/** @returns source candidates: `<stem>.<ext>` siblings with a dot-free extension. */
+const sourcesOf = (golden) => {
+    const dir = dirname(golden);
+    const stem = basename(golden).slice(0, -goldenSuffix.length);
+    return readdirSync(dir)
+        .filter(name => {
+        if (!name.startsWith(`${stem}.`)) {
+            return false;
+        }
+        const extension = name.slice(stem.length + 1);
+        return extension !== '' && !extension.includes('.') && statSync(join(dir, name)).isFile();
+    })
+        .sort()
+        .map(name => join(dir, name));
+};
+const instructionsOf = (golden, root, explicit) => {
+    const candidates = [
+        explicit,
+        `${golden.slice(0, -goldenSuffix.length)}${instructionsSuffix}`,
+        join(dirname(golden), sharedInstructions),
+        join(root, sharedInstructions)
+    ];
+    return candidates.find(path => path !== undefined && existsSync(path));
+};
+const caseOf = (golden, root, cwd, explicit) => {
+    const sources = sourcesOf(golden);
+    const name = relative(cwd, golden).slice(0, -goldenSuffix.length);
+    if (sources.length === 0) {
+        return { problem: `${name}: no source file — expected a single ${basename(golden).slice(0, -goldenSuffix.length)}.<ext> beside ${basename(golden)}` };
+    }
+    if (sources.length > 1) {
+        return { problem: `${name}: ambiguous source — ${sources.map(source => basename(source)).join(', ')}` };
+    }
+    const queries = `${golden.slice(0, -goldenSuffix.length)}${queriesSuffix}`;
+    const loop = `${golden.slice(0, -goldenSuffix.length)}${loopSuffix}`;
+    const instructions = instructionsOf(golden, root, explicit);
+    return {
+        kase: {
+            name,
+            source: sources[0],
+            golden,
+            ...existsSync(queries) ? { queries } : {},
+            ...existsSync(loop) ? { loop } : {},
+            ...instructions === undefined ? {} : { instructions }
+        }
+    };
+};
+/**
+ * Discovers the cases of one or more suites. Each root may be a directory
+ * (searched recursively for `*.golden.cave`) or a single golden file.
+ */
+export const discover = (roots, options = {}) => {
+    const cwd = options.cwd ?? process.cwd();
+    const explicit = options.instructions === undefined ? undefined : resolve(cwd, options.instructions);
+    const cases = [];
+    const problems = [];
+    for (const root of roots) {
+        const absolute = resolve(cwd, root);
+        if (!existsSync(absolute)) {
+            problems.push(`${root}: no such file or directory`);
+            continue;
+        }
+        if (statSync(absolute).isFile()) {
+            if (!absolute.endsWith(goldenSuffix)) {
+                problems.push(`${root}: not a suite directory or ${goldenSuffix} file`);
+                continue;
+            }
+            const outcome = caseOf(absolute, dirname(absolute), cwd, explicit);
+            if ('kase' in outcome) {
+                cases.push(outcome.kase);
+            }
+            else {
+                problems.push(outcome.problem);
+            }
+            continue;
+        }
+        const goldens = globSync(`**/*${goldenSuffix}`, { cwd: absolute }).sort();
+        if (goldens.length === 0) {
+            problems.push(`${root}: no ${goldenSuffix} cases found`);
+            continue;
+        }
+        for (const golden of goldens) {
+            const outcome = caseOf(join(absolute, golden), absolute, cwd, explicit);
+            if ('kase' in outcome) {
+                cases.push(outcome.kase);
+            }
+            else {
+                problems.push(outcome.problem);
+            }
+        }
+    }
+    return { cases: cases.sort((a, b) => a.name.localeCompare(b.name)), problems };
+};
+//# sourceMappingURL=suite.js.map

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

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

package/dist/internal/ingest/context.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Existing-knowledge context for an ingestion batch.
+ *
+ * Neither extreme works: dumping the whole database into every prompt
+ * stops scaling almost immediately, and tools-only leaves the model blind
+ * to established naming conventions and prone to duplicates. The middle
+ * road injected here is a small *relevant* slice — store statistics, the
+ * most-connected entities (naming anchors), and claims matching the batch
+ * files' path tokens — while the agent keeps full API access through the
+ * `cave_*` MCP tools for anything deeper.
+ */
+import type { Store } from '@cavelang/store';
+/** Tokens worth searching for, derived from a file path or URL. */
+export declare const pathTokens: (path: string) => string[];
+/**
+ * @returns a compact knowledge-context block for the batch, capped at
+ * `limit` claim lines; `undefined` for an empty store.
+ */
+export declare const contextFor: (store: Store, paths: readonly string[], limit?: number) => undefined | string;
+//# sourceMappingURL=context.d.ts.map

package/dist/internal/ingest/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAE5C,mEAAmE;AACnE,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,MAAM,EAO/C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,KAAK,EAAE,OAAO,SAAS,MAAM,EAAE,EAAE,cAAU,KAAG,SAAS,GAAG,MAgC3F,CAAA"}

package/dist/internal/ingest/context.js

@@ -0,0 +1,59 @@
+/**
+ * Existing-knowledge context for an ingestion batch.
+ *
+ * Neither extreme works: dumping the whole database into every prompt
+ * stops scaling almost immediately, and tools-only leaves the model blind
+ * to established naming conventions and prone to duplicates. The middle
+ * road injected here is a small *relevant* slice — store statistics, the
+ * most-connected entities (naming anchors), and claims matching the batch
+ * files' path tokens — while the agent keeps full API access through the
+ * `cave_*` MCP tools for anything deeper.
+ */
+import { emitClaim } from '@cavelang/canonical';
+/** Tokens worth searching for, derived from a file path or URL. */
+export const pathTokens = (path) => {
+    const parts = path
+        .split(/[/\\?#&=]/)
+        .flatMap(segment => segment.split('.'))
+        .filter(token => token.length >= 3 &&
+        !/^(src|test|index|json|md|ts|js|tsx|jsx|txt|yaml|yml|https?:|www|com|net|org|html|htm)$/.test(token));
+    return [...new Set(parts)];
+};
+/**
+ * @returns a compact knowledge-context block for the batch, capped at
+ * `limit` claim lines; `undefined` for an empty store.
+ */
+export const contextFor = (store, paths, limit = 40) => {
+    const current = store.currentBeliefs();
+    if (current.length === 0) {
+        return undefined;
+    }
+    const degree = new Map();
+    for (const row of current) {
+        degree.set(row.subject, (degree.get(row.subject) ?? 0) + 1);
+        if (row.object !== null) {
+            degree.set(row.object, (degree.get(row.object) ?? 0) + 1);
+        }
+    }
+    const topEntities = [...degree.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 15)
+        .map(([entity, count]) => `${entity} (${count})`);
+    const related = new Map();
+    for (const token of paths.flatMap(pathTokens)) {
+        for (const row of store.search(token, { limit: 5 })) {
+            if (related.size >= limit) {
+                break;
+            }
+            related.set(row.claim_key, emitClaim(store.toClaim(row)));
+        }
+    }
+    return [
+        `The database currently holds ${current.length} current belief(s).`,
+        `Established entities (use these names, do not invent variants): ${topEntities.join(', ')}`,
+        ...related.size > 0 ?
+            ['Existing claims related to this batch:', ...[...related.values()].map(line => `  ${line}`)] :
+            []
+    ].join('\n');
+};
+//# sourceMappingURL=context.js.map

package/dist/internal/ingest/context.js.map

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

package/dist/internal/ingest/files.d.ts

@@ -0,0 +1,46 @@
+/**
+ * File selection for ingestion: glob expansion, batching, and the
+ * incremental-skip bookkeeping.
+ *
+ * Ingestion provenance is recorded as ordinary CAVE claims —
+ * `<path> HAS ingest-digest: <sha256/12> @src:cave-ingest` — so "which
+ * files are already ingested at which content version" lives in the same
+ * append-only store as the knowledge itself, and re-running `cave ingest`
+ * over a monorepo only processes files whose content changed.
+ */
+import type { Store } from '@cavelang/store';
+/** Digest attribute name used in provenance claims. */
+export declare const digestAttribute = "ingest-digest";
+/** Context marking provenance claims. */
+export declare const provenanceContext = "src:cave-ingest";
+/** @returns matching regular-file paths — globs expanded, directories dropped, deduplicated, sorted. */
+export declare const expand: (patterns: readonly string[], cwd?: string) => string[];
+/** @returns first 12 hex chars of the content's sha256. */
+export declare const digestOf: (content: string) => string;
+export type Selected = {
+    readonly path: string;
+    readonly digest: string;
+    /** Pre-fetched content (URL sources); files are read from disk instead. */
+    readonly content?: string;
+};
+export type Selection = {
+    readonly files: readonly Selected[];
+    /** Files skipped because their current digest claim matches. */
+    readonly skipped: readonly string[];
+};
+/** @returns whether the source's current `ingest-digest` belief matches. */
+export declare const isIngested: (store: Store, path: string, digest: string) => boolean;
+/**
+ * Reads and digests candidate files (paths relative to `cwd`), skipping
+ * the ones whose current `ingest-digest` belief already matches (pass
+ * `force` to re-ingest all).
+ */
+export declare const select: (store: Store, paths: readonly string[], options?: {
+    force?: boolean;
+    cwd?: string;
+}) => Selection;
+/** Records provenance claims for successfully ingested files. */
+export declare const recordDigests: (store: Store, files: readonly Selected[]) => void;
+/** @returns `files` split into batches of at most `size`. */
+export declare const batch: <T>(files: readonly T[], size: number) => T[][];
+//# sourceMappingURL=files.d.ts.map

package/dist/internal/ingest/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAE5C,uDAAuD;AACvD,eAAO,MAAM,eAAe,kBAAkB,CAAA;AAE9C,yCAAyC;AACzC,eAAO,MAAM,iBAAiB,oBAAoB,CAAA;AAiClD,wGAAwG;AACxG,eAAO,MAAM,MAAM,GAAI,UAAU,SAAS,MAAM,EAAE,EAAE,MAAK,MAAsB,KAAG,MAAM,EAKvF,CAAA;AAED,2DAA2D;AAC3D,eAAO,MAAM,QAAQ,GAAI,SAAS,MAAM,KAAG,MACsB,CAAA;AAMjE,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAA;IACnC,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC,CAAA;AAED,4EAA4E;AAC5E,eAAO,MAAM,UAAU,GAAI,OAAO,KAAK,EAAE,MAAM,MAAM,EAAE,QAAQ,MAAM,KAAG,OAGvE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM,GACjB,OAAO,KAAK,EACZ,OAAO,SAAS,MAAM,EAAE,EACxB,UAAS;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,KAC9C,SAaF,CAAA;AAED,iEAAiE;AACjE,eAAO,MAAM,aAAa,GAAI,OAAO,KAAK,EAAE,OAAO,SAAS,QAAQ,EAAE,KAAG,IAkBxE,CAAA;AAED,6DAA6D;AAC7D,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,OAAO,SAAS,CAAC,EAAE,EAAE,MAAM,MAAM,KAAG,CAAC,EAAE,EAS/D,CAAA"}

package/dist/internal/ingest/files.js

@@ -0,0 +1,115 @@
+/**
+ * File selection for ingestion: glob expansion, batching, and the
+ * incremental-skip bookkeeping.
+ *
+ * Ingestion provenance is recorded as ordinary CAVE claims —
+ * `<path> HAS ingest-digest: <sha256/12> @src:cave-ingest` — so "which
+ * files are already ingested at which content version" lives in the same
+ * append-only store as the knowledge itself, and re-running `cave ingest`
+ * over a monorepo only processes files whose content changed.
+ */
+import { createHash } from 'node:crypto';
+import { globSync, readFileSync, statSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { Key, Claim, Value } from '@cavelang/core';
+/** Digest attribute name used in provenance claims. */
+export const digestAttribute = 'ingest-digest';
+/** Context marking provenance claims. */
+export const provenanceContext = 'src:cave-ingest';
+/**
+ * File paths normally remain entity atoms for compatibility with existing
+ * provenance. Paths that would be split or interpreted as metadata use a
+ * code literal so their exact spelling round-trips through CAVE text.
+ */
+const provenanceSubject = (path) => {
+    const isEntityAtom = path !== '' &&
+        !/[\s"`;]/u.test(path) &&
+        !/^(?:[@#]|\+\/-|!$|\(\d+(?:\.\d+)?σ\)$)/u.test(path);
+    if (isEntityAtom) {
+        return Claim.entity(path);
+    }
+    // Prefer a code literal for path-like data; use text when the path itself
+    // contains a backtick. CAVE has no literal escape syntax, so a path with
+    // both delimiters needs a deterministic encoded representation to remain
+    // valid through canonical export/import.
+    if (path.includes('`')) {
+        return path.includes('"') ? Claim.code(`percent-encoded:${encodeURIComponent(path)}`) : Claim.text(path);
+    }
+    return Claim.code(path);
+};
+/** One construction path keeps digest lookup and storage identities identical. */
+const provenanceClaim = (path, digest) => Claim.of({
+    subject: provenanceSubject(path),
+    verb: 'HAS',
+    payload: Claim.attribute(digestAttribute, Value.parse(digest)),
+    contexts: [provenanceContext]
+});
+/** @returns matching regular-file paths — globs expanded, directories dropped, deduplicated, sorted. */
+export const expand = (patterns, cwd = process.cwd()) => {
+    const matched = patterns.flatMap(pattern => globSync(pattern, { cwd }));
+    return [...new Set(matched)]
+        .filter(path => statSync(resolvePath(cwd, path)).isFile())
+        .sort();
+};
+/** @returns first 12 hex chars of the content's sha256. */
+export const digestOf = (content) => createHash('sha256').update(content).digest('hex').slice(0, 12);
+/** Claim key of a file's provenance claim (value excluded by design, §9.2). */
+const provenanceKey = (path) => Key.of(provenanceClaim(path, 'x'));
+/** @returns whether the source's current `ingest-digest` belief matches. */
+export const isIngested = (store, path, digest) => {
+    const known = store.currentBelief(provenanceKey(path));
+    return known !== undefined && known.value_text === digest && known.conf > 0;
+};
+/**
+ * Reads and digests candidate files (paths relative to `cwd`), skipping
+ * the ones whose current `ingest-digest` belief already matches (pass
+ * `force` to re-ingest all).
+ */
+export const select = (store, paths, options = {}) => {
+    const files = [];
+    const skipped = [];
+    const cwd = options.cwd ?? process.cwd();
+    for (const path of paths) {
+        const digest = digestOf(readFileSync(resolvePath(cwd, path), 'utf8'));
+        if (options.force !== true && isIngested(store, path, digest)) {
+            skipped.push(path);
+        }
+        else {
+            files.push({ path, digest });
+        }
+    }
+    return { files, skipped };
+};
+/** Records provenance claims for successfully ingested files. */
+export const recordDigests = (store, files) => {
+    if (files.length === 0) {
+        return;
+    }
+    try {
+        store.insertResult({
+            claims: files.map((file, index) => ({
+                line: index + 1,
+                claim: provenanceClaim(file.path, file.digest)
+            })),
+            edges: [],
+            registry: store.registry(),
+            problems: []
+        });
+    }
+    catch (error) {
+        const sources = files.map(file => JSON.stringify(file.path)).join(', ');
+        throw new Error(`failed to record ingest digest(s) for ${sources}`, { cause: error });
+    }
+};
+/** @returns `files` split into batches of at most `size`. */
+export const batch = (files, size) => {
+    if (!(size >= 1)) {
+        throw new Error(`batch size must be >= 1, got ${size}`);
+    }
+    const batches = [];
+    for (let at = 0; at < files.length; at += size) {
+        batches.push(files.slice(at, at + size));
+    }
+    return batches;
+};
+//# sourceMappingURL=files.js.map

package/dist/internal/ingest/files.js.map

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

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

@@ -0,0 +1,31 @@
+/**
+ * `@cavelang/cli/ingest` — LLM-driven knowledge ingestion.
+ *
+ * ```sh
+ * cave ingest 'src/**' https://example.com/design-notes --db k.db \
+ *   --agent 'claude -p --mcp-config {mcp-config} --allowedTools "mcp__cave__*"'
+ * ```
+ *
+ * Library API for SDK scripts:
+ *
+ * ```ts
+ * import { run } from '@cavelang/cli/ingest'
+ * import { open } from '@cavelang/store'
+ *
+ * const store = open('k.db')
+ * await run({
+ *   db: 'k.db', store, patterns: ['docs/**'], mode: 'stdout', embed: true,
+ *   agent: async prompt => callYourSdk(prompt),  // returns CAVE text
+ *   // policy: 'lenient'                         // strict is the default
+ * })
+ * ```
+ */
+export * as Context from './context.ts';
+export * as Files from './files.ts';
+export * as Web from './web.ts';
+export { buildPrompt, extractionRules, readInstructions } from './prompt.ts';
+export type { Mode, PromptInput } from './prompt.ts';
+export { caveTextOf, promptFor, run, runShellAgent, selectBatches, writeMcpConfig } from './run.ts';
+export type { Agent, AgentContext, Batch, BatchReport, Options, Policy, Report, SourceReport, SourceStatus } from './run.ts';
+export { runIngest } from './main.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,GAAG,MAAM,UAAU,CAAA;AAC/B,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC5E,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACnG,YAAY,EACV,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAC7F,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA"}