agentfootprint 9.2.0 → 9.4.0

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

@@ -0,0 +1,244 @@
+/**
+ * adapters/memory/pgVector — the target our own port has named since 2.x.
+ *
+ * `MemoryStore`'s docstring has listed the backends it was designed for from
+ * the beginning — *"Every storage backend (InMemory, Redis, DynamoDB,
+ * **Postgres**, Bedrock AgentCore) implements this interface"* — and named the
+ * query, twice, in the places an implementer would look: *"**Postgres**:
+ * multi-row INSERT … ON CONFLICT DO UPDATE"* for `putMany`, *"**pgvector**:
+ * `ORDER BY embedding <=> query LIMIT k`"* for `search`. Every one of those
+ * sentences was true about the design and false about the shipped package.
+ * This is the adapter that makes them the same sentence.
+ *
+ * It matters more than one row in a table of backends. Postgres is the database
+ * most teams already run, `pgvector` is an extension away, and a corpus that
+ * lives beside the application's own data inherits its backups, its failover,
+ * its access control and its migrations. `sqliteVectorStore` is one machine;
+ * `s3VectorsStore` is serverless and eventually consistent; this is the one for
+ * a fleet that already has a database.
+ *
+ * ── The table, and why this does not create it ──────────────────────────────
+ * A `vector(N)` column fixes N at creation, and N is a fact about your
+ * embedder. Creating the table implicitly would pick that number — and the
+ * index type, and the operator class — on your behalf, in a migration you never
+ * reviewed, in a database whose DDL is usually somebody's job. So the schema is
+ * yours to run, and this store REFUSES a table that is missing rather than
+ * silently answering "no matches" against nothing:
+ *
+ * ```sql
+ * CREATE EXTENSION IF NOT EXISTS vector;
+ *
+ * -- 1024 = your embedder's dimensions. bedrockEmbedder() default: 1024.
+ * --        openaiEmbedder() default: 1536. staticEmbedder(): 256.
+ * CREATE TABLE af_vectors (
+ *   namespace        TEXT    NOT NULL,
+ *   id               TEXT    NOT NULL,
+ *   value            JSONB   NOT NULL,
+ *   metadata         JSONB,
+ *   embedding        vector(1024),
+ *   embedder_fp      TEXT,
+ *   version          INTEGER NOT NULL,
+ *   created_at       BIGINT  NOT NULL,
+ *   updated_at       BIGINT  NOT NULL,
+ *   last_accessed_at BIGINT  NOT NULL,
+ *   access_count     INTEGER NOT NULL,
+ *   ttl              BIGINT,
+ *   tier             TEXT,
+ *   source           JSONB,
+ *   embedding_model  TEXT,
+ *   PRIMARY KEY (namespace, id)
+ * );
+ *
+ * -- Cosine, because that is the score this port reports and every threshold
+ * -- in this library is calibrated on. Match the operator class to the metric.
+ * CREATE INDEX af_vectors_hnsw ON af_vectors
+ *   USING hnsw (embedding vector_cosine_ops);
+ * CREATE INDEX af_vectors_ns ON af_vectors (namespace);
+ *
+ * -- Recognition (`seen`/`recordSignature`), usefulness feedback, and the
+ * -- per-namespace embedder fingerprint. Small, and each one is a port method
+ * -- that would otherwise have to be refused.
+ * CREATE TABLE af_signatures (
+ *   namespace TEXT NOT NULL, signature TEXT NOT NULL,
+ *   PRIMARY KEY (namespace, signature)
+ * );
+ * CREATE TABLE af_feedback (
+ *   namespace TEXT NOT NULL, id TEXT NOT NULL,
+ *   total DOUBLE PRECISION NOT NULL, count INTEGER NOT NULL,
+ *   PRIMARY KEY (namespace, id)
+ * );
+ * CREATE TABLE af_index_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+ * ```
+ *
+ * Every table and column name above is an OPTION with that value as its
+ * default, so this drops into a schema that already has naming conventions —
+ * see {@link PgVectorStoreOptions}. Identifiers are validated and quoted; a
+ * name that is not a plain SQL identifier is refused rather than interpolated.
+ *
+ * ── Cosine, and only cosine ─────────────────────────────────────────────────
+ * `search` is `1 - (embedding <=> $query::vector)` — pgvector's cosine
+ * DISTANCE, converted to the cosine SIMILARITY the port reports and
+ * `defineRAG`'s 0.7 default is calibrated on. `<->` (L2) and `<#>` (inner
+ * product) are deliberately not options: their ranges are not that range, and a
+ * number that reads like a cosine and is not one is the failure mode the whole
+ * fingerprint machinery exists to prevent. Build the HNSW index with
+ * `vector_cosine_ops` so the operator and the index agree — with the wrong
+ * operator class the query still returns the right answer, slowly, by scanning.
+ *
+ * ── One statement at a time, on purpose ─────────────────────────────────────
+ * The client here is anything with `query()` — a `pg.Pool` is the expected one,
+ * and a Pool hands each `query()` its own connection. `BEGIN` on one and the
+ * next statement on another is a transaction that silently is not one, so this
+ * adapter never writes multi-statement transactions. Everything that must be
+ * atomic is ONE statement: `putMany` is one multi-row upsert, `putIfVersion` is
+ * one conditional upsert, `forget` is one statement with CTEs across all four
+ * tables. That is a constraint that made the code better.
+ *
+ * ── Lazy peer dependency ────────────────────────────────────────────────────
+ * `pg` 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 reuse the pool your app already has — which is the
+ * recommended shape, because a second pool to the same database is a second set
+ * of connections nobody counted.
+ */
+import type { MemoryIdentity } from '../../memory/identity/index.js';
+import type { MemoryStore } from '../../memory/store/types.js';
+/** One result set, as this adapter reads it. */
+export interface PgQueryResult {
+    readonly rows: readonly Record<string, unknown>[];
+}
+/**
+ * The slice of a `pg` client this adapter calls.
+ *
+ * Structural, so a `Pool`, a `Client`, a pgBouncer-fronted wrapper or a test
+ * double all satisfy it without this package taking a hard type dependency on
+ * the optional peer.
+ */
+export interface PgLikeClient {
+    query(text: string, params?: readonly unknown[]): Promise<PgQueryResult>;
+    /** Optional — awaited by {@link PgVectorStore.close} when this store built the pool. */
+    end?(): Promise<void>;
+}
+/** The one constructor this adapter needs out of `pg`. */
+export interface PgSdkModule {
+    readonly Pool?: new (config: {
+        connectionString?: string;
+    }) => PgLikeClient;
+}
+/**
+ * Column names, so this store fits a schema that already has conventions.
+ * Every one defaults to the name in the `CREATE TABLE` above.
+ */
+export interface PgVectorColumns {
+    readonly namespace?: string;
+    readonly id?: string;
+    readonly value?: string;
+    readonly metadata?: string;
+    readonly embedding?: string;
+    readonly embedderFp?: string;
+    readonly version?: string;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly lastAccessedAt?: string;
+    readonly accessCount?: string;
+    readonly ttl?: string;
+    readonly tier?: string;
+    readonly source?: string;
+    readonly embeddingModel?: string;
+}
+export interface PgVectorStoreOptions {
+    /**
+     * Postgres connection string, used only when this store builds its own pool.
+     * Prefer `client` — a second pool to one database is a second set of
+     * connections nobody counted.
+     */
+    readonly connectionString?: string;
+    /** A pre-built `pg.Pool` (or anything with `query`). Recommended. */
+    readonly client?: PgLikeClient;
+    /** Schema the tables live in. Default `'public'`. */
+    readonly schema?: string;
+    /** The vectors table. Default `'af_vectors'`. */
+    readonly table?: string;
+    /** The recognition-set table (`seen`/`recordSignature`). Default `'af_signatures'`. */
+    readonly signaturesTable?: string;
+    /** The usefulness-aggregate table. Default `'af_feedback'`. */
+    readonly feedbackTable?: string;
+    /** The key/value table holding one embedder fingerprint per namespace. Default `'af_index_meta'`. */
+    readonly metaTable?: string;
+    /** Column names inside {@link table}. Each defaults to the documented one. */
+    readonly columns?: PgVectorColumns;
+    /**
+     * Rows per multi-row upsert. Default 500.
+     *
+     * Postgres caps a statement at 65,535 bound parameters and this store binds
+     * 15 per row, so 500 leaves an order of magnitude of headroom. Raising it
+     * trades round-trips for a statement that fails all-or-nothing on a bigger
+     * unit.
+     */
+    readonly batchSize?: number;
+    /** @internal Test injection — skips the `pg` require entirely. */
+    readonly _client?: PgLikeClient;
+    /** @internal Test injection — the `pg` module (exercises the real shim with a mock module). */
+    readonly _pg?: PgSdkModule;
+}
+/** A Postgres-backed vector store, plus the two things it owns beyond the port. */
+export interface PgVectorStore extends MemoryStore {
+    /**
+     * The embedder fingerprint (`'<id>@<dims>'`) a namespace was built with, or
+     * `undefined` when nothing with a vector has been written to it yet.
+     *
+     * Read this before an embedder swap: it is the fact `EmbedderMismatchError`
+     * refuses on, available up front instead of at the first failed write.
+     */
+    fingerprintOf(identity: MemoryIdentity): Promise<string | undefined>;
+    /**
+     * Release the pool, if this store built one. Idempotent. A client you passed
+     * in is yours and is left alone.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Raised when the database is reachable but its schema is not this store's.
+ *
+ * The law `sqliteVectorStore` states for a file, one backend over: **an
+ * unreadable index and an empty one are different facts, and only one of them
+ * is safe to answer with "no matches".** A store that treated a missing table
+ * as an empty corpus would answer every question from the model's own weights
+ * and log nothing.
+ */
+export declare class PgVectorSchemaError extends Error {
+    readonly code: "ERR_PGVECTOR_SCHEMA";
+    /** The schema-qualified table that could not be used. */
+    readonly table: string;
+    /** Columns this store needs and did not find. Empty when the table is absent entirely. */
+    readonly missingColumns: readonly string[];
+    constructor(table: string, missingColumns: readonly string[], detail: string);
+}
+/**
+ * Open a `MemoryStore` over an existing Postgres + pgvector table.
+ *
+ * @throws when `pg` is absent and no `client` was passed.
+ * @throws PgVectorSchemaError on the first call, when the table or a column it
+ *         needs is not there.
+ * @throws EmbedderMismatchError from `put`/`putMany`/`search` when a vector
+ *         meets a namespace built by a different embedder.
+ *
+ * @example  A corpus beside the application's own data
+ * ```ts
+ * import { Pool } from 'pg';
+ * import { defineRAG, indexDocuments } from 'agentfootprint';
+ * import { pgVectorStore } from 'agentfootprint/memory';
+ * import { openaiEmbedder } from 'agentfootprint/providers';
+ *
+ * const store = pgVectorStore({ client: new Pool({ connectionString: process.env.DATABASE_URL }) });
+ * const embedder = openaiEmbedder();
+ *
+ * await indexDocuments(store, embedder, docs, { embedderId: embedder.id });
+ *
+ * const agent = Agent.create({ provider })
+ *   .rag(defineRAG({ id: 'docs', store, embedder, embedderId: embedder.id }))
+ *   .build();
+ * ```
+ */
+export declare function pgVectorStore(options?: PgVectorStoreOptions): PgVectorStore;
+//# sourceMappingURL=pgVector.d.ts.map

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

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

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

@@ -0,0 +1,241 @@
+/**
+ * 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.
+ *
+ * ── The preflight: this store now READS the index before trusting it (9.4.0) ─
+ * One `GetIndex`, lazily on first use and memoized for the life of the store.
+ * It checks the three things this adapter used to assume — and that a
+ * production deployment got wrong in all three ways at once:
+ *
+ *   1. the distance metric really is cosine (a euclidean index scored a
+ *      self-query at 0.999…, where a true cosine is exactly 1.0);
+ *   2. `af` really is non-filterable, checked BEFORE the first write, so a
+ *      misconfigured index fails at document 1 rather than at document 400
+ *      with an AWS "Filterable metadata must have at most 2048 bytes";
+ *   3. the index dimension matches the vectors being written or searched.
+ *
+ * This is the discipline every sibling store already had at open —
+ * `sqliteVectorStore`'s schema identity, `pgVectorStore`'s schema check,
+ * `staticVectorStore`'s load-time fingerprint. This store had nothing to open,
+ * so it opened nothing.
+ *
+ * **IAM:** the caller now needs `s3vectors:GetIndex` alongside `PutVectors` /
+ * `QueryVectors` / `GetVectors` / `ListVectors` / `DeleteVectors`. A GetIndex
+ * that fails is refused by name, never passed through — an index this store
+ * cannot read is an index whose metric, layout and dimension it would be
+ * guessing at.
+ *
+ * ── 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.
+ *   - Since 9.4.0 the index's OWN dimension is checked too, at the preflight —
+ *     so a wrong-size embedder is caught on the first write and the first
+ *     search of a fresh process, which the per-process fingerprint could not do
+ *     (it has nothing to disagree with at boot).
+ *   - What is still NOT caught: the first write of a fresh process into a
+ *     namespace built by a different embedder OF THE SAME SIZE. Only the model
+ *     id separates those, and it lives in the vectors rather than on the index.
+ *     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;
+    /** The PREFLIGHT (9.4.0) — the one call that reads the index rather than its
+     *  vectors. See `verifyIndex` for what it checks and why each one is fatal. */
+    readonly GetIndexCommand?: new (input: unknown) => unknown;
+    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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsIG;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;mFAC+E;IAC/E,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAC3D,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,CAsoB7E"}

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/adapters/observability/cloudwatch.d.ts

@@ -90,6 +90,10 @@ export interface CloudwatchObservabilityOptions {
     /** Test injection — bypasses SDK lazy-require entirely. When set,
      *  `region` / IAM are ignored. */
     readonly _client?: CloudWatchLikeClient;
+    /** @internal Test injection (9.4.0) — the AWS SDK module, so the real shim
+     *  (`send(new Command(...))`) runs against a fake SDK and the command names
+     *  it dispatches can be asserted. Ignored when `_client` is set. */
+    readonly _sdk?: CloudWatchSdkModule;
 }
 export interface CloudWatchLikeClient {
     putLogEvents(input: {
@@ -112,6 +116,22 @@ export interface CloudWatchLikeClient {
         logStreamName: string;
     }): Promise<unknown>;
 }
+/**
+ * The slice of `@aws-sdk/client-cloudwatch-logs` this shim touches.
+ *
+ * Exported since 9.4.0 so `opts._sdk` can name it — which is what lets the
+ * shared command-name pin (test/adapters/aws/) assert the OPERATIONS this
+ * adapter dispatches without an AWS account or the peer dep installed. A
+ * `_client` double proves the batching; only an `_sdk` double can prove the
+ * adapter reaches for `PutLogEvents` and not something that does not exist.
+ */
+export interface CloudWatchSdkModule {
+    readonly CloudWatchLogsClient?: new (config: {
+        region?: string;
+    }) => unknown;
+    readonly PutLogEventsCommand?: new (input: unknown) => unknown;
+    readonly CreateLogStreamCommand?: new (input: unknown) => unknown;
+}
 /**
  * Internal: shared CloudWatch Logs base used by every adapter that
  * ships to CWL. `cloudwatchObservability` is the public generic

package/dist/types/adapters/observability/cloudwatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloudwatch.d.ts","sourceRoot":"","sources":["../../../../src/adapters/observability/cloudwatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAMvE,MAAM,WAAW,8BAA8B;IAC7C,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;0DAOsD;IACtD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;4BAKwB;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;oDAEgD;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;mEAC+D;IAC/D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACvE;sCACkC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;CACzC;AAID,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,KAAK,EAAE;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,aAAa,CAAC;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAClE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrB;;;;;;OAMG;IACH,eAAe,CAAC,CAAC,KAAK,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5F;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,8BAA8B,EACpC,YAAY,EAAE,MAAM,GACnB,qBAAqB,CAsOvB;AA4BD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,8BAA8B,GACnC,qBAAqB,CAEvB"}
+{"version":3,"file":"cloudwatch.d.ts","sourceRoot":"","sources":["../../../../src/adapters/observability/cloudwatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAMvE,MAAM,WAAW,8BAA8B;IAC7C,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;0DAOsD;IACtD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;4BAKwB;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;oDAEgD;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;mEAC+D;IAC/D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACvE;sCACkC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;IACxC;;wEAEoE;IACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAID,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,KAAK,EAAE;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,aAAa,CAAC;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAClE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrB;;;;;;OAMG;IACH,eAAe,CAAC,CAAC,KAAK,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5F;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,KAAK,MAAM,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC;IAC7E,QAAQ,CAAC,mBAAmB,CAAC,EAAE,KAAK,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAC/D,QAAQ,CAAC,sBAAsB,CAAC,EAAE,KAAK,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACnE;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,8BAA8B,EACpC,YAAY,EAAE,MAAM,GACnB,qBAAqB,CAsOvB;AA4BD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,8BAA8B,GACnC,qBAAqB,CAEvB"}

package/dist/types/adapters/observability/xray.d.ts

@@ -94,11 +94,29 @@ export interface XrayObservabilityOptions {
     readonly onError?: (error: Error, event?: AgentfootprintEvent) => void;
     /** Test injection — bypasses SDK lazy-require entirely. */
     readonly _client?: XRayLikeClient;
+    /** @internal Test injection (9.4.0) — the AWS SDK module, so the real shim
+     *  (`send(new Command(...))`) runs against a fake SDK and the command name it
+     *  dispatches can be asserted. Ignored when `_client` is set. */
+    readonly _sdk?: XRaySdkModule;
 }
 export interface XRayLikeClient {
     putTraceSegments(input: {
         TraceSegmentDocuments: ReadonlyArray<string>;
     }): Promise<unknown>;
 }
+/**
+ * The slice of `@aws-sdk/client-xray` this shim touches.
+ *
+ * Exported since 9.4.0 so `opts._sdk` can name it — which is what lets the
+ * shared command-name pin (test/adapters/aws/) assert that this adapter
+ * dispatches `PutTraceSegments` and nothing invented, without an AWS account
+ * or the peer dep installed.
+ */
+export interface XRaySdkModule {
+    readonly XRayClient?: new (config: {
+        region?: string;
+    }) => unknown;
+    readonly PutTraceSegmentsCommand?: new (input: unknown) => unknown;
+}
 export declare function xrayObservability(opts: XrayObservabilityOptions): ObservabilityStrategy;
 //# sourceMappingURL=xray.d.ts.map

package/dist/types/adapters/observability/xray.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xray.d.ts","sourceRoot":"","sources":["../../../../src/adapters/observability/xray.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAMvE,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;iCAC6B;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;oDAEgD;IAChD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;0CAEsC;IACtC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;yCACqC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACvE,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;CACnC;AAID,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,KAAK,EAAE;QAAE,qBAAqB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7F;AA6BD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,qBAAqB,CA4ZvF"}
+{"version":3,"file":"xray.d.ts","sourceRoot":"","sources":["../../../../src/adapters/observability/xray.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAMvE,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;iCAC6B;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;oDAEgD;IAChD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;0CAEsC;IACtC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;yCACqC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACvE,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC;;qEAEiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC;CAC/B;AAID,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,KAAK,EAAE;QAAE,qBAAqB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7F;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,MAAM,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC;IACnE,QAAQ,CAAC,uBAAuB,CAAC,EAAE,KAAK,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACpE;AAwBD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,qBAAqB,CA4ZvF"}