@ultimat3/ai 22.15.0 → 24.0.0

package/src/embeddings.ts

@@ -5,7 +5,7 @@
 // queried with another is a silent relevance collapse, and the only place to catch it is
 // where the two meet. `VectorStore` compares the declared dimension and refuses.
 
-import { finiteCount } from '@ultimat3/core';
+import { fingerprint, finiteCount } from '@ultimat3/core';
 import { AiEmbedderInvalidError } from './errors';
 
 export interface Embedder {
@@ -88,10 +88,10 @@ export class HashEmbedder implements Embedder {
   private one(text: string): Float32Array {
     const vector = new Float32Array(this.dimension);
     for (const token of tokenize(text)) {
-      const slot = fnv1a(token) % this.dimension;
+      const slot = hashOf(token) % this.dimension;
       // Signed accumulation: without it every vector is non-negative and cosine
       // similarity compresses into a narrow band where nothing ranks apart.
-      const sign = fnv1a(`${token}#sign`) % 2 === 0 ? 1 : -1;
+      const sign = hashOf(`${token}#sign`) % 2 === 0 ? 1 : -1;
       vector[slot] = (vector[slot] ?? 0) + sign;
     }
     return normalize(vector);
@@ -103,14 +103,13 @@ export function tokenize(text: string): readonly string[] {
   return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
 }
 
-/** FNV-1a 32-bit. Chosen for stability across runtimes, not for cryptographic strength. */
-export function fnv1a(text: string): number {
-  let hash = 0x811c9dc5;
-  for (let i = 0; i < text.length; i += 1) {
-    hash ^= text.charCodeAt(i);
-    hash = Math.imul(hash, 0x01000193) >>> 0;
-  }
-  return hash;
+/**
+ * A token's slot hash: 32 bits of core's `fingerprint`, never a local FNV-1a. FNV-1a/32 collides on
+ * ordinary words (`costarring` / `liquid`), and two colliding words embed IDENTICALLY here — cosine
+ * 1, so a semantic lookup answered one with the other's entry.
+ */
+function hashOf(text: string): number {
+  return Number.parseInt(fingerprint(text).slice(0, 8), 16);
 }
 
 /** L2 normalise in place so cosine similarity reduces to a dot product. */

package/src/error-body.ts

@@ -11,13 +11,20 @@ import { REDACTED } from '@ultimat3/core';
 /** Enough of an error body to name the field that was wrong, not enough to fill a log. */
 const DETAIL_LIMIT = 300;
 
+/**
+ * How much of a failure body is READ. Larger than what is shown, because the message sits inside a
+ * JSON envelope that has to parse; bounded, because a provider streaming an endless 5xx body held
+ * the call and its memory for as long as it kept sending.
+ */
+const READ_LIMIT = 4 * 1024;
+
 /**
  * The provider's own message, when it sent one — it names the offending field, we name the fix.
  * Falls back to the raw text because a proxy or a gateway timeout page is not JSON and is still
- * the best evidence there is.
+ * the best evidence there is. One reader for every transport, the embedder included.
  */
 export async function detailOf(response: Response): Promise<string> {
-  const body = await response.text().catch(() => '');
+  const body = await boundedText(response.body);
   try {
     const parsed: unknown = JSON.parse(body);
     if (typeof parsed === 'object' && parsed !== null) {
@@ -28,11 +35,39 @@ export async function detailOf(response: Response): Promise<string> {
       }
     }
   } catch {
-    // Not JSON — a proxy or a gateway timeout page. The raw text is still the best evidence.
+    // Not JSON — a proxy or a gateway timeout page, or a body cut at the read limit.
   }
   return body === '' ? response.statusText : body.slice(0, DETAIL_LIMIT);
 }
 
+/** The start of a body, never more than `READ_LIMIT` bytes of it; the rest is cancelled. */
+async function boundedText(body: ReadableStream<Uint8Array> | null): Promise<string> {
+  if (body === null) return '';
+  const reader = body.getReader();
+  const kept: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (total < READ_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);
+}
+
 /**
  * Every occurrence of the credential replaced with `[redacted]`. Cheap, and the one leak path:
  * a proxy that echoes the request headers into its own 400 body puts the key in an error, and an

package/src/errors.ts

@@ -27,6 +27,7 @@ export const AI_ERROR_CODES = [
   'X_VECTOR_DIM_MISMATCH',
   'X_VECTOR_SCOPE_WIDENED',
   'X_AI_EMBEDDER_INVALID',
+  'X_VECTOR_UNSCOPED',
 ] as const;
 
 export type AiErrorCode = (typeof AI_ERROR_CODES)[number];
@@ -55,6 +56,7 @@ export const AI_ERROR_TITLES: Readonly<Record<AiErrorCode, string>> = {
   X_VECTOR_DIM_MISMATCH: 'embedding dimensions differ from the store',
   X_VECTOR_SCOPE_WIDENED: 'a derived vector scope tried to leave its tenant',
   X_AI_EMBEDDER_INVALID: 'an Embedder returned fewer vectors than texts it was given',
+  X_VECTOR_UNSCOPED: 'a vector store was read with no tenant bound inside an org request',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Unconditional and

package/src/eval-baseline.ts

@@ -91,7 +91,11 @@ export function regressionsAgainst(input: {
   readonly tolerance: number;
 }): readonly Regression[] {
   const found: Regression[] = [];
-  const fell = (was: number, now: number): boolean => now < was - input.tolerance;
+  // Both sides at the precision the baseline is WRITTEN at, and the drop rounded too: a raw 2/3
+  // against its own recorded 0.667 fell at `tolerance: 0`, and `0.9 - 0.05` is not `0.85` in
+  // binary — a drop of exactly the tolerance must read as within it.
+  const fell = (was: number, now: number): boolean =>
+    round(round(was) - round(now)) > input.tolerance;
   if (fell(input.baseline.score, input.score)) {
     found.push({ case: OVERALL, baseline: input.baseline.score, score: input.score });
   }

package/src/gateway.ts

@@ -7,14 +7,16 @@
 import type { Random } from '@ultimat3/core';
 import {
   backoffDelay,
+  fingerprint,
   finiteCount,
   isRetryableStatus,
   isUltimateError,
+  logger,
   renderThrowable,
   stringField,
 } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
-import type { BudgetLimits, BudgetStore } from './budget';
+import type { BudgetKeys, BudgetLimits, BudgetStore } from './budget';
 import { BudgetLedger, currentBudget, estimateSpend, withBudget } from './budget';
 import { AiProviderUnavailableError } from './errors';
 import type { ModelId } from './models';
@@ -78,10 +80,11 @@ export interface Gateway {
   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.
+   * every call `llm()`, `agent()` and `hive()` make, each passing `budgetKeysFor(ctx.actor)` so the
+   * `actor` and `org` ceilings count the caller. Required: a gateway without it ran every such call
+   * under no gateway ceiling at all.
    */
-  callLedger?(): BudgetLedger;
+  callLedger(keys: BudgetKeys): BudgetLedger;
 }
 
 export function createGateway(input: CreateGatewayInput): Gateway {
@@ -114,23 +117,19 @@ class GatewayImpl implements Gateway {
   /**
    * `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.
+   * A raw `generate` / `stream` outside any scope passes no keys: it has no caller to count.
    */
-  callLedger(): BudgetLedger {
+  callLedger(keys: BudgetKeys): BudgetLedger {
     return new BudgetLedger({
       limits: this.config.budget ?? {},
+      ...(keys.actorKey !== undefined ? { actorKey: keys.actorKey } : {}),
+      ...(keys.orgKey !== undefined ? { orgKey: keys.orgKey } : {}),
       ...(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 ?? {},
-      ...(input.actorKey !== undefined ? { actorKey: input.actorKey } : {}),
-      ...(input.orgKey !== undefined ? { orgKey: input.orgKey } : {}),
-      ...(this.config.budgetStore !== undefined ? { store: this.config.budgetStore } : {}),
-    });
-    return withBudget(ledger, fn);
+  scope<T>(input: BudgetKeys, fn: () => Promise<T>): Promise<T> {
+    return withBudget(this.callLedger(input), fn);
   }
 
   async spent(): Promise<Money> {
@@ -153,7 +152,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() ?? this.callLedger();
+    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.
@@ -170,10 +169,20 @@ class GatewayImpl implements Gateway {
     await ledger?.record(result.usage, result.cost, reservation);
     // A refusal is not an answer, so it is not cached. Storing one would keep serving a decision
     // the classifier might not make twice, long after the prompt that provoked it was fixed.
-    if (result.stopReason !== 'refusal') {
+    if (result.stopReason !== 'refusal') await this.remember(cacheKey, result);
+    return result;
+  }
+
+  /**
+   * The cache write, AFTER the call was paid for and recorded. A throw here must not turn that
+   * answer into a failure: the caller would retry and pay for it twice. Logged, and the answer kept.
+   */
+  private async remember(cacheKey: string, result: GenerateResult): Promise<void> {
+    try {
       await this.config.cache?.set(cacheKey, JSON.stringify(result));
+    } catch (error) {
+      logger.warn('ai.cache.write_failed', { cacheKey, error: renderThrowable(error) });
     }
-    return result;
   }
 
   async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
@@ -196,7 +205,7 @@ class GatewayImpl implements Gateway {
     // `generate`, or reconnects itself and knows what it has already shown.
     const provider = this.providerFor(model);
 
-    const ledger = currentBudget() ?? this.callLedger();
+    const ledger = currentBudget() ?? this.callLedger({});
     const reservation = await ledger?.reserve(estimateSpend(resolved));
     let settled = false;
     try {
@@ -368,17 +377,20 @@ export function isRetryable(error: unknown): boolean {
 
 /**
  * Cache key. Every field that changes the answer is in it — a key that ignores `effort` or
- * `system` would serve one prompt's answer for another.
+ * `system` would serve one prompt's answer for another — and each tool WHOLE: every `llm()` tool
+ * is named `respond`, so a key over names alone served an answer shaped for an old `output` schema
+ * after the schema changed. Core's `fingerprint`, so key order never splits one request in two and
+ * the width is the one every other sharing key in the framework has.
  */
 export function cacheKeyFor(request: GenerateRequest): string {
-  return JSON.stringify({
+  return fingerprint({
     model: request.model,
     system: request.system ?? '',
     messages: request.messages,
     maxTokens: request.maxTokens,
     effort: request.effort ?? 'high',
     thinking: request.thinking ?? 'adaptive',
-    tools: request.tools?.map((t) => t.name) ?? [],
+    tools: request.tools ?? [],
     stop: request.stopSequences ?? [],
   });
 }

package/src/hive.ts

@@ -20,12 +20,13 @@ import type { Ctx } from '@ultimat3/core';
 import { finiteCount, throwIfAborted, withSpan } from '@ultimat3/core';
 import type { AnySchema, InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { BudgetLimits } from './budget';
-import { BudgetLedger, currentBudget, withBudget } from './budget';
+import { BudgetLedger, budgetKeysFor, currentBudget, withBudget } from './budget';
 import { HiveEmptyError } from './hive-errors';
 import { runPool } from './hive-pool';
 import type { HiveMember, HiveMemberError, HiveOutput, HiveResult } from './hive-result';
 import { hiveResultSchema } from './hive-result';
 import type { LlmBudget } from './llm';
+import { installedGateway } from './runtime';
 
 /**
  * Members in flight at once when the declaration omits one. Small and deliberately arbitrary — it
@@ -131,7 +132,14 @@ async function run<
       'hive.concurrency': width,
       'hive.on_member_error': def.onMemberError,
     });
-    const ledger = (currentBudget() ?? new BudgetLedger({ limits: {} })).derive(limitsOf(def));
+    // Rooted as `llm()` and `agent()` root: the gateway's ceilings, keyed on the caller. An empty
+    // root dropped every gateway ceiling for every member. No gateway installed is a hive of plain
+    // actions, which spends nothing — a model member is refused `X_AI_GATEWAY_MISSING` on its own.
+    const root =
+      currentBudget() ??
+      installedGateway()?.callLedger(budgetKeysFor(args.ctx.actor)) ??
+      new BudgetLedger({ limits: {} });
+    const ledger = root.derive(limitsOf(def));
     const result = await withBudget(ledger, () =>
       runPool<InferInput<MIn>, InferOutput<MOut>>({
         inputs,

package/src/index.ts

@@ -11,14 +11,17 @@ export { describeAgents, resetAgents } from './agent-facts';
 export type { AgentJobOptions } from './agent-job';
 export { agentJob } from './agent-job';
 export type {
+  BudgetKeys,
   BudgetLedgerInput,
   BudgetLimits,
   BudgetReport,
   BudgetStore,
+  BudgetTake,
   SpendEstimate,
 } from './budget';
 export {
   BudgetLedger,
+  budgetKeysFor,
   currentBudget,
   estimateSpend,
   MemoryBudgetStore,
@@ -29,7 +32,6 @@ export {
   cosine,
   embedBatched,
   embedOne,
-  fnv1a,
   HashEmbedder,
   normalize,
   tokenize,
@@ -219,5 +221,5 @@ export type {
 } from './vector';
 export { fuse, MemoryVectorStore } from './vector';
 export type { VectorScope } from './vector-scope';
-export { NO_TENANT, tenantOf, UNSCOPED } from './vector-scope';
+export { NO_TENANT, tenantOf, UNSCOPED, VectorUnscopedError } from './vector-scope';
 export type { StreamState } from './wire';

package/src/llm-cache.ts

@@ -16,8 +16,9 @@
  */
 
 import type { Ctx } from '@ultimat3/core';
+import { fingerprint } from '@ultimat3/core';
 import { parseDuration } from '@ultimat3/time';
-import { embedOne, fnv1a } from './embeddings';
+import { embedOne } from './embeddings';
 import { aiEmbedder, semanticCacheFor } from './runtime';
 
 /** What a `scope` may decide from. The same pair `vars()` receives, and for the same reason. */
@@ -119,7 +120,7 @@ export async function openCache<TParsed>(
     },
     remember(value: unknown): Promise<void> {
       return store.remember(
-        `${args.prompt.hash}:${fnv1a(args.rendered).toString(16)}`,
+        `${args.prompt.hash}:${fingerprint(args.rendered)}`,
         embedding,
         value,
         ttlMs === undefined ? {} : { ttlMs },

package/src/llm.ts

@@ -27,9 +27,9 @@ import type { Ctx, Span, SpanAttributes } from '@ultimat3/core';
 import { finiteCount, withSpan } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
-import { formatIssues, toMcpInputSchema, validateAsync } from '@ultimat3/schema';
+import { formatIssues, validateAsync } from '@ultimat3/schema';
 import type { BudgetLimits } from './budget';
-import { BudgetLedger, currentBudget, withBudget } from './budget';
+import { budgetKeysFor, currentBudget, withBudget } from './budget';
 import {
   LlmOutputInvalidError,
   LlmRefusedError,
@@ -47,15 +47,9 @@ import type { Prompt, PromptVars } from './prompt';
 import type { AiMessage, GenerateRequest, GenerateResult } from './provider';
 import { isTruncated } from './provider';
 import { assertNoSecrets } from './redaction';
+import type { Respond } from './respond';
+import { parseJsonish, RESPOND, respondFor } from './respond';
 import { aiGateway, aiRedactor } from './runtime';
-import type { LlmTool } from './tools';
-
-/**
- * The tool the model answers through. One name, so the reader never has to guess — and shared
- * with `agent()`, which offers the app's tools alongside it and needs the same name to tell an
- * answer from a tool call.
- */
-export const RESPOND = 'respond';
 
 /** Two attempts total: the answer, then one repair turn. See `LlmOutputInvalidError`. */
 const ATTEMPTS = 2;
@@ -138,8 +132,8 @@ export function llm<
   TOutput extends StandardSchemaV1,
   V extends PromptVars,
 >(def: LlmDef<TInput, TOutput, V>): LlmAction<TInput, TOutput> {
-  const respond = respondToolFor(def.output);
-  // Screened at DECLARATION, beside `respondToolFor`'s own refusal and for the same reason: an
+  const respond = respondFor(def.output);
+  // Screened at DECLARATION, beside `respondFor`'s own refusal and for the same reason: an
   // `llm()` is evaluated at module scope, so a bound that is not one fails the boot rather than
   // the first request. It is the read at `generate` below that makes it urgent — `maxTokens`
   // becomes the pre-flight ESTIMATE, a `NaN` estimate passes every `want > remaining` check, and
@@ -190,7 +184,7 @@ async function generate<
   V extends PromptVars,
 >(
   def: LlmDef<TInput, TOutput, V>,
-  respond: LlmTool,
+  respond: Respond,
   args: { readonly input: InferOutput<TInput>; readonly ctx: Ctx },
 ): Promise<InferOutput<TOutput>> {
   const { prompt } = def;
@@ -250,7 +244,7 @@ async function generate<
       // the provider call in flight, billed and unread, and the repair turn bought a SECOND one.
       signal: args.ctx.signal,
     };
-    const request: GenerateRequest = { ...base, tools: [respond] };
+    const request: GenerateRequest = { ...base, tools: [respond.tool] };
 
     // 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
@@ -259,11 +253,10 @@ async function generate<
     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);
+    // Keyed on the CALLER, so the gateway's `actor` / `org` ceilings count this call against them.
+    const ledger = (currentBudget() ?? gateway.callLedger(budgetKeysFor(args.ctx.actor))).derive(
+      limits,
+    );
     const sink = currentLlmSink();
 
     return withBudget(ledger, async () => {
@@ -292,7 +285,7 @@ async function generate<
             explanation: result.stopDetails?.explanation,
           });
         }
-        const parsed = await validateAsync(def.output, structuredOutputOf(result));
+        const parsed = await validateAsync(def.output, respond.read(result));
         if (parsed.issues === undefined) {
           await cache?.remember(parsed.value);
           return parsed.value;
@@ -403,21 +396,6 @@ function limitsOf(budget: LlmBudget | undefined): BudgetLimits {
   };
 }
 
-/**
- * The output schema as the only tool the model may answer through — the spec's "structured
- * output drives tool use". `toMcpInputSchema` is the same projection an MCP client sees, so
- * a model and an agent are shown one shape, and a schema it cannot express throws HERE, at
- * declaration time, rather than degrading into a permissive node the model cannot satisfy.
- */
-export function respondToolFor(output: StandardSchemaV1): LlmTool {
-  return {
-    name: RESPOND,
-    description: 'Return the result. Call this exactly once; do not answer in prose.',
-    input_schema: toMcpInputSchema(output),
-    strict: true,
-  };
-}
-
 /**
  * What the model answered, as text the Messages API will accept — or nothing.
  *
@@ -436,23 +414,3 @@ function assistantEcho(result: GenerateResult): string | undefined {
   const replayed = JSON.stringify(call.input);
   return replayed === undefined || replayed === '' ? undefined : replayed;
 }
-
-/**
- * The tool call if the model made one, otherwise the text parsed as JSON — a model that
- * answers in prose is a schema failure, not a crash, so it flows into the repair turn.
- */
-export function structuredOutputOf(result: GenerateResult): unknown {
-  const call = result.toolCalls.find((c) => c.name === RESPOND);
-  if (call !== undefined) return call.input;
-  return parseJsonish(result.text);
-}
-
-function parseJsonish(text: string): unknown {
-  const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
-  const body = (fenced?.[1] ?? text).trim();
-  try {
-    return JSON.parse(body);
-  } catch {
-    return undefined;
-  }
-}

package/src/openai-wire.ts

@@ -62,9 +62,14 @@ const ERROR_STATUS: ReadonlyMap<string, number> = new Map(
   }),
 );
 
-/** A finish reason this format knows, or `undefined` for `null` — which means "still going". */
+/**
+ * The finish reason, or `undefined` for a non-string (`null` on a delta means "still going").
+ * A string this table does not know FAILS CLOSED as `max_tokens` — `wire.ts`'s `parseStopReason`
+ * rule, so one unknown reason reads the same on both formats: a provider's new reason is far
+ * likelier to be a way of stopping early than of finishing.
+ */
 export function parseFinishReason(raw: unknown): StopReason | undefined {
-  return typeof raw === 'string' ? FINISH_REASONS.get(raw) : undefined;
+  return typeof raw === 'string' ? (FINISH_REASONS.get(raw) ?? 'max_tokens') : undefined;
 }
 
 /**

package/src/pg-vector.ts

@@ -24,7 +24,7 @@ import type {
   VectorRecord,
   VectorStore,
 } from './vector';
-import { narrowScope, tenantOf, UNSCOPED, type VectorScope } from './vector-scope';
+import { assertTenantRead, narrowScope, tenantOf, UNBOUND, type VectorScope } from './vector-scope';
 
 export interface PgVectorStoreInput {
   /** The table. Also the store's name in errors, and the stem of every index name. */
@@ -60,7 +60,7 @@ export class PgVectorStore implements VectorStore {
     this.input = input;
     this.name = input.name;
     this.dimension = input.dimension;
-    this.scope = input.scope ?? UNSCOPED;
+    this.scope = input.scope ?? UNBOUND;
     this.target = {
       table: input.name,
       dimension: input.dimension,
@@ -75,8 +75,8 @@ export class PgVectorStore implements VectorStore {
   }
 
   /**
-   * A view of the same table through a narrower envelope. The unscoped store is the backfill
-   * path; a request handler derives from it and can never widen back out.
+   * A view of the same table through a narrower envelope. A store opened with `scope: UNSCOPED`
+   * is the backfill path; a request handler derives from it and can never widen back out.
    */
   scoped(scope: VectorScope): PgVectorStore {
     return new PgVectorStore({
@@ -111,6 +111,7 @@ export class PgVectorStore implements VectorStore {
     k: number,
     filter?: MetadataFilter,
   ): Promise<readonly SearchHit[]> {
+    assertTenantRead(this.name, this.scope);
     this.assertDimension(vector.length);
     // `k` is the statement's `limit` and reaches Postgres as a bound parameter, so a `NaN` is the
     // database's error to report rather than this store's — and a fractional one is an error there
@@ -125,12 +126,14 @@ export class PgVectorStore implements VectorStore {
     k: number,
     filter?: MetadataFilter,
   ): Promise<readonly SearchHit[]> {
+    assertTenantRead(this.name, this.scope);
     return this.run(
       textSql(this.target, query, { scope: this.scope, filter, k: finiteCount(HYBRID, 'k', k) }),
     );
   }
 
   async hybrid(input: HybridSearchInput): Promise<readonly SearchHit[]> {
+    assertTenantRead(this.name, this.scope);
     this.assertDimension(input.vector.length);
     // The same three bounds `MemoryVectorStore.hybrid` screens, and they have to be screened in
     // BOTH stores: `rrfK` lands in `1.0 / (rrfK + rank)`, Postgres has a float8 `NaN`, and it

package/src/provider.ts

@@ -463,14 +463,17 @@ function lastUserMessage(messages: readonly AiMessage[]): string {
 }
 
 /**
- * ~4 characters per token. Deliberately an ESTIMATE and never used for billing — the
- * gateway's pre-flight budget check needs a number before the call exists, and the real
- * count from `usage` replaces it afterwards.
+ * ~4 characters per token. Deliberately an ESTIMATE and never used for billing — the gateway's
+ * pre-flight budget check needs a number before the call exists, and `usage` replaces it after.
+ * The completion is clamped to what the model can write, exactly as `estimateCost` clamps it.
  */
 export function estimateTokens(request: GenerateRequest): number {
-  return estimateInputTokens(request) + request.maxTokens;
+  return estimateInputTokens(request) + completionCeiling(request);
 }
 
+const completionCeiling = (request: GenerateRequest): number =>
+  Math.min(request.maxTokens, modelSpec(request.model ?? DEFAULT_MODEL).maxOutput);
+
 /** The prompt half alone — what the provider bills at the input rate. */
 export function estimateInputTokens(request: GenerateRequest): number {
   const body = request.messages.map(messageText).join(' ');
@@ -483,10 +486,9 @@ export function estimateInputTokens(request: GenerateRequest): number {
  * optimistic estimate is a ceiling one long completion walks through.
  */
 export function estimateCost(request: GenerateRequest): Money {
-  const model = request.model ?? DEFAULT_MODEL;
-  return costOf(model, {
+  return costOf(request.model ?? DEFAULT_MODEL, {
     inputTokens: estimateInputTokens(request),
-    outputTokens: Math.min(request.maxTokens, modelSpec(model).maxOutput),
+    outputTokens: completionCeiling(request),
     cacheReadTokens: 0,
     cacheWriteTokens: 0,
   });

package/src/rag.ts

@@ -56,7 +56,9 @@ export function chunk(input: ChunkInput): readonly Chunk[] {
         id: `${input.id}#${chunks.length}`,
         text,
         tokens: estimateChunkTokens(text),
-        metadata: { source: input.id, ...(input.metadata ?? {}) },
+        // Written AFTER the spread: `source` is the framework's stamp, and `indexDocument` prunes by
+        // it — a caller's own `source` replaced it, and a re-index pruned the wrong rows or none.
+        metadata: { ...(input.metadata ?? {}), source: input.id },
       });
     }
     // Carry the tail forward as the overlap for the next chunk — at most every unit BUT THE
@@ -78,6 +80,11 @@ export function chunk(input: ChunkInput): readonly Chunk[] {
   for (const unit of units) {
     const unitTokens = estimateChunkTokens(unit);
     if (tokens + unitTokens > size && buffer.length > 0) flush();
+    // The carried overlap yields to the unit, oldest first: a carry the unit does not fit beside
+    // made a chunk past `size` — the one promise this function makes.
+    while (buffer.length > 0 && tokens + unitTokens > size) {
+      tokens -= estimateChunkTokens(buffer.shift() ?? '');
+    }
     buffer.push(unit);
     tokens += unitTokens;
   }
@@ -158,7 +165,7 @@ function cutToBudget(run: string, size: number): readonly string[] {
  * 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.
+ * document is never absent from a search in between.
  */
 export async function indexDocument(input: {
   readonly store: VectorStore;
@@ -182,7 +189,7 @@ export async function indexDocument(input: {
     })),
   );
   // `source` is the chunker's own stamp (`chunk()`), so only THIS document's rows are touched.
-  await input.store.prune?.(
+  await input.store.prune(
     { source: input.document.id },
     chunks.map((c) => c.id),
   );