@ultimat3/ai 19.2.0 → 19.3.1

package/CLAUDE.md

@@ -249,6 +249,14 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
   closes, so nothing partial reaches a caller.
 - Thinking chunks are never appended to `text`. A consumer concatenating every chunk must not
   end up shipping the reasoning to the user.
+- **`embedBatched` enforces the `Embedder` arity, per batch** (`As of 2026-09`). "One vector per
+  input text, in the order the texts arrived" is the interface's own invariant and nothing
+  downstream can restore it: `indexDocument` writes `vectors[index]` per chunk, so an app embedder
+  that answered short stored `undefined` and surfaced a layer later as a `TypeError` inside the
+  vector store, naming nothing an author wrote. `X_AI_EMBEDDER_INVALID` — the shipped code whose
+  registered title already read "an Embedder returned fewer vectors than texts it was given" — now
+  carries the two counts in its cause and `meta`. `RemoteEmbedder.decode` refuses its own provider
+  on the same rule; an app's own `Embedder` was the unchecked half.
 - One `RemoteEmbedder` for every vendor: `baseUrl` selects the provider, the wire shape is the
   same. Vectors are L2-normalised on arrival so `cosine` stays a dot product, and a width other
   than the declared one is `X_VECTOR_DIM_MISMATCH` before anything reaches a store.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ai",
-  "version": "19.2.0",
+  "version": "19.3.1",
   "description": "LLM gateway, versioned prompts, evals as tests, embeddings, hybrid vector search, RAG",
   "license": "MIT",
   "type": "module",
@@ -32,14 +32,14 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "19.2.0",
-    "@ultimat3/cache": "19.2.0",
-    "@ultimat3/core": "19.2.0",
-    "@ultimat3/db": "19.2.0",
-    "@ultimat3/jobs": "19.2.0",
-    "@ultimat3/money": "19.2.0",
-    "@ultimat3/policy": "19.2.0",
-    "@ultimat3/schema": "19.2.0",
-    "@ultimat3/time": "19.2.0"
+    "@ultimat3/action": "19.3.1",
+    "@ultimat3/cache": "19.3.1",
+    "@ultimat3/core": "19.3.1",
+    "@ultimat3/db": "19.3.1",
+    "@ultimat3/jobs": "19.3.1",
+    "@ultimat3/money": "19.3.1",
+    "@ultimat3/policy": "19.3.1",
+    "@ultimat3/schema": "19.3.1",
+    "@ultimat3/time": "19.3.1"
   }
 }

package/src/embeddings.ts

@@ -40,7 +40,22 @@ export async function embedBatched(
   finiteCount('embedBatched', 'size', size, 1);
   const out: Float32Array[] = [];
   for (let i = 0; i < texts.length; i += size) {
-    out.push(...(await embedder.embed(texts.slice(i, i + size))));
+    const batch = texts.slice(i, i + size);
+    const vectors = await embedder.embed(batch);
+    // "One vector per input text, in the order the texts arrived" is this interface's invariant,
+    // and it is the last place it can be checked: `indexDocument` writes `vectors[index]` per
+    // chunk, so a short answer stored `undefined` as a row and surfaced a layer later as a
+    // `TypeError` inside the vector store, naming nothing the app author wrote.
+    // `RemoteEmbedder.decode` already refuses its own provider on the same rule — an app's own
+    // `Embedder` was the unchecked half.
+    if (vectors.length !== batch.length) {
+      throw new AiEmbedderInvalidError({
+        embedder: embedder.name,
+        expected: batch.length,
+        received: vectors.length,
+      });
+    }
+    out.push(...vectors);
   }
   return out;
 }

package/src/errors.ts

