agentfootprint 8.19.0 → 9.0.0

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/memory-providers.d.ts

@@ -1,25 +1,9 @@
 /**
- * agentfootprint/memory-providers — memory store adapters (canonical subpath).
+ * memory-providers — memory store adapters.
  *
- * The Block B canonical name. Mirrors the parallel structure shipped in
- * v2.5:
- *
- *   agentfootprint/llm-providers     ← LLM provider adapters
- *   agentfootprint/tool-providers    ← tool dispatch + tool sources
- *   agentfootprint/memory-providers  ← memory store adapters (this file)
- *   agentfootprint/security          ← cross-cutting authorization
- *
- * One subpath that grows — RedisStore, AgentCoreStore, and future
- * stores (DynamoDB, Postgres, Pinecone, …) all live here. No more
- * adding `agentfootprint/memory-<vendor>` per-adapter subpath each
- * time a new store ships.
- *
- * Per-adapter aliases (`agentfootprint/memory-redis`,
- * `agentfootprint/memory-agentcore`) stay available through the v2.x
- * line — they point at the same files. New code SHOULD import from
- * `agentfootprint/memory-providers`:
- *
- *   import { RedisStore, AgentCoreStore } from 'agentfootprint/memory-providers';
+ * RedisStore, AgentCoreStore, and future stores (DynamoDB, Postgres,
+ * Pinecone, …) all live here — a new store adds an export, never a new
+ * import path.
  *
  * Pattern: Adapter (GoF) — each store translates the `MemoryStore`
  *          interface onto a specific backend (Redis, DynamoDB-style
@@ -30,11 +14,11 @@
  *          actually instantiate pull their SDK in.
  *
  * @example
- *   import { RedisStore, AgentCoreStore } from 'agentfootprint/memory-providers';
+ *   import { RedisStore, AgentCoreStore } from 'agentfootprint/memory';
  *
- * @deprecated Since 8.0.0 — import from `agentfootprint/memory` instead.
- * This path keeps working for all of 8.x and is removed in 9.0.0. Every name
- * here is the same symbol on the new door, not a copy.
+ * Not an import path of its own since 9.0.0. This is the implementation barrel
+ * behind `agentfootprint/memory`, which re-exports every name here — same
+ * symbols, one door. Import from the door.
  */
 export { RedisStore, type RedisStoreOptions, type RedisLikeClient, type RedisLikePipeline, } from './adapters/memory/redis.js';
 export { AgentCoreStore, UnreadableMemoryEntryError, type AgentCoreStoreOptions, type AgentCoreLikeClient, type AgentCoreEvent, type AgentCoreMemoryRecord, } from './adapters/memory/agentcore.js';

package/dist/esm/memory-providers.js

@@ -1,25 +1,9 @@
 /**
- * agentfootprint/memory-providers — memory store adapters (canonical subpath).
+ * memory-providers — memory store adapters.
  *
- * The Block B canonical name. Mirrors the parallel structure shipped in
- * v2.5:
- *
- *   agentfootprint/llm-providers     ← LLM provider adapters
- *   agentfootprint/tool-providers    ← tool dispatch + tool sources
- *   agentfootprint/memory-providers  ← memory store adapters (this file)
- *   agentfootprint/security          ← cross-cutting authorization
- *
- * One subpath that grows — RedisStore, AgentCoreStore, and future
- * stores (DynamoDB, Postgres, Pinecone, …) all live here. No more
- * adding `agentfootprint/memory-<vendor>` per-adapter subpath each
- * time a new store ships.
- *
- * Per-adapter aliases (`agentfootprint/memory-redis`,
- * `agentfootprint/memory-agentcore`) stay available through the v2.x
- * line — they point at the same files. New code SHOULD import from
- * `agentfootprint/memory-providers`:
- *
- *   import { RedisStore, AgentCoreStore } from 'agentfootprint/memory-providers';
+ * RedisStore, AgentCoreStore, and future stores (DynamoDB, Postgres,
+ * Pinecone, …) all live here — a new store adds an export, never a new
+ * import path.
  *
  * Pattern: Adapter (GoF) — each store translates the `MemoryStore`
  *          interface onto a specific backend (Redis, DynamoDB-style
@@ -30,11 +14,11 @@
  *          actually instantiate pull their SDK in.
  *
  * @example
- *   import { RedisStore, AgentCoreStore } from 'agentfootprint/memory-providers';
+ *   import { RedisStore, AgentCoreStore } from 'agentfootprint/memory';
  *
- * @deprecated Since 8.0.0 — import from `agentfootprint/memory` instead.
- * This path keeps working for all of 8.x and is removed in 9.0.0. Every name
- * here is the same symbol on the new door, not a copy.
+ * Not an import path of its own since 9.0.0. This is the implementation barrel
+ * behind `agentfootprint/memory`, which re-exports every name here — same
+ * symbols, one door. Import from the door.
  */
 // Lazy-required peer-dep stores. Both adapters defer their vendor SDK
 // `require()` to constructor time; importing this barrel doesn't load

