@loomwork/knowledge 0.0.0-stage → 0.1.1

package/dist/KnowledgeBase.js

@@ -0,0 +1,394 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KnowledgeBase = void 0;
+exports.openKnowledgeBase = openKnowledgeBase;
+const classify_1 = require("@loomwork/classify");
+const core_1 = require("@loomwork/core");
+const memory_1 = require("@loomwork/memory");
+const verify_1 = require("@loomwork/verify");
+const chunk_1 = require("./chunk");
+/**
+ * A document corpus over a memory tier: ingest, revise, delete, retrieve — with the
+ * provenance and the recorded retrieval that make the result usable in a prompt.
+ *
+ * ## What this is not
+ *
+ * It is not a construct, an SPI, or a retrieval engine. Ranking is the `MemoryStore`'s
+ * (FTS5, `tsvector`, cosine — whichever backend is configured), reproducibility is
+ * `ctx.decide`'s, safety is ADR 0085's, and the corpus is an ordinary `semantic` tier
+ * anyone can read with `recall`. What lives here is the one thing none of those provide:
+ * the mapping from a DOCUMENT — the unit a corpus is edited in — to the PASSAGES it is
+ * searched in, so that revising a document supersedes its old passages instead of
+ * duplicating them.
+ *
+ * ## The tier must not evict
+ *
+ * A corpus is kept until someone deletes it, so the tier it lives in must have no `ttlMs`
+ * and no `maxEntries`. Under eviction, the store would drop passages the manifest still
+ * counts, and a document would silently retrieve as a fragment of itself. `semantic` and
+ * `procedural` are unbounded by default, which is exactly why they are the tiers a corpus
+ * belongs in — and the constructor refuses a bounded one rather than letting it rot.
+ *
+ * ## Two scopes
+ *
+ * Passages live in `scope`; the manifest lives in `scope::docs`, one small row per
+ * document. They are separate because they are searched differently: a manifest row in
+ * the corpus would be an entry that matches queries and answers nothing.
+ */
+class KnowledgeBase {
+    memory;
+    tier;
+    scope;
+    manifestScope;
+    chunker;
+    origin;
+    constructor(config) {
+        this.memory = config.memory;
+        this.tier = config.tier ?? "semantic";
+        this.scope = config.scope;
+        this.manifestScope = `${config.scope}::docs`;
+        this.chunker = config.chunker ?? (0, chunk_1.packParagraphs)();
+        this.origin = config.origin ?? ((doc) => `knowledge:${config.scope}:${doc.id}`);
+        const policy = this.memory.tierPolicy(this.tier);
+        if (policy === undefined) {
+            throw new Error(`KnowledgeBase: unknown memory tier "${this.tier}" (have: ${this.memory.tierNames.join(", ")})`);
+        }
+        if (policy.ttlMs !== undefined || policy.maxEntries !== undefined) {
+            throw new Error(`KnowledgeBase: tier "${this.tier}" evicts (ttlMs/maxEntries), and a corpus must not. Eviction would drop passages the document manifest still counts, so a document would retrieve as a fragment of itself with nothing to detect it. Use an unbounded tier ("semantic"/"procedural" are unbounded by default).`);
+        }
+    }
+    /** `docId#index` — derived, never stored, so a document's passage ids are its count. */
+    passageId(docId, index) {
+        return `${docId}#${index}`;
+    }
+    fingerprint(doc) {
+        // canonicalJson + fnv1a64 are core's one canonicalization and one hash (ADR 0063).
+        // Over the WHOLE document, not just its text: a changed title or a changed `meta`
+        // reaches the prompt through every passage, so it is a revision like any other.
+        return (0, core_1.fnv1a64)((0, core_1.canonicalJson)({
+            title: doc.title,
+            text: doc.text,
+            meta: doc.meta,
+        }));
+    }
+    toPassages(doc) {
+        const origin = this.origin(doc);
+        return this.chunker(doc).map((text, index) => ({
+            docId: doc.id,
+            ...(doc.title !== undefined && { title: doc.title }),
+            index,
+            text: (0, classify_1.tainted)(text, origin),
+            ...(doc.meta !== undefined && { meta: doc.meta }),
+        }));
+    }
+    /**
+     * What is actually WRITTEN for a passage: its `text`, and its `title`/`meta` if any.
+     *
+     * `docId` and `index` are deliberately NOT stored, because a store indexes the string
+     * and number leaves of `content` — so storing them would make a document's own id a term
+     * matching all of its passages, and the chunk ordinal a term matching the first passage
+     * of every document in the corpus. That is the same widening that made a tainted value's
+     * `origin` unindexable (ADR 0090), and the same rule the SPI states for `MemoryEntry.id`.
+     *
+     * They are not lost: the entry id IS `docId#index`, ids are required to round-trip
+     * (SPI 2.0.0), and ids are not indexed. The requirement earns its keep twice.
+     */
+    storedPassage(passage) {
+        return {
+            ...(passage.title !== undefined && { title: passage.title }),
+            text: passage.text,
+            ...(passage.meta !== undefined && { meta: passage.meta }),
+        };
+    }
+    /**
+     * The tiered memory the corpus lives in, for a caller that also wants to `recall` it,
+     * point a second corpus at the same store, or inspect it from ops code.
+     */
+    get tieredMemory() {
+        return this.memory;
+    }
+    /** `docId#revision` — a manifest row's id. Rows are appended; the highest revision wins. */
+    rowId(docId, revision) {
+        return `${docId}#${revision}`;
+    }
+    /**
+     * The manifest: the live record per document, plus every row id currently standing for
+     * it so superseded rows can be pruned.
+     *
+     * One read of a small scope — rows are ids, counts and hashes, never passage text — which
+     * is what keeps `sync` proportional to the number of DOCUMENTS rather than to the size of
+     * the corpus. Read order is append order (the SPI guarantees it), so the last row for a
+     * document is the live one.
+     */
+    async manifest() {
+        const entries = await this.memory.recall(this.tier, this.manifestScope);
+        const slots = new Map();
+        for (const entry of entries) {
+            const record = entry.content;
+            const slot = slots.get(record.docId);
+            const rowId = this.rowId(record.docId, record.revision);
+            if (slot === undefined)
+                slots.set(record.docId, { record, rowIds: [rowId] });
+            else {
+                slot.rowIds.push(rowId);
+                slot.record = record;
+            }
+        }
+        return slots;
+    }
+    async appendRecord(record) {
+        await this.memory.remember(this.tier, this.manifestScope, {
+            id: this.rowId(record.docId, record.revision),
+            content: record,
+        });
+    }
+    /**
+     * Remove a document's passages, by the count the manifest holds. Idempotent — a document
+     * that is absent, or whose passages were already deleted, is a no-op.
+     */
+    async removeDoc(docId) {
+        const slot = (await this.manifest()).get(docId);
+        if (slot === undefined)
+            return;
+        await this.removeRecordedPassages(slot.record);
+        await this.memory.forget(this.tier, this.manifestScope, slot.rowIds);
+    }
+    async removeRecordedPassages(record) {
+        const ids = Array.from({ length: record.chunkCount }, (_, i) => this.passageId(record.docId, i));
+        if (ids.length > 0)
+            await this.memory.forget(this.tier, this.scope, ids);
+    }
+    /**
+     * Ingest a document, superseding any previous revision of it. Returns the passages now
+     * stored for it (empty if the document chunked to nothing).
+     *
+     * UPSERT, not append. Ingesting the same document twice must not double it in the index
+     * — retrieval would then return the stale passage beside the current one, and a citation
+     * could not say which is live. That is the operation a `MemoryStore` alone cannot
+     * express, and the reason this class exists.
+     *
+     * The write order is the crash contract, and it is deliberate:
+     *
+     *  1. APPEND an uncommitted manifest row at the new count and fingerprint;
+     *  2. delete the previous revision's passages (by the count the old row holds);
+     *  3. append the new passages;
+     *  4. APPEND the committed manifest row, then prune the superseded rows.
+     *
+     * A crash before (4) leaves an uncommitted row, which {@link sync} and every later
+     * `putDoc` treat as changed no matter what the fingerprint says — so the document is
+     * rewritten rather than skipped.
+     *
+     * Two orderings look more natural and neither survives. Passages first: passages nothing
+     * counts are passages nothing can remove, and they stay retrievable forever. Manifest
+     * updated in place (delete the old row, write the new one): the crash window between
+     * them leaves the document with NO row, which is the same orphaning by a shorter path —
+     * which is why rows are appended and superseded ones are pruned only afterwards.
+     */
+    async putDoc(doc, opts = {}) {
+        const slot = (await this.manifest()).get(doc.id);
+        // Only an EXISTING document has an owner. An absent one is unclaimed, so any writer
+        // may create it — the check is about not taking someone else's, not about permission.
+        if (slot !== undefined)
+            assertOwned(doc.id, slot.record.source, opts.source);
+        return this.write(doc, slot, opts.source);
+    }
+    async write(doc, slot, source) {
+        const passages = this.toPassages(doc);
+        const pending = {
+            docId: doc.id,
+            chunkCount: passages.length,
+            fingerprint: this.fingerprint(doc),
+            committed: false,
+            revision: (slot?.record.revision ?? -1) + 1,
+            ...(source !== undefined && { source }),
+        };
+        await this.appendRecord(pending);
+        if (slot !== undefined)
+            await this.removeRecordedPassages(slot.record);
+        for (const passage of passages) {
+            await this.memory.remember(this.tier, this.scope, {
+                id: this.passageId(doc.id, passage.index),
+                content: this.storedPassage(passage),
+            });
+        }
+        const committed = { ...pending, committed: true, revision: pending.revision + 1 };
+        await this.appendRecord(committed);
+        // Prune only after the committed row is durable, and only rows this call has seen: a
+        // concurrent writer's row is not ours to delete.
+        const superseded = [...(slot?.rowIds ?? []), this.rowId(doc.id, pending.revision)];
+        await this.memory.forget(this.tier, this.manifestScope, superseded);
+        return passages;
+    }
+    /**
+     * Reconcile the corpus against the documents the source currently has: write what is new
+     * or changed, leave what is identical, remove what the source dropped.
+     *
+     * This is the operation a knowledge base is actually run with — a wiki export, a docs
+     * directory, a table of policies — and it is what makes deletion complete rather than
+     * best-effort. Without it, a document deleted upstream keeps answering questions.
+     *
+     * Cost is one manifest read (rows are ids and counts) plus writes for the documents that
+     * genuinely changed — NOT a rewrite of the corpus, which is the whole point of the
+     * fingerprint. Re-running it on an unchanged source writes nothing.
+     *
+     * `docs` is the COMPLETE set. Passing a subset removes everything not in it, which is
+     * the correct reading of "reconcile" and the wrong thing to do with a page of results.
+     */
+    async sync(docs, opts = {}) {
+        const manifest = await this.manifest();
+        const plan = this.classify(docs, manifest, opts.source);
+        // Indexed once: `written` is O(docs) and a scan per entry would make a sync of a
+        // 10,000-document corpus quadratic in the size of the source, not of the change.
+        const byId = new Map(docs.map((doc) => [doc.id, doc]));
+        for (const docId of plan.written) {
+            // An UNCOMMITTED row is rewritten even when the fingerprint matches. That case is
+            // exactly the crash this design exists for, and treating it as unchanged is how a
+            // document disappears from a corpus that still lists it.
+            await this.write(byId.get(docId), manifest.get(docId), opts.source);
+        }
+        for (const docId of plan.removed) {
+            const slot = manifest.get(docId);
+            await this.removeRecordedPassages(slot.record);
+            await this.memory.forget(this.tier, this.manifestScope, slot.rowIds);
+        }
+        return plan;
+    }
+    /**
+     * What {@link sync} WOULD do, without doing it. Read-only.
+     *
+     * Exists because a corpus sync is a destructive reconcile — `docs` is the complete set,
+     * so anything missing from it is deleted — and the operator command that runs it
+     * (`loom knowledge sync`) defaults to a dry run for that reason. A preview computed by a
+     * separate code path would be a preview of a different operation, so both go through the
+     * same classification and only `sync` writes.
+     */
+    async planSync(docs, opts = {}) {
+        return this.classify(docs, await this.manifest(), opts.source);
+    }
+    /** Pure: which documents are new/changed, unchanged, or no longer in the source. */
+    classify(docs, manifest, source) {
+        const result = { written: [], unchanged: [], removed: [], retained: [] };
+        const seen = new Set();
+        for (const doc of docs) {
+            if (seen.has(doc.id)) {
+                throw new Error(`KnowledgeBase.sync: duplicate document id "${doc.id}". Ids identify a document across revisions, so two documents sharing one would each supersede the other on every sync.`);
+            }
+            seen.add(doc.id);
+            const slot = manifest.get(doc.id);
+            if (slot !== undefined)
+                assertOwned(doc.id, slot.record.source, source);
+            if (slot?.record.committed === true && slot.record.fingerprint === this.fingerprint(doc)) {
+                result.unchanged.push(doc.id);
+            }
+            else {
+                result.written.push(doc.id);
+            }
+        }
+        for (const [docId, slot] of manifest) {
+            if (seen.has(docId))
+                continue;
+            // The whole point: a reconcile deletes only what it OWNS. Another writer's documents
+            // are not missing from this source — they were never this source's to list.
+            if (slot.record.source !== source)
+                result.retained.push(docId);
+            else
+                result.removed.push(docId);
+        }
+        return result;
+    }
+    /** The documents this corpus holds, in manifest order. Ids and counts — no passage text. */
+    async listDocs() {
+        return [...(await this.manifest()).values()].map((slot) => slot.record);
+    }
+    /**
+     * Retrieve the passages most relevant to a question, best first.
+     *
+     * `decide` is REQUIRED, and it is a type requirement rather than advice for the reason
+     * ADR 0090 gives: a corpus grows and is edited, so the passages a question retrieves
+     * genuinely differ between a run and its replay. Recorded, the retrieval is a fact and
+     * the replay rebuilds the prompt that actually ran; unrecorded, "reproducing" an
+     * incident quietly means asking today's corpus yesterday's question.
+     *
+     * What is recorded is the passage CONTENT, not passage ids — ids do not reconstruct a
+     * prompt once the document behind them has been revised.
+     */
+    async retrieve(query, opts) {
+        const hits = await this.memory.recallRelevant(this.tier, this.scope, query, {
+            decide: opts.decide,
+            ...(opts.limit !== undefined && { limit: opts.limit }),
+            ...(opts.decisionKey !== undefined && { decisionKey: opts.decisionKey }),
+        });
+        return hits.map(toPassage);
+    }
+}
+exports.KnowledgeBase = KnowledgeBase;
+// L34 - declared reach (ADR 0086). `kb.retrieve(q, { decide: ctx.decide })` is one `ctx.decide`
+// whose decider reads the memory store; it runs no tool (embedding, if any, is the store's own, not
+// a ctx effect). Declared on the PROTOTYPE so both `verify.reach["kb.retrieve"]` and `verify.reach.kb`
+// (the instance, which inherits it) and a method reference (`kb.retrieve`) resolve. Only `retrieve` is
+// ever handed a ctx seam.
+(0, verify_1.declareReach)(KnowledgeBase.prototype, { run: [], transient: [] });
+(0, verify_1.declareReach)(KnowledgeBase.prototype.retrieve, { run: [], transient: [] });
+/**
+ * Open a corpus over a `MemoryStore` directly — the two-line form of the four every
+ * consumer was writing by hand.
+ *
+ * A corpus needs exactly one memory tier and that tier must not evict, which is a fact
+ * about corpora and not a decision each application should be re-deriving. Both first
+ * consumers built the identical `new TieredMemory({ tiers: { semantic: {} }, store })`
+ * before they could construct anything, and an application wiring `defineConfig` cannot
+ * pass `app.memory` here at all — that is a {@link MemoryRuntime}, one layer below
+ * `TieredMemory` — so the boilerplate was mandatory rather than incidental.
+ *
+ * Reach for the constructor instead when the corpus shares a memory with something else
+ * (a conversation in `episodic`, say), which is exactly when the tier set is a decision.
+ */
+function openKnowledgeBase(store, opts) {
+    const tier = opts.tier ?? "semantic";
+    return new KnowledgeBase({
+        ...opts,
+        memory: new memory_1.TieredMemory({ tiers: { [tier]: {} }, store }),
+    });
+}
+/**
+ * Refuse a write to a document another writer owns.
+ *
+ * Loud rather than re-stamping, because silently taking ownership makes the two writers
+ * fight: each `sync` would claim the document and the other's next `sync` would delete it,
+ * so the corpus would flap between two revisions forever while every individual run looked
+ * correct. Two writers claiming one document is the ambiguity this field exists to remove.
+ */
+function assertOwned(docId, owner, writer) {
+    if (owner === writer)
+        return;
+    const name = (s) => s === undefined ? "the default writer" : `source "${s}"`;
+    throw new Error(`KnowledgeBase: document "${docId}" is managed by ${name(owner)}, and this call speaks for ${name(writer)}. One document, one writer — otherwise the two delete each other's revisions on alternate syncs. Use a different document id, or the owning source.`);
+}
+/** `docId#index` split at the LAST separator, so a document id may itself contain one. */
+function splitPassageId(id) {
+    const cut = id.lastIndexOf("#");
+    const index = Number(id.slice(cut + 1));
+    if (cut < 1 || !Number.isInteger(index)) {
+        throw new Error(`KnowledgeBase: entry id "${id}" is not a passage id (expected "docId#index"). The corpus scope holds passages this KnowledgeBase wrote; something else appended to it.`);
+    }
+    return { docId: id.slice(0, cut), index };
+}
+/**
+ * A stored entry, as a passage: its identity from the entry id, the rest from `content`.
+ *
+ * The content half is a cast and not a parse, deliberately: on replay this value comes back
+ * out of a `DECISION_RECORDED` payload as plain JSON, and re-validating it would only be
+ * able to reject what the log already contains — the value IS what ran. The taint wrapper
+ * survives that round trip because it is plain JSON too, which is the property ADR 0085 was
+ * built on. The identity half is checked, because an unparseable id means the entry was not
+ * written by a KnowledgeBase and a `docId: undefined` would flow straight into a citation.
+ */
+function toPassage(entry) {
+    if (entry.id === undefined) {
+        throw new Error("KnowledgeBase: a corpus entry has no id, so the document it belongs to cannot be named. Either the backend does not round-trip `MemoryEntry.id` (REQUIRED since MemoryStore SPI 2.0.0 — run `runMemoryStoreConformance` against it), or something other than this KnowledgeBase appended to the corpus scope.");
+    }
+    const { docId, index } = splitPassageId(entry.id);
+    const stored = entry.content;
+    return { docId, index, ...stored };
+}
+//# sourceMappingURL=KnowledgeBase.js.map

