@ultimat3/ai 20.2.1 → 22.0.0

package/README.md

@@ -270,7 +270,7 @@ summarize.contract();    // the contract tests
 | `budget` | reserved against the worst case **before** the provider is reached — nothing spent, nothing truncated |
 | `cache.semantic` | one store per scope, keyed by embedding; a prompt version bump reaches a different store, so the bump *is* the invalidation. `scope` receives `{ input, ctx }` and **defaults to the calling actor** — the narrowest key, `@ultimat3/query`'s `readAuthority` rule; a shared store is `scope: () => 'global'`, written down |
 | `policy` | the same object every surface evaluates — an MCP call and an HTTP call are denied identically |
-| `vars` | the one declared place a model call loads data, so a reader can see what was sent — and the one place a redactor sees it, and where a `Secret` is refused |
+| `vars` | the declared place an `llm()` call loads data, so a reader can see what was sent — the redactor sees it (and every `agent()` tool result), and a `Secret` is refused here |
 
 ### Streaming is the same action
 
@@ -466,8 +466,9 @@ an action with no name reaches no route, no tool catalogue and no queue.
 
 ## Redaction: one declared seam
 
-`vars()` is the one place a model call loads data, so it is the one place anything can sit between
-the row and a third-party endpoint.
+A model call loads data in two places — `vars()`, and in an `agent()` the RESULT of every tool it
+runs — and the redactor sits on both, between the row and a third-party endpoint. It sat on
+`vars()` alone until 2026-09-23, so an agent's tool results left the process unredacted.
 
 ```ts
 configureAi({ gateway, redact: (text) => scrubPatientIdentifiers(text) });
@@ -654,3 +655,36 @@ fail-closed `terminal` default.
 | `X_VECTOR_DIM_MISMATCH` | a vector's length disagrees with the store |
 | `X_VECTOR_SCOPE_WIDENED` | a derived vector scope tried to leave the tenant it was bound to |
 | `X_NOT_IMPLEMENTED` | a remote driver with no key or transport; the fix names the env var |
+
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `AgentMaxTurnsError` | `X_AGENT_MAX_TURNS` | `src/errors.ts` |
+| `AgentToolUnexposedError` | `X_AGENT_TOOL_UNEXPOSED` | `src/errors.ts` |
+| `AiBudgetExceededError` | `X_AI_BUDGET_EXCEEDED` | `src/errors.ts` |
+| `AiGatewayMissingError` | `X_AI_GATEWAY_MISSING` | `src/errors.ts` |
+| `AiKeyMissingError` | `X_AI_KEY_MISSING` | `src/errors.ts` |
+| `AiModelUnknownError` | `X_AI_MODEL_UNKNOWN` | `src/errors.ts` |
+| `AiPromptRenderError` | `X_AI_PROMPT_VERSION` | `src/errors.ts` |
+| `AiPromptSecretError` | `X_AI_PROMPT_SECRET` | `src/errors.ts` |
+| `AiPromptVersionError` | `X_AI_PROMPT_VERSION` | `src/errors.ts` |
+| `AiProviderUnavailableError` | `X_AI_PROVIDER_UNAVAILABLE` | `src/errors.ts` |
+| `AiRequestInvalidError` | `X_AI_REQUEST_INVALID` | `src/errors.ts` |
+| `AiTransportError` | `X_AI_PROVIDER_UNAVAILABLE` | `src/errors.ts` |
+| `EmbedderDimMismatchError` | `X_VECTOR_DIM_MISMATCH` | `src/errors.ts` |
+| `EvalBaselineInvalidError` | `X_EVAL_BASELINE_INVALID` | `src/eval-errors.ts` |
+| `EvalBaselineMissingError` | `X_EVAL_BASELINE_MISSING` | `src/eval-errors.ts` |
+| `EvalMissingError` | `X_EVAL_MISSING` | `src/eval-errors.ts` |
+| `EvalRecordingError` | `X_EVAL_RECORDING` | `src/eval-errors.ts` |
+| `EvalThresholdError` | `X_EVAL_THRESHOLD` | `src/eval-errors.ts` |
+| `HiveEmptyError` | `X_HIVE_EMPTY` | `src/hive-errors.ts` |
+| `LlmOutputInvalidError` | `X_LLM_OUTPUT_INVALID` | `src/errors.ts` |
+| `LlmRefusedError` | `X_LLM_REFUSED` | `src/errors.ts` |
+| `LlmStreamInvalidError` | `X_LLM_STREAM_INVALID` | `src/errors.ts` |
+| `LlmTruncatedError` | `X_LLM_TRUNCATED` | `src/errors.ts` |
+| `VectorDimMismatchError` | `X_VECTOR_DIM_MISMATCH` | `src/errors.ts` |
+| `VectorScopeWidenedError` | `X_VECTOR_SCOPE_WIDENED` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ai",
-  "version": "20.2.1",
+  "version": "22.0.0",
   "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": "20.2.1",
-    "@ultimat3/cache": "20.2.1",
-    "@ultimat3/core": "20.2.1",
-    "@ultimat3/db": "20.2.1",
-    "@ultimat3/jobs": "20.2.1",
-    "@ultimat3/money": "20.2.1",
-    "@ultimat3/policy": "20.2.1",
-    "@ultimat3/schema": "20.2.1",
-    "@ultimat3/time": "20.2.1"
+    "@ultimat3/action": "22.0.0",
+    "@ultimat3/cache": "22.0.0",
+    "@ultimat3/core": "22.0.0",
+    "@ultimat3/db": "22.0.0",
+    "@ultimat3/jobs": "22.0.0",
+    "@ultimat3/money": "22.0.0",
+    "@ultimat3/policy": "22.0.0",
+    "@ultimat3/schema": "22.0.0",
+    "@ultimat3/time": "22.0.0"
   }
 }

package/src/agent-transcript.ts

@@ -47,6 +47,12 @@ export function toolResultTurn(
   results: readonly LlmToolResult[],
   chars: number,
   unaccepted: readonly LlmToolCall[],
+  /**
+   * The app's `configureAi({ redact })`, run over each result BEFORE the truncation — a tool
+   * result is where an agent loads a row, and it left the process unredacted while the prompt
+   * that asked for it did not. Redacted first, so a cut never splits a match the redactor needs.
+   */
+  redact: (text: string) => string = (text) => text,
 ): AiMessage {
   return {
     role: 'user',
@@ -54,7 +60,7 @@ export function toolResultTurn(
       ...results.map((result) => ({
         type: 'tool_result' as const,
         tool_use_id: result.toolUseId,
-        content: truncate(result.content, chars),
+        content: truncate(redact(result.content), chars),
         // A denial or a failure is an outcome the model should read and react to, flagged so it
         // does not read as data.
         ...(result.isError === true ? { is_error: true } : {}),

package/src/agent.ts

@@ -51,6 +51,7 @@ import type {
   StopReason,
   TokenUsage,
 } from './provider';
+import { isTruncated } from './provider';
 import { assertNoSecrets } from './redaction';
 import { aiGateway, aiRedactor } from './runtime';
 import type { AgentTool, LlmTool, LlmToolResult, ProjectableAction } from './tools';
@@ -266,8 +267,15 @@ async function run<
       'llm.redacted': rendered !== rawPrompt || system !== prompt.system,
     });
 
-    const ledger = (currentBudget() ?? new BudgetLedger({ limits: {} })).derive(limitsOf(def));
+    // Screened first, as before: a bad declaration is refused whether or not a gateway exists.
+    const limits = limitsOf(def);
+    // Rooted in the GATEWAY's own ceilings when no scope is open — an empty root ignored them.
     const gateway = aiGateway(name);
+    const ledger = (
+      currentBudget() ??
+      gateway.callLedger?.() ??
+      new BudgetLedger({ limits: {} })
+    ).derive(limits);
     const base: GenerateRequest = {
       model,
       ...(system === undefined ? {} : { system }),
@@ -340,7 +348,7 @@ async function run<
             // the loop continues, and the answer is REJECTED on the wire rather than dropped,
             // because a replayed `respond` block with no `tool_result` is a 400 and the whole run
             // becomes an `X_AI_PROVIDER_UNAVAILABLE`.
-            toolResultTurn(results, chars, answers),
+            toolResultTurn(results, chars, answers, redact),
           ];
           continue;
         }
@@ -350,7 +358,7 @@ async function run<
         // A wrong shape gets another turn like any other, because unlike `llm()` this loop has
         // turns left by construction — and unlike a tool result, the correction is the message.
         issues = formatIssues(parsed.issues).join('; ');
-        if (result.stopReason === 'max_tokens') {
+        if (isTruncated(result.stopReason)) {
           throw new LlmTruncatedError({ prompt: name, maxTokens: base.maxTokens });
         }
         messages = [...messages, assistantTurn(result), repairTurn(answers, issues)];

package/src/budget.ts

@@ -19,7 +19,11 @@ import { estimateCost, estimateInputTokens, estimateTokens, totalTokens } from '
 
 /** Ceilings. An omitted scope is unlimited — declare the ones that matter. */
 export interface BudgetLimits {
-  /** Token ceiling for one `generate`/`stream` call, including its pre-flight estimate. */
+  /**
+   * Token ceiling for one call CHAIN — every `generate`/`stream` sharing a ledger, pre-flight
+   * estimates included. An `llm()` repair turn and an `agent()` turn each debit the same ledger,
+   * so this is not "one provider call" once a scope is open.
+   */
   readonly request?: number;
   /**
    * Prompt-token ceiling for ONE call. Distinct from `request`, which counts the completion

package/src/gateway.ts

@@ -76,6 +76,12 @@ export interface Gateway {
   scope<T>(input: { actorKey?: string; orgKey?: string }, fn: () => Promise<T>): Promise<T>;
   /** Accumulated cost of the ambient scope, or zero outside one. */
   spent(): Promise<Money>;
+  /**
+   * A ledger over this gateway's own `budget`, for a call made with no `scope()` open — which is
+   * every call `llm()` and `agent()` make. Optional so a hand-written gateway still satisfies the
+   * interface; absent, such a call runs under the ceilings its own declaration sets and no others.
+   */
+  callLedger?(): BudgetLedger;
 }
 
 export function createGateway(input: CreateGatewayInput): Gateway {
@@ -105,6 +111,18 @@ class GatewayImpl implements Gateway {
     this.random = config.random;
   }
 
+  /**
+   * `budget` held with no scope open. It was enforced ONLY inside `scope()`, which nothing in the
+   * framework calls — so `createGateway({ budget: { request: 100 } })` capped no call any app made.
+   * No actor or org key here: those scopes need `scope()` to name whose window they are.
+   */
+  callLedger(): BudgetLedger {
+    return new BudgetLedger({
+      limits: this.config.budget ?? {},
+      ...(this.config.budgetStore !== undefined ? { store: this.config.budgetStore } : {}),
+    });
+  }
+
   scope<T>(input: { actorKey?: string; orgKey?: string }, fn: () => Promise<T>): Promise<T> {
     const ledger = new BudgetLedger({
       limits: this.config.budget ?? {},
@@ -135,7 +153,7 @@ class GatewayImpl implements Gateway {
     // Reserve against the ESTIMATE before spending anything — tokens AND money, since a
     // cheap-in-tokens call on an expensive model is still a cost cap the app declared.
     // `record` below replaces the estimate with the provider's real counts.
-    const ledger = currentBudget();
+    const ledger = currentBudget() ?? this.callLedger();
     // The estimate is DEBITED here, not merely checked: three concurrent calls under one ledger
     // all read the same `spent()` otherwise, all pass, and all three record against a ceiling
     // only one of them fitted.
@@ -178,7 +196,7 @@ class GatewayImpl implements Gateway {
     // `generate`, or reconnects itself and knows what it has already shown.
     const provider = this.providerFor(model);
 
-    const ledger = currentBudget();
+    const ledger = currentBudget() ?? this.callLedger();
     const reservation = await ledger?.reserve(estimateSpend(resolved));
     let settled = false;
     try {
@@ -319,6 +337,20 @@ export function backoffMs(policy: RetryPolicy, attempt: number, random?: Random)
  * package was how it stayed invisible. The `code` branch has no equivalent in core and stays here:
  * that table is HTTP status only, and a socket that timed out never produced one.
  */
+/**
+ * A transport that never produced a response. Node spells these `ETIMEDOUT`/`ECONNRESET`; Bun's
+ * `fetch` spells a refused, dropped or unopenable connection `ConnectionRefused`,
+ * `ConnectionClosed` and `FailedToOpenSocket` — which this list did not know, so on the one runtime
+ * the framework runs on a provider mid-restart was never retried.
+ */
+const RETRYABLE_TRANSPORT_CODES: ReadonlySet<string> = new Set([
+  'ETIMEDOUT',
+  'ECONNRESET',
+  'ConnectionRefused',
+  'ConnectionClosed',
+  'FailedToOpenSocket',
+]);
+
 export function isRetryable(error: unknown): boolean {
   if (typeof error !== 'object' || error === null) return false;
   // A `Provider` is the APP's object, so the value it rejected with is one the framework did not
@@ -328,7 +360,7 @@ export function isRetryable(error: unknown): boolean {
   try {
     const e = error as { status?: unknown; code?: unknown };
     if (typeof e.status === 'number') return isRetryableStatus(e.status);
-    return e.code === 'ETIMEDOUT' || e.code === 'ECONNRESET';
+    return typeof e.code === 'string' && RETRYABLE_TRANSPORT_CODES.has(e.code);
   } catch {
     return false;
   }

package/src/index.ts

@@ -63,7 +63,6 @@ export type { EvalBaseline, Regression } from './eval-baseline';
 export {
   baselinePath,
   describeRegression,
-  OVERALL,
   RECORD_ENV,
   readBaseline,
   recordingBaselines,
@@ -113,7 +112,6 @@ export {
   modelIds,
   modelSpec,
   moreCapableThan,
-  reasoningBody,
   registeredModels,
   registerModel,
   resetModels,
@@ -133,11 +131,7 @@ export {
   conditionsSql,
   ddlSql,
   deleteSql,
-  hybridSql,
   searchSql,
-  textSql,
-  upsertSql,
-  vectorLiteral,
 } from './pg-vector-sql';
 export type { DefinePromptInput, Prompt, PromptVars } from './prompt';
 export {
@@ -169,6 +163,7 @@ export {
   estimateInputTokens,
   estimateTextTokens,
   estimateTokens,
+  isTruncated,
   messageText,
   parseMessage,
   requiresStreaming,
@@ -193,7 +188,6 @@ export {
   aiRedactor,
   configureAi,
   MAX_SEMANTIC_CACHE_SCOPES,
-  resetAiRuntime,
   semanticCacheFor,
 } from './runtime';
 export type { Scorer } from './scorers';
@@ -225,6 +219,5 @@ export type {
 } from './vector';
 export { fuse, MemoryVectorStore } from './vector';
 export type { VectorScope } from './vector-scope';
-export { NO_TENANT, narrowScope, scopeAdmits, tenantOf, UNSCOPED } from './vector-scope';
+export { NO_TENANT, tenantOf, UNSCOPED } from './vector-scope';
 export type { StreamState } from './wire';
-export { parseStopDetails, ZERO_USAGE } from './wire';

package/src/llm.ts

@@ -45,6 +45,7 @@ import type { ModelId } from './models';
 import { DEFAULT_MODEL, moreCapableThan } from './models';
 import type { Prompt, PromptVars } from './prompt';
 import type { AiMessage, GenerateRequest, GenerateResult } from './provider';
+import { isTruncated } from './provider';
 import { assertNoSecrets } from './redaction';
 import { aiGateway, aiRedactor } from './runtime';
 import type { LlmTool } from './tools';
@@ -254,10 +255,15 @@ async function generate<
     // A ledger derived from the ambient one, so a per-call budget can only TIGHTEN the actor
     // and org ceilings this call runs inside, never widen them. The gateway reserves against
     // it before the provider is touched — that is where `X_AI_BUDGET_EXCEEDED` comes from.
-    const ledger = (currentBudget() ?? new BudgetLedger({ limits: {} })).derive(
-      limitsOf(def.budget),
-    );
+    // Screened first, as before: a bad declaration is refused whether or not a gateway exists.
+    const limits = limitsOf(def.budget);
+    // Rooted in the GATEWAY's own ceilings when no scope is open — an empty root ignored them.
     const gateway = aiGateway(name);
+    const ledger = (
+      currentBudget() ??
+      gateway.callLedger?.() ??
+      new BudgetLedger({ limits: {} })
+    ).derive(limits);
     const sink = currentLlmSink();
 
     return withBudget(ledger, async () => {
@@ -293,7 +299,7 @@ async function generate<
         }
         // A cut-off answer that also fails its schema is not a disagreement about the shape: the
         // ceiling is the same on the next attempt, so the repair turn is a second truncation.
-        if (result.stopReason === 'max_tokens') {
+        if (isTruncated(result.stopReason)) {
           throw new LlmTruncatedError({ prompt: name, maxTokens: request.maxTokens });
         }
         issues = formatIssues(parsed.issues).join('; ');
@@ -352,7 +358,7 @@ async function streamedAnswer<TOutput extends StandardSchemaV1>(
       explanation: result.stopDetails?.explanation,
     });
   }
-  if (result.stopReason === 'max_tokens') {
+  if (isTruncated(result.stopReason)) {
     throw new LlmTruncatedError({ prompt: name, maxTokens: request.maxTokens });
   }
   // Prose, and its JSON parse when it has one. Both, because a stream carries no `respond` tool

package/src/pg-vector-sql.ts

@@ -192,6 +192,19 @@ order by f.score desc, d."id" asc
 limit ${args.k}`;
 }
 
