agentfootprint 8.19.0 → 8.20.0

package/bin/agentfootprint-index.mjs

@@ -26,11 +26,15 @@ const USAGE = `
 agentfootprint-index — build a corpus index
 
 USAGE
-  agentfootprint-index <dir> --to <file.db> [options]
+  agentfootprint-index <dir> --to <file.db|file.json> [options]
 
 REQUIRED
   <dir>                  Directory of documents to index
   --to <file.db>         SQLite index file (created if missing)
+  --to <file.json>       Corpus BUNDLE instead: index in memory, export a
+                         plain-JSON artifact for staticVectorStore() — the
+                         build-time half of serving a corpus on a runtime
+                         with no durable disk
 
 OPTIONS
   --embedder <name>      static (default) | local | openai | mock
@@ -53,6 +57,7 @@ EXAMPLES
   agentfootprint-index ./docs --to ./corpus.db
   agentfootprint-index ./docs --to ./corpus.db --embedder local --chars 800
   agentfootprint-index ./docs --to ./corpus.db --dry-run --json
+  agentfootprint-index ./docs --to ./corpus.json --embedder local
 `;
 
 function fail(message) {
@@ -100,7 +105,7 @@ if (!values.to && !values['dry-run']) {
 
 // Imported through the package's own entry points, so the CLI exercises the
 // same doors a consumer does — a break in the export map fails here too.
-const { indexCorpus } = await import('../dist/esm/doors/rag.js');
+const { indexCorpus, exportCorpus } = await import('../dist/esm/doors/rag.js');
 const { byHeading, byParagraph, fixedWithOverlap, wholeDocument } = await import(
   '../dist/esm/doors/rag.js'
 );
@@ -143,10 +148,18 @@ try {
   fail(err instanceof Error ? err.message : String(err));
 }
 
+// A `.json` target builds a corpus BUNDLE: index into a throwaway in-memory
+// store, export with exportCorpus, write one plain-JSON artifact for
+// staticVectorStore() to serve on a runtime with no durable disk.
+const jsonTarget = !values['dry-run'] && values.to !== undefined && values.to.endsWith('.json');
+
 // --dry-run writes to a throwaway in-memory index, so it reports real chunk
 // counts and real splitting without touching the file. It still EMBEDS —
 // the alternative is reporting a count that the real run might not match.
-const store = values['dry-run'] ? new InMemoryStore() : sqliteVectorStore({ file: resolve(values.to) });
+const store =
+  values['dry-run'] || jsonTarget
+    ? new InMemoryStore()
+    : sqliteVectorStore({ file: resolve(values.to) });
 
 try {
   const report = await indexCorpus({
@@ -162,6 +175,18 @@ try {
     ...(values.corpus && { corpus: { conversationId: values.corpus } }),
   });
 
+  if (jsonTarget) {
+    const { writeFileSync } = await import('node:fs');
+    const target = resolve(values.to);
+    const bundle = await exportCorpus(store, values.corpus ? { conversationId: values.corpus } : undefined);
+    writeFileSync(target, JSON.stringify(bundle));
+    process.stdout.write(
+      `wrote corpus bundle: ${target} — ${bundle.entries.length} entries, ` +
+        `'${bundle.embedder.id}@${bundle.embedder.dimensions}'. Serve it with ` +
+        `staticVectorStore(JSON.parse(readFileSync(...)), embedder).\n`,
+    );
+  }
+
   if (values.json) {
     process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
   } else {

package/dist/esm/lib/rag/defineRAG.d.ts

@@ -186,12 +186,15 @@ export interface DefineRAGOptions {
      * meets the threshold, NO injection happens (no fallback that would
      * pollute the prompt with weak matches). Default 0.7.
      *
-     * Tuning note: 0.7 is a high bar for some embedders. Sentence-BERT
-     * relatives (`all-MiniLM-L6-v2`, etc.) often score 0.4–0.6 even on
-     * relevant chunks. You no longer have to guess: the rejected
-     * candidates and their scores are on every
-     * `agentfootprint.memory.retrieved` event, so the right threshold is
-     * a number you can read off a run.
+     * Tuning note: the right threshold is a property of the EMBEDDER. 0.7
+     * is a high bar for some of them. Sentence-BERT relatives
+     * (`all-MiniLM-L6-v2`, etc.) often score 0.4–0.6 even on relevant
+     * chunks; Amazon Titan Text V2 was field-measured at 0.55–0.57 for a
+     * direct hit, ~0.49 for the right section diluted, 0.36–0.42 for
+     * noise — on that embedder the 0.7 default retrieves NOTHING,
+     * silently. You no longer have to guess: the rejected candidates and
+     * their scores are on every `agentfootprint.memory.retrieved` event,
+     * so the right threshold is a number you can read off a run.
      *
      * Shorthand for `retrieval: topK({ threshold })`; the two EXCLUDE.
      */

package/dist/esm/lib/rag/defineRAG.js.map

@@ -1 +1 @@
-{"version":3,"file":"defineRAG.js","sourceRoot":"","sources":["../../../../src/lib/rag/defineRAG.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"defineRAG.js","sourceRoot":"","sources":["../../../../src/lib/rag/defineRAG.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsHG;AAOH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAmB,EAAE,cAAc,EAAE,SAAS,EAAE,CAAC;AAsJrF;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,IAAsB;IAC9C,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;IACD,sEAAsE;IACtE,oEAAoE;IACpE,uDAAuD;IACvD,YAAY,CAAC,IAAI,EAAE,cAAc,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IAC9C,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,CAAC,EAAE,2BAA2B,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,CAAC,EAAE,8BAA8B,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,CAAC,EAAE,oCAAoC;YACtD,yEAAyE,CAC5E,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC;QAC1F,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,CAAC,EAAE,qEAAqE;YACvF,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,6DAA6D;YACrF,kFAAkF,CACrF,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACtD,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;YAAE,SAAS,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAChE,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,CAAC,EAAE,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,yCAAyC;gBACxF,qEAAqE;gBACrE,gBAAgB,IAAI,CAAC,SAAS,CAAC,IAAI,wBAAwB,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CACpF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,YAAY,CAAC;QAClB,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QACxE,IAAI,EAAE,YAAY,CAAC,QAAQ;QAC3B,QAAQ,EACN,IAAI,CAAC,SAAS,KAAK,SAAS;YAC1B,CAAC,CAAC;gBACE,IAAI,EAAE,iBAAiB,CAAC,KAAK;gBAC7B,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,GAAG,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC;gBACrE,8DAA8D;gBAC9D,mDAAmD;gBACnD,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;aAChE;YACH,CAAC,CAAC;gBACE,IAAI,EAAE,iBAAiB,CAAC,KAAK;gBAC7B,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC;gBACpB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,GAAG;gBAChC,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,GAAG,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC;gBACrE,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;aAChE;QACP,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,uDAAuD;QACvD,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,uBAAuB;QAC9C,MAAM,EAAE,KAAK;KACd,CAAC,CAAC;AACL,CAAC"}

package/dist/esm/memory/retrieval/topK.d.ts

@@ -31,13 +31,19 @@ export interface TopKOptions {
      * Minimum similarity to admit, in the store's score space ([-1, 1]
      * cosine for every shipped store). Default 0.7.
      *
-     * 0.7 is a high bar for some embedders. Sentence-transformer relatives
-     * (`all-MiniLM-L6-v2` and family, which `localEmbedder` uses by
+     * **The right threshold is a property of the EMBEDDER, not of this
+     * library.** 0.7 is a high bar for some embedders. Sentence-transformer
+     * relatives (`all-MiniLM-L6-v2` and family, which `localEmbedder` uses by
      * default) often score 0.4–0.6 on genuinely relevant chunks; OpenAI
-     * `text-embedding-3-*` sits comfortably at 0.7. If retrievals come back
-     * empty, read the `agentfootprint.memory.retrieved` event: it now
-     * carries the rejected candidates and their scores, so the right
-     * threshold is a number you can see rather than one you guess.
+     * `text-embedding-3-*` sits comfortably at 0.7. Amazon Titan Text V2
+     * (`bedrockEmbedder`'s default) was measured in a production corpus at
+     * 0.55–0.57 for a direct hit, ~0.49 for the right section diluted by its
+     * neighbours, and 0.36–0.42 for noise — **on that embedder the 0.7
+     * default retrieves NOTHING, silently**; ~0.5 separates its signal from
+     * its noise. If retrievals come back empty, read the
+     * `agentfootprint.memory.retrieved` event: it carries the rejected
+     * candidates and their scores, so the right threshold is a number you
+     * can see rather than one you guess.
      *
      * Pass `null` for no floor — every candidate up to `k` is admitted.
      */

package/dist/esm/memory/retrieval/topK.js.map

@@ -1 +1 @@
-{"version":3,"file":"topK.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/topK.ts"],"names":[],"mappings":"AAqDA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,IAAI,CAAC,UAAuB,EAAE;IAC5C,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC;IACzB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,qDAAqD,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7F,CAAC;IACD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CACb,oEAAoE,MAAM,CACxE,OAAO,CAAC,YAAY,CACrB,GAAG,CACL,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC;IACpF,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CACb,kEAAkE,MAAM,CACtE,OAAO,CAAC,SAAS,CAClB,GAAG,CACL,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,CAAC;QACD,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;QAC7C,YAAY;QACZ,MAAM,CAAC,IAAgC;YACrC,MAAM,QAAQ,GAAuB,EAAE,CAAC;YACxC,IAAI,QAAQ,GAAG,CAAC,CAAC;YACjB,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;gBAC7B,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,KAAK,GAAG,SAAS,EAAE,CAAC;oBAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAAC;oBAC9D,SAAS;gBACX,CAAC;gBACD,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;oBAClB,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAAC;oBAC/D,SAAS;gBACX,CAAC;gBACD,QAAQ,IAAI,CAAC,CAAC;gBACd,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YACpC,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"topK.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/topK.ts"],"names":[],"mappings":"AA2DA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,IAAI,CAAC,UAAuB,EAAE;IAC5C,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC;IACzB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,qDAAqD,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7F,CAAC;IACD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CACb,oEAAoE,MAAM,CACxE,OAAO,CAAC,YAAY,CACrB,GAAG,CACL,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC;IACpF,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CACb,kEAAkE,MAAM,CACtE,OAAO,CAAC,SAAS,CAClB,GAAG,CACL,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,CAAC;QACD,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;QAC7C,YAAY;QACZ,MAAM,CAAC,IAAgC;YACrC,MAAM,QAAQ,GAAuB,EAAE,CAAC;YACxC,IAAI,QAAQ,GAAG,CAAC,CAAC;YACjB,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;gBAC7B,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,KAAK,GAAG,SAAS,EAAE,CAAC;oBAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAAC;oBAC9D,SAAS;gBACX,CAAC;gBACD,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;oBAClB,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAAC;oBAC/D,SAAS;gBACX,CAAC;gBACD,QAAQ,IAAI,CAAC,CAAC;gBACd,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YACpC,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/memory/store/index.d.ts

@@ -1,2 +1,3 @@
 export type { MemoryStore, ListOptions, ListResult, MemoryCursor, PutIfVersionResult, SearchOptions, ScoredEntry, } from './types.js';
 export { InMemoryStore } from './InMemoryStore.js';
+export { staticVectorStore, assertCorpusBundle, bundleEntryToMemoryEntry, CORPUS_BUNDLE_FORMAT, type CorpusBundle, type CorpusBundleEntry, type EmbedderFingerprint, } from './staticVectorStore.js';

package/dist/esm/memory/store/index.js

@@ -1,2 +1,3 @@
 export { InMemoryStore } from './InMemoryStore.js';
+export { staticVectorStore, assertCorpusBundle, bundleEntryToMemoryEntry, CORPUS_BUNDLE_FORMAT, } from './staticVectorStore.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/memory/store/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/memory/store/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/memory/store/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,GAIrB,MAAM,wBAAwB,CAAC"}

package/dist/esm/memory/store/staticVectorStore.d.ts

@@ -0,0 +1,83 @@
+import type { MemoryEntry } from '../entry/index.js';
+import type { MemoryStore } from './types.js';
+/** The bundle format marker. Version the FORMAT, not the library. */
+export declare const CORPUS_BUNDLE_FORMAT: "agentfootprint-corpus-v1";
+/** One exported corpus entry: the passage, its vector, and its coordinates. */
+export interface CorpusBundleEntry {
+    /** The chunk id, e.g. `'refunds.md#3'` — what the model cites. */
+    readonly id: string;
+    /** The passage text. */
+    readonly text: string;
+    /** The embedding vector, in the bundle embedder's space. */
+    readonly vector: readonly number[];
+    /**
+     * Everything else the stored value carried — provenance (`docUri`,
+     * `heading`, `page`, offsets, hashes) and any consumer metadata, flattened
+     * into one record the retrieval formatter's provenance reader understands.
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A corpus as a plain-JSON build artifact. Produced by `exportCorpus`
+ * (`agentfootprint/rag`), served by {@link staticVectorStore}, loadable into a
+ * writable store by `importCorpus`. Survives `JSON.stringify` → `JSON.parse`
+ * byte-for-byte, which is the whole point.
+ */
+export interface CorpusBundle {
+    readonly format: typeof CORPUS_BUNDLE_FORMAT;
+    /** The embedding space every vector in `entries` lives in. */
+    readonly embedder: {
+        /** The embedder id recorded at index time (`'default-embedder'` when the index never named one). */
+        readonly id: string;
+        /** Vector length. Every entry's vector has exactly this many numbers. */
+        readonly dimensions: number;
+    };
+    /** The namespace the corpus was exported from (`identityNamespace` form). */
+    readonly namespace: string;
+    /** Unix ms at export time. */
+    readonly exportedAt: number;
+    readonly entries: readonly CorpusBundleEntry[];
+}
+/** The embedder-shaped slice the load-time fingerprint check needs. */
+export interface EmbedderFingerprint {
+    readonly id?: string;
+    readonly dimensions: number;
+}
+/**
+ * Validate a value as a `CorpusBundle`, teachingly. Shared by
+ * `staticVectorStore` and `importCorpus`, so a truncated file or a
+ * hand-edited bundle fails the same way at every door.
+ */
+export declare function assertCorpusBundle(bundle: unknown, caller: string): asserts bundle is CorpusBundle;
+/**
+ * The `MemoryEntry` a bundle entry seeds — in the exact shape the retrieval
+ * formatter reads: passage on `value.content`, provenance under
+ * `value.metadata`. Shared with `importCorpus` so a static corpus and an
+ * imported one render identically.
+ */
+export declare function bundleEntryToMemoryEntry(entry: CorpusBundleEntry, bundle: CorpusBundle): MemoryEntry<{
+    id: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}>;
+/**
+ * Serve an exported corpus bundle as a read-only, vector-capable
+ * `MemoryStore`.
+ *
+ * @param bundle   a `CorpusBundle` from `exportCorpus` (usually
+ *                 `JSON.parse` of the shipped file).
+ * @param embedder optional — the embedder the RUNTIME will query with (or
+ *                 just `{ id, dimensions }`). When given, a fingerprint
+ *                 mismatch is refused HERE, at load, instead of surfacing as
+ *                 an empty retrieval at the first question. Recommended.
+ *
+ * @example
+ * ```ts
+ * import { staticVectorStore } from 'agentfootprint/memory';
+ * import corpus from './corpus.json';
+ *
+ * const store = staticVectorStore(corpus, embedder);
+ * const docs = defineRAG({ id: 'docs', store, embedder });
+ * ```
+ */
+export declare function staticVectorStore(bundle: CorpusBundle, embedder?: EmbedderFingerprint): MemoryStore;

package/dist/esm/memory/store/staticVectorStore.js

@@ -0,0 +1,224 @@
+import { identityNamespace } from '../identity/index.js';
+import { cosineSimilarity } from '../embedding/cosine.js';
+/** The bundle format marker. Version the FORMAT, not the library. */
+export const CORPUS_BUNDLE_FORMAT = 'agentfootprint-corpus-v1';
+/**
+ * Validate a value as a `CorpusBundle`, teachingly. Shared by
+ * `staticVectorStore` and `importCorpus`, so a truncated file or a
+ * hand-edited bundle fails the same way at every door.
+ */
+export function assertCorpusBundle(bundle, caller) {
+    const b = bundle;
+    if (b === null || typeof b !== 'object') {
+        throw new Error(`${caller}: expected a corpus bundle object, received ${b === null ? 'null' : typeof b}. ` +
+            `A bundle comes from exportCorpus() — typically JSON.parse of the file it was saved to.`);
+    }
+    if (b.format !== CORPUS_BUNDLE_FORMAT) {
+        throw new Error(`${caller}: this is not a corpus bundle — \`format\` is ${JSON.stringify(b.format)}, expected '${CORPUS_BUNDLE_FORMAT}'. Bundles are produced by exportCorpus(); a raw ` +
+            `entries array or a different artifact cannot be served as one.`);
+    }
+    const dims = b.embedder?.dimensions;
+    if (typeof b.embedder?.id !== 'string' || typeof dims !== 'number' || dims < 1) {
+        throw new Error(`${caller}: the bundle does not name its embedding space — \`embedder\` must carry a ` +
+            `string \`id\` and a positive \`dimensions\`. Without them nothing can refuse a wrong ` +
+            `embedder at load, which is the silent failure this format exists to prevent.`);
+    }
+    if (typeof b.namespace !== 'string' || b.namespace.length === 0) {
+        throw new Error(`${caller}: the bundle carries no \`namespace\`. Re-export with exportCorpus().`);
+    }
+    if (!Array.isArray(b.entries)) {
+        throw new Error(`${caller}: \`entries\` must be an array. Re-export with exportCorpus().`);
+    }
+    b.entries.forEach((entry, i) => {
+        const where = `entries[${i}]${entry?.id ? ` ('${entry.id}')` : ''}`;
+        if (!entry || typeof entry.id !== 'string' || entry.id.length === 0) {
+            throw new Error(`${caller}: ${where} has no \`id\`.`);
+        }
+        if (typeof entry.text !== 'string' || entry.text.trim().length === 0) {
+            throw new Error(`${caller}: ${where} has no passage on \`text\`. A citable id with nothing to cite is ` +
+                `the blank-citation bug; a bundle never carries one.`);
+        }
+        if (!Array.isArray(entry.vector) || entry.vector.length !== dims) {
+            throw new Error(`${caller}: ${where} carries a vector of length ` +
+                `${Array.isArray(entry.vector) ? entry.vector.length : 'none'}, but the bundle's ` +
+                `embedder declares ${dims} dimensions. The bundle is corrupt or hand-edited — ` +
+                `re-export it.`);
+        }
+    });
+}
+/**
+ * The `MemoryEntry` a bundle entry seeds — in the exact shape the retrieval
+ * formatter reads: passage on `value.content`, provenance under
+ * `value.metadata`. Shared with `importCorpus` so a static corpus and an
+ * imported one render identically.
+ */
+export function bundleEntryToMemoryEntry(entry, bundle) {
+    return {
+        id: entry.id,
+        value: {
+            id: entry.id,
+            content: entry.text,
+            ...(entry.metadata !== undefined && { metadata: { ...entry.metadata } }),
+        },
+        version: 1,
+        createdAt: bundle.exportedAt,
+        updatedAt: bundle.exportedAt,
+        lastAccessedAt: bundle.exportedAt,
+        accessCount: 0,
+        embedding: [...entry.vector],
+        embeddingModel: bundle.embedder.id,
+    };
+}
+const READ_ONLY_FIX = `A static corpus is a build artifact: change it by re-indexing at build time and ` +
+    `re-exporting (exportCorpus), or load the bundle into a writable store with ` +
+    `importCorpus(store, bundle). For conversation memory alongside a static corpus, ` +
+    `register a SEPARATE defineMemory with its own writable store.`;
+function refuseWrite(method) {
+    throw new Error(`staticVectorStore.${method}: this store is read-only — accepting the write and losing ` +
+        `it with the process would be the quiet version of data loss. ${READ_ONLY_FIX}`);
+}
+/**
+ * Serve an exported corpus bundle as a read-only, vector-capable
+ * `MemoryStore`.
+ *
+ * @param bundle   a `CorpusBundle` from `exportCorpus` (usually
+ *                 `JSON.parse` of the shipped file).
+ * @param embedder optional — the embedder the RUNTIME will query with (or
+ *                 just `{ id, dimensions }`). When given, a fingerprint
+ *                 mismatch is refused HERE, at load, instead of surfacing as
+ *                 an empty retrieval at the first question. Recommended.
+ *
+ * @example
+ * ```ts
+ * import { staticVectorStore } from 'agentfootprint/memory';
+ * import corpus from './corpus.json';
+ *
+ * const store = staticVectorStore(corpus, embedder);
+ * const docs = defineRAG({ id: 'docs', store, embedder });
+ * ```
+ */
+export function staticVectorStore(bundle, embedder) {
+    assertCorpusBundle(bundle, 'staticVectorStore');
+    if (embedder !== undefined) {
+        // The sqliteVectorStore rule, applied at load: dimensions ALWAYS decide;
+        // ids decide only when both sides named themselves.
+        if (embedder.dimensions !== bundle.embedder.dimensions) {
+            throw new Error(`staticVectorStore: this bundle was built in '${bundle.embedder.id}@` +
+                `${bundle.embedder.dimensions}' and the configured embedder produces ` +
+                `${embedder.dimensions}-dimensional vectors. Vectors of different lengths cannot ` +
+                `be compared at all. Re-export the corpus with the runtime's embedder, or ` +
+                `configure the embedder the corpus was built with.`);
+        }
+        if (embedder.id !== undefined && embedder.id !== bundle.embedder.id) {
+            throw new Error(`staticVectorStore: this bundle was built in '${bundle.embedder.id}@` +
+                `${bundle.embedder.dimensions}' and the configured embedder is '${embedder.id}'. ` +
+                `Cosine similarity between two embedding spaces is not a weak signal — it is not ` +
+                `a signal, and it comes back as a confident number in the same range as a real ` +
+                `one. Re-export the corpus with '${embedder.id}', or configure ` +
+                `'${bundle.embedder.id}'.`);
+        }
+    }
+    const entries = new Map();
+    for (const entry of bundle.entries) {
+        entries.set(entry.id, bundleEntryToMemoryEntry(entry, bundle));
+    }
+    const namespace = bundle.namespace;
+    const inNamespace = (identity) => identityNamespace(identity) === namespace;
+    return {
+        // Vectors in, ranked vectors out — the cosine scan below ranks the
+        // embeddings the bundle carries. Declared, so corpus builders can tell
+        // this apart from a server-side store (and refuse to INDEX into it —
+        // which they will anyway, at the first write).
+        supportsVectorSearch: true,
+        async get(identity, id) {
+            if (!inNamespace(identity))
+                return null;
+            // No access-count bump: the store is read-only, decay signals frozen
+            // at export.
+            return entries.get(id) ?? null;
+        },
+        async put() {
+            refuseWrite('put');
+        },
+        async putMany() {
+            refuseWrite('putMany');
+        },
+        async putIfVersion() {
+            refuseWrite('putIfVersion');
+        },
+        async delete() {
+            refuseWrite('delete');
+        },
+        async forget() {
+            refuseWrite('forget');
+        },
+        async recordSignature() {
+            refuseWrite('recordSignature');
+        },
+        async feedback() {
+            refuseWrite('feedback');
+        },
+        async list(identity, options) {
+            if (!inNamespace(identity))
+                return { entries: [] };
+            const limit = Math.max(1, Math.min(options?.limit ?? 100, 1000));
+            const all = [...entries.values()];
+            const offset = options?.cursor ? parseInt(options.cursor, 10) : 0;
+            const safeOffset = Number.isFinite(offset) && offset >= 0 ? offset : 0;
+            const page = all.slice(safeOffset, safeOffset + limit);
+            const next = safeOffset + page.length;
+            return {
+                entries: page,
+                ...(next < all.length && { cursor: String(next) }),
+            };
+        },
+        async seen() {
+            return false; // no signature set was exported; recognition is a write-side concern
+        },
+        async getFeedback() {
+            return null;
+        },
+        async search(identity, query, options) {
+            // A wrong-space query is refused BY NAME rather than ranked to an empty
+            // page — the loud version of the mismatch machinery, because on a
+            // static corpus "no results" reads as "the corpus has nothing to say".
+            if (query.length !== bundle.embedder.dimensions) {
+                throw new Error(`staticVectorStore.search: the query vector has ${query.length} dimensions, but ` +
+                    `this bundle was built in '${bundle.embedder.id}@${bundle.embedder.dimensions}'. ` +
+                    `The query was embedded with a different embedder than the corpus. Configure the ` +
+                    `embedder the corpus was built with, or re-export the corpus.`);
+            }
+            if (options?.embedderId !== undefined && options.embedderId !== bundle.embedder.id) {
+                throw new Error(`staticVectorStore.search: the retriever declares embedderId '${options.embedderId}' ` +
+                    `but this bundle was built in '${bundle.embedder.id}@` +
+                    `${bundle.embedder.dimensions}'. Silently skipping every entry would look like an ` +
+                    `empty corpus. Align the retriever's \`embedderId\` with the bundle, or re-export ` +
+                    `the corpus with the new embedder.`);
+            }
+            if (!inNamespace(identity))
+                return [];
+            const k = options?.k ?? 10;
+            const tierFilter = options?.tiers ? new Set(options.tiers) : undefined;
+            const minScore = options?.minScore;
+            const scored = [];
+            for (const entry of entries.values()) {
+                if (tierFilter && (!entry.tier || !tierFilter.has(entry.tier)))
+                    continue;
+                const emb = entry.embedding;
+                if (!emb || emb.length !== query.length)
+                    continue;
+                const score = cosineSimilarity(emb, query);
+                if (minScore !== undefined && score < minScore)
+                    continue;
+                scored.push({ entry: entry, score });
+            }
+            scored.sort((a, b) => {
+                if (b.score !== a.score)
+                    return b.score - a.score;
+                return a.entry.id < b.entry.id ? -1 : a.entry.id > b.entry.id ? 1 : 0;
+            });
+            return scored.slice(0, k);
+        },
+    };
+}
+//# sourceMappingURL=staticVectorStore.js.map

package/dist/esm/memory/store/staticVectorStore.js.map

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

package/dist/esm/observe.d.ts

@@ -39,6 +39,7 @@ export { boundaryRecorder, BoundaryRecorder, type ActorArrow, type BoundaryAggre
 export { buildRunSteps, RunStepRecorder, runStepRecorder, type BuildRunStepsOptions, type RunStep, type RunStepGraph, type RunStepKind, type RunStepMeta, type RunStepRecorderOptions, type RunStepTransition, } from './recorders/observability/RunStepRecorder.js';
 export { attachFlowchart, buildStepGraph, buildStepGraphFromEvents, type StepGraph, type StepNode, type StepEdge, type SlotBoundary, type ContextInjection, type FlowchartOptions, type FlowchartHandle, } from './recorders/observability/FlowchartRecorder.js';
 export { recordRun, type Recording, type RecordRunOptions, type RunRecorder, } from './recorders/observability/recordRun.js';
+export { summarizeEmbeddings, summarizeVector, type EmbeddingSummary, } from './recorders/observability/embeddingSummary.js';
 export { serializeTrace, redactContent, traceToStepGraph, type Trace, type TraceSummary, type TraceRedaction, type SerializeTraceOptions, } from './recorders/observability/trace.js';
 export { attachLocalObservability, type LocalObservabilityHandle, type LocalObservabilityOptions, } from './recorders/observability/localObservability.js';
 export { liveStateRecorder, LiveStateRecorder, LiveLLMTracker, LiveToolTracker, LiveAgentTurnTracker, type LLMLiveState, type ToolLiveState, type AgentTurnLiveState, type LiveStateRunnerLike, } from './recorders/observability/LiveStateRecorder.js';

package/dist/esm/observe.js

@@ -45,6 +45,11 @@ export { attachFlowchart, buildStepGraph, buildStepGraphFromEvents, } from './re
 // which is the shape the UIs consume (lens's `observeRecording`) and the one
 // every integration used to assemble by hand, each missing a different piece.
 export { recordRun, } from './recorders/observability/recordRun.js';
+// What a recording keeps of a vector: `{ dims, norm }`, not the bytes (8.20.0).
+// Applied by BoundaryRecorder and recordRun unless `recordEmbeddings: true`;
+// exported so consumers that render or post-process recordings can apply or
+// recognise the same projection.
+export { summarizeEmbeddings, summarizeVector, } from './recorders/observability/embeddingSummary.js';
 // Offline replay: freeze a live run model into a UI-free, JSON-lossless Trace
 // (redaction applied at the serialize boundary). agentfootprint-lens's <Replay>
 // rehydrates it. See docs/design/local-observability-and-pii.md.

package/dist/esm/observe.js.map

@@ -1 +1 @@
-{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,4BAA4B;AAC5B,OAAO,EAAE,eAAe,EAA+B,MAAM,qCAAqC,CAAC;AACnG,OAAO,EAAE,cAAc,EAA8B,MAAM,oCAAoC,CAAC;AAEhG,+BAA+B;AAC/B,OAAO,EACL,mBAAmB,GAEpB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GAkBjB,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACL,aAAa,EACb,eAAe,EACf,eAAe,GAQhB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,eAAe,EACf,cAAc,EACd,wBAAwB,GAQzB,MAAM,gDAAgD,CAAC;AAExD,yEAAyE;AACzE,6EAA6E;AAC7E,6EAA6E;AAC7E,8EAA8E;AAC9E,OAAO,EACL,SAAS,GAIV,MAAM,wCAAwC,CAAC;AAEhD,8EAA8E;AAC9E,gFAAgF;AAChF,iEAAiE;AACjE,OAAO,EACL,cAAc,EACd,aAAa,EACb,gBAAgB,GAKjB,MAAM,oCAAoC,CAAC;AAE5C,mEAAmE;AACnE,4EAA4E;AAC5E,mDAAmD;AACnD,OAAO,EACL,wBAAwB,GAGzB,MAAM,iDAAiD,CAAC;AAEzD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,oBAAoB,GAKrB,MAAM,gDAAgD,CAAC;AAExD,6BAA6B;AAC7B,OAAO,EAAE,YAAY,EAA4B,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,wBAAwB,GAEzB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAAE,YAAY,EAA4B,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,cAAc,EAA8B,MAAM,oCAAoC,CAAC;AAChG,OAAO,EACL,iBAAiB,GAElB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,kBAAkB,GAEnB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,qEAAqE;AACrE,0EAA0E;AAC1E,wEAAwE;AACxE,oDAAoD;AACpD,OAAO,EACL,kBAAkB,GAEnB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,aAAa,EACb,cAAc,GAIf,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,YAAY,GAGb,MAAM,6CAA6C,CAAC;AACrD,4EAA4E;AAC5E,gFAAgF;AAChF,OAAO,EACL,mBAAmB,GAMpB,MAAM,kDAAkD,CAAC;AAC1D,gFAAgF;AAChF,gFAAgF;AAChF,OAAO,EACL,kBAAkB,GAQnB,MAAM,yDAAyD,CAAC;AAEjE,uDAAuD;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE1D,kEAAkE;AAClE,uEAAuE;AACvE,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,wEAAwE;AACxE,cAAc,YAAY,CAAC;AAC3B,sEAAsE;AACtE,uEAAuE;AACvE,qEAAqE;AACrE,oEAAoE;AACpE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GAOnB,MAAM,iDAAiD,CAAC;AAEzD,OAAO,EACL,aAAa,EACb,cAAc,GAOf,MAAM,4CAA4C,CAAC;AAEpD,sEAAsE;AACtE,4EAA4E;AAC5E,+CAA+C;AAC/C,OAAO,EACL,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,WAAW,GACZ,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/observe.ts"],"names":[],"mappings":"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"}

package/dist/esm/rag/exportCorpus.d.ts

@@ -0,0 +1,64 @@
+/**
+ * exportCorpus / importCorpus — a corpus as a build artifact.
+ *
+ * Pattern: projection (store → plain-JSON bundle) and its inverse.
+ * Role:    rag/ layer — the build-time half of the story whose runtime half
+ *          is `staticVectorStore` (`agentfootprint/memory`). Index where the
+ *          credentials and the durable disk live; ship the bundle with the
+ *          deploy; serve it read-only where the process runs.
+ * Emits:   N/A — build-step helpers, not run-time stages.
+ *
+ * ── The deployment shape this exists for ────────────────────────────────────
+ * An immutable or serverless runtime loses its disk between invocations and
+ * often holds no embedding-API credentials — while the build machine has
+ * both. So the corpus becomes an artifact of the BUILD:
+ *
+ *   // build step (cron, CI, deploy hook) — credentials live here
+ *   const report = await indexFolder('./docs', { to: store, embedder });
+ *   writeFileSync('corpus.json', JSON.stringify(await exportCorpus(store)));
+ *
+ *   // runtime — no disk, no embedding writes, no drift
+ *   const store = staticVectorStore(JSON.parse(readFileSync('corpus.json', 'utf8')), embedder);
+ *   const docs = defineRAG({ id: 'docs', store, embedder });
+ *
+ * The bundle records the embedder id and dimensions it was built with, so the
+ * runtime can REFUSE a mismatched embedder at load instead of discovering it
+ * as an empty retrieval — the same fingerprint discipline the durable store
+ * enforces per write.
+ *
+ * `importCorpus` is the inverse for a WRITABLE store: load a bundle into
+ * InMemoryStore at boot, or into sqliteVectorStore to migrate a corpus
+ * between machines without re-embedding (and re-billing) anything.
+ */
+import type { MemoryStore } from '../memory/store/index.js';
+import type { MemoryIdentity } from '../memory/identity/index.js';
+import { type CorpusBundle } from '../memory/store/staticVectorStore.js';
+/**
+ * Export every entry of a corpus namespace as a plain-JSON bundle.
+ *
+ * @param store    the store the corpus was indexed into. Any `MemoryStore`
+ *                 that can `list` — the reference stores and the durable one
+ *                 all can.
+ * @param identity the namespace to export. Defaults to the same
+ *                 `{ conversationId: '_global' }` that `indexCorpus`,
+ *                 `indexFolder`, `indexDocuments` and `defineRAG` default to,
+ *                 so the plain path needs no argument anywhere.
+ *
+ * @throws when the namespace is empty (almost always an identity mismatch,
+ *         named as such), when an entry carries no vector or no passage (a
+ *         bundle never ships an unservable entry), or when the namespace
+ *         mixes embedding spaces (two spaces in one bundle could never be
+ *         served by one embedder).
+ */
+export declare function exportCorpus(store: MemoryStore, identity?: MemoryIdentity): Promise<CorpusBundle>;
+/**
+ * Load a bundle into a WRITABLE vector-capable store — the inverse of
+ * `exportCorpus`. Use it to seed an `InMemoryStore` at boot from a shipped
+ * bundle, or to migrate a corpus between machines without re-embedding.
+ *
+ * Entries are written in the same formatter-ready shape `staticVectorStore`
+ * serves, so the two paths render identically.
+ *
+ * @returns the number of entries written.
+ */
+export declare function importCorpus(store: MemoryStore, bundle: CorpusBundle, identity?: MemoryIdentity): Promise<number>;