agentfootprint 8.7.0 → 8.8.0

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

@@ -1,23 +1,66 @@
 /**
- * defineRAG — sugar factory for retrieval-augmented generation.
+ * defineRAG — retrieval-augmented generation over a document corpus.
  *
- * RAG is a context-engineering flavor: embed the user's question,
- * retrieve top-K semantically similar chunks from a vector store,
- * inject those chunks into the system-prompt slot of the next LLM call.
- * It's the same plumbing as `defineMemory({ type: SEMANTIC,
- * strategy: TOP_K })` — the rename is for intent + ergonomics.
+ * Embed the user's question, retrieve the most similar chunks from a
+ * vector store, inject them into the system-prompt slot of the next LLM
+ * call. It is the same machinery as `defineMemory({ type: SEMANTIC,
+ * strategy: TOP_K })` — with three differences that are not cosmetic:
  *
  *   defineMemory ─┬─► EPISODIC   (raw conversation)
  *                 ├─► SEMANTIC   (extracted facts / RAG chunks)
  *                 ├─► NARRATIVE  (beats / summaries)
  *                 └─► CAUSAL     (footprintjs decision snapshots)
  *
- *   defineRAG    ─►  SEMANTIC + TOP_K with RAG-specific defaults
- *                    (topK=3, threshold=0.7, no LLM-extract)
+ *   defineRAG    ─►  SEMANTIC + TOP_K, READ-ONLY, over a NAMED CORPUS,
+ *                    rendered as citable <source> blocks.
+ *
+ * ─── What changed in 8.8.0, and why ────────────────────────────────────
+ *
+ * **1. A corpus is read-only.** Until 8.8.0 `defineRAG` also mounted the
+ * semantic pipeline's WRITE half, which embedded every conversation turn
+ * and stored it in the same namespace as the documents. The consequence
+ * was measurable and bad: the user's own question, re-embedded, is the
+ * single best-scoring "document" in the corpus (cosine 1.0 against
+ * itself), so it came back as retrieval hit #1 and consumed a slot in
+ * the top-K budget that a real passage should have had. A corpus is not
+ * a conversation log. Nothing this retriever reads is written back.
+ *
+ * If you want conversation memory ALONGSIDE a corpus, that is what
+ * `defineMemory` is for, and the two are registered separately, each
+ * with its own store:
+ *
+ * ```ts
+ * const agent = Agent.create({ provider })
+ *   .rag(defineRAG({ id: 'product-docs', store: corpusStore, embedder }))
+ *   .memory(defineMemory({
+ *     id: 'chat',
+ *     type: MEMORY_TYPES.EPISODIC,
+ *     strategy: { kind: MEMORY_STRATEGIES.WINDOW, size: 10 },
+ *     store: conversationStore,
+ *   }))
+ *   .build();
+ * ```
+ *
+ * **2. The corpus has its own namespace.** A memory reads under the
+ * identity passed to `agent.run()`. For conversation recall that is
+ * right. For a shared corpus it was the reason the documented example
+ * retrieved NOTHING: `indexDocuments` writes under
+ * `{ conversationId: '_global' }` by default, while a run with no
+ * explicit identity gets `{ conversationId: 'run-<timestamp>-<n>' }` —
+ * so the write side and the read side never met, silently. `corpus`
+ * defaults to the same `'_global'` the indexer uses, so the documented
+ * example works with no extra arguments; pass it explicitly when you
+ * index per tenant.
+ *
+ * **3. Chunks are citable.** Retrieved passages render as
+ * `<source id="refunds.md#3" doc="refunds.md" score="0.81">` under a
+ * corpus header, instead of the conversation-recall shape that printed
+ * `role="unknown" turn="0"` on a page of a PDF and gave the model
+ * nothing to cite.
  *
  * Pattern: Composition over duplication — defineRAG returns a
  *          MemoryDefinition produced by defineMemory. No new engine
- *          code, no new slot subflow, no new event type.
+ *          code, no new slot subflow, no new stage.
  *
  * Role:    Layer-3 context-engineering primitive. Lives next to
  *          defineSkill / defineSteering / defineInstruction / defineFact
@@ -25,27 +68,32 @@
  *          (RAG content is computed at runtime via async retrieval —
  *          can't fit the synchronous Injection.inject shape).
  *
- * Emits:   Indirectly — the underlying memory pipeline emits
- *          `agentfootprint.context.injected` when retrieved chunks
- *          land in the system-prompt slot.
+ * Emits:   `agentfootprint.memory.retrieved` (once per retrieval, with
+ *          every candidate and its score — including the rejected ones),
+ *          `agentfootprint.memory.attached` (once per chunk that reached
+ *          the prompt), and `agentfootprint.context.injected` with
+ *          `source: 'rag'` (once per chunk).
  *
  * @see ./indexDocuments.ts  for the seeding helper
  * @see ../../memory/define.ts  for the underlying factory
+ * @see ../../memory/retrieval/  for the retrieval seam
  * @see ../../memory/asRoleRefusal.ts  for why `asRole` is refused, not honoured
  *
- * @example  Basic usage
+ * @example  Basic usage — works with no identity argument anywhere
  * ```ts
- * import { *   Agent, defineRAG, indexDocuments, * } from 'agentfootprint'
-import { InMemoryStore, mockEmbedder } from 'agentfootprint/memory'
-import { mock } from 'agentfootprint/llm-providers';
+ * import { Agent, defineRAG, indexDocuments } from 'agentfootprint';
+ * import { InMemoryStore, mockEmbedder } from 'agentfootprint/memory';
+ * import { mock } from 'agentfootprint/providers';
  *
  * const embedder = mockEmbedder();
  * const store = new InMemoryStore();
  *
- * // Seed the store once at startup
+ * // Seed the corpus once at startup (defaults to the '_global' namespace).
  * await indexDocuments(store, embedder, [
- *   { id: 'doc1', content: 'Refunds are processed within 3 business days.' },
- *   { id: 'doc2', content: 'Pro plan costs $20/month.' },
+ *   { id: 'refunds.md#0', content: 'Refunds are processed within 3 business days.',
+ *     metadata: { source: 'refunds.md' } },
+ *   { id: 'pricing.md#0', content: 'Pro plan costs $20/month.',
+ *     metadata: { source: 'pricing.md' } },
  * ]);
  *
  * const docs = defineRAG({
@@ -60,11 +108,27 @@ import { mock } from 'agentfootprint/llm-providers';
  * const agent = Agent.create({ provider: mock({ reply: 'ok' }), model: 'mock' })
  *   .rag(docs)
  *   .build();
+ *
+ * agent.on('agentfootprint.memory.retrieved', (e) => {
+ *   // every candidate, admitted or not, with its score and its reason
+ *   console.log(e.payload.candidates);
+ * });
+ *
+ * await agent.run({ message: 'How long do refunds take?' });
  * ```
  */
 import type { Embedder } from '../../memory/embedding/index.js';
 import type { MemoryStore } from '../../memory/store/index.js';
