@alvin0/ai-agent-sdk-core 0.1.0 → 0.1.1

package/dist/embedding/handle.d.ts

@@ -0,0 +1,76 @@
+import { EmbeddingSpaceId } from "./profile.js";
+import { EmbeddingPurpose } from "./purpose.js";
+import { ResolvedEmbeddingBatchLimits } from "./limits.js";
+import { EmbeddingContentPart, EmbeddingTruncation } from "./request.js";
+import { EmbeddingManyResult, EmbeddingResult } from "./result.js";
+//#region src/embedding/handle.d.ts
+/** One cached vector, stored with the space identity it was produced in. */
+interface EmbeddingCacheEntry {
+  readonly values: readonly number[];
+  /**
+   * `Space_Id` at the time of writing. A read whose space does not match the
+   * current `PreparedEmbeddingCall` is discarded rather than trusted.
+   */
+  readonly space: EmbeddingSpaceId;
+}
+/**
+ * Caller-supplied cache backing. Sync or async implementations are both
+ * accepted so an in-process `Map` needs no promise ceremony.
+ */
+interface EmbeddingCacheStore {
+  get(key: string): Promise<EmbeddingCacheEntry | undefined> | EmbeddingCacheEntry | undefined;
+  set(key: string, entry: EmbeddingCacheEntry): Promise<void> | void;
+}
+/** Opt-in embedding cache. Disabled unless supplied. */
+interface EmbeddingCacheOptions {
+  readonly store: EmbeddingCacheStore;
+  /**
+   * REQUIRED security scope, no default (DD-8). It is the first component of
+   * every cache key, so a missing scope is a configuration error rather than
+   * something the runtime silently fills in.
+   */
+  readonly scope: string;
+}
+/** Configuration of one `EmbeddingModelHandle`. */
+interface EmbeddingModelOptions {
+  /** Provider route key that must own an `Embedding_Adapter`. */
+  readonly provider: string;
+  readonly model: string;
+  /** Requested dimensions; absent means the model default. */
+  readonly dimensions?: number;
+  /** SDK default is `'reject'`, even where the provider default is to cut. */
+  readonly truncation?: EmbeddingTruncation;
+  /** Expected `Space_Id`; an incompatible resolution rejects the call. */
+  readonly expectedSpace?: EmbeddingSpaceId;
+  /** Upper bound on in-flight `Physical_Batch`es of one `Logical_Call`. */
+  readonly concurrency?: number;
+  readonly batchLimits?: Partial<ResolvedEmbeddingBatchLimits>;
+  readonly cache?: EmbeddingCacheOptions;
+}
+/** Input of {@link EmbeddingModelHandle.embed}: exactly one object to embed. */
+interface EmbedOneInput {
+  readonly value: string | readonly EmbeddingContentPart[];
+  readonly purpose: EmbeddingPurpose;
+  readonly signal?: AbortSignal;
+  readonly expectedSpace?: EmbeddingSpaceId;
+}
+/** Input of {@link EmbeddingModelHandle.embedMany}; output follows this order. */
+interface EmbedManyInput {
+  readonly values: readonly (string | readonly EmbeddingContentPart[])[];
+  readonly purpose: EmbeddingPurpose;
+  readonly signal?: AbortSignal;
+  readonly expectedSpace?: EmbeddingSpaceId;
+}
+/**
+ * What `runtime.embeddingModel()` hands back.
+ *
+ * Both methods are one `Logical_Call` each: batching, retry, concurrency and
+ * order restoration happen behind them and are never the caller's concern.
+ */
+interface EmbeddingModelHandle {
+  embed(input: EmbedOneInput): Promise<EmbeddingResult>;
+  embedMany(input: EmbedManyInput): Promise<EmbeddingManyResult>;
+}
+//#endregion
+export { EmbedManyInput, EmbedOneInput, EmbeddingCacheEntry, EmbeddingCacheOptions, EmbeddingCacheStore, EmbeddingModelHandle, EmbeddingModelOptions };
+//# sourceMappingURL=handle.d.ts.map

package/dist/embedding/handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","names":[],"sources":["../../src/embedding/handle.ts"],"mappings":";;;;;;;UA+BiB;WACN;;;;;WAKA,OAAO;;;;;;UAOD;EACf,IAAI,cAAc,QAAQ,mCAAmC;EAC7D,IAAI,aAAa,OAAO,sBAAsB;;;UAI/B;WACN,OAAO;;;;;;WAMP;;;UAIM;;WAEN;WACA;;WAEA;;WAEA,aAAa;;WAEb,gBAAgB;;WAEhB;WACA,cAAc,QAAQ;WACtB,QAAQ;;;UAIF;WACN,yBAAyB;WACzB,SAAS;WACT,SAAS;WACT,gBAAgB;;;UAIV;WACN,oCAAoC;WACpC,SAAS;WACT,SAAS;WACT,gBAAgB;;;;;;;;UASV;EACf,MAAM,OAAO,gBAAgB,QAAQ;EACrC,UAAU,OAAO,iBAAiB,QAAQ"}

package/dist/embedding/limits.d.ts

@@ -0,0 +1,47 @@
+import { ResolvedEmbeddingModelInfo } from "./catalog.js";
+//#region src/embedding/limits.d.ts
+/**
+ * Safe fallbacks used for BATCHING when a catalog capability is not a declared
+ * number.
+ *
+ * Batching always needs a finite upper bound, otherwise the memory of one
+ * `Logical_Call` is unbounded (Requirement 17.4). Validation is the opposite
+ * case: an `unknown` capability is NEVER a reason to reject a request, so these
+ * values must not be read as limits the provider claimed (DD-6).
+ */
+declare const EMBEDDING_BATCH_DEFAULTS: Readonly<{
+  readonly maxItems: 96;
+  readonly maxTokens: 100000;
+  readonly maxBytes: number;
+}>;
+/** Fully decided batch bounds plus the estimator that measures against them. */
+interface ResolvedEmbeddingBatchLimits {
+  readonly maxItems: number;
+  readonly maxTokens: number;
+  readonly maxBytes: number;
+  readonly estimateTokens: (text: string) => number;
+}
+/**
+ * Shared token estimate for batching and for input-length checks.
+ *
+ * Default `ceil(utf8Bytes / 4)`. This is an ESTIMATE, not a provider tokenizer:
+ * it is used only to split batches and to reject an input when `maxInputTokens`
+ * is `supported` and the estimate already exceeds it. An adapter with a closer
+ * estimator passes it through `limits.estimateTokens`.
+ *
+ * There is exactly ONE owner of this heuristic — this function — so a batch
+ * split and a length check can never disagree about the size of the same text.
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * Merges caller overrides over the catalog's declared bounds, falling back to
+ * {@link EMBEDDING_BATCH_DEFAULTS} for anything the catalog leaves `unknown`.
+ *
+ * Precedence is override → catalog → default. Because the fallback is total, the
+ * result is always finite, which is what lets a model id outside the catalog be
+ * batched without being rejected.
+ */
+declare function resolveBatchLimits(model: ResolvedEmbeddingModelInfo, overrides?: Partial<ResolvedEmbeddingBatchLimits>): ResolvedEmbeddingBatchLimits;
+//#endregion
+export { EMBEDDING_BATCH_DEFAULTS, ResolvedEmbeddingBatchLimits, estimateTokens, resolveBatchLimits };
+//# sourceMappingURL=limits.d.ts.map

package/dist/embedding/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","names":[],"sources":["../../src/embedding/limits.ts"],"mappings":";;;;;;;;;;;cAuBa,0BAAwB;WACzB;WACC;;;;UAKI;WACN;WACA;WACA;WACA,iBAAiB;;;;;;;;;;;;;iBAmBZ,eAAe;;;;;;;;;iBAwBf,mBACd,OAAO,4BACP,YAAY,QAAQ,gCACnB"}

package/dist/embedding/limits.js

