agentfootprint 9.2.0 → 9.3.0

package/dist/types/adapters/memory/s3Vectors.d.ts

@@ -0,0 +1,209 @@
+/**
+ * adapters/memory/s3Vectors — the corpus outlives the runtime, and can still
+ * be updated without one.
+ *
+ * `sqliteVectorStore` (8.9.0) made a corpus survive a restart by putting it in
+ * a file, and `staticVectorStore` (8.20.0) made it survive a runtime with no
+ * disk at all by shipping it as a build artifact. Both leave the same gap, and
+ * a production field report named it: **a bundle can only change when you
+ * redeploy.** Add three documents on a Tuesday and the answer arrives with the
+ * next release train. That is a fine trade for product documentation and a bad
+ * one for anything a human edits during the day.
+ *
+ * Amazon S3 Vectors closes it. It is object storage with a native vector index
+ * and a query API: durable, serverless, nothing to run, priced like storage
+ * rather than like a database cluster. This adapter is the `MemoryStore` port
+ * over it, and the two halves that matter are:
+ *
+ *   - `search()` maps 1:1 onto **QueryVectors** — the vector goes as
+ *     `queryVector.float32`, `k` becomes `topK`, tiers become a metadata
+ *     `filter`, and the returned `distance` becomes the port's score.
+ *   - `put()` / `putMany()` map onto **PutVectors** — so `indexCorpus`,
+ *     `indexFolder` and `indexDocuments` run against it unchanged. **That is
+ *     the point of writing it rather than only reading it:** a corpus you can
+ *     add to from a cron job at 14:00 is a different product from one you can
+ *     add to at the next deploy.
+ *
+ * ── What it is NOT ──────────────────────────────────────────────────────────
+ * A vector index is not a key-value store, and this adapter refuses the
+ * operations that would need one rather than faking them:
+ *
+ *   - `putIfVersion` — PutVectors is last-write-wins; there is no
+ *     compare-and-set. A read-then-write here would be a compare-and-set that
+ *     another writer can walk through the middle of, which is worse than none.
+ *   - `recordSignature` / `feedback` — a set of strings and a running average
+ *     are not vectors. `seen()` answers `false` and `getFeedback()` `null`,
+ *     which are both TRUE (nothing can be recorded, so nothing has been); the
+ *     WRITE halves refuse by name.
+ *
+ * Pair it with a second store for conversation memory — `defineRAG` for the
+ * corpus, `defineMemory` for the chat, each with the backend it suits. That is
+ * the same shape `staticVectorStore` documents.
+ *
+ * ── The index you must create first, and why this does not create it ────────
+ * A vector index has a DIMENSION and a DISTANCE METRIC fixed at creation, and
+ * both are decisions about your embedder that this library must not make on
+ * your behalf — creating one silently would pick a size and a metric your
+ * corpus then lives with. Create it once, with your infrastructure:
+ *
+ * ```bash
+ * aws s3vectors create-vector-bucket --vector-bucket-name my-corpus
+ * aws s3vectors create-index \
+ *   --vector-bucket-name my-corpus \
+ *   --index-name docs \
+ *   --data-type float32 \
+ *   --dimension 1024 \
+ *   --distance-metric cosine \
+ *   --metadata-configuration '{"nonFilterableMetadataKeys":["af"]}'
+ * ```
+ *
+ * `nonFilterableMetadataKeys: ["af"]` is load-bearing, not decoration. This
+ * adapter stores the whole entry — the passage the model will read, its
+ * provenance, its timestamps — as JSON under the metadata key `af`. Filterable
+ * metadata has a small per-vector budget; non-filterable metadata has the large
+ * one. Declare `af` non-filterable and a full passage fits; leave it filterable
+ * and PutVectors starts refusing your longer chunks partway through an
+ * indexing run.
+ *
+ * Only `ns` (the identity namespace) and `tier` are ever filtered on, and both
+ * are short strings.
+ *
+ * ── Cosine only, said out loud ──────────────────────────────────────────────
+ * The port's score is a cosine similarity, and every threshold in this library
+ * — starting with `defineRAG`'s 0.7 default — is calibrated on that range. A
+ * cosine distance converts exactly (`score = 1 - distance`). A EUCLIDEAN
+ * distance does not: any mapping into [-1, 1] produces a number that READS like
+ * a cosine and is not one, which is the same class of confident-and-meaningless
+ * value the embedder-mismatch refusal exists to stop. So a euclidean index is
+ * refused at construction, by name.
+ *
+ * ── The fingerprint guarantee, stated exactly ───────────────────────────────
+ * `sqliteVectorStore` owns its file and can keep a fingerprint row in it. This
+ * store owns nothing but vectors, so the guarantee is assembled from what the
+ * service actually provides, and it is smaller — so it is spelled out rather
+ * than implied:
+ *
+ *   - **Dimensions** are enforced by S3 Vectors itself. The index declares one;
+ *     a vector of another length is rejected by the service, loudly, at the
+ *     call. Nothing here can be sloppier than that.
+ *   - **The model id** is stamped into every vector's metadata (`fp`) and
+ *     checked in two places: against the fingerprint this process has already
+ *     seen for the namespace (at write and at search), and against the
+ *     fingerprint carried by the HITS that come back (at search). The second
+ *     one is what survives a restart: the first query after an embedder swap
+ *     sees documents stamped by the old embedder and refuses by name, instead
+ *     of returning a confident ranking of two incompatible spaces.
+ *   - What is NOT caught: the first WRITE of a fresh process into a namespace
+ *     another embedder built. There is no cheap read that would catch it, and a
+ *     full index scan on every boot is not one either. It is caught at the next
+ *     search, before a single wrong answer is returned.
+ *
+ * ── Lazy peer dependency ────────────────────────────────────────────────────
+ * `@aws-sdk/client-s3vectors` is an OPTIONAL peer dependency, required at
+ * construction time. Importing `agentfootprint/memory` costs nothing for
+ * consumers who never build one of these. Pass `client` to share the SDK
+ * configuration your app already has.
+ */
+import type { MemoryIdentity } from '../../memory/identity/index.js';
+import type { MemoryStore } from '../../memory/store/types.js';
+/**
+ * The slice of an S3 Vectors client this adapter calls.
+ *
+ * Structural, so the real SDK client, a pre-built one shared with the rest of
+ * your app, or a test double all satisfy it without this package taking a hard
+ * type dependency on the optional peer.
+ */
+export interface S3VectorsLikeClient {
+    /** `send(command, options?)` — the second argument carries `abortSignal`. */
+    send(command: unknown, options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<unknown>;
+    /** Optional — released by {@link S3VectorsStore.close} when this store built the client. */
+    destroy?(): void;
+}
+/** The constructors this adapter needs out of `@aws-sdk/client-s3vectors`. */
+export interface S3VectorsSdkModule {
+    readonly S3VectorsClient?: new (config: {
+        region?: string;
+    }) => S3VectorsLikeClient;
+    readonly PutVectorsCommand?: new (input: unknown) => unknown;
+    readonly QueryVectorsCommand?: new (input: unknown) => unknown;
+    readonly GetVectorsCommand?: new (input: unknown) => unknown;
+    readonly ListVectorsCommand?: new (input: unknown) => unknown;
+    readonly DeleteVectorsCommand?: new (input: unknown) => unknown;
+}
+export interface S3VectorsStoreOptions {
+    /** The vector bucket (`vectorBucketName`). Created by you, not by this. */
+    readonly bucket: string;
+    /** The vector index inside it (`indexName`). Created by you, not by this. */
+    readonly index: string;
+    /** AWS region. Passed to the SDK client when this factory builds one. */
+    readonly region?: string;
+    /**
+     * The metric the index was created with. Only `'cosine'` is supported, and
+     * anything else is refused at construction — see the header. This is a
+     * DECLARATION about an index this store did not create; state the metric you
+     * actually used.
+     */
+    readonly distanceMetric?: 'cosine';
+    /**
+     * How many vectors go in one PutVectors call. Default 100 — deliberately
+     * well under the service limit, because the failure mode of guessing that
+     * limit high is a corpus that indexes 90% of the way and stops.
+     */
+    readonly batchSize?: number;
+    /** A pre-built S3 Vectors client, so one SDK config serves the whole app. */
+    readonly client?: S3VectorsLikeClient;
+    /** @internal Test injection — skips the SDK require entirely. */
+    readonly _client?: S3VectorsLikeClient;
+    /** @internal Test injection — the AWS SDK module (exercises the real shim with a mock SDK). */
+    readonly _sdk?: S3VectorsSdkModule;
+}
+/** A durable vector index in S3, plus the two things this store owns beyond the port. */
+export interface S3VectorsStore extends MemoryStore {
+    /** The vector bucket this store reads and writes. */
+    readonly bucket: string;
+    /** The vector index inside it. */
+    readonly index: string;
+    /**
+     * The embedder fingerprint (`'<id>@<dims>'`) this PROCESS has seen for a
+     * namespace, or `undefined` when it has seen none yet.
+     *
+     * Deliberately not "the fingerprint the index was built with" — see the
+     * header for exactly what this store can and cannot know. It is populated by
+     * the first write or the first search of the namespace in this process.
+     */
+    fingerprintOf(identity: MemoryIdentity): string | undefined;
+    /**
+     * Release the SDK client, if this store built one. Idempotent. A client you
+     * passed in is yours and is left alone.
+     */
+    close(): void;
+}
+/**
+ * Open a `MemoryStore` over an existing S3 Vectors index.
+ *
+ * @throws when `@aws-sdk/client-s3vectors` is absent and no `client` was passed.
+ * @throws when `distanceMetric` is anything but `'cosine'`.
+ * @throws EmbedderMismatchError from `put`/`putMany`/`search` when a vector
+ *         meets a namespace built by a different embedder.
+ *
+ * @example  A corpus you can add to without a redeploy
+ * ```ts
+ * import { defineRAG, indexDocuments } from 'agentfootprint';
+ * import { s3VectorsStore } from 'agentfootprint/memory';
+ * import { bedrockEmbedder } from 'agentfootprint/providers';
+ *
+ * const store = s3VectorsStore({ bucket: 'my-corpus', index: 'docs', region: 'us-east-1' });
+ * const embedder = bedrockEmbedder({ region: 'us-east-1' });
+ *
+ * // Run this from a cron job. No deploy, no restart — the agent sees it next turn.
+ * await indexDocuments(store, embedder, newDocs, { embedderId: embedder.id });
+ *
+ * const agent = Agent.create({ provider })
+ *   .rag(defineRAG({ id: 'docs', store, embedder, embedderId: embedder.id }))
+ *   .build();
+ * ```
+ */
+export declare function s3VectorsStore(options: S3VectorsStoreOptions): S3VectorsStore;
+//# sourceMappingURL=s3Vectors.d.ts.map

package/dist/types/adapters/memory/s3Vectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3Vectors.d.ts","sourceRoot":"","sources":["../../../../src/adapters/memory/s3Vectors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AAWH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,OAAO,KAAK,EAGV,WAAW,EAIZ,MAAM,6BAA6B,CAAC;AAIrC;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClF,4FAA4F;IAC5F,OAAO,CAAC,IAAI,IAAI,CAAC;CAClB;AAED,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,MAAM,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,mBAAmB,CAAC;IACpF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,KAAK,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAC7D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,KAAK,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAC/D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,KAAK,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAC7D,QAAQ,CAAC,kBAAkB,CAAC,EAAE,KAAK,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAC9D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,KAAK,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACjE;AAID,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IACtC,iEAAiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;IACvC,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED,yFAAyF;AACzF,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,aAAa,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAAC;IAC5D;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CA2c7E"}

package/dist/types/adapters/memory/sqliteVector.d.ts

@@ -141,34 +141,12 @@ export declare class UnreadableIndexFileError extends Error {
 /**
  * Raised when a vector meets an index built by a different embedder.
  *
- * **This is the refusal that keeps the store honest.** Cosine similarity between
- * two different embedding spaces is not a weak signal — it is not a signal at
- * all, and it comes back as a confident number in the same 0-to-1 range as a
- * real one. There is no threshold that separates them, and nothing downstream
- * can tell them apart. So the mismatch is refused where it happens, on both
- * sides:
- *
- *  - at **write**, so a second embedder's vectors never enter a namespace;
- *  - at **query**, so a swapped embedder never scores against the old ones.
- *
- * The named fix is an explicit re-index — delete the namespace and build it
- * again with one embedder, or point the retriever at a different file. It is
- * never a fallback: silently ignoring the mismatch is the failure, and silently
- * re-embedding somebody's corpus is a bill they did not agree to.
- *
- * `problem` says which half is wrong. `'dimensions'` is arithmetically
- * impossible to score at all; `'model'` would score, and lie.
+ * Since 9.3.0 this is ONE class shared by every store that can make the check
+ * (`lib/embedderMismatch.ts`), re-exported here so the import path that has
+ * worked since 8.9.0 keeps working. A second class of the same name would make
+ * `instanceof` depend on which store threw.
  */
-export declare class EmbedderMismatchError extends Error {
-    readonly code: "ERR_EMBEDDER_MISMATCH";
-    /** The fingerprint the namespace was built with, `'<id>@<dims>'`. */
-    readonly indexed: string;
-    /** The fingerprint that just arrived. */
-    readonly incoming: string;
-    /** Which half disagrees. */
-    readonly problem: 'dimensions' | 'model';
-    constructor(namespace: string, indexed: string, incoming: string, problem: EmbedderMismatchError['problem'], operation: 'write to' | 'search');
-}
+export { EmbedderMismatchError } from '../../lib/embedderMismatch.js';
 /** A durable vector store, plus the three things a file owns beyond the port. */
 export interface SqliteVectorStore extends MemoryStore {
     /**

package/dist/types/adapters/memory/sqliteVector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqliteVector.d.ts","sourceRoot":"","sources":["../../../../src/adapters/memory/sqliteVector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sqliteVector.d.ts","sourceRoot":"","sources":["../../../../src/adapters/memory/sqliteVector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAYH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,OAAO,KAAK,EAGV,WAAW,EAIZ,MAAM,6BAA6B,CAAC;AAIrC,wDAAwD;AACxD,MAAM,WAAW,yBAAyB;IACxC,GAAG,CAAC,GAAG,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC;IAC5C,GAAG,CAAC,GAAG,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC;IAC5C,GAAG,CAAC,GAAG,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;CAC/C;AAED,mDAAmD;AACnD,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,yBAAyB,CAAC;IAChD,KAAK,IAAI,IAAI,CAAC;CACf;AAED,uEAAuE;AACvE,MAAM,WAAW,sBAAsB;IACrC,KAAK,IAAI,EAAE,MAAM,GAAG,wBAAwB,CAAC;CAC9C;AAID,MAAM,WAAW,wBAAwB;IACvC;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAC;CAC3C;AAID;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,8BAAwC;IACrD,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,gBAAgB,GAAG,cAAc,CAAC;gBAExD,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM;CAmBvF;AAED;;;;;;;GAOG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AA4CtE,iFAAiF;AACjF,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,aAAa,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAAC;IAC5D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/E;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAqetF"}

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

@@ -8,7 +8,8 @@
  * you use and agentfootprint stays dependency-free.
  *
  *   openaiEmbedder()  — hosted; needs OPENAI_API_KEY; no extra install (fetch).
- *   bedrockEmbedder() — hosted on AWS; Titan Text Embeddings V2; credentials
+ *   bedrockEmbedder() — hosted on AWS; Titan Text Embeddings and Cohere Embed
+ *                       v3 (the model id picks the body shape); credentials
  *                       come from the AWS chain, so no key option at all.
  *                       peer dep: @aws-sdk/client-bedrock-runtime.
  *   localEmbedder()   — on-device sentence-transformer; no key; offline after a
@@ -111,25 +112,85 @@ export interface BedrockRuntimeSdkModule {
     }) => BedrockRuntimeLikeClient;
     readonly InvokeModelCommand?: new (input: unknown) => unknown;
 }
+/**
+ * The request/response SHAPE a Bedrock embedding model speaks (9.3.0).
+ *
+ * `InvokeModel` is one operation with a vendor-specific body on both sides:
+ * Titan takes `{ inputText }` and answers `{ embedding }`, Cohere takes
+ * `{ texts, input_type }` and answers `{ embeddings }`. One model id therefore
+ * does not describe one call, and until 9.3.0 this factory sent Titan's body to
+ * everything — so a Cohere model id was accepted at construction (with
+ * `dimensions`) and failed at the first embed, against the real service, with a
+ * validation error from AWS rather than a sentence from here.
+ */
+export type BedrockEmbeddingFamily = 'titan' | 'cohere';
+/**
+ * Cohere's `input_type`, which is a real parameter and not a hint: the v3
+ * models embed a QUERY and a DOCUMENT into deliberately different places, and
+ * the two are meant to be compared with each other. Sending one value for both
+ * halves is a measurable loss of retrieval quality, not a style choice — and
+ * Cohere requires the field, so there is no "unset" to fall back to.
+ */
+export type CohereInputType = 'search_document' | 'search_query';
 export interface BedrockEmbedderOptions {
     /**
      * Bedrock model id. Default `'amazon.titan-embed-text-v2:0'`.
      *
-     * Titan V2 is the one this factory knows the sizes of. Another model (V1,
-     * a Cohere embedding model, an inference profile ARN) works, but its
-     * output length is not something this library can know — pass
-     * `dimensions` with it, the same rule `openaiEmbedder` applies.
+     * Four are known by name — Titan V2, Titan V1, and Cohere Embed English /
+     * Multilingual v3 (see {@link BEDROCK_EMBEDDING_MODELS}) — and each brings
+     * its own body shape, vector length and input window. An id that WRAPS one of
+     * those (a cross-region inference profile `us.amazon.titan-embed-text-v2:0`,
+     * or an ARN ending in the model id) is resolved to the model it names.
+     *
+     * Anything else is a model this library has never met: pass `dimensions`
+     * with it (its vector length is not something this can know) and `family` if
+     * it is not Titan-shaped.
      */
     readonly model?: string;
     /**
-     * Vector length to request. Titan V2 supports 1024 (default), 512 and 256;
+     * Vector length to request.
+     *
+     * Titan V2 is the one CONFIGURABLE model — 1024 (default), 512 or 256 — and
      * the value is SENT to the model AND reported as `.dimensions`, so the two
-     * can never disagree.
+     * can never disagree. Every other known model has ONE size, and asking for a
+     * different one is refused rather than reported: `.dimensions` is what a
+     * vector store fingerprints on, and a wrong one corrupts it silently.
      *
-     * Required for a model outside {@link TITAN_DIMENSIONS} — a wrong
-     * `.dimensions` silently corrupts a vector store.
+     * Required for a model outside {@link BEDROCK_EMBEDDING_MODELS}.
      */
     readonly dimensions?: number;
+    /**
+     * The body shape to speak, when the model id does not say (9.3.0).
+     *
+     * Inferred for every known model and for anything that wraps one, so this is
+     * only for a model id this library has never met — a provisioned-throughput
+     * ARN, a custom deployment. Unknown and unstated, the body is **Titan's**,
+     * which is the shape every release before 9.3.0 sent to everything.
+     *
+     * Stating a family that contradicts a known model id is refused by name.
+     */
+    readonly family?: BedrockEmbeddingFamily;
+    /**
+     * Pin Cohere's `input_type` instead of deriving it from the call (9.3.0).
+     *
+     * Unset — the default — `embed()` sends `'search_query'` and `embedBatch()`
+     * sends `'search_document'`, because that is what this library's own two
+     * call sites are: retrieval embeds ONE question (`loadRelevant`), indexing
+     * embeds MANY passages (`indexDocuments`, `embedMessages`). Pin it when your
+     * own code uses the two calls differently — embedding a single document, say,
+     * or scoring a batch of queries.
+     *
+     * Ignored by Titan, which has no such parameter.
+     */
+    readonly inputType?: CohereInputType;
+    /**
+     * The longest input this model reads whole, in CHARACTERS
+     * ({@link Embedder.maxInputChars}). Declared for every known model from its
+     * documented token window; this option is how a model this library does not
+     * know states its own, rather than declaring none and leaving the indexer's
+     * conservative default in place. An explicit value always wins.
+     */
+    readonly maxInputChars?: number;
     /** AWS region. Passed to the SDK client when this factory builds one. */
     readonly region?: string;
     /** A pre-built Bedrock runtime client, so one SDK config serves the whole app. */
@@ -167,19 +228,31 @@ export interface BedrockEmbedderOptions {
  * q8 and an fp32 build of one model are near-identical spaces, and "near" is
  * exactly the difference that surfaces as a mysteriously worse ranking.)
  *
+ * ── One operation, two body shapes (9.3.0) ───────────────────────────────
+ * `InvokeModel` is a single API over vendor-specific JSON. Titan takes
+ * `{ inputText }` and answers `{ embedding }`; Cohere takes
+ * `{ texts, input_type }` and answers `{ embeddings }`, embeds up to
+ * {@link COHERE_MAX_TEXTS_PER_CALL} of them per call, and distinguishes a
+ * QUERY from a DOCUMENT. So the model id selects a FAMILY
+ * ({@link BedrockEmbeddingFamily}), and the family owns the request, the
+ * response and the batching. Before this, one shape was sent to everything —
+ * a Cohere id constructed fine and failed at the first embed.
+ *
  * ── The input ceiling (9.1.0) ────────────────────────────────────────────
- * `.maxInputChars` reports **32,000** for both Titan text-embedding models:
- * their documented 8,192-token window, converted at the stated
- * {@link CHARS_PER_TOKEN} assumption of 4 characters per token. Sixteen times
- * the indexer's own default, which was measured on an on-device model — so an
- * indexing run against this embedder now embeds a 2,500-character chunk whole
- * instead of clipping it and calling that success. Dense text (code, tables,
- * CJK) tokenises tighter than the assumption; pass an explicit `maxChunkChars`
- * for such a corpus, and it wins over this number.
+ * `.maxInputChars` is per MODEL, from its documented token window converted at
+ * the stated {@link CHARS_PER_TOKEN} assumption of 4 characters per token:
+ * **32,000** for both Titan text-embedding models (8,192 tokens — sixteen
+ * times the indexer's own default, which was measured on an on-device model),
+ * and **2,000** for Cohere Embed v3 (512 tokens). Those two numbers are why the
+ * ceiling cannot be a per-vendor constant: the same 2,500-character chunk is
+ * read whole by Titan and truncated by Cohere. Dense text (code, tables, CJK)
+ * tokenises tighter than the assumption; pass an explicit `maxChunkChars` for
+ * such a corpus, and it wins over this number.
  *
  * @throws if `model` is unknown and `dimensions` was not supplied; if
- *         `dimensions` is not one of Titan V2's supported sizes; or if the SDK
- *         is missing and no `client` / `_client` / `_sdk` was passed.
+ *         `dimensions` is a size the model does not produce; if `family`
+ *         contradicts a known model id; or if the SDK is missing and no
+ *         `client` / `_client` / `_sdk` was passed.
  *
  * @example
  * ```ts
@@ -190,6 +263,13 @@ export interface BedrockEmbedderOptions {
  * const embedder = bedrockEmbedder({ region: 'us-east-1', dimensions: 512 });
  * await indexFolder('./docs', { to: sqliteVectorStore({ file: './corpus.db' }), embedder });
  * ```
+ *
+ * @example  A Cohere embedding model on the same runtime
+ * ```ts
+ * // Body shape, response field, batch size and 512-token window all follow
+ * // from the model id — nothing else changes at the call site.
+ * const embedder = bedrockEmbedder({ model: 'cohere.embed-english-v3' });
+ * ```
  */
 export declare function bedrockEmbedder(options?: BedrockEmbedderOptions): Embedder;
 /**

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

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

package/dist/types/lib/embedderMismatch.d.ts

@@ -0,0 +1,68 @@
+/**
+ * EmbedderMismatchError — one class, for every store that can tell.
+ *
+ * Pattern: shared refusal type (the `SqliteUnavailableError` precedent).
+ * Role:    lib/, so no store adapter owns it and none has to import another.
+ * Emits:   N/A.
+ *
+ * It lived inside `sqliteVector.ts` from 8.9.0 until 9.3.0, when a second and
+ * a third store learned to make the same check. A duplicate class of the same
+ * name would mean `catch (e) { if (e instanceof EmbedderMismatchError) }`
+ * quietly depended on WHICH store threw — so there is exactly one, here, and
+ * the stores import it.
+ */
+/**
+ * Raised when a vector meets an index built by a different embedder.
+ *
+ * **This is the refusal that keeps a vector store honest.** Cosine similarity
+ * between two different embedding spaces is not a weak signal — it is not a
+ * signal at all, and it comes back as a confident number in the same 0-to-1
+ * range as a real one. There is no threshold that separates them, and nothing
+ * downstream can tell them apart. So the mismatch is refused where it happens,
+ * on both sides:
+ *
+ *  - at **write**, so a second embedder's vectors never enter a namespace;
+ *  - at **query**, so a swapped embedder never scores against the old ones.
+ *
+ * The named fix is an explicit re-index — delete the namespace and build it
+ * again with one embedder, or point the retriever somewhere else. It is never a
+ * fallback: silently ignoring the mismatch is the failure, and silently
+ * re-embedding somebody's corpus is a bill they did not agree to.
+ *
+ * `problem` says which half is wrong. `'dimensions'` is arithmetically
+ * impossible to score at all; `'model'` would score, and lie.
+ */
+export declare class EmbedderMismatchError extends Error {
+    readonly code: "ERR_EMBEDDER_MISMATCH";
+    /** The fingerprint the namespace was built with, `'<id>@<dims>'`. */
+    readonly indexed: string;
+    /** The fingerprint that just arrived. */
+    readonly incoming: string;
+    /** Which half disagrees. */
+    readonly problem: 'dimensions' | 'model';
+    /**
+     * @param alternative the store-specific second way out, named in the
+     *   message. A file-backed store says "point this store at a different
+     *   file"; a service-backed one names its own unit of separation.
+     */
+    constructor(namespace: string, indexed: string, incoming: string, problem: EmbedderMismatchError['problem'], operation: 'write to' | 'search', alternative?: string);
+}
+/** An embedder fingerprint, split into the two halves that decide separately. */
+export interface Fingerprint {
+    readonly id?: string;
+    readonly dims: number;
+}
+/** `'<id>@<dims>'`, with `'?'` for an embedder that did not name itself. */
+export declare function fingerprintText(fp: Fingerprint): string;
+/** Parse the `'<id>@<dims>'` form back into its halves. */
+export declare function parseFingerprint(text: string): Fingerprint;
+/**
+ * What, if anything, makes these two incompatible.
+ *
+ * Dimensions always decide: two lengths cannot be compared at all. Model ids
+ * decide only when BOTH sides named themselves — an anonymous vector is not
+ * evidence of a different embedder, and refusing on absence would break every
+ * caller who never passed an `embedderId`, which is most of them.
+ */
+export declare function fingerprintConflict(stored: Fingerprint, incoming: Fingerprint): 'dimensions' | 'model' | null;
+//# sourceMappingURL=embedderMismatch.d.ts.map

package/dist/types/lib/embedderMismatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedderMismatch.d.ts","sourceRoot":"","sources":["../../../src/lib/embedderMismatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,0BAAoC;IACjD,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC;IAEzC;;;;OAIG;gBAED,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,qBAAqB,CAAC,SAAS,CAAC,EACzC,SAAS,EAAE,UAAU,GAAG,QAAQ,EAChC,WAAW,SAA0C;CAoBxD;AAED,iFAAiF;AACjF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAEvD;AAED,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAQ1D;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,WAAW,GACpB,YAAY,GAAG,OAAO,GAAG,IAAI,CAM/B"}

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

@@ -139,22 +139,40 @@ export interface DefineRAGOptions {
      */
     readonly description?: string;
     /**
-     * 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
-     * a durable adapter in production.
+     * 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 a durable adapter in
+     * production.
+     *
+     * A store that declares `ranksBy: 'server-text'` is served by the backend's
+     * own index rather than one built here — see {@link embedder}.
      */
     readonly store: MemoryStore;
     /**
      * Embedder used for the read-side query. Pass the SAME embedder
      * instance (or one with the same `embedderId`) that was used for
      * indexing — cross-model similarity scores are not comparable.
+     *
+     * **Optional since 9.3.0, for one case only.** A store that declares
+     * `ranksBy: 'server-text'` (see {@link MemoryStore.ranksBy}) takes the
+     * question as WORDS and ranks it on the backend's side; there is nothing
+     * here for an embedder to do, and embedding the query anyway would be spend
+     * on a vector discarded on arrival. Against such a store this must be
+     * OMITTED — passing one is refused rather than ignored, because an ignored
+     * embedder reads, from the wiring, exactly like a working one.
+     *
+     * Against every other store it is still required.
      */
-    readonly embedder: Embedder;
+    readonly embedder?: Embedder;
     /**
      * Stable id of the embedder. Stored on entries during indexing
      * (via `indexDocuments`) and filtered at search time so a later
      * embedder swap doesn't pollute results.
+     *
+     * Refused alongside a `'server-text'` store for the same reason
+     * {@link embedder} is: the backend's records were never written here and
+     * carry no `embeddingModel` to filter on, so the option would name a filter
+     * that filtered nothing.
      */
     readonly embedderId?: string;
     /**
@@ -264,7 +282,11 @@ export interface DefineRAGOptions {
  * (or, equivalently, `.memory(definition)` — same plumbing).
  *
  * @throws when `store` does not implement `search()`. RAG requires a
- *         vector-capable adapter.
+ *         store that can retrieve.
+ * @throws when `embedder` is missing and the store does not rank text
+ *         server-side — somebody has to turn the question into a vector.
+ * @throws when `embedder`/`embedderId` is passed to a store that DOES rank
+ *         text server-side — the option would be read by nothing.
  * @throws when `retrieval` is combined with `topK` or `threshold`.
  */
 export declare function defineRAG(opts: DefineRAGOptions): MemoryDefinition;

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAUxC;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,gBAAgB,CAqElE"}
+{"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;AAMzE;;;;;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;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAE7B;;;;;;;;;OASG;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;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAUxC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,gBAAgB,CAmGlE"}

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,CA4B3E;AA+TD;;;;;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;AAcH,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;AAmWD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,OAAO,CAErF"}

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

@@ -172,7 +172,17 @@ export interface TopKShorthandStrategy {
     readonly topK: number;
     /** Min cosine similarity. Strict — no fallback below this. Default 0.7. */
     readonly threshold?: number;
-    readonly embedder: Embedder;
+    /**
+     * The embedder that turns the query into a vector.
+     *
+     * Optional since 9.3.0 for ONE case: a store declaring
+     * `ranksBy: 'server-text'` ranks the question as words on the backend's
+     * side, so there is nothing here to embed. Omitted anywhere else,
+     * `defineMemory` refuses by name — the requirement moved from the type to a
+     * runtime check because it now depends on the STORE, which the type cannot
+     * see.
+     */
+    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
@@ -189,7 +199,8 @@ export interface TopKShorthandStrategy {
 /** 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;
+    /** See {@link TopKShorthandStrategy.embedder} — optional for server-text stores only. */
+    readonly embedder?: Embedder;
     readonly retrieval: RetrievalStrategy;
     /** See {@link TopKShorthandStrategy.embedderId}. */
     readonly embedderId?: string;