+import type { MemoryIdentity } from '../../memory/identity/index.js';
 import type { MemoryDefinition } from '../../memory/define.types.js';
+import type { RetrievalStrategy } from '../../memory/retrieval/index.js';
+/**
+ * The namespace a corpus lives in unless told otherwise — the same one
+ * `indexDocuments` writes to by default. The two defaults are one value
+ * on purpose: index with no options, retrieve with no options, and the
+ * documents are found.
+ */
+export declare const DEFAULT_CORPUS_IDENTITY: MemoryIdentity;
 export interface DefineRAGOptions {
     /** Stable id. Becomes the scope-key suffix and the Lens label. */
     readonly id: string;
@@ -78,13 +142,13 @@ export interface DefineRAGOptions {
      * Vector-capable store containing the indexed corpus. Must implement
      * `search()`. Use `indexDocuments(store, embedder, docs)` at startup
      * to populate it. Ships with `InMemoryStore` for dev/tests; swap to
-     * `pgvector` / Pinecone / Qdrant adapters in production.
+     * a durable adapter in production.
      */
     readonly store: MemoryStore;
     /**
      * Embedder used for the read-side query. Pass the SAME embedder
-     * instance (or one with the same `name`) that was used for indexing
-     * — cross-model similarity scores are not comparable.
+     * instance (or one with the same `embedderId`) that was used for
+     * indexing — cross-model similarity scores are not comparable.
      */
     readonly embedder: Embedder;
     /**
@@ -93,10 +157,28 @@ export interface DefineRAGOptions {
      * embedder swap doesn't pollute results.
      */
     readonly embedderId?: string;
+    /**
+     * The namespace this corpus lives in. Default
+     * `{ conversationId: '_global' }` — the same default `indexDocuments`
+     * writes to, so the plain path needs no argument on either side.
+     *
+     * A corpus is deliberately NOT scoped to the run's identity: it is
+     * shared by every conversation, and reading it under a per-run
+     * conversation id is the bug this default fixes.
+     *
+     * **Multi-tenant:** pass the tenant's identity here AND the same one to
+     * `indexDocuments({ identity })`. A namespace that holds nothing is now
+     * reported (`corpusEmpty` on `agentfootprint.memory.retrieved`, plus a
+     * one-time warning naming the namespace), so a mismatch is loud rather
+     * than an empty answer.
+     */
+    readonly corpus?: MemoryIdentity;
     /**
      * Top-K chunks to retrieve per turn. Default 3 (balanced —
      * defends against lost-in-the-middle while giving multiple
      * perspectives). Increase for richer context, decrease for cost.
+     *
+     * Shorthand for `retrieval: topK({ k })`; the two EXCLUDE.
      */
     readonly topK?: number;
     /**
@@ -106,12 +188,29 @@ export interface DefineRAGOptions {
      *
      * 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. If you see frequent zero-result silent skips,
-     * lower to ~0.5 and observe the `agentfootprint.context.injected`
-     * stream. OpenAI `text-embedding-3-*` and Cohere embed-v3 typically
-     * sit comfortably with 0.7.
+     * 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.
+     *
+     * Shorthand for `retrieval: topK({ threshold })`; the two EXCLUDE.
      */
     readonly threshold?: number;
+    /**
+     * The retrieval rule, spelled out. Replaces `topK` + `threshold`
+     * entirely — passing both is refused, because they could disagree
+     * and the recording would then name a `k` the run did not use.
+     *
+     * ```ts
+     * import { topK } from 'agentfootprint/memory';
+     * defineRAG({ id, store, embedder, retrieval: topK({ k: 5, threshold: 0.55 }) });
+     * ```
+     *
+     * A cross-encoder re-ranker and a diversity (MMR) selector are the
+     * next two adapters behind this same interface; neither ships in
+     * 8.8.0, and the seam exists so that when they do, nothing else moves.
+     */
+    readonly retrieval?: RetrievalStrategy;
 }
 /**
  * Build a RAG context-engineering definition. The returned
@@ -120,6 +219,7 @@ export interface DefineRAGOptions {
  *
  * @throws when `store` does not implement `search()`. RAG requires a
  *         vector-capable adapter.
+ * @throws when `retrieval` is combined with `topK` or `threshold`.
  */
 export declare function defineRAG(opts: DefineRAGOptions): MemoryDefinition;
 //# sourceMappingURL=defineRAG.d.ts.map

package/dist/types/lib/rag/defineRAG.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defineRAG.d.ts","sourceRoot":"","sources":["../../../../src/lib/rag/defineRAG.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAKrE,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAU7B;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,gBAAgB,CAiClE"}
+{"version":3,"file":"defineRAG.d.ts","sourceRoot":"","sources":["../../../../src/lib/rag/defineRAG.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsHG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAKzE;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,cAA8C,CAAC;AAErF,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IAEjC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAUxC;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,gBAAgB,CA0DlE"}

package/dist/types/lib/rag/index.d.ts

@@ -3,6 +3,6 @@
  * flavor. ONE factory + ONE seeding helper. Composes over the memory
  * subsystem (semantic + top-K + strict threshold).
  */
-export { defineRAG, type DefineRAGOptions } from './defineRAG.js';
+export { defineRAG, DEFAULT_CORPUS_IDENTITY, type DefineRAGOptions } from './defineRAG.js';
 export { indexDocuments, type IndexDocumentsOptions, type RagDocument } from './indexDocuments.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/lib/rag/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/rag/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/rag/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,uBAAuB,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/types/memory/define.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/memory/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAaH,OAAO,EAIL,KAAK,mBAAmB,EAYzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAInF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,CAoB3E;AA8QD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,OAAO,CAErF"}
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/memory/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAaH,OAAO,EAIL,KAAK,mBAAmB,EAYzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAInF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,CA4B3E;AAkTD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,OAAO,CAErF"}

package/dist/types/memory/define.types.d.ts

@@ -41,6 +41,8 @@
 import type { LLMProvider } from '../adapters/types.js';
 import type { Embedder } from './embedding/index.js';
 import type { MemoryStore } from './store/index.js';
+import type { MemoryIdentity } from './identity/index.js';
+import type { RetrievalStrategy } from './retrieval/types.js';
 /**
  * What shape of memory you're keeping.
  *
@@ -152,12 +154,44 @@ export interface SummarizeStrategy {
  * STRICT threshold: when no entry meets the threshold, return EMPTY.
  * No fallback — garbage in context is worse than no memory.
  */
-export interface TopKStrategy {
+/**
+ * Top-K retrieval, in either of its two spellings — and never both.
+ *
+ * The arms EXCLUDE (8.8.0). `{ topK, threshold }` is the shorthand;
+ * `{ retrieval }` is the same rule written as a {@link RetrievalStrategy},
+ * which is also how a different rule gets in. Accepting both would mean
+ * one of two `k`s silently loses and the recording would name a `k` the
+ * run did not use — so the type refuses it at the keystroke, and
+ * `defineMemory` refuses it again at runtime for JavaScript callers.
+ */
+export type TopKStrategy = TopKShorthandStrategy | TopKRetrievalStrategy;
+/** The historical spelling: two loose numbers. Unchanged since 2.x. */
+export interface TopKShorthandStrategy {
     readonly kind: typeof MEMORY_STRATEGIES.TOP_K;
     readonly topK: number;
     /** Min cosine similarity. Strict — no fallback below this. Default 0.7. */
     readonly threshold?: number;
     readonly embedder: Embedder;
+    /**
+     * Stable id of the embedder, filtered against `MemoryEntry.embeddingModel`
+     * at search time so a later embedder swap cannot silently mix two vector
+     * spaces. Pair it with the same value passed to `indexDocuments`.
+     *
+     * Wired in 8.8.0. `defineRAG` has accepted an `embedderId` since 7.x and
+     * never forwarded it — an option the run did not read.
+     */
+    readonly embedderId?: string;
+    readonly retrieval?: never;
+}
+/** The spelled-out rule (8.8.0) — and the seam a re-ranker will arrive through. */
+export interface TopKRetrievalStrategy {
+    readonly kind: typeof MEMORY_STRATEGIES.TOP_K;
+    readonly embedder: Embedder;
+    readonly retrieval: RetrievalStrategy;
+    /** See {@link TopKShorthandStrategy.embedderId}. */
+    readonly embedderId?: string;
+    readonly topK?: never;
+    readonly threshold?: never;
 }
 /**
  * Extract — on WRITE, an LLM (or pattern matcher) distills entries from
@@ -234,7 +268,34 @@ export interface MemoryDefinition<T = unknown> {
     readonly redact?: MemoryRedactionPolicy;
     /** Snapshot projection — only meaningful when `type === CAUSAL`. */
     readonly projection?: SnapshotProjection;
+    /**
+     * The namespace this memory reads and writes (8.8.0).
+     *
+     * Absent — the historical behaviour, and still the right one for
+     * conversation memory — means "whatever identity the run was given",
+     * so each conversation remembers its own turns.
+     *
+     * Present means "always this namespace, whoever is asking", which is
+     * what a shared document corpus is: a corpus does not belong to a
+     * conversation, and reading it under a per-run conversation id is why
+     * `defineRAG`'s own documented example retrieved nothing at all before
+     * 8.8.0. `defineRAG` defaults it to `{ conversationId: '_global' }`,
+     * matching `indexDocuments`'s default so the two sides meet.
+     */
+    readonly corpus?: MemoryIdentity;
+    /**
+     * Which claim this memory's injected block makes (8.8.0). `'memory'`
+     * is conversation recall; `'rag'` is corpus retrieval, and it is the
+     * value that reaches the recording as `ContextInjectedPayload.source`.
+     *
+     * The event vocabulary has carried a `'rag'` source since 2.x and
+     * nothing ever emitted it — a declared value no run can produce is a
+     * gap in the contract, not a spare.
+     */
+    readonly flavor?: MemoryFlavor;
 }
+/** What an injected memory block is claiming to be. */
+export type MemoryFlavor = 'memory' | 'rag';
 /**
  * Opaque tag for the compiled flowchart the factory hands back.
  * The actual type is `FlowChart<MemoryState>` from footprintjs but we
@@ -256,6 +317,23 @@ export interface DefineMemoryOptionsBase {
     readonly strategy: Strategy;
     readonly timing?: MemoryTiming;
     readonly redact?: MemoryRedactionPolicy;
+    /**
+     * Read and write under THIS namespace instead of the run's identity
+     * (8.8.0). See {@link MemoryDefinition.corpus}.
+     */
+    readonly corpus?: MemoryIdentity;
+    /**
+     * Build a read-only memory (8.8.0): no write subflow is compiled, so
+     * nothing this memory sees is ever stored back.
+     *
+     * The reason it exists: a retrieval corpus and a conversation log are
+     * two different things sharing one pipeline. Writing the conversation
+     * into the corpus makes the user's own question the best-scoring
+     * "document" in it. `defineRAG` sets this.
+     */
+    readonly readOnly?: boolean;
+    /** Which claim the injected block makes. See {@link MemoryDefinition.flavor}. */
+    readonly flavor?: MemoryFlavor;
 }
 export interface DefineEpisodicOptions extends DefineMemoryOptionsBase {
     readonly type: typeof MEMORY_TYPES.EPISODIC;
@@ -286,4 +364,18 @@ export declare function isSnapshotProjection(value: string): value is SnapshotPr
 export declare const MEMORY_INJECTION_KEY_PREFIX: "memoryInjection_";
 export declare function memoryInjectionKey(id: string): string;
 export declare function isMemoryInjectionKey(key: string): boolean;
+/**
+ * Scope-key prefix for the retrieval record a memory lifts to the parent
+ * scope (8.8.0), one key per memory id — the same layering rule as
+ * `memoryInjection_`.
+ *
+ * This key is the reason a backward slice can now reach a passage. It is
+ * ORDINARY root state, so `sliceForKey('finalContent')` walks the
+ * system-prompt write, and the record naming every candidate id and score
+ * is one hop away. Before 8.8.0 the scores existed only inside the memory
+ * subflow, which the root commit log never sees.
+ */
+export declare const RETRIEVAL_EVIDENCE_KEY_PREFIX: "retrievalEvidence_";
+export declare function retrievalEvidenceKey(id: string): string;
+export declare function isRetrievalEvidenceKey(key: string): boolean;
 //# sourceMappingURL=define.types.d.ts.map

package/dist/types/memory/define.types.d.ts.map

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

package/dist/types/memory/embedding/loadRelevant.d.ts

@@ -1,29 +1,54 @@
 /**
  * loadRelevant — read-side stage that embeds a query and fetches the
- * top-k most similar entries from a vector-capable `MemoryStore`.
+ * most similar entries from a vector-capable `MemoryStore`.
  *
- * Reads from scope:   `identity`, `newMessages` (or custom queryFrom)
- * Writes to scope:    `loaded` (MemoryEntry[], ordered best-first — to be
- *                     narrowed by `pickByBudget` downstream)
+ * Reads from scope:   `identity`, `messages` (or `newMessages`, or custom queryFrom)
+ * Writes to scope:    `loaded` (MemoryEntry[], ordered best-first — narrowed
+ *                     by `pickByBudget` downstream)
+ *                     `retrieved` (RetrievalEvidence — what was considered,
+ *                     what was admitted, and why about each one)
  *
  * Query derivation:
- *   Default: the last user message in `newMessages`. That's the natural
- *   "what is the user asking about?" signal. Override with `queryFrom`
- *   for custom retrieval (e.g., compose user + assistant content,
- *   pull a summary, etc.).
+ *   Default: the last user message. That's the natural "what is the user
+ *   asking about?" signal. Override with `queryFrom` for custom retrieval.
  *
  * Empty behavior:
- *   No query text → no search → `loaded = []`. Downstream
- *   `pickByBudget` picks nothing and the formatter emits nothing — safe.
+ *   No query text → no search → `loaded = []`. Downstream `pickByBudget`
+ *   picks nothing and the formatter emits nothing — safe, and now
+ *   RECORDED: the evidence still lands, saying the query was empty.
  *
  * Feature detection:
- *   Throws at stage build time if the store doesn't implement
- *   `search()`. Fail-loud — a semantic pipeline configured against a
- *   non-vector store is a config bug, not a runtime condition.
+ *   Throws at stage build time if the store doesn't implement `search()`.
+ *   Fail-loud — a semantic pipeline configured against a non-vector store
+ *   is a config bug, not a runtime condition.
+ *
+ * ─── Why the threshold moved out of the store (8.8.0) ──────────────────
+ *
+ * Until 8.8.0 the quality floor was passed to `store.search({ minScore })`,
+ * so every candidate that failed it was filtered INSIDE the store and never
+ * came back. The consequence was not a small one: a retrieval that injected
+ * nothing left no trace of what it nearly injected, and "why did the agent
+ * not read that passage" had no answer anywhere in the recording.
+ *
+ * The floor is now applied here, over a pool of `k + rejectWindow`. **This
+ * does not change which entries are admitted, ever.** Proof: `search`
+ * returns score-descending, and the pool is at least `k`. Either
+ *
+ *   (a) every entry in the pool clears the floor — then the admitted set is
+ *       the first `k` of them, which is exactly what `{ minScore, k }` would
+ *       have returned; or
+ *   (b) some entry at position p fails the floor — then every entry after p
+ *       fails it too, so the pool already contains EVERY entry in the
+ *       namespace that clears the floor, and admitting all of them (capped
+ *       at `k`) is again exactly what `{ minScore, k }` would have returned.
+ *
+ * `rejectWindow` therefore only controls how many near-misses we can SHOW.
+ * It cannot change what the model sees.
  */
 import type { TypedScope } from 'footprintjs';
 import type { MemoryStore } from '../store/index.js';
 import type { MemoryState } from '../stages/index.js';
+import type { RetrievalStrategy } from '../retrieval/types.js';
 import type { Embedder } from './types.js';
 export interface LoadRelevantConfig {
     /** The vector-capable store. Must implement `search()`. */
@@ -43,10 +68,19 @@ export interface LoadRelevantConfig {
     /** Filter results by tier. */
     readonly tiers?: ReadonlyArray<'hot' | 'warm' | 'cold'>;
     /**
-     * Extract the query text from scope. Default: the last user message
-     * in `newMessages`. Override for custom retrieval signals.
+     * The rule that decides which candidates reach the prompt. Defaults to
+     * `topK({ k, threshold: minScore })` — i.e. `k` and `minScore` above are
+     * the shorthand, and this is the same rule spelled out. Pass a strategy
+     * to replace the rule entirely.
+     */
+    readonly retrieval?: RetrievalStrategy;
+    /**
+     * Extract the query text from scope. Default: the last user message.
+     * Override for custom retrieval signals.
      */
     readonly queryFrom?: (scope: TypedScope<MemoryState>) => string;
 }
 export declare function loadRelevant(config: LoadRelevantConfig): (scope: TypedScope<MemoryState>) => Promise<void>;
+/** Test seam — the once-per-process warning is per PROCESS, which tests must be able to reset. */
+export declare function __resetEmptyCorpusWarnings(): void;
 //# sourceMappingURL=loadRelevant.d.ts.map

package/dist/types/memory/embedding/loadRelevant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loadRelevant.d.ts","sourceRoot":"","sources":["../../../../src/memory/embedding/loadRelevant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,4EAA4E;IAC5E,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IAEpB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC;IAExD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,MAAM,CAAC;CACjE;AAwBD,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,WAWhC,WAAW,WAAW,CAAC,KAAG,QAAQ,IAAI,CAAC,CA4B7D"}
+{"version":3,"file":"loadRelevant.d.ts","sourceRoot":"","sources":["../../../../src/memory/embedding/loadRelevant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAKtD,OAAO,KAAK,EAEV,iBAAiB,EAGlB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,4EAA4E;IAC5E,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IAEpB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC;IAExD;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAEvC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,MAAM,CAAC;CACjE;AA8BD,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,WAuBhC,WAAW,WAAW,CAAC,KAAG,QAAQ,IAAI,CAAC,CAgI7D;AAkBD,kGAAkG;AAClG,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}

package/dist/types/memory/index.d.ts

@@ -15,7 +15,8 @@ export * from './pipeline/index.js';
 export * from './stages/index.js';
 export * from './store/index.js';
 export * from './wire/index.js';
-export { MEMORY_TYPES, MEMORY_STRATEGIES, MEMORY_TIMING, SNAPSHOT_PROJECTIONS, MEMORY_INJECTION_KEY_PREFIX, isMemoryType, isMemoryStrategyKind, isMemoryTiming, isSnapshotProjection, memoryInjectionKey, isMemoryInjectionKey, type MemoryType, type MemoryStrategyKind, type MemoryTiming, type SnapshotProjection, type Strategy, type MemoryWindowStrategy, type BudgetStrategy, type SummarizeStrategy, type TopKStrategy, type ExtractStrategy, type DecayStrategy, type HybridStrategy, type MemoryDefinition, type DefineMemoryOptions, type DefineEpisodicOptions, type DefineSemanticOptions, type DefineNarrativeOptions, type DefineCausalOptions, type MemoryRedactionPolicy, } from './define.types.js';
+export * from './retrieval/index.js';
+export { MEMORY_TYPES, MEMORY_STRATEGIES, MEMORY_TIMING, SNAPSHOT_PROJECTIONS, MEMORY_INJECTION_KEY_PREFIX, RETRIEVAL_EVIDENCE_KEY_PREFIX, isMemoryType, isMemoryStrategyKind, isMemoryTiming, isSnapshotProjection, memoryInjectionKey, isMemoryInjectionKey, retrievalEvidenceKey, isRetrievalEvidenceKey, type MemoryType, type MemoryStrategyKind, type MemoryTiming, type SnapshotProjection, type Strategy, type MemoryWindowStrategy, type BudgetStrategy, type SummarizeStrategy, type TopKStrategy, type TopKShorthandStrategy, type TopKRetrievalStrategy, type MemoryFlavor, type ExtractStrategy, type DecayStrategy, type HybridStrategy, type MemoryDefinition, type DefineMemoryOptions, type DefineEpisodicOptions, type DefineSemanticOptions, type DefineNarrativeOptions, type DefineCausalOptions, type MemoryRedactionPolicy, } from './define.types.js';
 /**
  * @deprecated Since 7.27.1 — use `MemoryWindowStrategy`.
  *

package/dist/types/memory/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAGhC,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,EAC3B,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC;AAC3B;;;;;;;;GAQG;AACH,YAAY,EAAE,oBAAoB,IAAI,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEhF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AAGrC,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,EAC3B,6BAA6B,EAC7B,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC;AAC3B;;;;;;;;GAQG;AACH,YAAY,EAAE,oBAAoB,IAAI,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEhF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/types/memory/pipeline/semantic.d.ts

@@ -1,3 +1,5 @@
+import { type MemoryFormatFlavor } from '../stages/formatDefault.js';
+import type { RetrievalStrategy } from '../retrieval/types.js';
 import type { MemoryStore } from '../store/index.js';
 import type { MemoryPipeline } from './types.js';
 import type { Embedder } from '../embedding/types.js';
@@ -29,6 +31,19 @@ export interface SemanticPipelineConfig {
     /** Forwarded to `formatDefault`. */
     readonly formatHeader?: string;
     readonly formatFooter?: string;
+    /**
+     * The retrieval rule (8.8.0). Replaces `k` + `minScore` above; see
+     * {@link RetrievalStrategy}. When absent, `topK({ k, threshold: minScore })`
+     * is built from those two — the same rule, spelled the old way.
+     */
+    readonly retrieval?: RetrievalStrategy;
+    /**
+     * Which claim the injected block makes (8.8.0). `'rag'` renders each
+     * entry as a citable `<source>` with its document, page and score;
+     * `'memory'` (default) keeps the conversation-recall `<memory>` shape
+     * byte for byte.
+     */
+    readonly flavor?: MemoryFormatFlavor;
 }
 /**
  * Build the semantic read + write pipelines sharing a single store.

package/dist/types/memory/pipeline/semantic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../../../src/memory/pipeline/semantic.ts"],"names":[],"mappings":"AA2CA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAQjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,MAAM,WAAW,sBAAsB;IACrC,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,8EAA8E;IAC9E,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IAEpB,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,iCAAiC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC;IAExD,+BAA+B;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAE7C,oDAAoD;IACpD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,mCAAmC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,oCAAoC;IACpC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,cAAc,CAoE/E"}
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../../../src/memory/pipeline/semantic.ts"],"names":[],"mappings":"AAwCA,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAQjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,MAAM,WAAW,sBAAsB;IACrC,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,8EAA8E;IAC9E,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IAEpB,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,iCAAiC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC;IAExD,+BAA+B;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAE7C,oDAAoD;IACpD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,mCAAmC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,oCAAoC;IACpC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAEvC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAC;CACtC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,cAAc,CAsE/E"}

package/dist/types/memory/retrieval/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * memory/retrieval — what a retrieval considered, and the seam that
+ * decides what it keeps.
+ *
+ * @see ./types.ts   the record + the strategy interface
+ * @see ./topK.ts    the strategy 8.7.0 had, now written down as one
+ */
+export type { RetrievalEvidence, RetrievalRejectReason, RetrievalStrategy, RetrievalVerdict, RetrievedCandidate, ScoredCandidate, } from './types.js';
+export { topK, type TopKOptions } from './topK.js';
+export { chunkProvenance, chunkText, type ChunkProvenance } from './provenance.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/memory/retrieval/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/types/memory/retrieval/provenance.d.ts

@@ -0,0 +1,44 @@
+/**
+ * provenance — read a stored entry's coordinates back out of it.
+ *
+ * Pattern: pure projection.
+ * Role:    memory/ layer. One place that knows which metadata keys mean
+ *          "which document", "which page", "which section", so the
+ *          retrieval record and the citation the model sees can never
+ *          disagree about a chunk's origin.
+ * Emits:   N/A.
+ *
+ * The keys are the ones `indexDocuments` already accepts on
+ * `RagDocument.metadata`, and the ones a document splitter will write.
+ * Nothing is invented: an entry that carries no metadata simply has no
+ * coordinates, and the record says so by omitting the fields rather than
+ * by guessing a filename from an id.
+ */
+/** The document coordinates a chunk can carry. All optional — absence is honest. */
+export interface ChunkProvenance {
+    /** Which document this text came from. Read from `docUri`, else `source`. */
+    readonly docUri?: string;
+    /** Which page, for paginated formats. */
+    readonly page?: number;
+    /** Which section heading the splitter cut under. */
+    readonly heading?: string;
+}
+/**
+ * Pull the coordinates out of a stored value.
+ *
+ * Accepts metadata at the value's `metadata` key (where `indexDocuments`
+ * puts it) or directly on the value, so a hand-built entry works too.
+ */
+export declare function chunkProvenance(value: unknown): ChunkProvenance;
+/**
+ * The text a stored value carries.
+ *
+ * Two shapes reach the formatter through the same pipeline: a chat
+ * `Message` (`{ role, content }`) from conversation memory, and a
+ * document (`{ id, content, metadata }`) from `indexDocuments`. Both
+ * keep their text on `content`, which is why one accessor serves both —
+ * but only the message shape has a meaningful `role`, which is why the
+ * corpus formatter does not print one.
+ */
+export declare function chunkText(value: unknown): string;
+//# sourceMappingURL=provenance.d.ts.map