package/dist/esm/memory-providers.js.map

@@ -1 +1 @@
-{"version":3,"file":"memory-providers.js","sourceRoot":"","sources":["../../src/memory-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,sEAAsE;AACtE,sEAAsE;AACtE,wDAAwD;AACxD,OAAO,EACL,UAAU,GAIX,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,EACd,0BAA0B,GAK3B,MAAM,gCAAgC,CAAC;AAExC,gFAAgF;AAChF,gFAAgF;AAChF,8EAA8E;AAC9E,mDAAmD;AACnD,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,qBAAqB,GAMtB,MAAM,mCAAmC,CAAC;AAE3C,6EAA6E;AAC7E,8EAA8E;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEpE,8EAA8E;AAC9E,yEAAyE;AACzE,OAAO,EACL,kBAAkB,GAInB,MAAM,yCAAyC,CAAC"}
+{"version":3,"file":"memory-providers.js","sourceRoot":"","sources":["../../src/memory-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,sEAAsE;AACtE,sEAAsE;AACtE,wDAAwD;AACxD,OAAO,EACL,UAAU,GAIX,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,cAAc,EACd,0BAA0B,GAK3B,MAAM,gCAAgC,CAAC;AAExC,gFAAgF;AAChF,gFAAgF;AAChF,8EAA8E;AAC9E,mDAAmD;AACnD,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,qBAAqB,GAMtB,MAAM,mCAAmC,CAAC;AAE3C,6EAA6E;AAC7E,8EAA8E;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEpE,8EAA8E;AAC9E,yEAAyE;AACzE,OAAO,EACL,kBAAkB,GAInB,MAAM,yCAAyC,CAAC"}

package/dist/esm/observability/contextError/finders/index.d.ts

@@ -6,16 +6,16 @@
  * `src/lib/context-bisect` + `src/lib/influence-core`; the academic method + citation
  * live in `meta`, never in the import name.
  *
- *   import { rankSuspects } from 'agentfootprint/observability/contextError/finders';
+ *   import { rankSuspects } from 'agentfootprint/observe';
  *   const r = await rankSuspects.find(input);   // r.lead, r.evidence ('guessed'|'proven')
  *
  * Tree-shakeable: one finder = one file = one named export. Importing one finder does
  * not pull the others (or the heavy ablation path behind removeAndRetry). This barrel
  * is re-export-only — no runtime code, no registry.
  *
- * @deprecated Since 8.0.0 — import from `agentfootprint/observe` instead.
- * This path keeps working for all of 8.x and is removed in 9.0.0. Every name
- * here is the same symbol on the new door, not a copy.
+ * Not an import path of its own since 9.0.0. This is the implementation barrel
+ * behind `agentfootprint/observe`, which re-exports every name here — same
+ * symbols, one door. Import from the door.
  */
 export type { ContextPiece, Evidence, Finder, FinderMeta, FindInput, FindResult, Granularity, ScoredSuspect, StepInput, } from './types.js';
 export { rankSuspects } from './rankSuspects.js';

package/dist/esm/observability-providers.d.ts

@@ -1,5 +1,5 @@
 /**
- * agentfootprint/observability-providers — vendor observability strategies.
+ * observability-providers — vendor observability strategies.
  *
  * Grouped subpath following the parallel-providers pattern v2.5
  * established for `llm-providers` / `tool-providers` /
@@ -13,7 +13,7 @@
  *
  * @example
  * ```ts
- * import { agentcoreObservability } from 'agentfootprint/observability-providers';
+ * import { agentcoreObservability } from 'agentfootprint/observe';
  * import { microtaskBatchDriver } from 'footprintjs/detach';
  *
  * agent.enable.observability({
@@ -38,9 +38,9 @@
  * dedicated `dd-trace`-based adapter only if real-world feedback
  * demands the native Datadog APM client.
  *
- * @deprecated Since 8.0.0 — import from `agentfootprint/observe` instead.
- * This path keeps working for all of 8.x and is removed in 9.0.0. Every name
- * here is the same symbol on the new door, not a copy.
+ * Not an import path of its own since 9.0.0. This is the implementation barrel
+ * behind `agentfootprint/observe`, which re-exports every name here — same
+ * symbols, one door. Import from the door.
  */
 export { agentcoreObservability, type AgentcoreObservabilityOptions, } from './adapters/observability/agentcore.js';
 export { cloudwatchObservability, type CloudwatchObservabilityOptions, } from './adapters/observability/cloudwatch.js';

package/dist/esm/observability-providers.js

@@ -1,5 +1,5 @@
 /**
- * agentfootprint/observability-providers — vendor observability strategies.
+ * observability-providers — vendor observability strategies.
  *
  * Grouped subpath following the parallel-providers pattern v2.5
  * established for `llm-providers` / `tool-providers` /
@@ -13,7 +13,7 @@
  *
  * @example
  * ```ts
- * import { agentcoreObservability } from 'agentfootprint/observability-providers';
+ * import { agentcoreObservability } from 'agentfootprint/observe';
  * import { microtaskBatchDriver } from 'footprintjs/detach';
  *
  * agent.enable.observability({
@@ -38,9 +38,9 @@
  * dedicated `dd-trace`-based adapter only if real-world feedback
  * demands the native Datadog APM client.
  *
- * @deprecated Since 8.0.0 — import from `agentfootprint/observe` instead.
- * This path keeps working for all of 8.x and is removed in 9.0.0. Every name
- * here is the same symbol on the new door, not a copy.
+ * Not an import path of its own since 9.0.0. This is the implementation barrel
+ * behind `agentfootprint/observe`, which re-exports every name here — same
+ * symbols, one door. Import from the door.
  */
 export { agentcoreObservability, } from './adapters/observability/agentcore.js';
 export { cloudwatchObservability, } from './adapters/observability/cloudwatch.js';

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.
@@ -78,12 +83,12 @@ export { toolLineageRecorder, } from './recorders/observability/ToolLineageRecor
 export { agentThinkingTrace, } from './recorders/observability/AgentThinkingTraceRecorder.js';
 // Emit primitive — used by every Tier-3 source-domain.
 export { typedEmit } from './recorders/core/typedEmit.js';
-// ── DEPRECATED (moved to agentfootprint/debug) ─────────────────
-// The diagnosis tools (influence-core, trace-toolpack, context-bisect,
-// tool-lint) moved to `agentfootprint/debug` in the surface cleanup, so the
-// import path matches the Debug docs category. They are re-exported here for
-// ONE transition version — import them from `agentfootprint/debug` instead.
-// They will be removed from `agentfootprint/observe` in the next major.
+// ── Diagnosis tools ────────────────────────────────────────────
+// influence-core, trace-toolpack, context-bisect and tool-lint live in
+// `src/debug.ts`. 8.0.0 folded their import path INTO this one, and 9.0.0
+// removed the separate `agentfootprint/debug` subpath, so this re-export is
+// how they reach the door. Watching a healthy run and performing the autopsy
+// on a broken one come through the same door on purpose.
 export * from './debug.js';
 // Tool-choice margin recorder (RFC-002 tier 2, C4–C6) — per LLM call,
 // ranks the OFFERED catalog against the choice context (user message +

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/providers.d.ts

@@ -1,11 +1,11 @@
 /**
- * LLM provider adapters — implementation behind the `agentfootprint/llm-providers`
+ * LLM provider adapters — implementation behind the `agentfootprint/providers`
  * subpath (which re-exports this file).
  *
  * The standalone `agentfootprint/providers` subpath alias was removed in 4.0.0.
  * Import from the canonical subpath:
  *
- *   import { mock, anthropic, openai } from 'agentfootprint/llm-providers';
+ *   import { mock, anthropic, openai } from 'agentfootprint/providers';
  *
  * Pattern: Adapter (GoF) — concrete `LLMProvider` implementations that
  *          translate the agentfootprint port to a specific vendor SDK.

package/dist/esm/providers.js

@@ -1,11 +1,11 @@
 /**
- * LLM provider adapters — implementation behind the `agentfootprint/llm-providers`
+ * LLM provider adapters — implementation behind the `agentfootprint/providers`
  * subpath (which re-exports this file).
  *
  * The standalone `agentfootprint/providers` subpath alias was removed in 4.0.0.
  * Import from the canonical subpath:
  *
- *   import { mock, anthropic, openai } from 'agentfootprint/llm-providers';
+ *   import { mock, anthropic, openai } from 'agentfootprint/providers';
  *
  * Pattern: Adapter (GoF) — concrete `LLMProvider` implementations that
  *          translate the agentfootprint port to a specific vendor SDK.

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>;