@ultimat3/ai 23.0.0 → 25.0.0

package/src/scorers.ts

@@ -4,7 +4,7 @@
 // is a model call, which means it is itself a measuring instrument that can drift — so its
 // prompt is a versioned artifact and its hash is part of the scorer's name.
 
-import { finiteCount } from '@ultimat3/core';
+import { assert, finiteCount, finiteOption } from '@ultimat3/core';
 import type { Gateway } from './gateway';
 import type { Prompt } from './prompt';
 
@@ -81,8 +81,17 @@ export function jsonSchemaValid(required: readonly string[]): Scorer {
   };
 }
 
-/** Graded numeric closeness — 1 at exact, 0 at or beyond `tolerance`. */
+/**
+ * Graded numeric closeness — 1 at exact, 0 at or beyond `tolerance`. `tolerance: 0` is exact match.
+ * Screened at declaration: a `NaN` scored every answer `NaN`, a negative one every answer 0.
+ */
 export function numericTolerance(tolerance: number): Scorer {
+  finiteOption('numericTolerance', 'tolerance', tolerance);
+  assert(
+    tolerance >= 0,
+    `numericTolerance tolerance is ${String(tolerance)}: a distance cannot be negative, so every answer would score 0`,
+    'numericTolerance(0)   # 0 is exact match; a positive tolerance grades closeness',
+  );
   return {
     name: 'numeric-tolerance',
     score: ({ output, expected }) => {
@@ -90,6 +99,8 @@ export function numericTolerance(tolerance: number): Scorer {
       const want = Number.parseFloat((expected ?? '').trim());
       if (Number.isNaN(got) || Number.isNaN(want)) return 0;
       const delta = Math.abs(got - want);
+      // Exact first: at `tolerance: 0`, `0 >= 0` read an exact match as out of range.
+      if (delta === 0) return 1;
       return delta >= tolerance ? 0 : 1 - delta / tolerance;
     },
   };
@@ -121,7 +132,7 @@ export function llmJudge(input: {
         maxTokens: finiteCount('llmJudge', 'maxTokens', input.maxTokens ?? 256, 1),
         ...(input.judge.system !== undefined ? { system: input.judge.system } : {}),
         ...(input.judge.model !== undefined ? { model: input.judge.model } : {}),
-        // The judge prompt's hash is this scorer's NAME, and `contentHash` covers `effort` and
+        // The judge prompt's hash is this scorer's NAME, and `promptHash` covers `effort` and
         // `thinking` — so dropping either measures with a judge the name does not describe.
         ...(input.judge.effort !== undefined ? { effort: input.judge.effort } : {}),
         ...(input.judge.thinking !== undefined ? { thinking: input.judge.thinking } : {}),

package/src/tool-idempotency.ts

@@ -0,0 +1,79 @@
+// The in-app half of `idempotent: true`: an agent's tool carries the reserved `idempotencyKey`
+// argument exactly as `@ultimat3/mcp`'s does, so an action an external agent may retry safely is
+// one an in-app agent may retry safely too. Restated, not imported — `mcp` is this package's own
+// tier — and held equal to `mcp/src/idempotency-arg.ts` by `scripts/ai-mcp-tool-parity.test.ts`.
+
+import { MAX_IDEMPOTENCY_KEY_LENGTH } from '@ultimat3/action';
+import { UltimateError } from '@ultimat3/core';
+import type { JsonSchema } from './tools';
+
+/** The reserved argument name on every idempotent action's tool — the one MCP reserves. */
+export const TOOL_IDEMPOTENCY_KEY_ARG = 'idempotencyKey';
+
+/** Contract text, byte-identical to MCP's: it is what the model reads on either surface. */
+const DESCRIPTION =
+  'Idempotency key. Retrying this call with the same key and the same arguments returns the ' +
+  'first result instead of running it again; the same key with different arguments is refused. ' +
+  'Any unique string, e.g. a UUID — reuse it only to retry.';
+
+const KEY_SCHEMA: JsonSchema = {
+  type: 'string',
+  description: DESCRIPTION,
+  minLength: 1,
+  maxLength: MAX_IDEMPOTENCY_KEY_LENGTH,
+};
+
+/**
+ * MCP's own refusal, raised for the same tool: an agent tool is an MCP-exposed action by
+ * construction (`X_AGENT_TOOL_UNEXPOSED`), so this is the projection `@ultimat3/mcp` refuses too,
+ * and one code for it on both surfaces is the parity. Never titled here — `mcp` registers it.
+ */
+export class ToolIdempotencyKeyShadowedError extends UltimateError {
+  constructor(input: { readonly name: string; readonly argument: string }) {
+    super({
+      code: 'X_MCP_IDEMPOTENCY_KEY_SHADOWED',
+      cause: `${input.name} is idempotent and its input declares "${input.argument}", the MCP argument reserved for the idempotency key`,
+      fix: `rename ${input.name}'s "${input.argument}" input field — MCP clients send the Idempotency-Key as the reserved "${input.argument}" argument, and the action receives the rest`,
+      meta: { action: input.name, argument: input.argument },
+    });
+  }
+}
+
+/** `schema` with the optional key argument; a non-object input is left alone, a clash refused. */
+export function withToolIdempotencyKey(name: string, schema: JsonSchema): JsonSchema {
+  if (schema.type !== 'object') return schema;
+  const properties = schema.properties ?? {};
+  if (Object.hasOwn(properties, TOOL_IDEMPOTENCY_KEY_ARG)) {
+    throw new ToolIdempotencyKeyShadowedError({ name, argument: TOOL_IDEMPOTENCY_KEY_ARG });
+  }
+  return { ...schema, properties: { ...properties, [TOOL_IDEMPOTENCY_KEY_ARG]: KEY_SCHEMA } };
+}
+
+/**
+ * The model's arguments split into the action's input and the key. No key is an un-keyed run, as
+ * HTTP without the header; a non-string is no key. A blank or over-long one goes to `invoke`, whose
+ * `X_IDEMPOTENCY_KEY_INVALID` the model reads as a tool error naming the bound.
+ */
+export function takeToolIdempotencyKey(args: unknown): {
+  readonly input: unknown;
+  readonly idempotencyKey: string | null;
+} {
+  if (typeof args !== 'object' || args === null || Array.isArray(args)) {
+    return { input: args, idempotencyKey: null };
+  }
+  if (!Object.hasOwn(args, TOOL_IDEMPOTENCY_KEY_ARG)) return { input: args, idempotencyKey: null };
+  const input: Record<string, unknown> = {};
+  let key: unknown;
+  for (const [field, value] of Object.entries(args)) {
+    if (field === TOOL_IDEMPOTENCY_KEY_ARG) key = value;
+    // defineProperty, never `input[field] =`: a `__proto__` field would re-prototype the copy.
+    else
+      Object.defineProperty(input, field, {
+        value,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      });
+  }
+  return { input, idempotencyKey: typeof key === 'string' ? key : null };
+}

package/src/tools.ts

@@ -6,8 +6,9 @@
 // permissions" concept in Ultimate, because there is no second authz system.
 //
 // `run` below is `ProjectableAction`'s — the projection SEAM, which is what carries `invoke`.
-// It is not a member of the action facade: an `action()` is `as`/`tool`/`openapi`/`job`/
-// `contract` and the callable itself, and this header claimed `action.run` until 2026-08.
+// It is not a member of the action facade: an `action()` is `as`/`openapi`/`client`/`job`/
+// `contract` and the callable itself (no `tool` since 25.0.0 — `@ultimat3/mcp`'s `toolFrom` is
+// the MCP projection), and this header claimed `action.run` until 2026-08.
 // `asProjectableAction` is what BUILDS that seam out of a real `action()`, so an app writes
 // `agent({ tools: [publishPost] })` and never a hand-shaped stand-in — the same union
 // @ultimat3/mcp's `ListedPrimitive` accepts, adapted at this package's own edge because the two
@@ -20,21 +21,17 @@
 import type { AnyAction } from '@ultimat3/action';
 import { actionName, invoke, isAction } from '@ultimat3/action';
 import type { Actor } from '@ultimat3/core';
-import { isMcpExposed, stringField } from '@ultimat3/core';
-import { toMcpInputSchema } from '@ultimat3/schema';
+import { isMcpExposed, tryUseContext } from '@ultimat3/core';
+import type { WireJsonSchema } from '@ultimat3/schema';
+import { toWireSchema } from '@ultimat3/schema';
+import { discloseFailure } from './failure-disclosure';
+import { takeToolIdempotencyKey, withToolIdempotencyKey } from './tool-idempotency';
 
-/** The JSON Schema subset the framework emits for tool arguments. */
-export interface JsonSchema {
-  readonly type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'null';
-  readonly description?: string;
-  readonly properties?: Readonly<Record<string, JsonSchema>>;
-  readonly required?: readonly string[];
-  /** A schema, not just a flag: `@ultimat3/schema` emits one for open records. */
-  readonly additionalProperties?: boolean | JsonSchema;
-  readonly items?: JsonSchema;
-  readonly enum?: readonly (string | number | boolean | null)[];
-  readonly default?: unknown;
-}
+/**
+ * The JSON Schema subset the framework emits for tool arguments — `@ultimat3/schema`'s
+ * `WireJsonSchema`, the one document `toolFrom`, `tools/list` and the model are all handed.
+ */
+export type JsonSchema = WireJsonSchema;
 
 /** Anthropic Messages API tool definition shape (`tools[]` on a request). */
 export interface LlmTool {
@@ -80,7 +77,7 @@ export interface ProjectableAction {
  *
  * The real `action()` comes first because it is what an app has. Until 2026-08 this list took
  * `ProjectableAction` alone, which no `action()` structurally satisfies — an action carries
- * `as`/`tool`/`openapi`/`job`/`contract` and never `run` — so the documented shape
+ * `as`/`openapi`/`client`/`job`/`contract` and never `run` — so the documented shape
  * `agent({ tools: [publishPost] })` was a `TS2741` and every test in this package hand-built a
  * stand-in, which is why the suite stayed green over an API that did not compile (issue #124).
  * `ProjectableAction` stays in the union for a surface that builds its catalog programmatically
@@ -89,12 +86,10 @@ export interface ProjectableAction {
 export type AgentTool = AnyAction | ProjectableAction;
 
 /**
- * Adapt whatever the author listed. The same shape @ultimat3/mcp's `asProjectable` produces, from
- * the same `invoke` — an in-app agent and an external MCP client end at one execution path, so one
- * policy decides both. It is not shared code and cannot be: `mcp` is this package's own tier, and
- * the two projections narrow the schema differently on purpose (`toWireSchema` publishes only what
- * that server's arg validator will hold a call to; this one publishes the tool schema the Messages
- * API reads).
+ * Adapt whatever the author listed. The same shape @ultimat3/mcp's `primitiveFromAction` produces,
+ * from the same `invoke` — an in-app agent and an external MCP client end at one execution path, so one
+ * policy decides both. The execution adapter is not shared code and cannot be — `mcp` is this
+ * package's own tier — but the schema is: both publish `@ultimat3/schema`'s `toWireSchema`.
  *
  * `isAction` is structural against @ultimat3/action's PRIVATE declaration store, so a look-alike
  * carrying `kind: 'action'` cannot take the first branch — it falls through as the already
@@ -103,17 +98,30 @@ export type AgentTool = AnyAction | ProjectableAction;
 export function asProjectableAction(listed: AgentTool): ProjectableAction {
   if (!isAction(listed)) return listed;
   const mcp = listed.mcp;
+  // Throws `X_ACTION_UNREGISTERED` on an unnamed action rather than offering a tool called `''`:
+  // a nameless tool is unaddressable by the model, by `runLlmToolCall` and by the author.
+  const name = actionName(listed);
+  const wire = toWireSchema(listed.input);
+  // `idempotent: true` is honoured here as over MCP and HTTP: the model's key reaches `invoke`,
+  // which files it under the action, the caller and the key. Until 25.0.0 this adapter dropped it,
+  // so an action an external agent could retry safely was one an in-app agent could not.
+  const keyed = listed.describe().idempotent;
   return {
-    // Throws `X_ACTION_UNREGISTERED` on an unnamed action rather than offering a tool called `''`:
-    // a nameless tool is unaddressable by the model, by `runLlmToolCall` and by the author.
-    name: actionName(listed),
+    name,
     ...(mcp === undefined ? {} : { mcp }),
     ...(mcp?.description === undefined ? {} : { description: mcp.description }),
-    inputJsonSchema: toMcpInputSchema(listed.input),
+    inputJsonSchema: keyed ? withToolIdempotencyKey(name, wire) : wire,
     // The actor rides in on the options and `invoke` swaps it inside the one execution path —
     // the action's own `policy` still decides, and its `input:` still parses what the model sent,
     // which is what drops a `{ actor: 'admin' }` the model invented before any handler sees it.
-    run: ({ input, actor }) => invoke(listed, input, { surface: 'mcp', actor }),
+    // No `admit`: MCP's is its early gate ahead of ITS argument validation, and this surface has
+    // none — `invoke` asks the same policy before it reads the input, which is the same order.
+    run: keyed
+      ? ({ input: args, actor }) => {
+          const { input, idempotencyKey } = takeToolIdempotencyKey(args);
+          return invoke(listed, input, { surface: 'mcp', actor, idempotencyKey });
+        }
+      : ({ input, actor }) => invoke(listed, input, { surface: 'mcp', actor }),
   };
 }
 
@@ -169,7 +177,7 @@ export async function runLlmToolCall(
     return resultOf(call.id, output);
   } catch (error) {
     // A policy denial is an outcome the model should read and react to, not a crash.
-    return { toolUseId: call.id, content: describeFailure(error), isError: true };
+    return { toolUseId: call.id, content: describeFailure(error, call.name), isError: true };
   }
 }
 
@@ -198,15 +206,20 @@ function resultOf(toolUseId: string, output: unknown): LlmToolResult {
 }
 
 /**
- * The thrown value, read STRUCTURALLY and totally. `stringField` from `@ultimat3/core`, never
- * `typeof e.code === 'string'`: the value is whatever an app's handler, its driver or its SDK
- * threw, so each read is a getter call or a `Proxy` trap — and it runs inside the catch block
- * that has nothing left to answer the model with if the probe itself raises.
+ * What the model reads in place of a cause it may not see. Fixed, so nothing of the throw rides on
+ * it: the provider keeps every request it is sent, and a cause that reached it cannot be recalled.
+ */
+export const HIDDEN_TOOL_CAUSE =
+  'the tool failed inside the server; the details are withheld from this conversation; the server log records its code and where it failed';
+
+/**
+ * `discloseFailure`'s verdict, rendered as the `tool_result` line — the same rule a hive member's
+ * reason follows, so what an agent may read of a throw is decided once. An uncoded throw says only
+ * that it failed; a withheld cause becomes `HIDDEN_TOOL_CAUSE`, and the log has the rest.
  */
-function describeFailure(error: unknown): string {
-  const code = stringField(error, 'code');
-  if (code === undefined) return 'tool failed';
-  const cause = stringField(error, 'cause') ?? 'unknown';
-  const fix = stringField(error, 'fix') ?? '';
-  return fix === '' ? `${code}: ${cause}` : `${code}: ${cause} (fix: ${fix})`;
+function describeFailure(error: unknown, toolName: string): string {
+  const shown = discloseFailure(error, tryUseContext()?.logger, `tool ${toolName}`);
+  if (shown.code === undefined) return 'tool failed';
+  const line = `${shown.code}: ${shown.cause ?? HIDDEN_TOOL_CAUSE}`;
+  return shown.fix === undefined ? line : `${line} (fix: ${shown.fix})`;
 }

package/src/vector-scope.ts

@@ -4,6 +4,7 @@
 // production is a leak nobody finds. Deriving a scope may only ever TIGHTEN it: a scope that
 // could be widened from a call site is not a scope, it is a hint.
 
+import { tryUseContext, UltimateError } from '@ultimat3/core';
 import { VectorScopeWidenedError } from './errors';
 
 export interface VectorScope {
@@ -14,16 +15,28 @@ export interface VectorScope {
    * deny — a row missing the key is invisible, and an empty list matches nothing at all.
    */
   readonly allow?: Readonly<Record<string, readonly string[]>> | undefined;
+  /**
+   * Every tenant, ON PURPOSE — `UNSCOPED`'s mark, and the only way a read with no tenant bound
+   * runs inside a request acting for an org. Meaningless once a tenant is bound, so dropped then.
+   */
+  readonly crossTenant?: true | undefined;
 }
 
-/** The store as constructed: every tenant, every row. The backfill and migration path. */
-export const UNSCOPED: VectorScope = Object.freeze({});
+/**
+ * Every tenant, every row, named on purpose: the backfill and migration path. Pass it as a
+ * store's `scope` (or `.scoped(UNSCOPED)`) where a cross-tenant read is the point. A store opened
+ * with no scope binds no tenant either, but reading it inside an org's request is refused.
+ */
+export const UNSCOPED: VectorScope = Object.freeze({ crossTenant: true });
+
+/** A store's scope when none was given: no tenant, and no cross-tenant opt-in. */
+export const UNBOUND: VectorScope = Object.freeze({});
 
 /** The tenant column value a row carries when its store had no tenant bound. */
-export const NO_TENANT = '';
+export const NO_VECTOR_TENANT = '';
 
 export function tenantOf(scope: VectorScope): string {
-  return scope.tenant ?? NO_TENANT;
+  return scope.tenant ?? NO_VECTOR_TENANT;
 }
 
 /**
@@ -33,12 +46,41 @@ export function tenantOf(scope: VectorScope): string {
 export function narrowScope(store: string, base: VectorScope, next: VectorScope): VectorScope {
   const tenant = narrowTenant(store, base.tenant, next.tenant);
   const allow = narrowAllow(base.allow, next.allow);
+  const crossTenant =
+    tenant === undefined && (base.crossTenant === true || next.crossTenant === true);
   return {
     ...(tenant === undefined ? {} : { tenant }),
     ...(allow === undefined ? {} : { allow }),
+    ...(crossTenant ? { crossTenant: true as const } : {}),
   };
 }
 
+/**
+ * Refuse a read that would search every tenant inside a request acting for one. Entities derive
+ * the tenant from the ambient actor; a vector store is bound by `.scoped({ tenant })`, and a
+ * forgotten call answered with every org's rows. Outside a request, or for an actor with no org,
+ * there is no tenant to leak across — a single-tenant app and a job's system actor read as before.
+ */
+export function assertTenantRead(store: string, scope: VectorScope): void {
+  if (scope.tenant !== undefined || scope.crossTenant === true) return;
+  if (tryUseContext()?.actor.orgId === undefined) return;
+  throw new VectorUnscopedError({ store });
+}
+
+/** `X_VECTOR_UNSCOPED`. Its code and title stay in `errors.ts`, beside every other `X_VECTOR_*`. */
+export class VectorUnscopedError extends UltimateError {
+  constructor(input: { store: string }) {
+    super({
+      code: 'X_VECTOR_UNSCOPED',
+      cause:
+        `vector store "${input.store}" was read with no tenant bound, inside a request acting ` +
+        'for an org — the read would answer with every tenant’s rows. A deliberate cross-tenant ' +
+        'read (a backfill, a migration) opens the store with scope: UNSCOPED',
+      fix: 'vectorStore.scoped({ tenant: ctx.actor.orgId })',
+    });
+  }
+}
+
 function narrowTenant(
   store: string,
   base: string | undefined,

package/src/vector.ts

@@ -1,5 +1,5 @@
 // Vector storage and retrieval: the `VectorStore` contract and the in-memory dev store.
-// `PgVectorStore` — the production path — implements this same contract in `pg-vector.ts`.
+// `PostgresVectorStore` — the production path — implements this same contract in `pg-vector.ts`.
 //
 // The store interface is shaped for pgvector (one table, one index, SQL you can read), with
 // an in-memory cosine implementation as the dev default. Hybrid search is first-class rather
@@ -9,9 +9,16 @@
 // be comparable — which they never are.
 
 import { finiteCount, finiteOption } from '@ultimat3/core';
-import { cosine, tokenize } from './embeddings';
+import { cosine, wordTokens } from './embeddings';
 import { VectorDimMismatchError } from './errors';
-import { NO_TENANT, narrowScope, scopeAdmits, UNSCOPED, type VectorScope } from './vector-scope';
+import {
+  assertTenantRead,
+  NO_VECTOR_TENANT,
+  narrowScope,
+  scopeAdmits,
+  UNBOUND,
+  type VectorScope,
+} from './vector-scope';
 
 export interface VectorRecord {
   readonly id: string;
@@ -44,7 +51,7 @@ export interface HybridSearchInput {
 export interface VectorStore {
   readonly name: string;
   readonly dimension: number;
-  /** The tenant + policy envelope every statement carries. `UNSCOPED` on a fresh store. */
+  /** The tenant + policy envelope every statement carries. `UNBOUND` on a fresh store. */
   readonly scope: VectorScope;
   /** A view of the same rows through a NARROWER envelope. It can only ever tighten. */
   scoped(scope: VectorScope): VectorStore;
@@ -56,10 +63,10 @@ export interface VectorStore {
   /**
    * Delete every row `filter` matches EXCEPT the ids in `keep`, inside this store's scope. What a
    * re-index needs: `indexDocument` upserts a document's new chunks, then prunes the ones the
-   * shorter text no longer produced. Optional so a hand-written store still satisfies the type;
-   * without it a re-index cannot clean up, and says so in `indexDocument`'s doc.
+   * shorter text no longer produced. Required: an optional `prune` was a re-index that silently
+   * left the old tail retrievable on any store that skipped it.
    */
-  prune?(filter: MetadataFilter, keep: readonly string[]): Promise<void>;
+  prune(filter: MetadataFilter, keep: readonly string[]): Promise<void>;
 }
 
 export interface MemoryVectorStoreInput {
@@ -88,6 +95,15 @@ export interface StoredRecord extends VectorRecord {
   readonly tenant: string;
 }
 
+/** The row's primary key, `(tenant, id)` as the pg table declares it. NUL never occurs in a tenant. */
+const storageKey = (tenant: string, id: string): string => `${tenant}\u0000${id}`;
+
+/** A row and its score inside one ranking, before the tenant is dropped from the public hit. */
+interface Scored {
+  readonly record: StoredRecord;
+  readonly score: number;
+}
+
 export class MemoryVectorStore implements VectorStore {
   readonly name: string;
   readonly dimension: number;
@@ -101,7 +117,7 @@ export class MemoryVectorStore implements VectorStore {
     this.input = input;
     this.name = input.name ?? 'memory';
     this.dimension = input.dimension;
-    this.scope = input.scope ?? UNSCOPED;
+    this.scope = input.scope ?? UNBOUND;
     this.records = input.records ?? new Map<string, StoredRecord>();
     // Screened, not clamped: a `NaN` here makes every BM25 score `NaN`, `hit.score > 0` reads
     // false for every document, and `searchText` answers an empty list — zero work reported as a
@@ -112,7 +128,7 @@ export class MemoryVectorStore implements VectorStore {
   }
 
   /**
-   * Same envelope, same rule as `PgVectorStore.scoped`. The dev store enforces it too, because
+   * Same envelope, same rule as `PostgresVectorStore.scoped`. The dev store enforces it too, because
    * a tenant leak that only reproduces against production Postgres is a leak nobody finds.
    */
   scoped(scope: VectorScope): MemoryVectorStore {
@@ -124,10 +140,10 @@ export class MemoryVectorStore implements VectorStore {
   }
 
   async upsert(records: readonly VectorRecord[]): Promise<void> {
-    const tenant = this.scope.tenant ?? NO_TENANT;
+    const tenant = this.scope.tenant ?? NO_VECTOR_TENANT;
     for (const record of records) {
       this.assertDimension(record.vector.length);
-      this.records.set(`${tenant}\u0000${record.id}`, { ...record, tenant });
+      this.records.set(storageKey(tenant, record.id), { ...record, tenant });
     }
   }
 
@@ -136,13 +152,13 @@ export class MemoryVectorStore implements VectorStore {
     k: number,
     filter?: MetadataFilter,
   ): Promise<readonly SearchHit[]> {
+    assertTenantRead(this.name, this.scope);
     this.assertDimension(vector.length);
     // `k` carries no default, so `??` never sees it and nothing else does either: `slice(0, NaN)`
     // is `[]`, which is a search that answers "no matches" for every query and reports success.
-    return this.candidates(filter)
-      .map((record) => this.hit(record, cosine(vector, record.vector)))
-      .sort(byScoreDesc)
-      .slice(0, finiteCount(SUBJECT, 'k', k));
+    return this.dense(vector, finiteCount(SUBJECT, 'k', k), filter).map(({ record, score }) =>
+      this.hit(record, score),
+    );
   }
 
   /** BM25 over the stored text. Real lexical scoring, so a rare exact term actually wins. */
@@ -151,12 +167,67 @@ export class MemoryVectorStore implements VectorStore {
     k: number,
     filter?: MetadataFilter,
   ): Promise<readonly SearchHit[]> {
-    const width = finiteCount(SUBJECT, 'k', k);
+    assertTenantRead(this.name, this.scope);
+    return this.lexical(query, finiteCount(SUBJECT, 'k', k), filter).map(({ record, score }) =>
+      this.hit(record, score),
+    );
+  }
+
+  /**
+   * Reciprocal-rank fusion. Each ranking contributes `1 / (rrfK + rank)`, so only ORDER
+   * matters — the two score scales never have to be reconciled, and a document ranked first
+   * by exact term match beats one that merely leads a flat vector ranking.
+   *
+   * Fused on the stored `(tenant, id)`, as `hybridSql` groups: an unscoped read sees every
+   * tenant's rows, and two tenants may share an id. Fusing on the id alone summed both rows'
+   * ranks into whichever came first and dropped the other. `fuse` keys on `SearchHit.id`, so the
+   * rankings reach it under the row's storage key and leave under the caller's id again.
+   */
+  async hybrid(input: HybridSearchInput): Promise<readonly SearchHit[]> {
+    assertTenantRead(this.name, this.scope);
+    this.assertDimension(input.vector.length);
+    // Three bounds, none of which `Math.max` screens — it PROPAGATES a `NaN`. A `NaN` `k` collapses
+    // both candidate widths and the final slice to `[]`; a `NaN` `rrfK` makes every fused score
+    // `NaN`, and the ranking this method exists to produce becomes whatever order the sort left.
+    const k = finiteCount(HYBRID, 'k', input.k);
+    const width = finiteCount(HYBRID, 'candidates', input.candidates ?? Math.max(k * 4, 20));
+    const rrfK = finiteOption(HYBRID, 'rrfK', input.rrfK ?? 60);
+    const rows = new Map<string, StoredRecord>();
+    const keyed = (ranking: readonly Scored[]): readonly SearchHit[] =>
+      ranking.map(({ record, score }) => {
+        const key = storageKey(record.tenant, record.id);
+        rows.set(key, record);
+        return { ...this.hit(record, score), id: key };
+      });
+    const fused = fuse(
+      [
+        keyed(this.dense(input.vector, width, input.filter)),
+        keyed(this.lexical(input.query, width, input.filter)),
+      ],
+      rrfK,
+    );
+    // Re-sorted once the ids are the caller's again: the tie-break is `d."id" asc`, never the key.
+    return fused
+      .map((hit) => ({ ...hit, id: rows.get(hit.id)?.id ?? hit.id }))
+      .sort(byScoreDesc)
+      .slice(0, k);
+  }
+
+  /** The cosine ranking `search` answers and `hybrid` fuses, rows still carrying their tenant. */
+  private dense(vector: Float32Array, k: number, filter?: MetadataFilter): readonly Scored[] {
+    return this.candidates(filter)
+      .map((record) => ({ record, score: cosine(vector, record.vector) }))
+      .sort(byRankDesc)
+      .slice(0, k);
+  }
+
+  /** BM25 over the stored text, rows still carrying their tenant. Only a positive score matches. */
+  private lexical(query: string, width: number, filter?: MetadataFilter): readonly Scored[] {
     const candidates = this.candidates(filter);
     if (candidates.length === 0) return [];
-    const docs = candidates.map((record) => ({ record, tokens: tokenize(record.text) }));
+    const docs = candidates.map((record) => ({ record, tokens: wordTokens(record.text) }));
     const avgLength = docs.reduce((sum, d) => sum + d.tokens.length, 0) / docs.length;
-    const terms = [...new Set(tokenize(query))];
+    const terms = [...new Set(wordTokens(query))];
 
     return docs
       .map(({ record, tokens }) => {
@@ -169,32 +240,13 @@ export class MemoryVectorStore implements VectorStore {
           const norm = this.k1 * (1 - this.b + (this.b * tokens.length) / avgLength);
           score += idf * ((tf * (this.k1 + 1)) / (tf + norm));
         }
-        return this.hit(record, score);
+        return { record, score };
       })
-      .filter((hit) => hit.score > 0)
-      .sort(byScoreDesc)
+      .filter((scored) => scored.score > 0)
+      .sort(byRankDesc)
       .slice(0, width);
   }
 
-  /**
-   * Reciprocal-rank fusion. Each ranking contributes `1 / (rrfK + rank)`, so only ORDER
-   * matters — the two score scales never have to be reconciled, and a document ranked first
-   * by exact term match beats one that merely leads a flat vector ranking.
-   */
-  async hybrid(input: HybridSearchInput): Promise<readonly SearchHit[]> {
-    // Three bounds, none of which `Math.max` screens — it PROPAGATES a `NaN`. A `NaN` `k` collapses
-    // both candidate widths and the final slice to `[]`; a `NaN` `rrfK` makes every fused score
-    // `NaN`, and the ranking this method exists to produce becomes whatever order the sort left.
-    const k = finiteCount(HYBRID, 'k', input.k);
-    const width = finiteCount(HYBRID, 'candidates', input.candidates ?? Math.max(k * 4, 20));
-    const rrfK = finiteOption(HYBRID, 'rrfK', input.rrfK ?? 60);
-    const [dense, lexical] = await Promise.all([
-      this.search(input.vector, width, input.filter),
-      this.searchText(input.query, width, input.filter),
-    ]);
-    return fuse([dense, lexical], rrfK).slice(0, k);
-  }
-
   /** Scoped and filtered, exactly like `pruneSql`: everything `filter` matches but `keep`. */
   async prune(filter: MetadataFilter, keep: readonly string[]): Promise<void> {
     const kept = new Set(keep);
@@ -237,6 +289,14 @@ export class MemoryVectorStore implements VectorStore {
   }
 }
 
+/**
+ * The one way to build the in-process store — the twin of `postgresVectorStore()`. The class is a
+ * type in the barrel only (`X_FACTORY_NAME_SPELLING`), so `new` is never a second spelling.
+ */
+export function memoryVectorStore(input: MemoryVectorStoreInput): MemoryVectorStore {
+  return new MemoryVectorStore(input);
+}
+
 /**
  * Fuse ranked lists by reciprocal rank. Exported so a reranker can reuse it — which is why the
  * damping is screened HERE too and not only in `hybrid`: a default parameter is a bound like any
@@ -269,4 +329,20 @@ export function fuse(
  * sort then resolves them by dense-list insertion order, which no SQL engine reproduces.
  */
 const byScoreDesc = (a: SearchHit, b: SearchHit): number =>
-  b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+  byScore(a.score, b.score) || byId(a.id, b.id);
+
+/** The same order over a ranking's rows, which still carry their tenant. */
+const byRankDesc = (a: Scored, b: Scored): number =>
+  byScore(a.score, b.score) || byId(a.record.id, b.record.id);
+
+const byId = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+/**
+ * Descending, `NaN` last. A cosine against a zero-norm vector is `NaN`, and float8 orders `NaN`
+ * above every number, so pg's `order by distance` puts that row at the end. `b - a` alone is `NaN`
+ * for any pair holding one, which reads as a tie and leaves the sort inconsistent.
+ */
+function byScore(a: number, b: number): number {
+  if (Number.isNaN(a) || Number.isNaN(b)) return Number.isNaN(a) ? (Number.isNaN(b) ? 0 : 1) : -1;
+  return b - a;
+}

package/src/wire.ts

@@ -185,9 +185,14 @@ export class MessageStream {
     }
   }
 
-  /** True once `message_stop` arrived. False means the connection died mid-answer. */
+  /**
+   * True once `message_stop` arrived with every tool_use block closed. False means the connection
+   * died mid-answer — or the stream ended with a call's arguments still open, which drops the call
+   * (it is emitted whole or not at all), and for `llm()` that call IS the answer. `openai-wire.ts`
+   * refuses the same case.
+   */
   isComplete(): boolean {
-    return this.stopped;
+    return this.stopped && this.pending.size === 0;
   }
 
   state(): StreamState {