package/dist/KnowledgeBase.js.map

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

package/dist/chunk.d.ts

@@ -0,0 +1,18 @@
+import type { Chunker } from "./types";
+/**
+ * The default {@link Chunker}: split on blank lines, then greedily pack paragraphs up to
+ * `maxChars` so a passage is a coherent unit of prose rather than a fixed window that cuts
+ * mid-sentence.
+ *
+ * It is a DEFAULT and not a recommendation. Chunking decides what retrieval can return —
+ * too small and a passage loses the context that makes it answer the question, too large
+ * and one irrelevant paragraph drags a whole page into the prompt — and the right split is
+ * a property of the corpus, not of the framework. Pass your own for anything structured.
+ *
+ * A paragraph longer than `maxChars` is emitted whole rather than cut: splitting mid-word
+ * to satisfy a soft bound produces two passages that each retrieve badly, and the bound is
+ * a packing target, not a storage limit. Oversized content belongs behind
+ * `claimCheckMiddleware` at the effect boundary, which is where size actually bites.
+ */
+export declare function packParagraphs(maxChars?: number): Chunker;
+//# sourceMappingURL=chunk.d.ts.map

package/dist/chunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../src/chunk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,SAAS,CAAC;AAErD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,QAAQ,SAAQ,GAAG,OAAO,CAuBxD"}