@@ -0,0 +1,2 @@
+const e=Object.freeze({maxItems:96,maxTokens:1e5,maxBytes:1048576}),t=new TextEncoder;function n(e){return Math.ceil(t.encode(e).byteLength/4)}function r(e){if(e.state===`supported`)return i(e.value)}function i(e){if(!(e===void 0||!Number.isInteger(e)||e<=0))return e}function a(t,a){return{maxItems:i(a?.maxItems)??r(t.maxBatchItems)??e.maxItems,maxTokens:i(a?.maxTokens)??r(t.maxBatchTokens)??e.maxTokens,maxBytes:i(a?.maxBytes)??r(t.maxBatchBytes)??e.maxBytes,estimateTokens:a?.estimateTokens??n}}export{e as EMBEDDING_BATCH_DEFAULTS,n as estimateTokens,a as resolveBatchLimits};
+//# sourceMappingURL=limits.js.map

package/dist/embedding/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","names":[],"sources":["../../src/embedding/limits.ts"],"sourcesContent":["/**\n * Batch limits and the one shared token estimator.\n *\n * These are contract DATA, not a composition detail: `prepareEmbeddingCall()`\n * and `PreparedEmbeddingCall` both carry them. Putting them in\n * `composition/embedding/planner.ts` would force `embedding/` to import from\n * `composition/`, the exact reversed dependency Requirements 1.6 and 19.6\n * forbid (DD-12). So they live here, and the planner consumes them.\n *\n * @module ai-agent-sdk/core/embedding/limits\n */\n\nimport type { EmbeddingCapability, ResolvedEmbeddingModelInfo } from './catalog.ts'\n\n/**\n * Safe fallbacks used for BATCHING when a catalog capability is not a declared\n * number.\n *\n * Batching always needs a finite upper bound, otherwise the memory of one\n * `Logical_Call` is unbounded (Requirement 17.4). Validation is the opposite\n * case: an `unknown` capability is NEVER a reason to reject a request, so these\n * values must not be read as limits the provider claimed (DD-6).\n */\nexport const EMBEDDING_BATCH_DEFAULTS = Object.freeze({\n  maxItems: 96,\n  maxTokens: 100_000,\n  maxBytes: 1024 * 1024,\n} as const)\n\n/** Fully decided batch bounds plus the estimator that measures against them. */\nexport interface ResolvedEmbeddingBatchLimits {\n  readonly maxItems: number\n  readonly maxTokens: number\n  readonly maxBytes: number\n  readonly estimateTokens: (text: string) => number\n}\n\nconst ENCODER = new TextEncoder()\n\n/** Bytes per estimated token in the default heuristic. */\nconst BYTES_PER_TOKEN = 4\n\n/**\n * Shared token estimate for batching and for input-length checks.\n *\n * Default `ceil(utf8Bytes / 4)`. This is an ESTIMATE, not a provider tokenizer:\n * it is used only to split batches and to reject an input when `maxInputTokens`\n * is `supported` and the estimate already exceeds it. An adapter with a closer\n * estimator passes it through `limits.estimateTokens`.\n *\n * There is exactly ONE owner of this heuristic — this function — so a batch\n * split and a length check can never disagree about the size of the same text.\n */\nexport function estimateTokens(text: string): number {\n  return Math.ceil(ENCODER.encode(text).byteLength / BYTES_PER_TOKEN)\n}\n\n/** A declared positive integer bound, or `undefined` when there is none to use. */\nfunction declared(capability: EmbeddingCapability<number>): number | undefined {\n  if (capability.state !== 'supported') return undefined\n  return override(capability.value)\n}\n\n/** A caller override wins outright, when it is a usable positive integer. */\nfunction override(value: number | undefined): number | undefined {\n  if (value === undefined || !Number.isInteger(value) || value <= 0) return undefined\n  return value\n}\n\n/**\n * Merges caller overrides over the catalog's declared bounds, falling back to\n * {@link EMBEDDING_BATCH_DEFAULTS} for anything the catalog leaves `unknown`.\n *\n * Precedence is override → catalog → default. Because the fallback is total, the\n * result is always finite, which is what lets a model id outside the catalog be\n * batched without being rejected.\n */\nexport function resolveBatchLimits(\n  model: ResolvedEmbeddingModelInfo,\n  overrides?: Partial<ResolvedEmbeddingBatchLimits>,\n): ResolvedEmbeddingBatchLimits {\n  return {\n    maxItems:\n      override(overrides?.maxItems)\n      ?? declared(model.maxBatchItems)\n      ?? EMBEDDING_BATCH_DEFAULTS.maxItems,\n    maxTokens:\n      override(overrides?.maxTokens)\n      ?? declared(model.maxBatchTokens)\n      ?? EMBEDDING_BATCH_DEFAULTS.maxTokens,\n    maxBytes:\n      override(overrides?.maxBytes)\n      ?? declared(model.maxBatchBytes)\n      ?? EMBEDDING_BATCH_DEFAULTS.maxBytes,\n    estimateTokens: overrides?.estimateTokens ?? estimateTokens,\n  }\n}\n"],"mappings":"AAuBA,MAAa,EAA2B,OAAO,OAAO,CACpD,SAAU,GACV,UAAW,IACX,SAAU,OACZ,CAAU,EAUJ,EAAU,IAAI,YAgBpB,SAAgB,EAAe,EAAsB,CACnD,OAAO,KAAK,KAAK,EAAQ,OAAO,CAAI,CAAC,CAAC,WAAa,CAAe,CACpE,CAGA,SAAS,EAAS,EAA6D,CACzE,KAAW,QAAU,YACzB,OAAO,EAAS,EAAW,KAAK,CAClC,CAGA,SAAS,EAAS,EAA+C,CAC3D,SAAU,IAAA,IAAa,CAAC,OAAO,UAAU,CAAK,GAAK,GAAS,GAChE,OAAO,CACT,CAUA,SAAgB,EACd,EACA,EAC8B,CAC9B,MAAO,CACL,SACE,EAAS,GAAW,QAAQ,GACzB,EAAS,EAAM,aAAa,GAC5B,EAAyB,SAC9B,UACE,EAAS,GAAW,SAAS,GAC1B,EAAS,EAAM,cAAc,GAC7B,EAAyB,UAC9B,SACE,EAAS,GAAW,QAAQ,GACzB,EAAS,EAAM,aAAa,GAC5B,EAAyB,SAC9B,eAAgB,GAAW,gBAAkB,CAC/C,CACF"}

package/dist/embedding/profile.d.ts

