agentfootprint 8.7.0 → 8.9.0

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

@@ -59,10 +59,15 @@ export interface IndexDocumentsOptions {
      */
     readonly identity?: MemoryIdentity;
     /**
-     * Stable id of the embedder. Stored on each entry so a future
-     * embedder swap doesn't silently mix similarity scores. Default:
-     * `'default-embedder'` — pass an explicit id when you may rotate
-     * embedders.
+     * Stable id of the embedder. Stored on each entry so a future embedder swap
+     * doesn't silently mix similarity scores.
+     *
+     * Defaults to the embedder's own `id` (8.9.0 — every shipped embedder sets
+     * one), and to `'default-embedder'` for a hand-written `Embedder` that has
+     * none. That default matters more with a durable store: it is half of the
+     * `'<id>@<dims>'` fingerprint `sqliteVectorStore` records per vector and
+     * refuses on, so an index built by `staticEmbedder()` will not silently
+     * accept vectors from `openaiEmbedder()`.
      */
     readonly embedderId?: string;
     /**
@@ -81,6 +86,23 @@ export interface IndexDocumentsOptions {
      * this through to abort batch indexing on shutdown / timeout.
      */
     readonly signal?: AbortSignal;
+    /**
+     * Called once with the cost of the embedding work this call did (8.9.0).
+     *
+     * `indexDocuments` runs at STARTUP, outside any agent run, so it has no
+     * emit channel to ride — there is no scope, no dispatcher and no
+     * `runtimeStageId` to correlate against. Rather than pretend otherwise, it
+     * hands the same payload the in-run stages emit as
+     * `agentfootprint.embedding.generated` straight to you, so the index-time
+     * half of the cost model is reportable from a boot script:
+     *
+     * ```ts
+     * await indexDocuments(store, embedder, docs, {
+     *   onEmbedding: (e) => console.log(`embedded ${e.count} documents in ${e.durationMs}ms`),
+     * });
+     * ```
+     */
+    readonly onEmbedding?: (payload: import('../../events/payloads.js').EmbeddingGeneratedPayload) => void;
     /**
      * Max number of concurrent embed calls when the embedder doesn't
      * implement `embedBatch`. Default `8`. Without this cap, a 10K-doc

package/dist/esm/lib/rag/indexDocuments.js

@@ -51,8 +51,11 @@ export async function indexDocuments(store, embedder, documents, options = {}) {
     if (!Array.isArray(documents) || documents.length === 0)
         return 0;
     const identity = options.identity ?? DEFAULT_IDENTITY;
-    const embedderId = options.embedderId ?? 'default-embedder';
+    // The embedder's own name first: it is what a durable store fingerprints
+    // the namespace with, and an anonymous index cannot refuse a later swap.
+    const embedderId = options.embedderId ?? embedder.id ?? 'default-embedder';
     const now = Date.now();
+    const embedStartedAt = Date.now();
     const ttl = options.ttlMs ? now + options.ttlMs : undefined;
     // Embed in batch when supported, else fall back to capped-concurrency
     // single calls. Unlimited concurrency on a large corpus would
@@ -69,6 +72,14 @@ export async function indexDocuments(store, embedder, documents, options = {}) {
         const limit = Math.max(1, options.maxConcurrency ?? 8);
         vectors = await embedWithConcurrency(embedder, texts, limit, options.signal);
     }
+    options.onEmbedding?.({
+        model: embedderId,
+        provider: 'custom',
+        inputKind: 'document',
+        dimension: embedder.dimensions,
+        count: vectors.length,
+        durationMs: Date.now() - embedStartedAt,
+    });
     const entries = documents.map((doc, i) => {
         const vec = vectors[i];
         return {

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

@@ -1 +1 @@
-{"version":3,"file":"indexDocuments.js","sourceRoot":"","sources":["../../../../src/lib/rag/indexDocuments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAwEH,MAAM,gBAAgB,GAAmB,EAAE,cAAc,EAAE,SAAS,EAAE,CAAC;AAEvE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,KAAkB,EAClB,QAAkB,EAClB,SAAiC,EACjC,UAAiC,EAAE;IAEnC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IACpE,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC1E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAElE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,gBAAgB,CAAC;IACtD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,kBAAkB,CAAC;IAC5D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAE5D,sEAAsE;IACtE,8DAA8D;IAC9D,oDAAoD;IACpD,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC9C,IAAI,OAAuC,CAAC;IAC5C,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;QACxB,OAAO,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC;YAClC,KAAK;YACL,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;SAClD,CAAC,CAAC;IACL,CAAC;SAAM,CAAC;QACN,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,cAAc,IAAI,CAAC,CAAC,CAAC;QACvD,OAAO,GAAG,MAAM,oBAAoB,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/E,CAAC;IAED,MAAM,OAAO,GAA+B,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;QACnE,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACvB,OAAO;YACL,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,KAAK,EAAE,GAAG;YACV,OAAO,EAAE,CAAC;YACV,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,GAAG;YACd,cAAc,EAAE,GAAG;YACnB,WAAW,EAAE,CAAC;YACd,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC;YACrD,cAAc,EAAE,UAAU;YAC1B,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,CAAC;YACjC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;YAC3C,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE;SAC9B,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACvC,OAAO,OAAO,CAAC,MAAM,CAAC;AACxB,CAAC;AAED,KAAK,UAAU,oBAAoB,CACjC,QAAkB,EAClB,KAAwB,EACxB,KAAa,EACb,MAAoB;IAEpB,MAAM,OAAO,GAA0B,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/D,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,IAAI,EAAE;QAC/E,SAAS,CAAC;YACR,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC;YACjB,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM;gBAAE,OAAO;YAC9B,wDAAwD;YACxD,oEAAoE;YACpE,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;YACvB,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC;gBAChC,IAAI;gBACJ,GAAG,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,CAAC;aAC1B,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;IACH,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"indexDocuments.js","sourceRoot":"","sources":["../../../../src/lib/rag/indexDocuments.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/sqliteUnavailable.d.ts

@@ -0,0 +1,55 @@
+/**
+ * lib/sqliteUnavailable — the one refusal for "this Node has no `node:sqlite`".
+ *
+ * Pattern: leaf error type (imports nothing).
+ * Role:    shared by `hosting/sqliteSessions` and `adapters/memory/sqliteVector`.
+ *          It lives here rather than in either of them because two adapters
+ *          hitting the same missing module must raise the same error: a
+ *          consumer catching `SqliteUnavailableError` should not have to know
+ *          which of our stores was being constructed, and two classes of one
+ *          name is a duplicate type the build refuses anyway.
+ * Emits:   N/A.
+ *
+ * Node 20 does not have the module at all; Node 22.5 through 22.12 have it
+ * behind `--experimental-sqlite`; Node 22.13+ and 23.4+ have it as-is (still
+ * marked experimental by Node, which is why it prints a warning on first use).
+ *
+ * The refusal names the version you are on and the three ways out, because
+ * "cannot find module 'node:sqlite'" out of a library's guts tells you what
+ * broke and nothing about what to do.
+ *
+ * **There is deliberately no fallback.** Each caller supplies its own last
+ * sentence saying what a silent fallback would have looked like from the
+ * outside, because that sentence is the argument — not decoration.
+ */
+/** What the refusal says about the caller that raised it. */
+export interface SqliteUnavailableContext {
+    /** The factory the consumer actually wrote, e.g. `sqliteSessions()`. */
+    readonly factory: string;
+    /** The honest in-memory alternative, named so it can be reached for. */
+    readonly alternative: string;
+    /** Why falling back to that alternative silently would be worse than refusing. */
+    readonly whyNotFallback: string;
+    /** Which door the message belongs to, for the `[prefix]` tag. */
+    readonly door: string;
+}
+/**
+ * Raised when `node:sqlite` is not available in the running Node.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const store = sqliteVectorStore({ file: './corpus.db' });
+ * } catch (err) {
+ *   if (err instanceof SqliteUnavailableError) {
+ *     console.error(`Node ${err.nodeVersion} cannot do this`, err.message);
+ *   }
+ * }
+ * ```
+ */
+export declare class SqliteUnavailableError extends Error {
+    readonly code: "ERR_SQLITE_UNAVAILABLE";
+    /** The Node version this process is running. */
+    readonly nodeVersion: string;
+    constructor(nodeVersion: string, reason: string, context?: SqliteUnavailableContext);
+}

package/dist/esm/lib/sqliteUnavailable.js

@@ -0,0 +1,61 @@
+/**
+ * lib/sqliteUnavailable — the one refusal for "this Node has no `node:sqlite`".
+ *
+ * Pattern: leaf error type (imports nothing).
+ * Role:    shared by `hosting/sqliteSessions` and `adapters/memory/sqliteVector`.
+ *          It lives here rather than in either of them because two adapters
+ *          hitting the same missing module must raise the same error: a
+ *          consumer catching `SqliteUnavailableError` should not have to know
+ *          which of our stores was being constructed, and two classes of one
+ *          name is a duplicate type the build refuses anyway.
+ * Emits:   N/A.
+ *
+ * Node 20 does not have the module at all; Node 22.5 through 22.12 have it
+ * behind `--experimental-sqlite`; Node 22.13+ and 23.4+ have it as-is (still
+ * marked experimental by Node, which is why it prints a warning on first use).
+ *
+ * The refusal names the version you are on and the three ways out, because
+ * "cannot find module 'node:sqlite'" out of a library's guts tells you what
+ * broke and nothing about what to do.
+ *
+ * **There is deliberately no fallback.** Each caller supplies its own last
+ * sentence saying what a silent fallback would have looked like from the
+ * outside, because that sentence is the argument — not decoration.
+ */
+const SESSIONS_CONTEXT = {
+    door: 'hosting',
+    factory: 'sqliteSessions()',
+    alternative: 'memorySessions() — which keeps conversations in a Map and loses them on restart, and says so in its name',
+    whyNotFallback: 'a store that silently forgot every conversation on restart looks, from the outside, exactly like a brand-new user',
+};
+/**
+ * Raised when `node:sqlite` is not available in the running Node.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const store = sqliteVectorStore({ file: './corpus.db' });
+ * } catch (err) {
+ *   if (err instanceof SqliteUnavailableError) {
+ *     console.error(`Node ${err.nodeVersion} cannot do this`, err.message);
+ *   }
+ * }
+ * ```
+ */
+export class SqliteUnavailableError extends Error {
+    code = 'ERR_SQLITE_UNAVAILABLE';
+    /** The Node version this process is running. */
+    nodeVersion;
+    constructor(nodeVersion, reason, context = SESSIONS_CONTEXT) {
+        super(`[${context.door}] ${context.factory} needs Node's built-in 'node:sqlite' module, and this ` +
+            `process (Node ${nodeVersion}) does not have it (${reason}). ` +
+            `That module ships with Node 22.5 and newer: on Node 22.13+ (and 23.4+) it is ` +
+            `available as-is, and on Node 22.5–22.12 it is behind --experimental-sqlite. ` +
+            `So: upgrade Node, add that flag, or use ${context.alternative}. ` +
+            `This refuses rather than falling back to memory on your behalf: ` +
+            `${context.whyNotFallback}.`);
+        this.name = 'SqliteUnavailableError';
+        this.nodeVersion = nodeVersion;
+    }
+}
+//# sourceMappingURL=sqliteUnavailable.js.map

package/dist/esm/lib/sqliteUnavailable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqliteUnavailable.js","sourceRoot":"","sources":["../../../src/lib/sqliteUnavailable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAcH,MAAM,gBAAgB,GAA6B;IACjD,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,kBAAkB;IAC3B,WAAW,EACT,0GAA0G;IAC5G,cAAc,EACZ,mHAAmH;CACtH,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACtC,IAAI,GAAG,wBAAiC,CAAC;IAClD,gDAAgD;IACvC,WAAW,CAAS;IAE7B,YACE,WAAmB,EACnB,MAAc,EACd,UAAoC,gBAAgB;QAEpD,KAAK,CACH,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,wDAAwD;YAC1F,iBAAiB,WAAW,uBAAuB,MAAM,KAAK;YAC9D,+EAA+E;YAC/E,8EAA8E;YAC9E,2CAA2C,OAAO,CAAC,WAAW,IAAI;YAClE,kEAAkE;YAClE,GAAG,OAAO,CAAC,cAAc,GAAG,CAC/B,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF"}

package/dist/esm/memory/define.js

@@ -65,14 +65,21 @@ import { MEMORY_TYPES, MEMORY_STRATEGIES, MEMORY_TIMING, } from './define.types.
 export function defineMemory(options) {
     validate(options);
     const pipeline = buildPipeline(options);
+    // `readOnly` drops the write half entirely (8.8.0). Not "writes are
+    // skipped at runtime" — the subflow is never compiled and never mounted,
+    // so a read-only memory has no write stage in its chart, no write commit
+    // in its log, and nothing to disable later by accident.
+    const write = options.readOnly === true ? undefined : pipeline.write;
     const definition = {
         id: options.id,
         ...(options.description !== undefined && { description: options.description }),
         type: options.type,
         read: brandPipeline(pipeline.read),
-        ...(pipeline.write !== undefined && { write: brandPipeline(pipeline.write) }),
+        ...(write !== undefined && { write: brandPipeline(write) }),
         timing: options.timing ?? MEMORY_TIMING.TURN_START,
         ...(options.redact !== undefined && { redact: options.redact }),
+        ...(options.corpus !== undefined && { corpus: options.corpus }),
+        ...(options.flavor !== undefined && { flavor: options.flavor }),
         ...(options.type === MEMORY_TYPES.CAUSAL &&
             options.projection !== undefined && {
             projection: options.projection,
@@ -93,6 +100,26 @@ function validate(options) {
         throw new Error(`defineMemory[id=${options.id}]: \`store\` is required. ` +
             'Pass `new InMemoryStore()` for dev/tests, or a backed store for production.');
     }
+    // The shorthand and the spelled-out rule EXCLUDE. Accepting both would
+    // mean one of two numbers silently loses, and the recording would name
+    // a `k` the run did not use.
+    // Read through a structural shape, not the union: the union's arms
+    // declare the OTHER spelling as `never`, so intersecting them here
+    // would make the very field this check reads unreadable.
+    const strategy = options.strategy;
+    if (strategy?.retrieval !== undefined) {
+        const shorthand = [];
+        if (strategy.topK !== undefined)
+            shorthand.push('`topK`');
+        if (strategy.threshold !== undefined)
+            shorthand.push('`threshold`');
+        if (shorthand.length > 0) {
+            throw new Error(`defineMemory[id=${options.id}]: ${shorthand.join(' and ')} cannot be combined with ` +
+                '`retrieval` — they are two spellings of the same rule and could disagree. ' +
+                `Keep the strategy (\`retrieval: ${strategy.retrieval.name}({ ... })\`) and drop ` +
+                `${shorthand.join('/')}, or drop \`retrieval\`.`);
+        }
+    }
 }
 // ─── Pipeline dispatch ─────────────────────────────────────────────
 function buildPipeline(options) {
@@ -177,8 +204,11 @@ function buildSemanticPipeline(options) {
             const config = {
                 store: options.store,
                 embedder: t.embedder,
-                k: t.topK,
+                ...(t.topK !== undefined && { k: t.topK }),
                 ...(t.threshold !== undefined && { minScore: t.threshold }),
+                ...(t.embedderId !== undefined && { embedderId: t.embedderId }),
+                ...(t.retrieval !== undefined && { retrieval: t.retrieval }),
+                ...(options.flavor !== undefined && { flavor: options.flavor }),
             };
             return semanticPipeline(config);
         }
@@ -268,6 +298,12 @@ function buildCausalPipeline(options) {
             'Pass `new InMemoryStore({ embedder })` for dev/tests, or a vector adapter ' +
             '(pgvector, Pinecone, Qdrant) for production.');
     }
+    // CAUSAL predates the retrieval seam and reads the shorthand only. A
+    // strategy passed here would be accepted and ignored, so it is refused.
+    if (s.retrieval !== undefined) {
+        throw new Error(`defineMemory[${options.id}]: CAUSAL type does not read \`retrieval\` — snapshot recall ` +
+            'matches a stored query vector, not a document pool. Use `topK` + `threshold`.');
+    }
     const config = {
         store: options.store,
         embedder: s.embedder,

package/dist/esm/memory/define.js.map

@@ -1 +1 @@
-{"version":3,"file":"define.js","sourceRoot":"","sources":["../../../src/memory/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,eAAe,EAA8B,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAA+B,MAAM,wBAAwB,CAAC;AACvF,OAAO,EAAE,YAAY,EAA2B,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAgC,MAAM,yBAAyB,CAAC;AAC1F,OAAO,EAAE,YAAY,EAA2B,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAA+B,MAAM,mBAAmB,CAAC;AAGlF,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,GAad,MAAM,mBAAmB,CAAC;AAG3B,sEAAsE;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,YAAY,CAAC,OAA4B;IACvD,QAAQ,CAAC,OAAO,CAAC,CAAC;IAElB,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IAExC,MAAM,UAAU,GAAqB;QACnC,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;QAC9E,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC;QAClC,GAAG,CAAC,QAAQ,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7E,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,aAAa,CAAC,UAAU;QAClD,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QAC/D,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,YAAY,CAAC,MAAM;YACrC,OAA+B,CAAC,UAAU,KAAK,SAAS,IAAI;YAC3D,UAAU,EAAG,OAA+B,CAAC,UAAU;SACxD,CAAC;KACL,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;AACnC,CAAC;AAED,sEAAsE;AAEtE,SAAS,QAAQ,CAAC,OAA4B;IAC5C,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,sEAAsE;IACtE,qEAAqE;IACrE,8CAA8C;IAC9C,YAAY,CAAC,OAAO,EAAE,iBAAiB,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC;IACvD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CACb,mBAAmB,OAAO,CAAC,EAAE,4BAA4B;YACvD,6EAA6E,CAChF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,sEAAsE;AAEtE,SAAS,aAAa,CAAC,OAA4B;IACjD,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,YAAY,CAAC,QAAQ;YACxB,OAAO,qBAAqB,CAAC,OAAO,CAAC,CAAC;QACxC,KAAK,YAAY,CAAC,QAAQ;YACxB,OAAO,qBAAqB,CAAC,OAAO,CAAC,CAAC;QACxC,KAAK,YAAY,CAAC,SAAS;YACzB,OAAO,sBAAsB,CAAC,OAAO,CAAC,CAAC;QACzC,KAAK,YAAY,CAAC,MAAM;YACtB,OAAO,mBAAmB,CAAC,OAAO,CAAC,CAAC;QACtC,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,WAAW,GAAU,OAAO,CAAC;YACnC,KAAK,WAAW,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,gCAAiC,OAA4B,CAAC,IAAI,EAAE,CAAC,CAAC;QACxF,CAAC;IACH,CAAC;AACH,CAAC;AAED,sEAAsE;AAEtE,SAAS,qBAAqB,CAAC,OAA8B;IAC3D,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;IAE3B,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;YAC9B,MAAM,CAAC,GAAG,CAAyB,CAAC;YACpC,MAAM,MAAM,GAA0B,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YAClF,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QAED,KAAK,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;YAC9B,MAAM,CAAC,GAAG,CAAmB,CAAC;YAC9B,MAAM,MAAM,GAA0B;gBACpC,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,GAAG,CAAC,CAAC,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC,aAAa,EAAE,CAAC;gBACxE,GAAG,CAAC,CAAC,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC,aAAa,EAAE,CAAC;gBACxE,GAAG,CAAC,CAAC,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC;aAChE,CAAC;YACF,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QAED,KAAK,iBAAiB,CAAC,SAAS,CAAC,CAAC,CAAC;YACjC,iEAAiE;YACjE,2DAA2D;YAC3D,8DAA8D;YAC9D,sCAAsC;YACtC,MAAM,GAAG,GAAG,CAAsB,CAAC;YACnC,MAAM,MAAM,GAA0B,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;YACtF,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QAED,KAAK,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;YAC9B,4DAA4D;YAC5D,gEAAgE;YAChE,2DAA2D;YAC3D,sBAAsB;YACtB,MAAM,CAAC,GAAG,CAAmB,CAAC;YAC9B,MAAM,KAAK,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CACb,gBAAgB,OAAO,CAAC,EAAE,wDAAwD,CACnF,CAAC;YACJ,CAAC;YACD,OAAO,qBAAqB,CAAC,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;QAChE,CAAC;QAED,KAAK,iBAAiB,CAAC,OAAO;YAC5B,MAAM,IAAI,KAAK,CACb,gBAAgB,OAAO,CAAC,EAAE,0DAA0D;gBAClF,0FAA0F,CAC7F,CAAC;QAEJ,KAAK,iBAAiB,CAAC,KAAK;YAC1B,MAAM,IAAI,KAAK,CACb,gBAAgB,OAAO,CAAC,EAAE,8DAA8D;gBACtF,4FAA4F,CAC/F,CAAC;QAEJ,KAAK,iBAAiB,CAAC,KAAK;YAC1B,MAAM,IAAI,KAAK,CACb,gBAAgB,OAAO,CAAC,EAAE,sCAAsC;gBAC9D,8EAA8E,CACjF,CAAC;QAEJ,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,WAAW,GAAU,CAAC,CAAC;YAC7B,KAAK,WAAW,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;AACH,CAAC;AAED,sEAAsE;AAEtE,SAAS,qBAAqB,CAAC,OAA8B;IAC3D,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;IAE3B,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC;YAC7B,MAAM,CAAC,GAAG,CAAiB,CAAC;YAC5B,MAAM,MAAM,GAA2B;gBACrC,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,QAAQ,EAAE,CAAC,CAAC,QAAQ;gBACpB,CAAC,EAAE,CAAC,CAAC,IAAI;gBACT,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;aAC5D,CAAC;YACF,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;QAED,KAAK,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;YAC/B,MAAM,CAAC,GAAG,CAAoB,CAAC;YAC/B,IAAI,CAAC,CAAC,SAAS,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;gBACpC,MAAM,IAAI,KAAK,CACb,gBAAgB,OAAO,CAAC,EAAE,6DAA6D;oBACrF,4EAA4E,CAC/E,CAAC;YACJ,CAAC;YACD,MAAM,MAAM,GAAuB,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAC5D,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QAED,KAAK,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;YAC9B,mEAAmE;YACnE,wEAAwE;YACxE,qBAAqB;YACrB,MAAM,CAAC,GAAG,CAAyB,CAAC;YACpC,MAAM,MAAM,GAAuB,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YAC/E,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QAED,KAAK,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;YAC9B,8DAA8D;YAC9D,MAAM,MAAM,GAAuB,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAC5D,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QAED,KAAK,iBAAiB,CAAC,MAAM,CAAC;QAC9B,KAAK,iBAAiB,CAAC,SAAS,CAAC;QACjC,KAAK,iBAAiB,CAAC,KAAK;YAC1B,MAAM,IAAI,KAAK,CACb,gBAAgB,OAAO,CAAC,EAAE,MAAM,MAAM,CACpC,CAAC,CAAC,IAAI,CACP,+CAA+C;gBAC9C,uEAAuE;gBACvE,kDAAkD,CACrD,CAAC;QAEJ,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,WAAW,GAAU,CAAC,CAAC;YAC7B,KAAK,WAAW,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;AACH,CAAC;AAED,sEAAsE;AAEtE,SAAS,sBAAsB,CAAC,OAA+B;IAC7D,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;IAE3B,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;YAC/B,MAAM,CAAC,GAAG,CAAoB,CAAC;YAC/B,IAAI,CAAC,CAAC,SAAS,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;gBACpC,MAAM,IAAI,KAAK,CACb,gBAAgB,OAAO,CAAC,EAAE,4DAA4D,CACvF,CAAC;YACJ,CAAC;YACD,MAAM,MAAM,GAA4B,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YACjE,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC;QAED,KAAK,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;YAC9B,MAAM,CAAC,GAAG,CAAyB,CAAC;YACpC,MAAM,MAAM,GAA4B,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YACpF,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC;QAED,KAAK,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;YAC9B,MAAM,MAAM,GAAuB,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAC5D,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QAED,KAAK,iBAAiB,CAAC,KAAK,CAAC;QAC7B,KAAK,iBAAiB,CAAC,MAAM,CAAC;QAC9B,KAAK,iBAAiB,CAAC,SAAS,CAAC;QACjC,KAAK,iBAAiB,CAAC,KAAK;YAC1B,MAAM,IAAI,KAAK,CACb,gBAAgB,OAAO,CAAC,EAAE,MAAM,MAAM,CACpC,CAAC,CAAC,IAAI,CACP,gDAAgD;gBAC/C,gFAAgF,CACnF,CAAC;QAEJ,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,WAAW,GAAU,CAAC,CAAC;YAC7B,KAAK,WAAW,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;AACH,CAAC;AAED,sEAAsE;AAEtE,SAAS,mBAAmB,CAAC,OAA4B;IACvD,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;IAE3B,mEAAmE;IACnE,8DAA8D;IAC9D,mEAAmE;IACnE,kEAAkE;IAClE,IAAI,CAAC,CAAC,IAAI,KAAK,iBAAiB,CAAC,KAAK,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CACb,gBAAgB,OAAO,CAAC,EAAE,+CAA+C;YACvE,iEAAiE;YACjE,2DAA2D,CAC9D,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,gBAAgB,OAAO,CAAC,EAAE,kDAAkD;YAC1E,4EAA4E;YAC5E,8CAA8C,CACjD,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAA2B;QACrC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;QAC3D,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;KAC5E,CAAC;IACF,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAClC,CAAC;AAED,sEAAsE;AAEtE;;;;GAIG;AACH,SAAS,aAAa,CAAI,EAAW;IACnC,OAAO,EAAgC,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAI,OAAmC;IAC1E,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,kEAAkE;AAClE,sDAAsD;AACtD,KAAK,iBAAiB,CAAC;AACvB,iEAAiE;AACjE,KAAM,IAA4B,CAAC"}
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../../src/memory/define.ts"],"names":[],"mappings":"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"}

package/dist/esm/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,3 +364,17 @@ 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;

package/dist/esm/memory/define.types.js

@@ -126,4 +126,22 @@ export function memoryInjectionKey(id) {
 export function isMemoryInjectionKey(key) {
     return key.startsWith(MEMORY_INJECTION_KEY_PREFIX);
 }
+/**
+ * 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 const RETRIEVAL_EVIDENCE_KEY_PREFIX = 'retrievalEvidence_';
+export function retrievalEvidenceKey(id) {
+    return `${RETRIEVAL_EVIDENCE_KEY_PREFIX}${id}`;
+}
+export function isRetrievalEvidenceKey(key) {
+    return key.startsWith(RETRIEVAL_EVIDENCE_KEY_PREFIX);
+}
 //# sourceMappingURL=define.types.js.map

package/dist/esm/memory/define.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"define.types.js","sourceRoot":"","sources":["../../../src/memory/define.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAMH,uEAAuE;AAEvE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;IACpB,SAAS,EAAE,WAAW;IACtB,MAAM,EAAE,QAAQ;CACR,CAAC;AAGX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,WAAW;IACtB,KAAK,EAAE,MAAM;IACb,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;CACR,CAAC;AAGX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,eAAe,EAAE,iBAAiB;IAClC,UAAU,EAAE,YAAY;CAChB,CAAC;AAGX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,SAAS,EAAE,WAAW;IACtB,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,WAAW;IACtB,IAAI,EAAE,MAAM;CACJ,CAAC;AAiOX,uEAAuE;AAEvE,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAQ,MAAM,CAAC,MAAM,CAAC,YAAY,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAQ,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAQ,MAAM,CAAC,MAAM,CAAC,aAAa,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAQ,MAAM,CAAC,MAAM,CAAC,oBAAoB,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3E,CAAC;AAED,uEAAuE;AAEvE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,kBAA2B,CAAC;AAEvE,MAAM,UAAU,kBAAkB,CAAC,EAAU;IAC3C,OAAO,GAAG,2BAA2B,GAAG,EAAE,EAAE,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,OAAO,GAAG,CAAC,UAAU,CAAC,2BAA2B,CAAC,CAAC;AACrD,CAAC"}
+{"version":3,"file":"define.types.js","sourceRoot":"","sources":["../../../src/memory/define.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAQH,uEAAuE;AAEvE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;IACpB,SAAS,EAAE,WAAW;IACtB,MAAM,EAAE,QAAQ;CACR,CAAC;AAGX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,WAAW;IACtB,KAAK,EAAE,MAAM;IACb,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;CACR,CAAC;AAGX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,eAAe,EAAE,iBAAiB;IAClC,UAAU,EAAE,YAAY;CAChB,CAAC;AAGX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,SAAS,EAAE,WAAW;IACtB,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,WAAW;IACtB,IAAI,EAAE,MAAM;CACJ,CAAC;AAqTX,uEAAuE;AAEvE,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAQ,MAAM,CAAC,MAAM,CAAC,YAAY,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAQ,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAQ,MAAM,CAAC,MAAM,CAAC,aAAa,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAQ,MAAM,CAAC,MAAM,CAAC,oBAAoB,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3E,CAAC;AAED,uEAAuE;AAEvE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,kBAA2B,CAAC;AAEvE,MAAM,UAAU,kBAAkB,CAAC,EAAU;IAC3C,OAAO,GAAG,2BAA2B,GAAG,EAAE,EAAE,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,OAAO,GAAG,CAAC,UAAU,CAAC,2BAA2B,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,oBAA6B,CAAC;AAE3E,MAAM,UAAU,oBAAoB,CAAC,EAAU;IAC7C,OAAO,GAAG,6BAA6B,GAAG,EAAE,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,GAAW;IAChD,OAAO,GAAG,CAAC,UAAU,CAAC,6BAA6B,CAAC,CAAC;AACvD,CAAC"}

package/dist/esm/memory/embedding/embedMessages.js

@@ -1,3 +1,4 @@
+import { emitEmbedding } from './emitEmbedding.js';
 /** Default: extract plaintext from any supported content shape. */
 function defaultTextFrom(message) {
     return message.content ?? '';
@@ -18,6 +19,7 @@ export function embedMessages(config) {
         }
         const texts = messages.map(textFrom);
         const signal = scope.$getEnv?.()?.signal;
+        const startedAt = Date.now();
         let vectors;
         if (embedder.embedBatch) {
             vectors = (await embedder.embedBatch({
@@ -28,6 +30,20 @@ export function embedMessages(config) {
         else {
             vectors = await Promise.all(texts.map((text) => embedder.embed({ text, ...(signal ? { signal } : {}) })));
         }
+        // The INDEX-time half of the two-phase cost model (8.9.0). Embedding cost
+        // splits in two — this side scales with the size of what you store, and
+        // the query side scales with traffic — and telling them apart is the whole
+        // reason for a durable index. `agentfootprint.embedding.generated` has been
+        // declared since 2.x with an `inputKind` field and no emitter; this is one
+        // of its two.
+        emitEmbedding(scope, {
+            model: config.embedderId ?? embedder.id ?? 'unknown',
+            provider: 'custom',
+            inputKind: 'document',
+            dimension: embedder.dimensions,
+            count: vectors.length,
+            durationMs: Date.now() - startedAt,
+        });
         scope.newMessageEmbeddings = vectors;
         if (config.embedderId !== undefined) {
             scope.newMessageEmbeddingModel = config.embedderId;

package/dist/esm/memory/embedding/embedMessages.js.map

@@ -1 +1 @@
-{"version":3,"file":"embedMessages.js","sourceRoot":"","sources":["../../../../src/memory/embedding/embedMessages.ts"],"names":[],"mappings":"AA0DA,mEAAmE;AACnE,SAAS,eAAe,CAAC,OAAgB;IACvC,OAAO,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAA2B;IACvD,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAC5B,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,eAAe,CAAC;IAEpD,OAAO,KAAK,EAAE,KAAqC,EAAiB,EAAE;QACpE,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAuB,CAAC;QACjE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,KAAK,CAAC,oBAAoB,GAAG,EAAE,CAAC;YAChC,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACrC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC;QAEzC,IAAI,OAAmB,CAAC;QACxB,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;YACxB,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,UAAU,CAAC;gBACnC,KAAK;gBACL,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9B,CAAC,CAAe,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CACzB,KAAK,CAAC,GAAG,CACP,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAsB,CACvF,CACF,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,oBAAoB,GAAG,OAAO,CAAC;QACrC,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACpC,KAAK,CAAC,wBAAwB,GAAG,MAAM,CAAC,UAAU,CAAC;QACrD,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"embedMessages.js","sourceRoot":"","sources":["../../../../src/memory/embedding/embedMessages.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAmCnD,mEAAmE;AACnE,SAAS,eAAe,CAAC,OAAgB;IACvC,OAAO,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAA2B;IACvD,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAC5B,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,eAAe,CAAC;IAEpD,OAAO,KAAK,EAAE,KAAqC,EAAiB,EAAE;QACpE,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAuB,CAAC;QACjE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,KAAK,CAAC,oBAAoB,GAAG,EAAE,CAAC;YAChC,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACrC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC;QAEzC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,IAAI,OAAmB,CAAC;QACxB,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;YACxB,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,UAAU,CAAC;gBACnC,KAAK;gBACL,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9B,CAAC,CAAe,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CACzB,KAAK,CAAC,GAAG,CACP,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAsB,CACvF,CACF,CAAC;QACJ,CAAC;QAED,0EAA0E;QAC1E,wEAAwE;QACxE,2EAA2E;QAC3E,4EAA4E;QAC5E,2EAA2E;QAC3E,cAAc;QACd,aAAa,CAAC,KAAK,EAAE;YACnB,KAAK,EAAE,MAAM,CAAC,UAAU,IAAI,QAAQ,CAAC,EAAE,IAAI,SAAS;YACpD,QAAQ,EAAE,QAAQ;YAClB,SAAS,EAAE,UAAU;YACrB,SAAS,EAAE,QAAQ,CAAC,UAAU;YAC9B,KAAK,EAAE,OAAO,CAAC,MAAM;YACrB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;SACnC,CAAC,CAAC;QAEH,KAAK,CAAC,oBAAoB,GAAG,OAAO,CAAC;QACrC,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACpC,KAAK,CAAC,wBAAwB,GAAG,MAAM,CAAC,UAAU,CAAC;QACrD,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/esm/memory/embedding/emitEmbedding.d.ts

@@ -0,0 +1,38 @@
+/**
+ * emitEmbedding — one place that reports an embedding call.
+ *
+ * Pattern: leaf helper over the emit channel.
+ * Role:    memory/ layer. Both halves of the two-phase cost model go through
+ *          it — `embedMessages` reports `'document'`, `loadRelevant` reports
+ *          `'query'` — so the two can never drift into describing the same
+ *          fact two different ways.
+ * Emits:   `agentfootprint.embedding.generated`.
+ *
+ * ── Why this event matters more than it looks ───────────────────────────────
+ * Embedding cost is not one number. **Index time** embeds the corpus: it
+ * happens once, and its cost scales with how much you store. **Query time**
+ * embeds the user's question: it happens per retrieval, and its cost scales
+ * with traffic. `inputKind` is the field that separates them, and separating
+ * them is what makes "should this corpus live in a file?" a question with an
+ * arithmetic answer instead of a feeling.
+ *
+ * The payload has been declared since 2.x and nothing emitted it, so any
+ * dashboard built against it has been reading a flat line that meant "not
+ * wired", not "no cost".
+ *
+ * Telemetry rides the EMIT channel, never a commit payload — a cost report is
+ * an observation about a stage, not state the next stage reads.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { EmbeddingGeneratedPayload } from '../../events/payloads.js';
+/**
+ * Fire the event when the scope has an emit channel, and do nothing when it
+ * does not.
+ *
+ * A memory pipeline can be mounted outside an Agent (`mountMemoryRead` on a
+ * bare flowchart), and a stage that threw because nobody was listening would
+ * make observability a requirement rather than an option.
+ */
+export declare function emitEmbedding(scope: TypedScope<Record<string, unknown>> | {
+    $emit?: unknown;
+}, payload: EmbeddingGeneratedPayload): void;

package/dist/esm/memory/embedding/emitEmbedding.js

@@ -0,0 +1,15 @@
+/**
+ * Fire the event when the scope has an emit channel, and do nothing when it
+ * does not.
+ *
+ * A memory pipeline can be mounted outside an Agent (`mountMemoryRead` on a
+ * bare flowchart), and a stage that threw because nobody was listening would
+ * make observability a requirement rather than an option.
+ */
+export function emitEmbedding(scope, payload) {
+    const emitter = scope.$emit;
+    if (typeof emitter === 'function') {
+        emitter.call(scope, 'agentfootprint.embedding.generated', payload);
+    }
+}
+//# sourceMappingURL=emitEmbedding.js.map

package/dist/esm/memory/embedding/emitEmbedding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitEmbedding.js","sourceRoot":"","sources":["../../../../src/memory/embedding/emitEmbedding.ts"],"names":[],"mappings":"AA4BA;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAgE,EAChE,OAAkC;IAElC,MAAM,OAAO,GAAI,KAA8D,CAAC,KAAK,CAAC;IACtF,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,oCAAoC,EAAE,OAAO,CAAC,CAAC;IACrE,CAAC;AACH,CAAC"}