@@ -374,20 +374,31 @@ export class EmbedderDimMismatchError extends UltimateError {
 }
 
 /**
- * `embedOne` asked an `Embedder` for one vector and got none back — a batch-size invariant the
- * embedder itself broke, not a caller mistake. Distinct from `X_VECTOR_DIM_MISMATCH`: this fires
- * before there is a vector at all, so there is nothing yet to measure the width of.
+ * An `Embedder` answered fewer vectors than it was given texts — a batch invariant the embedder
+ * itself broke, not a caller mistake. Distinct from `X_VECTOR_DIM_MISMATCH`: this fires before
+ * there is a vector at all, so there is nothing yet to measure the width of.
+ *
+ * The counts are optional because `embedOne` has nothing to report beyond "none for one", and its
+ * cause has always read that way; `embedBatched` knows both numbers and states them.
  */
 export class AiEmbedderInvalidError extends UltimateError {
-  constructor(input: { embedder: string }) {
+  constructor(input: { embedder: string; expected?: number; received?: number }) {
+    const counted =
+      input.expected === undefined || input.received === undefined
+        ? 'no vector for a batch of one text'
+        : `${input.received} vectors for a batch of ${input.expected} texts`;
     super({
       code: 'X_AI_EMBEDDER_INVALID',
-      cause: `embedder "${input.embedder}" returned no vector for a batch of one text`,
+      cause: `embedder "${input.embedder}" returned ${counted}`,
       // The `${…}` the fix used to carry is unreadable to the `errors` gate, which blanks every
       // interpolation — so the literal half alone has to name the call. Which embedder broke the
       // invariant is a fact of the failure, and the cause and `meta` are where facts live.
       fix: 'return one vector per input text from embed(), in the order the texts arrived',
-      meta: { embedder: input.embedder },
+      meta: {
+        embedder: input.embedder,
+        ...(input.expected === undefined ? {} : { expected: input.expected }),
+        ...(input.received === undefined ? {} : { received: input.received }),
+      },
     });
   }
 }

package/src/pg-vector-sql.ts

@@ -197,6 +197,10 @@ export function deleteSql(
   scope: VectorScope,
   ids: readonly string[],
 ): SqlFragment {
+  // `in ()` is a syntax error, so an empty list takes the same constant an empty allow-list does.
+  // `PgVectorStore.delete` returns before it gets here, but this function is exported from
+  // `index.ts` — an app compiling the statement itself is a caller too.
+  const byId = ids.length === 0 ? NEVER : sql`"id" in (${join(ids.map((id) => sql`${id}`))})`;
   return sql`delete from ${identifier(target.table)}
-where "id" in (${join(ids.map((id) => sql`${id}`))}) and ${conditionsSql(scope)}`;
+where ${byId} and ${conditionsSql(scope)}`;
 }

package/src/rag.ts

@@ -168,6 +168,9 @@ export async function indexDocument(input: {
   await input.store.upsert(
     chunks.map((c, index) => ({
       id: c.id,
+      // The cast is sound because `embedBatched` refuses an embedder that answered fewer vectors
+      // than it was given texts (`X_AI_EMBEDDER_INVALID`) — without that check this wrote
+      // `undefined` and failed a layer later inside the store, naming nothing an author wrote.
       vector: vectors[index] as Float32Array,
       text: c.text,
       metadata: c.metadata,

package/src/scorers.ts

@@ -70,7 +70,12 @@ export function jsonSchemaValid(required: readonly string[]): Scorer {
       }
       if (typeof parsed !== 'object' || parsed === null) return 0;
       const record = parsed as Record<string, unknown>;
-      const present = required.filter((key) => record[key] !== undefined).length;
+      // `Object.hasOwn`, never `record[key] !== undefined`: the keys are the CALLER's and the
+      // object is a `JSON.parse` result carrying `Object.prototype`, so the index read answered
+      // "present" for `constructor`, `toString`, `valueOf` and `hasOwnProperty` — a full 1 out of
+      // the scorer whose job is saying the answer holds none of them. It also read a declared
+      // `null` as absent, which is the same mistake pointing the other way.
+      const present = required.filter((key) => Object.hasOwn(record, key)).length;
       return required.length === 0 ? 1 : present / required.length;
     },
   };

package/src/wire.ts

@@ -281,8 +281,14 @@ export class MessageStream {
 
   private onMessageDelta(payload: Record<string, unknown>): readonly StreamChunk[] {
     const delta = asRecord(payload['delta']);
-    if (delta !== undefined && delta['stop_reason'] !== null) {
-      this.stopReason = parseStopReason(delta['stop_reason']);
+    // ABSENT is not a report, and neither is `null`. `!== null` alone admitted the absent key, so
+    // a `message_delta` carrying only running usage ran `parseStopReason(undefined)` — which
+    // answers `end_turn` — and rewrote a refusal already reported as a clean finish, erasing its
+    // `stopDetails` with it. `openai-wire.ts`'s `onFinish` returns early on `undefined` for the
+    // same reason; this was the copy that did not.
+    const reported = delta?.['stop_reason'];
+    if (delta !== undefined && reported !== null && reported !== undefined) {
+      this.stopReason = parseStopReason(reported);
       // A refusal mid-stream keeps whatever was already streamed, so the reason alone reads as
       // a complete answer that simply stopped. The detail is what says it is not one.
       this.stopDetails = parseStopDetails(delta['stop_details']);