+/** Every row the scope and `filter` admit, except the ids in `keep` — a re-index's cleanup. */
+export function pruneSql(
+  target: PgVectorTable,
+  scope: VectorScope,
+  filter: MetadataFilter,
+  keep: readonly string[],
+): SqlFragment {
+  const kept =
+    keep.length === 0 ? ALWAYS : sql`"id" not in (${join(keep.map((id) => sql`${id}`))})`;
+  return sql`delete from ${identifier(target.table)}
+where ${kept} and ${conditionsSql(scope, filter)}`;
+}
+
 export function deleteSql(
   target: PgVectorTable,
   scope: VectorScope,

package/src/pg-vector.ts

@@ -12,6 +12,7 @@ import {
   hybridSql,
   type PgHybridArgs,
   type PgVectorTable,
+  pruneSql,
   searchSql,
   textSql,
   upsertSql,
@@ -87,11 +88,15 @@ export class PgVectorStore implements VectorStore {
   async upsert(records: readonly VectorRecord[]): Promise<void> {
     if (records.length === 0) return;
     for (const record of records) this.assertDimension(record.vector.length);
+    // One row per id, the LAST one winning — what `MemoryVectorStore` answers. Postgres refuses a
+    // statement whose `on conflict do update` touches one row twice, so a batch carrying an id
+    // twice failed here and succeeded there.
+    const unique = [...new Map(records.map((record) => [record.id, record])).values()];
     await this.client().execute(
       upsertSql(
         this.target,
         tenantOf(this.scope),
-        records.map((record) => ({
+        unique.map((record) => ({
           id: record.id,
           vector: record.vector,
           text: record.text,
@@ -142,6 +147,10 @@ export class PgVectorStore implements VectorStore {
     return this.run(hybridSql(this.target, input.query, input.vector, args));
   }
 
+  async prune(filter: MetadataFilter, keep: readonly string[]): Promise<void> {
+    await this.client().execute(pruneSql(this.target, this.scope, filter, keep));
+  }
+
   async delete(ids: readonly string[]): Promise<void> {
     if (ids.length === 0) return;
     await this.client().execute(deleteSql(this.target, this.scope, ids));

package/src/provider.ts

@@ -102,7 +102,13 @@ export type StopReason =
   | 'stop_sequence'
   | 'tool_use'
   | 'pause_turn'
-  | 'refusal';
+  | 'refusal'
+  /** The prompt plus the answer outgrew the model's context window: cut off, like `max_tokens`. */
+  | 'model_context_window_exceeded';
+
+/** Whether an answer was CUT OFF — never parse one of these as a complete answer. */
+export const isTruncated = (reason: StopReason): boolean =>
+  reason === 'max_tokens' || reason === 'model_context_window_exceeded';
 
 /**
  * Why a refusal happened. Only ever present when `stopReason` is `refusal`, and `category` is

package/src/rag.ts

@@ -154,7 +154,12 @@ function cutToBudget(run: string, size: number): readonly string[] {
   return pieces;
 }
 
-/** Index a document: chunk, embed, upsert. One call so no step is skipped by accident. */
+/**
+ * Index a document: chunk, embed, upsert, prune. One call so no step is skipped by accident. The
+ * prune is what re-indexing a SHORTER document needs: chunk ids are `<doc>#<n>`, so the upsert
+ * overwrote the first chunks and left the old tail retrievable. Upsert first, prune after, so the
+ * document is never absent from a search in between. A store without `prune` cannot clean up.
+ */
 export async function indexDocument(input: {
   readonly store: VectorStore;
   readonly embedder: Embedder;
@@ -176,6 +181,11 @@ export async function indexDocument(input: {
       metadata: c.metadata,
     })),
   );
+  // `source` is the chunker's own stamp (`chunk()`), so only THIS document's rows are touched.
+  await input.store.prune?.(
+    { source: input.document.id },
+    chunks.map((c) => c.id),
+  );
   return chunks;
 }
 

package/src/remote-embedder.ts

@@ -132,7 +132,7 @@ export class RemoteEmbedder implements Embedder {
       throw new AiTransportError({
         provider: this.name,
         status: response.status,
-        detail: (await response.text().catch(() => '')).slice(0, DETAIL_LIMIT),
+        detail: await detailOf(response.body),
         envVar: API_KEY_ENV,
       });
     }
@@ -218,3 +218,36 @@ function asRecord(value: unknown): Record<string, unknown> | undefined {
 function countOf(data: unknown): string {
   return Array.isArray(data) ? String(data.length) : 'no data array';
 }
+
+/**
+ * The start of an error body, and never more. `response.text()` read it WHOLE — outside
+ * `maxResponseBytes`, which bounds a success only — so a provider streaming an endless 5xx body
+ * held the call and its memory forever. Capped through the same counting reader, and decoded from
+ * the bytes it kept: `over` still has a detail worth showing.
+ */
+async function detailOf(body: ReadableStream<Uint8Array> | null): Promise<string> {
+  if (body === null) return '';
+  const reader = body.getReader();
+  const kept: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (total < DETAIL_LIMIT) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      kept.push(value);
+      total += value.byteLength;
+    }
+  } catch {
+    // A body that fails mid-read still has whatever arrived; the status is the error's substance.
+  } finally {
+    await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of kept) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(bytes).slice(0, DETAIL_LIMIT);
+}

package/src/vector.ts

@@ -53,6 +53,13 @@ export interface VectorStore {
   searchText(query: string, k: number, filter?: MetadataFilter): Promise<readonly SearchHit[]>;
   hybrid(input: HybridSearchInput): Promise<readonly SearchHit[]>;
   delete(ids: readonly string[]): Promise<void>;
+  /**
+   * 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.
+   */
+  prune?(filter: MetadataFilter, keep: readonly string[]): Promise<void>;
 }
 
 export interface MemoryVectorStoreInput {
@@ -188,6 +195,15 @@ export class MemoryVectorStore implements VectorStore {
     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);
+    for (const record of this.candidates(filter)) {
+      if (kept.has(record.id)) continue;
+      for (const [key, stored] of this.records) if (stored === record) this.records.delete(key);
+    }
+  }
+
   /** Scoped, exactly like the SQL `delete ... where id in (...) and <scope>`. */
   async delete(ids: readonly string[]): Promise<void> {
     const wanted = new Set(ids);

package/src/wire.ts

@@ -59,10 +59,16 @@ const STOP_REASONS: readonly StopReason[] = [
   'tool_use',
   'pause_turn',
   'refusal',
+  'model_context_window_exceeded',
 ];
 
+/**
+ * FAILS CLOSED: a reason this list does not know is read as `max_tokens`. It fell back to
+ * `end_turn`, so `model_context_window_exceeded` — a cut-off answer — was parsed as a complete
+ * one. A provider's new reason is far likelier to be a way of stopping early than of finishing.
+ */
 export function parseStopReason(raw: unknown): StopReason {
-  return STOP_REASONS.find((reason) => reason === raw) ?? 'end_turn';
+  return STOP_REASONS.find((reason) => reason === raw) ?? 'max_tokens';
 }
 
 /**