@@ -0,0 +1,89 @@
+import { ResolvedEmbeddingModelInfo } from "./catalog.js";
+//#region src/embedding/profile.d.ts
+/** Output representation of a vector. v1 declares exactly one. */
+type EmbeddingRepresentation = 'dense-float32';
+/**
+ * Whether vectors arrive normalized.
+ *
+ * `'unknown'` is a first-class value: a route that has not documented its
+ * normalization must say so rather than have `'none'` assumed for it.
+ */
+type EmbeddingNormalization = 'unit-l2' | 'none' | 'unknown';
+/** Post-processing is version-managed; it is never an implicit slice or pad. */
+interface EmbeddingPostProcessing {
+  readonly kind: 'l2-renormalize';
+  readonly revision: string;
+}
+/** Everything about one call configuration that a vector's meaning depends on. */
+interface EmbeddingProfile {
+  /** `${route}:${modelId}` — a model identity, NOT a space identity. */
+  readonly modelIdentity: string;
+  readonly modelRevision?: string;
+  readonly dimensions: number;
+  readonly representation: EmbeddingRepresentation;
+  readonly normalization: EmbeddingNormalization;
+  readonly postProcessing?: EmbeddingPostProcessing;
+  /** Recorded for traceability; excluded from the `Space_Id` derivation (DD-7). */
+  readonly documentRecipeRevision: string;
+  /** Recorded for traceability; excluded from the `Space_Id` derivation (DD-7). */
+  readonly queryRecipeRevision: string;
+  /** The provider's declaration about the embedding space. Declared by adapter/route. */
+  readonly compatibilityIdentity: string;
+  readonly profileRevision: string;
+}
+/** Canonical identifier of an embedding space. */
+type EmbeddingSpaceId = string & {
+  readonly __brand: 'EmbeddingSpaceId';
+};
+/**
+ * Call configuration a caller supplies on top of resolved catalog metadata.
+ *
+ * Every field is optional: an adapter that knows nothing beyond the model id
+ * still gets a usable profile out of {@link defaultEmbeddingProfile}.
+ */
+interface EmbeddingProfileInput {
+  /** Requested dimensions; absent means the model default. */
+  readonly dimensions?: number;
+  /** Revision of the rule turning a document's content parts into wire input. */
+  readonly documentRecipeRevision?: string;
+  /** Revision of the rule turning a query's content parts into wire input. */
+  readonly queryRecipeRevision?: string;
+  /** Bumped when any profile-affecting configuration changes. */
+  readonly profileRevision?: string;
+}
+/**
+ * Derives the `Space_Id` from what decides whether two vectors are comparable.
+ *
+ * SYNCHRONOUS and UNHASHED: a `Space_Id` is a canonical string, not a digest.
+ * It is an identifier for comparison, not a secret to hide, so no hash function
+ * is needed and `packages/core` takes on no `crypto.subtle` dependency (DD-11).
+ * Being synchronous, `prepareEmbeddingCall` calls it directly without `await`.
+ *
+ * Format: `emb:1|{compatibilityIdentity}|{dimensions}|{representation}|
+ * {normalization}|{postProcessing.kind}:{postProcessing.revision}|{profileRevision}`,
+ * where each component has `|` and `\` escaped before joining, so two different
+ * component tuples cannot produce the same string.
+ *
+ * NOTE: `documentRecipeRevision` and `queryRecipeRevision` are recorded on the
+ * profile but take NO part in the derivation. That is exactly what puts a query
+ * and a document in the same `Space_Id` when they share a retrieval profile.
+ */
+declare function deriveSpaceId(profile: EmbeddingProfile): EmbeddingSpaceId;
+/**
+ * Space compatibility is its own concept: decided by the declared compatibility
+ * identity, independent of comparing model names and independent of comparing
+ * dimension counts.
+ */
+declare function isSpaceCompatible(a: EmbeddingProfile, b: EmbeddingProfile): boolean;
+/**
+ * A usable default for `EmbeddingAdapter.embeddingProfile()`: compatibility
+ * identity derived from `${route}:${modelId}` when the catalog declares none,
+ * normalization `'unknown'`, no post-processing. This default is what keeps
+ * `EmbeddingAdapter` at exactly one abstract method (Requirement 1.2); an adapter
+ * that knows what its provider declares about the embedding space MUST override
+ * to state the real identity.
+ */
+declare function defaultEmbeddingProfile(model: ResolvedEmbeddingModelInfo, request: EmbeddingProfileInput): EmbeddingProfile;
+//#endregion
+export { EmbeddingNormalization, EmbeddingPostProcessing, EmbeddingProfile, EmbeddingProfileInput, EmbeddingRepresentation, EmbeddingSpaceId, defaultEmbeddingProfile, deriveSpaceId, isSpaceCompatible };
+//# sourceMappingURL=profile.d.ts.map

package/dist/embedding/profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.d.ts","names":[],"sources":["../../src/embedding/profile.ts"],"mappings":";;;KAYY;;;;;;;KAQA;;UAGK;WACN;WACA;;;UAIM;;WAEN;WACA;WACA;WACA,gBAAgB;WAChB,eAAe;WACf,iBAAiB;;WAEjB;;WAEA;;WAEA;WACA;;;KAIC;WAAuC;;;;;;;;UAQlC;;WAEN;;WAEA;;WAEA;;WAEA;;;;;;;;;;;;;;;;;;;iBA6DK,cAAc,SAAS,mBAAmB;;;;;;iBAS1C,kBAAkB,GAAG,kBAAkB,GAAG;;;;;;;;;iBAc1C,wBACd,OAAO,4BACP,SAAS,wBACR"}

package/dist/embedding/profile.js

@@ -0,0 +1,2 @@
+function e(e){return e.replace(/\\/g,`\\\\`).replace(/\|/g,`\\|`)}function t(t){return t===void 0?`none`:`${e(t.kind)}:${e(t.revision)}`}function n(n){return[e(n.compatibilityIdentity),String(n.dimensions),e(n.representation),e(n.normalization),t(n.postProcessing),e(n.profileRevision)]}function r(e){return[`emb:1`,...n(e)].join(`|`)}function i(e,t){let r=n(e),i=n(t);return r.every((e,t)=>e===i[t])}function a(e,t){let n=`${e.provider}:${e.id}`,r=e.compatibilityIdentity.state===`supported`?e.compatibilityIdentity.value:n,i=e.representation.state===`supported`?e.representation.value:`dense-float32`,a=e.defaultDimensions.state===`supported`?e.defaultDimensions.value:void 0;return{modelIdentity:n,...e.modelRevision===void 0?{}:{modelRevision:e.modelRevision},dimensions:t.dimensions??a??0,representation:i,normalization:`unknown`,documentRecipeRevision:t.documentRecipeRevision??`1`,queryRecipeRevision:t.queryRecipeRevision??`1`,compatibilityIdentity:r,profileRevision:t.profileRevision??`1`}}export{a as defaultEmbeddingProfile,r as deriveSpaceId,i as isSpaceCompatible};
+//# sourceMappingURL=profile.js.map