package/dist/chunk.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packParagraphs = packParagraphs;
+/**
+ * The default {@link Chunker}: split on blank lines, then greedily pack paragraphs up to
+ * `maxChars` so a passage is a coherent unit of prose rather than a fixed window that cuts
+ * mid-sentence.
+ *
+ * It is a DEFAULT and not a recommendation. Chunking decides what retrieval can return —
+ * too small and a passage loses the context that makes it answer the question, too large
+ * and one irrelevant paragraph drags a whole page into the prompt — and the right split is
+ * a property of the corpus, not of the framework. Pass your own for anything structured.
+ *
+ * A paragraph longer than `maxChars` is emitted whole rather than cut: splitting mid-word
+ * to satisfy a soft bound produces two passages that each retrieve badly, and the bound is
+ * a packing target, not a storage limit. Oversized content belongs behind
+ * `claimCheckMiddleware` at the effect boundary, which is where size actually bites.
+ */
+function packParagraphs(maxChars = 1_000) {
+    if (!Number.isFinite(maxChars) || maxChars < 1) {
+        throw new TypeError(`packParagraphs: maxChars must be a positive number (got ${maxChars})`);
+    }
+    return (doc) => {
+        const paragraphs = doc.text
+            .split(/\n\s*\n/)
+            .map((p) => p.replace(/\s+/g, " ").trim())
+            .filter((p) => p.length > 0);
+        const chunks = [];
+        let current = "";
+        for (const paragraph of paragraphs) {
+            if (current.length > 0 && current.length + paragraph.length + 1 > maxChars) {
+                chunks.push(current);
+                current = paragraph;
+            }
+            else {
+                current = current.length > 0 ? `${current} ${paragraph}` : paragraph;
+            }
+        }
+        if (current.length > 0)
+            chunks.push(current);
+        return chunks;
+    };
+}
+//# sourceMappingURL=chunk.js.map

package/dist/chunk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../src/chunk.ts"],"names":[],"mappings":";;AAiBA,wCAuBC;AAtCD;;;;;;;;;;;;;;GAcG;AACH,SAAgB,cAAc,CAAC,QAAQ,GAAG,KAAK;IAC7C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,SAAS,CAAC,2DAA2D,QAAQ,GAAG,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,CAAC,GAAiB,EAAY,EAAE;QACrC,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI;aACxB,KAAK,CAAC,SAAS,CAAC;aAChB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;aACzC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAE/B,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,IAAI,OAAO,GAAG,EAAE,CAAC;QACjB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,GAAG,QAAQ,EAAE,CAAC;gBAC3E,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACrB,OAAO,GAAG,SAAS,CAAC;YACtB,CAAC;iBAAM,CAAC;gBACN,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;YACvE,CAAC;QACH,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7C,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/dist/citations.d.ts

@@ -0,0 +1,45 @@
+import type { Passage } from "./types";
+export interface CitationCheck {
+    /** Claimed ids that were actually retrieved, deduplicated, in retrieval order. */
+    grounded: string[];
+    /**
+     * Claimed ids that were NOT retrieved — the model named a source it was never shown.
+     * Non-empty is a fabricated citation, not a near miss.
+     */
+    ungrounded: string[];
+    /** Retrieved documents the answer did not cite. Not an error — evidence for tuning `limit`. */
+    unused: string[];
+}
+export declare class UngroundedCitationError extends Error {
+    readonly ungrounded: readonly string[];
+    readonly retrieved: readonly string[];
+    constructor(ungrounded: readonly string[], retrieved: readonly string[]);
+}
+/**
+ * Compare the documents an answer CLAIMS to cite against the ones actually retrieved.
+ *
+ * The check is nearly free and almost never written, because the number it needs is
+ * already in hand: the retrieval was recorded, so the set of documents the model could
+ * possibly have read is known exactly. A citation outside that set was not misread from a
+ * passage — there was no passage. It is the one hallucination in a RAG answer that can be
+ * detected with certainty rather than judged, which is what makes it mechanism and not a
+ * quality heuristic.
+ *
+ * What it does NOT check is whether the answer's CLAIMS follow from the cited passage.
+ * That needs a judge, it belongs to `@loomwork/learning`'s evaluation surface, and conflating
+ * the two would turn a decidable check into an approximate one.
+ *
+ * Ids are compared exactly: a corpus's document ids are its own keys, and normalizing
+ * case or punctuation here would be guessing at someone else's namespace.
+ */
+export declare function checkCitations(claimed: readonly string[], passages: readonly Passage[]): CitationCheck;
+/**
+ * {@link checkCitations}, but a fabricated citation throws.
+ *
+ * Returns the grounded ids, so the caller's happy path is `cited: assertGrounded(...)`.
+ * Use it where an answer is about to be shown as sourced: the failure mode this prevents
+ * is an answer that reads as attributed, names a plausible document, and cannot be traced
+ * to anything — the citation making it MORE trusted than an uncited answer would be.
+ */
+export declare function assertGrounded(claimed: readonly string[], passages: readonly Passage[]): string[];
+//# sourceMappingURL=citations.d.ts.map