package/dist/embedding/profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.js","names":[],"sources":["../../src/embedding/profile.ts"],"sourcesContent":["/**\n * `Embedding_Profile` and the derived `Space_Id`.\n *\n * Two vectors with the same dimension count are NOT compatible for that reason\n * alone. This module owns the one place where compatibility is decided.\n *\n * @module ai-agent-sdk/core/embedding/profile\n */\n\nimport type { ResolvedEmbeddingModelInfo } from './catalog.ts'\n\n/** Output representation of a vector. v1 declares exactly one. */\nexport type EmbeddingRepresentation = 'dense-float32'\n\n/**\n * Whether vectors arrive normalized.\n *\n * `'unknown'` is a first-class value: a route that has not documented its\n * normalization must say so rather than have `'none'` assumed for it.\n */\nexport type EmbeddingNormalization = 'unit-l2' | 'none' | 'unknown'\n\n/** Post-processing is version-managed; it is never an implicit slice or pad. */\nexport interface EmbeddingPostProcessing {\n  readonly kind: 'l2-renormalize'\n  readonly revision: string\n}\n\n/** Everything about one call configuration that a vector's meaning depends on. */\nexport interface EmbeddingProfile {\n  /** `${route}:${modelId}` — a model identity, NOT a space identity. */\n  readonly modelIdentity: string\n  readonly modelRevision?: string\n  readonly dimensions: number\n  readonly representation: EmbeddingRepresentation\n  readonly normalization: EmbeddingNormalization\n  readonly postProcessing?: EmbeddingPostProcessing\n  /** Recorded for traceability; excluded from the `Space_Id` derivation (DD-7). */\n  readonly documentRecipeRevision: string\n  /** Recorded for traceability; excluded from the `Space_Id` derivation (DD-7). */\n  readonly queryRecipeRevision: string\n  /** The provider's declaration about the embedding space. Declared by adapter/route. */\n  readonly compatibilityIdentity: string\n  readonly profileRevision: string\n}\n\n/** Canonical identifier of an embedding space. */\nexport type EmbeddingSpaceId = string & { readonly __brand: 'EmbeddingSpaceId' }\n\n/**\n * Call configuration a caller supplies on top of resolved catalog metadata.\n *\n * Every field is optional: an adapter that knows nothing beyond the model id\n * still gets a usable profile out of {@link defaultEmbeddingProfile}.\n */\nexport interface EmbeddingProfileInput {\n  /** Requested dimensions; absent means the model default. */\n  readonly dimensions?: number\n  /** Revision of the rule turning a document's content parts into wire input. */\n  readonly documentRecipeRevision?: string\n  /** Revision of the rule turning a query's content parts into wire input. */\n  readonly queryRecipeRevision?: string\n  /** Bumped when any profile-affecting configuration changes. */\n  readonly profileRevision?: string\n}\n\n/** Version prefix of the canonical `Space_Id` string. */\nconst SPACE_ID_VERSION = 'emb:1'\n\n/** Revision used when the caller declares none. */\nconst DEFAULT_REVISION = '1'\n\n/**\n * Dimensions recorded when neither the caller nor the catalog declares a count.\n *\n * `0` is not a legal vector width, so it cannot collide with a real declaration.\n */\nconst UNDECLARED_DIMENSIONS = 0\n\n/**\n * Escapes `|` and `\\` so no two distinct component tuples can join to the same\n * string.\n */\nfunction escapeComponent(value: string): string {\n  return value.replace(/\\\\/g, '\\\\\\\\').replace(/\\|/g, '\\\\|')\n}\n\n/** The post-processing component, present or explicitly absent. */\nfunction postProcessingComponent(\n  postProcessing: EmbeddingPostProcessing | undefined,\n): string {\n  if (postProcessing === undefined) return 'none'\n  return `${escapeComponent(postProcessing.kind)}:${escapeComponent(postProcessing.revision)}`\n}\n\n/** The exact component tuple that decides space identity, in fixed order. */\nfunction spaceComponents(profile: EmbeddingProfile): readonly string[] {\n  return [\n    escapeComponent(profile.compatibilityIdentity),\n    String(profile.dimensions),\n    escapeComponent(profile.representation),\n    escapeComponent(profile.normalization),\n    postProcessingComponent(profile.postProcessing),\n    escapeComponent(profile.profileRevision),\n  ]\n}\n\n/**\n * Derives the `Space_Id` from what decides whether two vectors are comparable.\n *\n * SYNCHRONOUS and UNHASHED: a `Space_Id` is a canonical string, not a digest.\n * It is an identifier for comparison, not a secret to hide, so no hash function\n * is needed and `packages/core` takes on no `crypto.subtle` dependency (DD-11).\n * Being synchronous, `prepareEmbeddingCall` calls it directly without `await`.\n *\n * Format: `emb:1|{compatibilityIdentity}|{dimensions}|{representation}|\n * {normalization}|{postProcessing.kind}:{postProcessing.revision}|{profileRevision}`,\n * where each component has `|` and `\\` escaped before joining, so two different\n * component tuples cannot produce the same string.\n *\n * NOTE: `documentRecipeRevision` and `queryRecipeRevision` are recorded on the\n * profile but take NO part in the derivation. That is exactly what puts a query\n * and a document in the same `Space_Id` when they share a retrieval profile.\n */\nexport function deriveSpaceId(profile: EmbeddingProfile): EmbeddingSpaceId {\n  return [SPACE_ID_VERSION, ...spaceComponents(profile)].join('|') as EmbeddingSpaceId\n}\n\n/**\n * Space compatibility is its own concept: decided by the declared compatibility\n * identity, independent of comparing model names and independent of comparing\n * dimension counts.\n */\nexport function isSpaceCompatible(a: EmbeddingProfile, b: EmbeddingProfile): boolean {\n  const left = spaceComponents(a)\n  const right = spaceComponents(b)\n  return left.every((component, index) => component === right[index])\n}\n\n/**\n * A usable default for `EmbeddingAdapter.embeddingProfile()`: compatibility\n * identity derived from `${route}:${modelId}` when the catalog declares none,\n * normalization `'unknown'`, no post-processing. This default is what keeps\n * `EmbeddingAdapter` at exactly one abstract method (Requirement 1.2); an adapter\n * that knows what its provider declares about the embedding space MUST override\n * to state the real identity.\n */\nexport function defaultEmbeddingProfile(\n  model: ResolvedEmbeddingModelInfo,\n  request: EmbeddingProfileInput,\n): EmbeddingProfile {\n  const modelIdentity = `${model.provider}:${model.id}`\n  const compatibilityIdentity =\n    model.compatibilityIdentity.state === 'supported'\n      ? model.compatibilityIdentity.value\n      : modelIdentity\n  const representation =\n    model.representation.state === 'supported'\n      ? model.representation.value\n      : 'dense-float32'\n  const declaredDefault =\n    model.defaultDimensions.state === 'supported'\n      ? model.defaultDimensions.value\n      : undefined\n\n  return {\n    modelIdentity,\n    ...(model.modelRevision === undefined ? {} : { modelRevision: model.modelRevision }),\n    dimensions: request.dimensions ?? declaredDefault ?? UNDECLARED_DIMENSIONS,\n    representation,\n    // Never inferred from the dimension count or the provider's reputation.\n    normalization: 'unknown',\n    documentRecipeRevision: request.documentRecipeRevision ?? DEFAULT_REVISION,\n    queryRecipeRevision: request.queryRecipeRevision ?? DEFAULT_REVISION,\n    compatibilityIdentity,\n    profileRevision: request.profileRevision ?? DEFAULT_REVISION,\n  }\n}\n"],"mappings":"AAmFA,SAAS,EAAgB,EAAuB,CAC9C,OAAO,EAAM,QAAQ,MAAO,MAAM,CAAC,CAAC,QAAQ,MAAO,KAAK,CAC1D,CAGA,SAAS,EACP,EACQ,CAER,OADI,IAAmB,IAAA,GAAkB,OAClC,GAAG,EAAgB,EAAe,IAAI,EAAE,GAAG,EAAgB,EAAe,QAAQ,GAC3F,CAGA,SAAS,EAAgB,EAA8C,CACrE,MAAO,CACL,EAAgB,EAAQ,qBAAqB,EAC7C,OAAO,EAAQ,UAAU,EACzB,EAAgB,EAAQ,cAAc,EACtC,EAAgB,EAAQ,aAAa,EACrC,EAAwB,EAAQ,cAAc,EAC9C,EAAgB,EAAQ,eAAe,CACzC,CACF,CAmBA,SAAgB,EAAc,EAA6C,CACzE,MAAO,CAAC,QAAkB,GAAG,EAAgB,CAAO,CAAC,CAAC,CAAC,KAAK,GAAG,CACjE,CAOA,SAAgB,EAAkB,EAAqB,EAA8B,CACnF,IAAM,EAAO,EAAgB,CAAC,EACxB,EAAQ,EAAgB,CAAC,EAC/B,OAAO,EAAK,OAAO,EAAW,IAAU,IAAc,EAAM,EAAM,CACpE,CAUA,SAAgB,EACd,EACA,EACkB,CAClB,IAAM,EAAgB,GAAG,EAAM,SAAS,GAAG,EAAM,KAC3C,EACJ,EAAM,sBAAsB,QAAU,YAClC,EAAM,sBAAsB,MAC5B,EACA,EACJ,EAAM,eAAe,QAAU,YAC3B,EAAM,eAAe,MACrB,gBACA,EACJ,EAAM,kBAAkB,QAAU,YAC9B,EAAM,kBAAkB,MACxB,IAAA,GAEN,MAAO,CACL,gBACA,GAAI,EAAM,gBAAkB,IAAA,GAAY,CAAC,EAAI,CAAE,cAAe,EAAM,aAAc,EAClF,WAAY,EAAQ,YAAc,GAAmB,EACrD,iBAEA,cAAe,UACf,uBAAwB,EAAQ,wBAA0B,IAC1D,oBAAqB,EAAQ,qBAAuB,IACpD,wBACA,gBAAiB,EAAQ,iBAAmB,GAC9C,CACF"}

package/dist/embedding/purpose.d.ts

@@ -0,0 +1,37 @@
+//#region src/embedding/purpose.d.ts
+/**
+ * Purpose of an embedding input, declared once at the shared API.
+ *
+ * @module ai-agent-sdk/core/embedding/purpose
+ */
+/**
+ * Why an input is being embedded.
+ *
+ * Exactly two values. Purpose is REQUIRED on every `embed()`/`embedMany()` call,
+ * and translating it to a provider mechanism belongs entirely to the adapter.
+ */
+type EmbeddingPurpose = 'retrieval-query' | 'retrieval-document';
+/**
+ * How one route expresses {@link EmbeddingPurpose} on the wire.
+ *
+ * A route whose handling is `unknown` or `{ kind: 'none' }` gets the text sent
+ * verbatim: an adapter never adds a prefix the provider has not documented.
+ */
+type EmbeddingPurposeHandling =
+/** Provider has a dedicated wire parameter, for example Gemini `taskType`. */
+{
+  readonly kind: 'wire-parameter';
+  readonly parameter: string;
+} |
+/** Provider requires an adapter-inserted prefix, per provider documentation. */
+{
+  readonly kind: 'adapter-prefix';
+  readonly documented: true;
+} |
+/** Provider exposes no mechanism; the adapter does NOT invent a prefix. */
+{
+  readonly kind: 'none';
+};
+//#endregion
+export { EmbeddingPurpose, EmbeddingPurposeHandling };
+//# sourceMappingURL=purpose.d.ts.map

package/dist/embedding/purpose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"purpose.d.ts","names":[],"sources":["../../src/embedding/purpose.ts"],"mappings":";;;;;;;;;;;;KAYY;;;;;;;KAQA;;;WAEG;WAAiC;;;;WAEjC;WAAiC;;;;WAEjC"}

package/dist/embedding/request.d.ts

@@ -0,0 +1,54 @@
+import { EmbeddingPurpose } from "./purpose.js";
+//#region src/embedding/request.d.ts
+/**
+ * One component of a single object to embed.
+ *
+ * v1 scope is text only; the union exists so multimodal parts can be added later
+ * without changing the surrounding contract.
+ */
+type EmbeddingContentPart = {
+  readonly type: 'text';
+  readonly text: string;
+};
+/** One object embedded independently of the others in the same call. */
+interface EmbeddingItem {
+  /**
+   * Index within the `Logical_Call`, NOT the index within the `Physical_Batch`.
+   *
+   * Result order is restored from this value, so it survives batching, retries and
+   * out-of-order settlement.
+   */
+  readonly index: number;
+  /** Components of the SAME object; a provider returns exactly one vector per item. */
+  readonly contentParts: readonly EmbeddingContentPart[];
+}
+/**
+ * Whether the caller accepts provider-side input truncation.
+ *
+ * `'reject'` means an over-length input is a structured error, not data to cut.
+ */
+type EmbeddingTruncation = 'reject' | 'allow';
+/**
+ * SDK default truncation.
+ *
+ * Stays `'reject'` even where the provider default is on: silently shortening an
+ * input changes the vector without telling the caller.
+ */
+declare const DEFAULT_EMBEDDING_TRUNCATION: EmbeddingTruncation;
+/** Exactly one physical embedding request handed to an adapter. */
+interface EmbeddingBatchRequest {
+  /** Provider route key that owns this call. */
+  readonly provider: string;
+  /** Model id as passed by the caller. */
+  readonly model: string;
+  readonly purpose: EmbeddingPurpose;
+  readonly items: readonly EmbeddingItem[];
+  /** Requested dimensions; absent means the model default. */
+  readonly dimensions?: number;
+  /** Resolved from the caller, defaulting to {@link DEFAULT_EMBEDDING_TRUNCATION}. */
+  readonly truncation: EmbeddingTruncation;
+  readonly signal?: AbortSignal;
+}
+//#endregion
+export { DEFAULT_EMBEDDING_TRUNCATION, EmbeddingBatchRequest, EmbeddingContentPart, EmbeddingItem, EmbeddingTruncation };
+//# sourceMappingURL=request.d.ts.map

package/dist/embedding/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","names":[],"sources":["../../src/embedding/request.ts"],"mappings":";;;;;;;;KAcY;WACG;WAAuB;;;UAGrB;;;;;;;WAON;;WAEA,uBAAuB;;;;;;;KAQtB;;;;;;;cAQC,8BAA8B;;UAG1B;;WAEN;;WAEA;WACA,SAAS;WACT,gBAAgB;;WAEhB;;WAEA,YAAY;WACZ,SAAS"}

package/dist/embedding/request.js

@@ -0,0 +1,2 @@
+const e=`reject`;export{e as DEFAULT_EMBEDDING_TRUNCATION};
+//# sourceMappingURL=request.js.map

package/dist/embedding/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","names":[],"sources":["../../src/embedding/request.ts"],"sourcesContent":["/**\n * Request shapes for one physical embedding batch.\n *\n * @module ai-agent-sdk/core/embedding/request\n */\n\nimport type { EmbeddingPurpose } from './purpose.ts'\n\n/**\n * One component of a single object to embed.\n *\n * v1 scope is text only; the union exists so multimodal parts can be added later\n * without changing the surrounding contract.\n */\nexport type EmbeddingContentPart =\n  | { readonly type: 'text'; readonly text: string }\n\n/** One object embedded independently of the others in the same call. */\nexport interface EmbeddingItem {\n  /**\n   * Index within the `Logical_Call`, NOT the index within the `Physical_Batch`.\n   *\n   * Result order is restored from this value, so it survives batching, retries and\n   * out-of-order settlement.\n   */\n  readonly index: number\n  /** Components of the SAME object; a provider returns exactly one vector per item. */\n  readonly contentParts: readonly EmbeddingContentPart[]\n}\n\n/**\n * Whether the caller accepts provider-side input truncation.\n *\n * `'reject'` means an over-length input is a structured error, not data to cut.\n */\nexport type EmbeddingTruncation = 'reject' | 'allow'\n\n/**\n * SDK default truncation.\n *\n * Stays `'reject'` even where the provider default is on: silently shortening an\n * input changes the vector without telling the caller.\n */\nexport const DEFAULT_EMBEDDING_TRUNCATION: EmbeddingTruncation = 'reject'\n\n/** Exactly one physical embedding request handed to an adapter. */\nexport interface EmbeddingBatchRequest {\n  /** Provider route key that owns this call. */\n  readonly provider: string\n  /** Model id as passed by the caller. */\n  readonly model: string\n  readonly purpose: EmbeddingPurpose\n  readonly items: readonly EmbeddingItem[]\n  /** Requested dimensions; absent means the model default. */\n  readonly dimensions?: number\n  /** Resolved from the caller, defaulting to {@link DEFAULT_EMBEDDING_TRUNCATION}. */\n  readonly truncation: EmbeddingTruncation\n  readonly signal?: AbortSignal\n}\n"],"mappings":"AA2CA,MAAa,EAAoD"}

package/dist/embedding/result.d.ts

@@ -0,0 +1,50 @@
+import { UsageCounters } from "../observation/usage.js";
+import { EmbeddingProfile, EmbeddingSpaceId } from "./profile.js";
+import { EmbeddingUsageReport } from "./usage.js";
+//#region src/embedding/result.d.ts
+/** One vector, mapped back to the input it belongs to. */
+interface EmbeddingVector {
+  /** MUST match the `index` of an item in the request. */
+  readonly index: number;
+  /**
+   * The values exactly as the provider returned them, apart from a post-processing
+   * step recorded in {@link EmbeddingProfile}. Never sliced or padded.
+   */
+  readonly values: readonly number[];
+  /** Provider reported this input was cut; only valid when `truncation === 'allow'`. */
+  readonly truncated?: boolean;
+}
+/** What one `Provider_Attempt` produced for one `Physical_Batch`. */
+interface EmbeddingBatchResult {
+  readonly vectors: readonly EmbeddingVector[];
+  /** Raw provider evidence. The runtime does NOT infer 0 when this is absent. */
+  readonly usage?: UsageCounters;
+  readonly providerRequestId?: string;
+  readonly warnings?: readonly EmbeddingWarning[];
+}
+/** A fact worth surfacing that is not a failure. */
+interface EmbeddingWarning {
+  readonly code: 'input-truncated' | 'usage-unreported' | 'usage-malformed';
+  /** Affected input indexes, in `Logical_Call` numbering. */
+  readonly itemIndexes?: readonly number[];
+  readonly message: string;
+}
+/** What `embed()` returns for one input. */
+interface EmbeddingResult {
+  readonly embedding: readonly number[];
+  readonly space: EmbeddingSpaceId;
+  readonly profile: EmbeddingProfile;
+  readonly usage: EmbeddingUsageReport;
+  readonly warnings: readonly EmbeddingWarning[];
+}
+/** What `embedMany()` returns; `embeddings` follows input order. */
+interface EmbeddingManyResult {
+  readonly embeddings: readonly (readonly number[])[];
+  readonly space: EmbeddingSpaceId;
+  readonly profile: EmbeddingProfile;
+  readonly usage: EmbeddingUsageReport;
+  readonly warnings: readonly EmbeddingWarning[];
+}
+//#endregion
+export { EmbeddingBatchResult, EmbeddingManyResult, EmbeddingResult, EmbeddingVector, EmbeddingWarning };
+//# sourceMappingURL=result.d.ts.map

package/dist/embedding/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","names":[],"sources":["../../src/embedding/result.ts"],"mappings":";;;;;UAciB;;WAEN;;;;;WAKA;;WAEA;;;UAIM;WACN,kBAAkB;;WAElB,QAAQ;WACR;WACA,oBAAoB;;;UAId;WACN;;WAEA;WACA;;;UAIM;WACN;WACA,OAAO;WACP,SAAS;WACT,OAAO;WACP,mBAAmB;;;UAIb;WACN;WACA,OAAO;WACP,SAAS;WACT,OAAO;WACP,mBAAmB"}

package/dist/embedding/usage.d.ts

@@ -0,0 +1,64 @@
+//#region src/embedding/usage.d.ts
+/**
+ * Usage accounting for embedding.
+ *
+ * Embedding has no output tokens, so it does NOT reuse `UsageCounters` /
+ * `validateUsageCounters`: that shape only reports `complete` once
+ * `outputTokens` is present, which for embedding could only be satisfied by
+ * inventing a `0`. Usage honesty forbids that. Missing or malformed usage stays
+ * missing here — it remains evidence of a `Provider_Attempt`, but never leaves
+ * the runtime as a published number.
+ *
+ * @module ai-agent-sdk/core/embedding/usage
+ */
+/** Tokens a provider actually reported for embedding work. Never contains `outputTokens`. */
+interface EmbeddingTokenUsage {
+  readonly inputTokens: number;
+  readonly totalTokens?: number;
+}
+/**
+ * Coverage of a `Logical_Call`'s usage.
+ *
+ * `complete` only when every batch sent to the provider returned readable usage.
+ */
+type EmbeddingUsageStatus = 'complete' | 'partial' | 'missing';
+/** What the runtime publishes about the usage of one `Logical_Call`. */
+interface EmbeddingUsageReport {
+  readonly status: EmbeddingUsageStatus;
+  /** Present only when `status === 'complete'`. Never a `TokenUsage`. */
+  readonly tokens?: EmbeddingTokenUsage;
+  readonly batches: number;
+  readonly batchesWithUsage: number;
+  readonly providerAttempts: number;
+  readonly inputsFromCache: number;
+  readonly inputsFromProvider: number;
+}
+declare const COUNTER_KEYS: readonly ['inputTokens', 'totalTokens'];
+type EmbeddingCounterKey = typeof COUNTER_KEYS[number];
+/** Counterpart of `UsageValidationResult` for embedding. */
+interface EmbeddingUsageValidation {
+  /**
+   * Absent when the provider reported no readable `inputTokens`. No branch
+   * substitutes a `0`: an unreported counter is unknown, not zero.
+   */
+  readonly reported?: EmbeddingTokenUsage;
+  readonly invalidFields: readonly EmbeddingCounterKey[];
+  readonly complete: boolean;
+  readonly overflow: boolean;
+}
+/**
+ * Rejects invalid fields individually and keeps only counters the provider
+ * genuinely reported. A hostile or malformed payload yields
+ * `reported === undefined` rather than a fabricated total.
+ */
+declare function validateEmbeddingUsage(value: unknown): EmbeddingUsageValidation;
+/** True when the provider reported at least one readable embedding counter. */
+declare function hasEmbeddingUsage(value: EmbeddingTokenUsage | undefined): boolean;
+/**
+ * Applies the status rule to batches that were actually sent to the provider.
+ * Batches served from cache are not evidence of unreported usage.
+ */
+declare function classifyEmbeddingUsageStatus(batchesSent: number, batchesWithUsage: number): EmbeddingUsageStatus;
+//#endregion
+export { EmbeddingCounterKey, EmbeddingTokenUsage, EmbeddingUsageReport, EmbeddingUsageStatus, EmbeddingUsageValidation, classifyEmbeddingUsageStatus, hasEmbeddingUsage, validateEmbeddingUsage };
+//# sourceMappingURL=usage.d.ts.map

package/dist/embedding/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","names":[],"sources":["../../src/embedding/usage.ts"],"mappings":";;;;;;;;;;;;;;UAciB;WACN;WACA;;;;;;;KAQC;;UAGK;WACN,QAAQ;;WAER,SAAS;WACT;WACA;WACA;WACA;WACA;;cAGL;KACM,6BAA6B;;UAGxB;;;;;WAKN,WAAW;WACX,wBAAwB;WACxB;WACA;;;;;;;iBAoBK,uBAAuB,iBAAiB;;iBA0CxC,kBAAkB,OAAO;;;;;iBAQzB,6BAA6B,qBAAqB,2BAA2B"}

package/dist/embedding/usage.js

@@ -0,0 +1,2 @@
+const e=[`inputTokens`,`totalTokens`];function t(e){return typeof e==`number`&&Number.isSafeInteger(e)&&e>=0}function n(e,t){try{return{value:Reflect.get(e,t),unreadable:!1}}catch{return{unreadable:!0}}}function r(r){let i=typeof r==`object`&&r?r:{},a={},o=[],s=!1;for(let r of e){let e=n(i,r);if(e.unreadable){o.push(r);continue}let c=e.value;c!==void 0&&(t(c)?a[r]=c:(typeof c==`number`&&c>2**53-1&&(s=!0),o.push(r)))}a.inputTokens!==void 0&&a.totalTokens!==void 0&&a.totalTokens<a.inputTokens&&(delete a.totalTokens,o.push(`totalTokens`));let c=a.inputTokens,l=c===void 0?void 0:Object.freeze(a.totalTokens===void 0?{inputTokens:c}:{inputTokens:c,totalTokens:a.totalTokens});return Object.freeze({...l===void 0?{}:{reported:l},invalidFields:Object.freeze([...new Set(o)]),complete:l!==void 0&&o.length===0&&!s,overflow:s})}function i(t){return t!==void 0&&e.some(e=>t[e]!==void 0)}function a(e,t){return t<=0?`missing`:t>=e?`complete`:`partial`}export{a as classifyEmbeddingUsageStatus,i as hasEmbeddingUsage,r as validateEmbeddingUsage};
+//# sourceMappingURL=usage.js.map

package/dist/embedding/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","names":[],"sources":["../../src/embedding/usage.ts"],"sourcesContent":["/**\n * Usage accounting for embedding.\n *\n * Embedding has no output tokens, so it does NOT reuse `UsageCounters` /\n * `validateUsageCounters`: that shape only reports `complete` once\n * `outputTokens` is present, which for embedding could only be satisfied by\n * inventing a `0`. Usage honesty forbids that. Missing or malformed usage stays\n * missing here — it remains evidence of a `Provider_Attempt`, but never leaves\n * the runtime as a published number.\n *\n * @module ai-agent-sdk/core/embedding/usage\n */\n\n/** Tokens a provider actually reported for embedding work. Never contains `outputTokens`. */\nexport interface EmbeddingTokenUsage {\n  readonly inputTokens: number\n  readonly totalTokens?: number\n}\n\n/**\n * Coverage of a `Logical_Call`'s usage.\n *\n * `complete` only when every batch sent to the provider returned readable usage.\n */\nexport type EmbeddingUsageStatus = 'complete' | 'partial' | 'missing'\n\n/** What the runtime publishes about the usage of one `Logical_Call`. */\nexport interface EmbeddingUsageReport {\n  readonly status: EmbeddingUsageStatus\n  /** Present only when `status === 'complete'`. Never a `TokenUsage`. */\n  readonly tokens?: EmbeddingTokenUsage\n  readonly batches: number\n  readonly batchesWithUsage: number\n  readonly providerAttempts: number\n  readonly inputsFromCache: number\n  readonly inputsFromProvider: number\n}\n\nconst COUNTER_KEYS = ['inputTokens', 'totalTokens'] as const\nexport type EmbeddingCounterKey = typeof COUNTER_KEYS[number]\n\n/** Counterpart of `UsageValidationResult` for embedding. */\nexport interface EmbeddingUsageValidation {\n  /**\n   * Absent when the provider reported no readable `inputTokens`. No branch\n   * substitutes a `0`: an unreported counter is unknown, not zero.\n   */\n  readonly reported?: EmbeddingTokenUsage\n  readonly invalidFields: readonly EmbeddingCounterKey[]\n  readonly complete: boolean\n  readonly overflow: boolean\n}\n\nfunction validCounter(value: unknown): value is number {\n  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0\n}\n\nfunction readCounter(source: Readonly<Record<string, unknown>>, key: EmbeddingCounterKey): { value?: unknown; unreadable: boolean } {\n  try {\n    return { value: Reflect.get(source, key), unreadable: false }\n  } catch {\n    return { unreadable: true }\n  }\n}\n\n/**\n * Rejects invalid fields individually and keeps only counters the provider\n * genuinely reported. A hostile or malformed payload yields\n * `reported === undefined` rather than a fabricated total.\n */\nexport function validateEmbeddingUsage(value: unknown): EmbeddingUsageValidation {\n  const source = typeof value === 'object' && value !== null ? value as Readonly<Record<string, unknown>> : {}\n  const counters: Partial<Record<EmbeddingCounterKey, number>> = {}\n  const invalid: EmbeddingCounterKey[] = []\n  let overflow = false\n  for (const key of COUNTER_KEYS) {\n    const read = readCounter(source, key)\n    if (read.unreadable) {\n      invalid.push(key)\n      continue\n    }\n    const field = read.value\n    if (field === undefined) continue\n    if (validCounter(field)) counters[key] = field\n    else {\n      // A count past safe-integer precision is authority lost, not merely a bad field.\n      if (typeof field === 'number' && field > Number.MAX_SAFE_INTEGER) overflow = true\n      invalid.push(key)\n    }\n  }\n  // A total below the only disjoint bucket cannot describe the same call.\n  if (counters.inputTokens !== undefined && counters.totalTokens !== undefined\n    && counters.totalTokens < counters.inputTokens) {\n    delete counters.totalTokens\n    invalid.push('totalTokens')\n  }\n  const inputTokens = counters.inputTokens\n  // Without a reported input bucket there is nothing honest to publish.\n  const reported = inputTokens === undefined\n    ? undefined\n    : Object.freeze<EmbeddingTokenUsage>(counters.totalTokens === undefined\n      ? { inputTokens }\n      : { inputTokens, totalTokens: counters.totalTokens })\n  return Object.freeze({\n    ...(reported === undefined ? {} : { reported }),\n    invalidFields: Object.freeze([...new Set(invalid)]),\n    complete: reported !== undefined && invalid.length === 0 && !overflow,\n    overflow,\n  })\n}\n\n/** True when the provider reported at least one readable embedding counter. */\nexport function hasEmbeddingUsage(value: EmbeddingTokenUsage | undefined): boolean {\n  return value !== undefined && COUNTER_KEYS.some(key => value[key] !== undefined)\n}\n\n/**\n * Applies the status rule to batches that were actually sent to the provider.\n * Batches served from cache are not evidence of unreported usage.\n */\nexport function classifyEmbeddingUsageStatus(batchesSent: number, batchesWithUsage: number): EmbeddingUsageStatus {\n  if (batchesWithUsage <= 0) return 'missing'\n  return batchesWithUsage >= batchesSent ? 'complete' : 'partial'\n}\n"],"mappings":"AAsCA,MAAM,EAAe,CAAC,cAAe,aAAa,EAelD,SAAS,EAAa,EAAiC,CACrD,OAAO,OAAO,GAAU,UAAY,OAAO,cAAc,CAAK,GAAK,GAAS,CAC9E,CAEA,SAAS,EAAY,EAA2C,EAAoE,CAClI,GAAI,CACF,MAAO,CAAE,MAAO,QAAQ,IAAI,EAAQ,CAAG,EAAG,WAAY,EAAM,CAC9D,MAAQ,CACN,MAAO,CAAE,WAAY,EAAK,CAC5B,CACF,CAOA,SAAgB,EAAuB,EAA0C,CAC/E,IAAM,EAAS,OAAO,GAAU,UAAY,EAAiB,EAA6C,CAAC,EACrG,EAAyD,CAAC,EAC1D,EAAiC,CAAC,EACpC,EAAW,GACf,IAAK,IAAM,KAAO,EAAc,CAC9B,IAAM,EAAO,EAAY,EAAQ,CAAG,EACpC,GAAI,EAAK,WAAY,CACnB,EAAQ,KAAK,CAAG,EAChB,QACF,CACA,IAAM,EAAQ,EAAK,MACf,IAAU,IAAA,KACV,EAAa,CAAK,EAAG,EAAS,GAAO,GAGnC,OAAO,GAAU,UAAY,YAAiC,EAAW,IAC7E,EAAQ,KAAK,CAAG,GAEpB,CAEI,EAAS,cAAgB,IAAA,IAAa,EAAS,cAAgB,IAAA,IAC9D,EAAS,YAAc,EAAS,cACnC,OAAO,EAAS,YAChB,EAAQ,KAAK,aAAa,GAE5B,IAAM,EAAc,EAAS,YAEvB,EAAW,IAAgB,IAAA,GAC7B,IAAA,GACA,OAAO,OAA4B,EAAS,cAAgB,IAAA,GAC1D,CAAE,aAAY,EACd,CAAE,cAAa,YAAa,EAAS,WAAY,CAAC,EACxD,OAAO,OAAO,OAAO,CACnB,GAAI,IAAa,IAAA,GAAY,CAAC,EAAI,CAAE,UAAS,EAC7C,cAAe,OAAO,OAAO,CAAC,GAAG,IAAI,IAAI,CAAO,CAAC,CAAC,EAClD,SAAU,IAAa,IAAA,IAAa,EAAQ,SAAW,GAAK,CAAC,EAC7D,UACF,CAAC,CACH,CAGA,SAAgB,EAAkB,EAAiD,CACjF,OAAO,IAAU,IAAA,IAAa,EAAa,KAAK,GAAO,EAAM,KAAS,IAAA,EAAS,CACjF,CAMA,SAAgB,EAA6B,EAAqB,EAAgD,CAEhH,OADI,GAAoB,EAAU,UAC3B,GAAoB,EAAc,WAAa,SACxD"}

package/dist/embedding/validation.d.ts

@@ -0,0 +1,68 @@
+import { EmbeddingProfile, EmbeddingSpaceId } from "./profile.js";
+import { EmbeddingPurpose } from "./purpose.js";
+import { EmbeddingCapability } from "./catalog.js";
+import { EmbeddingBatchRequest, EmbeddingItem, EmbeddingTruncation } from "./request.js";
+import { EmbeddingBatchResult } from "./result.js";
+import { PreparedEmbeddingCall } from "./adapter.js";
+//#region src/embedding/validation.d.ts
+/**
+ * One `Logical_Call` as it stands just before the first dispatch.
+ *
+ * Deliberately NOT an {@link EmbeddingBatchRequest}: validation runs once per
+ * logical call, over ALL items, before any batch exists.
+ */
+interface PreDispatchRequest {
+  readonly purpose: EmbeddingPurpose;
+  /** Every item of the logical call, in input order. */
+  readonly items: readonly EmbeddingItem[];
+  /** Caller-requested width; absent means the model default. */
+  readonly dimensions?: number;
+  /** Resolved truncation preference. */
+  readonly truncation: EmbeddingTruncation;
+  /** Space the caller demands; incompatibility is a rejection. */
+  readonly expectedSpace?: EmbeddingSpaceId;
+  /**
+   * The profile behind {@link expectedSpace}, when the caller has it.
+   *
+   * Present ⇒ compatibility is decided by {@link isSpaceCompatible}; absent ⇒ by
+   * canonical `Space_Id` equality. Both answer the same question, since the
+   * `Space_Id` is derived from exactly the components that decide compatibility.
+   */
+  readonly expectedProfile?: EmbeddingProfile;
+  /**
+   * Whether the route has a truncation parameter at all.
+   *
+   * `'unsupported'` is the route positively stating the provider exposes no such
+   * parameter, which is the only state that rejects `truncation: 'allow'`.
+   * `'unknown'` never rejects.
+   */
+  readonly truncationSupport?: EmbeddingCapability<boolean>;
+}
+/**
+ * Validates one `Logical_Call` against the SAME `PreparedEmbeddingCall` that will
+ * dispatch it, BEFORE any `Physical_Batch` goes out.
+ *
+ * Every rejection here happens with 0 `Provider_Attempt`. Checks run cheapest
+ * first, so a malformed request never pays for token estimation.
+ *
+ * @param request - the logical call as resolved from the caller.
+ * @param prepared - the generation whose metadata, profile and limits will be used.
+ * @throws EmbeddingError with a code from `EMBEDDING_ERROR_CODES` on any violation.
+ */
+declare function validatePreDispatch(request: PreDispatchRequest, prepared: PreparedEmbeddingCall): void;
+/**
+ * Validates one `Provider_Attempt`'s response against the batch that produced it.
+ *
+ * Order is fixed — count, indexes, values, width, truncation reports — so the
+ * SAME malformed response yields the SAME code across providers, which is what
+ * lets one contract-test suite run against all of them. Nothing here infers or
+ * repairs: a response that breaks the contract is a protocol error.
+ *
+ * @param batch - the physical batch that was dispatched.
+ * @param result - what the adapter parsed out of exactly one provider attempt.
+ * @throws EmbeddingError with a vector- or response-level code on any violation.
+ */
+declare function validateBatchResult(batch: EmbeddingBatchRequest, result: EmbeddingBatchResult): void;
+//#endregion
+export { PreDispatchRequest, validateBatchResult, validatePreDispatch };
+//# sourceMappingURL=validation.d.ts.map

package/dist/embedding/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","names":[],"sources":["../../src/embedding/validation.ts"],"mappings":";;;;;;;;;;;;;UA4CiB;WACN,SAAS;;WAET,gBAAgB;;WAEhB;;WAEA,YAAY;;WAEZ,gBAAgB;;;;;;;;WAQhB,kBAAkB;;;;;;;;WAQlB,oBAAoB;;;;;;;;;;;;;iBAyJf,oBACd,SAAS,oBACT,UAAU;;;;;;;;;;;;;iBAwII,oBACd,OAAO,uBACP,QAAQ"}

package/dist/embedding/validation.js

@@ -0,0 +1,2 @@
+import{EMBEDDING_ERROR_CODES as e,EmbeddingError as t}from"./errors.js";import{isSpaceCompatible as n}from"./profile.js";const r=Object.freeze([`retrieval-query`,`retrieval-document`]);function i(e){let t=``;for(let n of e.contentParts)n.type===`text`&&(t+=n.text);return t}function a(n,i){if(!r.includes(n.purpose))throw new t(`Embedding purpose must be "retrieval-query" or "retrieval-document"`,e.REQUEST_INVALID,d(i))}function o(n,r){if(n.items.length===0)throw new t(`Embedding request carries no input values`,e.REQUEST_INVALID,d(r));let a=[];for(let e of n.items)(e.contentParts.length===0||i(e).length===0)&&a.push(e.index);if(a.length>0)throw new t(`Embedding input is empty at ${a.length} item(s)`,e.REQUEST_INVALID,{...d(r),itemIndexes:a})}function s(n,r){let i=n.dimensions;if(i===void 0)return;if(!Number.isInteger(i)||i<=0)throw new t(`Embedding dimensions must be a positive integer`,e.REQUEST_INVALID,d(r));let a=r.model.dimensions;if(a.state===`supported`&&!a.value.includes(i))throw new t(`Embedding model does not support ${i} dimensions`,e.DIMENSIONS_UNSUPPORTED,d(r))}function c(n,r){let a=r.model.maxInputTokens;if(a.state!==`supported`)return;let o=a.value;if(!Number.isFinite(o)||o<=0)return;let s=[];for(let e of n.items)r.limits.estimateTokens(i(e))>o&&s.push(e.index);if(s.length!==0)throw new t(`Embedding input exceeds the declared limit of ${o} tokens`,e.INPUT_TOO_LARGE,{...d(r),itemIndexes:s,limit:o})}function l(r,i){let a=r.expectedSpace,o=r.expectedProfile;if((a!==void 0||o!==void 0)&&!(o===void 0?a===i.spaceId:n(o,i.profile)))throw new t(`Expected embedding space is incompatible with the prepared call`,e.SPACE_INCOMPATIBLE,{...d(i),space:i.spaceId})}function u(n,r){if(n.truncation===`allow`&&n.truncationSupport?.state===`unsupported`)throw new t(`Provider route exposes no truncation parameter`,e.TRUNCATION_UNSUPPORTED,d(r))}function d(e){return{provider:e.model.provider,model:e.model.id}}function f(e,t){a(e,t),o(e,t),s(e,t),u(e,t),l(e,t),c(e,t)}function p(n,r){if(r.vectors.length!==n.items.length)throw new t(`Provider returned ${r.vectors.length} vectors for ${n.items.length} inputs`,e.VECTOR_COUNT_MISMATCH,{provider:n.provider,model:n.model})}function m(n,r){let i=new Set(n.items.map(e=>e.index)),a=new Set;for(let o of r.vectors){if(!Number.isInteger(o.index)||!i.has(o.index)||a.has(o.index))throw new t(`Provider returned a duplicate, missing or out-of-range vector index`,e.VECTOR_INDEX_INVALID,{provider:n.provider,model:n.model});a.add(o.index)}}function h(n,r){for(let i of r.vectors){if(!Array.isArray(i.values))throw new t(`Provider returned a vector whose values are not an array`,e.RESPONSE_MALFORMED,{provider:n.provider,model:n.model,itemIndexes:[i.index]});for(let r of i.values)if(!(typeof r==`number`&&Number.isFinite(r)))throw new t(`Provider returned a vector containing a non-finite value`,e.VECTOR_VALUE_INVALID,{provider:n.provider,model:n.model,itemIndexes:[i.index]})}}function g(n,r){let i=n.dimensions;if(i!==void 0){for(let a of r.vectors)if(a.values.length!==i)throw new t(`Provider returned a ${a.values.length}-dimensional vector, expected ${i}`,e.VECTOR_DIMENSIONS_MISMATCH,{provider:n.provider,model:n.model,itemIndexes:[a.index],limit:i})}}function _(n,r){if(n.truncation!==`reject`)return;let i=r.vectors.filter(e=>e.truncated===!0);if(i.length!==0)throw new t(`Provider reported truncation although truncation was rejected`,e.RESPONSE_MALFORMED,{provider:n.provider,model:n.model,itemIndexes:i.map(e=>e.index)})}function v(e,t){p(e,t),m(e,t),h(e,t),g(e,t),_(e,t)}export{v as validateBatchResult,f as validatePreDispatch};
+//# sourceMappingURL=validation.js.map