package/dist/citations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citations.d.ts","sourceRoot":"","sources":["../src/citations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,+FAA+F;IAC/F,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAE9C,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE;IACtC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE;gBAD5B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,SAAS,EAAE,SAAS,MAAM,EAAE;CAOxC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,QAAQ,EAAE,SAAS,OAAO,EAAE,GAC3B,aAAa,CAyBf;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,EAAE,CAMjG"}

package/dist/citations.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UngroundedCitationError = void 0;
+exports.checkCitations = checkCitations;
+exports.assertGrounded = assertGrounded;
+class UngroundedCitationError extends Error {
+    ungrounded;
+    retrieved;
+    constructor(ungrounded, retrieved) {
+        super(`answer cites ${ungrounded.length} document(s) that were not retrieved: ${ungrounded.join(", ")} (retrieved: ${retrieved.join(", ") || "none"})`);
+        this.ungrounded = ungrounded;
+        this.retrieved = retrieved;
+        this.name = "UngroundedCitationError";
+    }
+}
+exports.UngroundedCitationError = UngroundedCitationError;
+/**
+ * Compare the documents an answer CLAIMS to cite against the ones actually retrieved.
+ *
+ * The check is nearly free and almost never written, because the number it needs is
+ * already in hand: the retrieval was recorded, so the set of documents the model could
+ * possibly have read is known exactly. A citation outside that set was not misread from a
+ * passage — there was no passage. It is the one hallucination in a RAG answer that can be
+ * detected with certainty rather than judged, which is what makes it mechanism and not a
+ * quality heuristic.
+ *
+ * What it does NOT check is whether the answer's CLAIMS follow from the cited passage.
+ * That needs a judge, it belongs to `@loomwork/learning`'s evaluation surface, and conflating
+ * the two would turn a decidable check into an approximate one.
+ *
+ * Ids are compared exactly: a corpus's document ids are its own keys, and normalizing
+ * case or punctuation here would be guessing at someone else's namespace.
+ */
+function checkCitations(claimed, passages) {
+    const retrieved = [];
+    const retrievedSet = new Set();
+    for (const passage of passages) {
+        if (retrievedSet.has(passage.docId))
+            continue;
+        retrievedSet.add(passage.docId);
+        retrieved.push(passage.docId);
+    }
+    const claimedSet = new Set(claimed);
+    const ungrounded = [];
+    const seen = new Set();
+    for (const id of claimed) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        if (!retrievedSet.has(id))
+            ungrounded.push(id);
+    }
+    return {
+        // Retrieval order, not claim order: it is the order the app can explain (best first),
+        // and the model's ordering carries no meaning worth preserving.
+        grounded: retrieved.filter((id) => claimedSet.has(id)),
+        ungrounded,
+        unused: retrieved.filter((id) => !claimedSet.has(id)),
+    };
+}
+/**
+ * {@link checkCitations}, but a fabricated citation throws.
+ *
+ * Returns the grounded ids, so the caller's happy path is `cited: assertGrounded(...)`.
+ * Use it where an answer is about to be shown as sourced: the failure mode this prevents
+ * is an answer that reads as attributed, names a plausible document, and cannot be traced
+ * to anything — the citation making it MORE trusted than an uncited answer would be.
+ */
+function assertGrounded(claimed, passages) {
+    const check = checkCitations(claimed, passages);
+    if (check.ungrounded.length > 0) {
+        throw new UngroundedCitationError(check.ungrounded, [...new Set(passages.map((p) => p.docId))]);
+    }
+    return check.grounded;
+}
+//# sourceMappingURL=citations.js.map

package/dist/citations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citations.js","sourceRoot":"","sources":["../src/citations.ts"],"names":[],"mappings":";;;AA2CA,wCA4BC;AAUD,wCAMC;AAzED,MAAa,uBAAwB,SAAQ,KAAK;IAErC;IACA;IAFX,YACW,UAA6B,EAC7B,SAA4B;QAErC,KAAK,CACH,gBAAgB,UAAU,CAAC,MAAM,yCAAyC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,GAAG,CACjJ,CAAC;QALO,eAAU,GAAV,UAAU,CAAmB;QAC7B,cAAS,GAAT,SAAS,CAAmB;QAKrC,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAVD,0DAUC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,cAAc,CAC5B,OAA0B,EAC1B,QAA4B;IAE5B,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,SAAS;QAC9C,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAChC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,SAAS;QAC3B,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACb,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,OAAO;QACL,sFAAsF;QACtF,gEAAgE;QAChE,QAAQ,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtD,UAAU;QACV,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;KACtD,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,cAAc,CAAC,OAA0B,EAAE,QAA4B;IACrF,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAChD,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,uBAAuB,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,KAAK,CAAC,QAAQ,CAAC;AACxB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { KnowledgeBase, openKnowledgeBase } from "./KnowledgeBase";
+export type { KnowledgeBaseConfig, RetrieveOptions, SourceOptions, SyncResult, } from "./KnowledgeBase";
+export { packParagraphs } from "./chunk";
+export { checkCitations, assertGrounded, UngroundedCitationError } from "./citations";
+export type { CitationCheck } from "./citations";
+export { groundedRequest, passageMessages } from "./prompt";
+export type { GroundedRequestOptions } from "./prompt";
+export type { Chunker, DocRecord, KnowledgeDoc, Passage } from "./types";
+//# 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,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAInE,YAAY,EACV,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtF,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC5D,YAAY,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACvD,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.passageMessages = exports.groundedRequest = exports.UngroundedCitationError = exports.assertGrounded = exports.checkCitations = exports.packParagraphs = exports.openKnowledgeBase = exports.KnowledgeBase = void 0;
+var KnowledgeBase_1 = require("./KnowledgeBase");
+Object.defineProperty(exports, "KnowledgeBase", { enumerable: true, get: function () { return KnowledgeBase_1.KnowledgeBase; } });
+Object.defineProperty(exports, "openKnowledgeBase", { enumerable: true, get: function () { return KnowledgeBase_1.openKnowledgeBase; } });
+var chunk_1 = require("./chunk");
+Object.defineProperty(exports, "packParagraphs", { enumerable: true, get: function () { return chunk_1.packParagraphs; } });
+var citations_1 = require("./citations");
+Object.defineProperty(exports, "checkCitations", { enumerable: true, get: function () { return citations_1.checkCitations; } });
+Object.defineProperty(exports, "assertGrounded", { enumerable: true, get: function () { return citations_1.assertGrounded; } });
+Object.defineProperty(exports, "UngroundedCitationError", { enumerable: true, get: function () { return citations_1.UngroundedCitationError; } });
+var prompt_1 = require("./prompt");
+Object.defineProperty(exports, "groundedRequest", { enumerable: true, get: function () { return prompt_1.groundedRequest; } });
+Object.defineProperty(exports, "passageMessages", { enumerable: true, get: function () { return prompt_1.passageMessages; } });
+//# sourceMappingURL=index.js.map