@ultimat3/ai 1.0.0

package/src/llm.ts

@@ -0,0 +1,313 @@
+/**
+ * `llm()` — a model call declared as an `action`, NOT a ninth primitive.
+ *
+ * The eight primitives are the whole vocabulary. A model call is a server-authoritative
+ * operation with an input schema, an output schema and a policy, which is the definition of
+ * an `action` — so this file is a FACTORY over `action()`, never a new kind of thing. That is
+ * why `summarize.tool()`, `.openapi()`, `.client()`, `.job()` and `.contract()` all exist
+ * without a line here: the value is an action, so it projects like one, and an app gains an
+ * MCP tool backed by a model the moment it declares one.
+ *
+ * What the factory adds is the model half: the prompt is rendered from the parsed input, the
+ * `output` schema is projected into a tool the model must answer through, a per-call budget is
+ * reserved before a token is spent, and a near-duplicate prompt hits the semantic cache.
+ */
+
+import type { Action, ActionMcp, ActionPolicy } from '@ultimat3/action';
+import { action } from '@ultimat3/action';
+import type { Ctx } from '@ultimat3/core';
+import { withSpan } from '@ultimat3/core';
+import type { Money } from '@ultimat3/money';
+import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import { formatIssues, toMcpInputSchema, validateAsync } from '@ultimat3/schema';
+import { parseDuration } from '@ultimat3/time';
+import type { BudgetLimits } from './budget';
+import { BudgetLedger, currentBudget, withBudget } from './budget';
+import { embedOne, fnv1a } from './embeddings';
+import { LlmOutputInvalidError, LlmRefusedError, LlmTruncatedError } from './errors';
+import type { ModelId } from './models';
+import { DEFAULT_MODEL, MODEL_IDS } from './models';
+import type { Prompt, PromptVars } from './prompt';
+import type { AiMessage, GenerateRequest, GenerateResult } from './provider';
+import { aiEmbedder, aiGateway, semanticCacheFor } from './runtime';
+import type { LlmTool } from './tools';
+
+/** The tool the model answers through. One name, so the reader never has to guess. */
+const RESPOND = 'respond';
+
+/** Two attempts total: the answer, then one repair turn. See `LlmOutputInvalidError`. */
+const ATTEMPTS = 2;
+
+/**
+ * Output ceiling when the declaration omits one. Not the model's maximum — a 128k ceiling
+ * makes the worst-case cost estimate so large that every `costPerCall` budget refuses.
+ */
+const DEFAULT_MAX_TOKENS = 4_096;
+
+export interface LlmSemanticCache<TParsed> {
+  /** Cosine floor. Below ~0.9 unrelated prompts collide and the cache answers the wrong one. */
+  readonly threshold?: number;
+  /** Entry lifetime as a duration string — `'7d'`, `'12h'`. `@ultimat3/time` owns the grammar. */
+  readonly ttl?: string;
+  /**
+   * Partition key, from the parsed input. Each scope is a separate cache: cosine similarity
+   * has no notion of a tenant, so a shared cache answers one tenant with another's data.
+   */
+  readonly scope?: (input: TParsed) => string;
+}
+
+export interface LlmCache<TParsed> {
+  readonly semantic: LlmSemanticCache<TParsed>;
+  // `05-caching.md` also declares `invalidates: [tag.post]` here. It is deliberately absent
+  // until `@ultimat3/cache`'s fan-out can reach something that is not a `CacheTier`: storing
+  // tags that the ONE invalidation path never visits would read as wired and silently not be.
+  // Today the invalidation story is the prompt version (a bump reaches a different store) and
+  // `ttl`.
+}
+
+/** Per-call ceilings, checked before the provider is reached. Never truncates — refuses. */
+export interface LlmBudget {
+  /** Prompt tokens. */
+  readonly tokensIn?: number;
+  /** Worst-case price of one call, integer minor units. */
+  readonly costPerCall?: Money;
+}
+
+export interface LlmVarsArgs<TInput extends StandardSchemaV1> {
+  readonly input: InferOutput<TInput>;
+  readonly ctx: Ctx;
+}
+
+export interface LlmDef<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+> {
+  /**
+   * Overrides the prompt artifact's own model. The prompt's is part of its content hash and
+   * travels with it; this one is the deployment decision, so it wins.
+   */
+  readonly model?: ModelId;
+  readonly input: TInput;
+  readonly output: TOutput;
+  readonly prompt: Prompt<V>;
+  /**
+   * Everything the prompt is allowed to see, derived from the parsed input. Required, and
+   * async, because the input is usually an id and the prompt needs the row behind it — this
+   * is the one declared place a model call loads data, so a reader can see what was sent.
+   */
+  vars(args: LlmVarsArgs<TInput>): V | Promise<V>;
+  readonly cache?: LlmCache<InferOutput<TInput>>;
+  readonly budget?: LlmBudget;
+  readonly policy: ActionPolicy;
+  readonly mcp?: ActionMcp;
+  /** Enforced completion ceiling. The model never sees it, so it can be cut off mid-answer. */
+  readonly maxTokens?: number;
+}
+
+export function llm<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+>(def: LlmDef<TInput, TOutput, V>): Action<TInput, TOutput> {
+  const respond = respondToolFor(def.output);
+  return action<TInput, TOutput>({
+    input: def.input,
+    output: def.output,
+    policy: def.policy,
+    ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
+    handle: (args) => generate(def, respond, args),
+  });
+}
+
+async function generate<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+>(
+  def: LlmDef<TInput, TOutput, V>,
+  respond: LlmTool,
+  args: { readonly input: InferOutput<TInput>; readonly ctx: Ctx },
+): Promise<InferOutput<TOutput>> {
+  const { prompt } = def;
+  // The prompt ref is the identity every failure here is about, and unlike the action's
+  // export name it exists before registration and can never twin.
+  const name = prompt.ref;
+  const model = def.model ?? prompt.model ?? DEFAULT_MODEL;
+  const rendered = prompt.render(await def.vars({ input: args.input, ctx: args.ctx }));
+
+  return withSpan('ai.llm', async (span) => {
+    span.setAttributes({
+      'llm.model': model,
+      'llm.prompt': prompt.ref,
+      'llm.prompt.hash': prompt.hash,
+    });
+
+    // A cached answer is still data of unknown provenance, so it goes through the schema like
+    // any other. One that no longer fits — the schema moved under it — is a miss, not a
+    // failure: the model can produce a fresh answer, and refusing would be worse than paying.
+    const cache = await openCache(def, args.input, rendered);
+    const hit = await accept(def.output, await cache?.lookup());
+    span.setAttribute('llm.cache.hit', hit !== undefined);
+    if (hit !== undefined) return hit.value;
+
+    const request: GenerateRequest = {
+      model,
+      ...(prompt.system === undefined ? {} : { system: prompt.system }),
+      messages: [{ role: 'user', content: rendered }],
+      maxTokens: def.maxTokens ?? DEFAULT_MAX_TOKENS,
+      ...(prompt.effort === undefined ? {} : { effort: prompt.effort }),
+      ...(prompt.thinking === undefined ? {} : { thinking: prompt.thinking }),
+      tools: [respond],
+    };
+
+    // 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),
+    );
+    const gateway = aiGateway(name);
+
+    return withBudget(ledger, async () => {
+      let messages: readonly AiMessage[] = request.messages;
+      let issues = 'no output';
+      for (let attempt = 1; attempt <= ATTEMPTS; attempt += 1) {
+        const result = await gateway.generate({ ...request, messages });
+        span.setAttributes({
+          'llm.attempts': attempt,
+          'llm.stop': result.stopReason,
+          'llm.tokens': result.usage.inputTokens + result.usage.outputTokens,
+          'llm.cost.minor': result.cost.minor,
+        });
+        // Branch on the stop reason BEFORE reading the answer. A refusal carries empty or partial
+        // content, so parsing it first reports a schema disagreement — a cause that is wrong, a
+        // fix that does not apply, and a repair turn spent buying the same refusal again.
+        if (result.stopReason === 'refusal') {
+          throw new LlmRefusedError({
+            prompt: name,
+            model: result.model,
+            // The fix names a model the caller can paste. `<another model>` is not one, and a
+            // refusal is exactly the moment nobody wants to go read the catalogue.
+            alternative: MODEL_IDS.find((id) => id !== result.model) ?? DEFAULT_MODEL,
+            category: result.stopDetails?.category,
+            explanation: result.stopDetails?.explanation,
+          });
+        }
+        const parsed = await validateAsync(def.output, structuredOutputOf(result));
+        if (parsed.issues === undefined) {
+          await cache?.remember(parsed.value);
+          return parsed.value;
+        }
+        // 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') {
+          throw new LlmTruncatedError({ prompt: name, maxTokens: request.maxTokens });
+        }
+        issues = formatIssues(parsed.issues).join('; ');
+        messages = [...messages, { role: 'assistant', content: result.text }, repair(issues)];
+      }
+      throw new LlmOutputInvalidError({ prompt: name, attempts: ATTEMPTS, issues });
+    });
+  });
+}
+
+/** `undefined` for "does not fit". Wrapped so a legitimately falsy value is still a hit. */
+async function accept<TOutput extends StandardSchemaV1>(
+  schema: TOutput,
+  value: unknown,
+): Promise<{ readonly value: InferOutput<TOutput> } | undefined> {
+  if (value === undefined) return undefined;
+  const parsed = await validateAsync(schema, value);
+  return parsed.issues === undefined ? { value: parsed.value } : undefined;
+}
+
+function repair(issues: string): AiMessage {
+  return {
+    role: 'user',
+    content: `That answer failed its schema: ${issues}. Call the "${RESPOND}" tool with a value that satisfies it. Answer only through the tool.`,
+  };
+}
+
+function limitsOf(budget: LlmBudget | undefined): BudgetLimits {
+  return {
+    ...(budget?.tokensIn === undefined ? {} : { tokensIn: budget.tokensIn }),
+    ...(budget?.costPerCall === undefined ? {} : { costPerCall: budget.costPerCall }),
+  };
+}
+
+/**
+ * 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.
+ */
+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,
+  };
+}
+
+/**
+ * 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.
+ */
+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;
+  }
+}
+
+interface PromptCache {
+  lookup(): Promise<unknown>;
+  remember(value: unknown): Promise<void>;
+}
+
+/**
+ * The semantic cache for one declaration, or `undefined` when none was declared. The instance
+ * is partitioned by prompt VERSION as well as scope, which is what makes "editing a prompt
+ * requires a version bump" invalidate the cache: a bumped version reaches a different store,
+ * so an old answer cannot survive a prompt edit no matter how similar the text.
+ */
+async function openCache<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+>(
+  def: LlmDef<TInput, TOutput, V>,
+  input: InferOutput<TInput>,
+  rendered: string,
+): Promise<PromptCache | undefined> {
+  const semantic = def.cache?.semantic;
+  if (semantic === undefined) return undefined;
+  const scope = semantic.scope?.(input) ?? 'global';
+  const store = semanticCacheFor(`${def.prompt.ref}#${def.prompt.hash}::${scope}`);
+  const embedding = Array.from(await embedOne(aiEmbedder(), rendered));
+  const ttlMs = semantic.ttl === undefined ? undefined : parseDuration(semantic.ttl);
+  return {
+    async lookup(): Promise<unknown> {
+      return (await store.lookup(embedding, semantic.threshold))?.value;
+    },
+    remember(value: unknown): Promise<void> {
+      return store.remember(
+        `${def.prompt.hash}:${fnv1a(rendered).toString(16)}`,
+        embedding,
+        value,
+        ttlMs === undefined ? {} : { ttlMs },
+      );
+    },
+  };
+}

package/src/models.ts

@@ -0,0 +1,163 @@
+// The blessed models: limits, prices, and the reasoning controls each one's request surface
+// actually accepts. Apart from ./provider because those controls are NOT uniform across the
+// catalogue — one body sent to all three is a guaranteed 400 on the oldest, and a downgrade for
+// price is not a licence to send a body the provider rejects. As of 2026-08.
+
+import type { Money } from '@ultimat3/money';
+import { AiRequestInvalidError } from './errors';
+
+/**
+ * Blessed models. Opus 5 is the default; the others are explicit downgrades. IDs are exact alias
+ * strings — never append a date suffix.
+ */
+export const MODEL_IDS = ['claude-opus-5', 'claude-sonnet-5', 'claude-haiku-4-5'] as const;
+export type ModelId = (typeof MODEL_IDS)[number];
+
+export const DEFAULT_MODEL: ModelId = 'claude-opus-5';
+
+/**
+ * Reasoning depth, shallowest first — the order is load-bearing, because a model that caps where
+ * thinking may be switched off compares against it. `xhigh` is the best setting for coding and
+ * agentic work; `high` is the API default. Distinct from `maxTokens`, which is an enforced
+ * ceiling the model cannot see.
+ */
+export const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'] as const;
+export type Effort = (typeof EFFORTS)[number];
+
+/**
+ * Thinking mode. Adaptive lets the model decide depth per request and is the default on every
+ * model that has it. There is no token budget to tune — `effort` replaced it.
+ */
+export type ThinkingMode = 'adaptive' | 'disabled';
+
+/**
+ * What one model's request surface accepts. Every field here is a 400 when it is sent to a model
+ * that does not take it, which is why it is data on the spec rather than a rule in the request
+ * builder: adding a fourth model is a row, not an `if`.
+ */
+export interface ModelReasoning {
+  /** `output_config.effort`. Models older than 4.6 reject it outright. */
+  readonly effort: boolean;
+  /** `thinking: {type:'adaptive'}`. Older models take a token budget this package never sends. */
+  readonly adaptive: boolean;
+  /** Deepest effort that still accepts `thinking: 'disabled'`; `undefined` = every effort does. */
+  readonly disableThinkingUpTo: Effort | undefined;
+}
+
+export interface ModelSpec {
+  readonly id: ModelId;
+  readonly contextWindow: number;
+  readonly maxOutput: number;
+  /** Cost of one million input tokens, in minor units. */
+  readonly inputPerMillion: Money;
+  /** Cost of one million output tokens, in minor units. */
+  readonly outputPerMillion: Money;
+  /** Minimum cacheable prefix; a shorter prefix silently does not cache. */
+  readonly cacheMinimumTokens: number;
+  readonly reasoning: ModelReasoning;
+}
+
+/**
+ * A price per million tokens, in INTEGER MINOR UNITS. Token spend is money, and the house rule
+ * applies to money wherever it comes from: never a float.
+ */
+const usd = (minor: number): Money => ({ minor, currency: 'USD' });
+
+export const MODELS: Readonly<Record<ModelId, ModelSpec>> = {
+  // $5 / $25 per MTok.
+  'claude-opus-5': {
+    id: 'claude-opus-5',
+    contextWindow: 1_000_000,
+    maxOutput: 128_000,
+    inputPerMillion: usd(500),
+    outputPerMillion: usd(2_500),
+    cacheMinimumTokens: 512,
+    // Thinking is on by default here, and switching it OFF is legal only at `high` or below.
+    reasoning: { effort: true, adaptive: true, disableThinkingUpTo: 'high' },
+  },
+  // $3 / $15 per MTok. The introductory rate is deliberately NOT modelled: a price that lapses on
+  // a date makes every recorded cost depend on when it was read, and a budget that under-reports
+  // spend after the lapse is a budget that is not one. List price over-reserves, which is safe.
+  'claude-sonnet-5': {
+    id: 'claude-sonnet-5',
+    contextWindow: 1_000_000,
+    maxOutput: 128_000,
+    inputPerMillion: usd(300),
+    outputPerMillion: usd(1_500),
+    cacheMinimumTokens: 1_024,
+    reasoning: { effort: true, adaptive: true, disableThinkingUpTo: undefined },
+  },
+  // $1 / $5 per MTok. Pre-4.6, so it has neither knob: an `output_config.effort` or an adaptive
+  // `thinking` block sent here is a 400 on every request, which is what made the cheap tier
+  // uncallable while the request body was one shape for the whole catalogue.
+  'claude-haiku-4-5': {
+    id: 'claude-haiku-4-5',
+    contextWindow: 200_000,
+    maxOutput: 64_000,
+    inputPerMillion: usd(100),
+    outputPerMillion: usd(500),
+    cacheMinimumTokens: 4_096,
+    reasoning: { effort: false, adaptive: false, disableThinkingUpTo: undefined },
+  },
+};
+
+const rankOf = (effort: Effort): number => EFFORTS.indexOf(effort);
+
+/**
+ * The reasoning half of a Messages body, shaped for one model. Everything it refuses, it refuses
+ * LOCALLY with a real code — a round trip to learn a rule this file already states costs latency
+ * and teaches nothing, and the provider's own message names the field rather than the fix.
+ *
+ * A control the caller never asked for is OMITTED rather than defaulted, so a model without the
+ * knob stays callable. A control the caller did ask for is never silently dropped: a declaration
+ * that reads `effort: 'max'` and quietly runs at the default is the failure nobody can see.
+ */
+export function reasoningBody(
+  model: ModelId,
+  effort: Effort | undefined,
+  thinking: ThinkingMode | undefined,
+): Record<string, unknown> {
+  const rules = MODELS[model].reasoning;
+  const body: Record<string, unknown> = {};
+
+  if (effort !== undefined && !rules.effort) {
+    throw new AiRequestInvalidError({
+      detail: `model "${model}" has no effort control; output_config.effort is a 400 on it`,
+      fix: `drop effort from definePrompt, or set model: '${DEFAULT_MODEL}' on the llm() declaration`,
+    });
+  }
+  // Only what the caller asked for. `output_config`, not a top-level `effort` — a top-level one
+  // is silently ignored — and no block at all when nothing was requested, because a default sent
+  // as a request is indistinguishable on the wire from a declaration that asked for it.
+  if (effort !== undefined) body['output_config'] = { effort };
+
+  if (!rules.adaptive) {
+    if (thinking === 'adaptive') {
+      throw new AiRequestInvalidError({
+        detail: `model "${model}" predates adaptive thinking; a thinking block is a 400 on it`,
+        fix: `set model: '${DEFAULT_MODEL}' on the llm() declaration, or drop thinking from definePrompt`,
+      });
+    }
+    // No `thinking` field at all is exactly "no thinking" on a pre-4.6 model, so `disabled`
+    // needs nothing sent — and sending a block it may not parse would be a 400 for no gain.
+    return body;
+  }
+
+  if ((thinking ?? 'adaptive') === 'disabled') {
+    assertDisableAllowed(model, rules, effort ?? 'high');
+    body['thinking'] = { type: 'disabled' };
+    return body;
+  }
+  body['thinking'] = { type: 'adaptive', display: 'summarized' };
+  return body;
+}
+
+/** Some models cap the effort at which thinking may be switched off. Above the cap it is a 400. */
+function assertDisableAllowed(model: ModelId, rules: ModelReasoning, effort: Effort): void {
+  const cap = rules.disableThinkingUpTo;
+  if (cap === undefined || rankOf(effort) <= rankOf(cap)) return;
+  throw new AiRequestInvalidError({
+    detail: `model "${model}" allows thinking: 'disabled' only at effort '${cap}' or below, not '${effort}'`,
+    fix: `set effort: '${cap}' in definePrompt alongside thinking: 'disabled', or drop thinking from it`,
+  });
+}

package/src/pg-vector-sql.ts

@@ -0,0 +1,198 @@
+// Single responsibility: compile every pgvector statement. It lives apart from the store for
+// the same reason `@ultimat3/entity` splits `pg-sql.ts` from `pg-driver.ts` — the SQL an agent
+// has to read when a search is slow or wrong should be one file it can open, and every scalar
+// here goes through `sql` so a metadata key or a tenant id can never become syntax.
+
+import { identifier, join, literal, type SqlFragment, sql } from '@ultimat3/db';
+import type { MetadataFilter } from './vector';
+import type { VectorScope } from './vector-scope';
+
+export interface PgVectorTable {
+  readonly table: string;
+  readonly dimension: number;
+  /** The `regconfig` the FTS column and every query share. Both sides must agree or `@@` lies. */
+  readonly language: string;
+}
+
+/** Nothing matches. `in ()` is a syntax error, so an empty allow-list needs a constant. */
+const NEVER = sql`1 = 0`;
+const ALWAYS = sql`true`;
+
+/** pgvector's text input form. Float32 widens to double exactly, so no precision is invented. */
+export function vectorLiteral(vector: Float32Array): string {
+  return `[${Array.from(vector).join(',')}]`;
+}
+
+/**
+ * The scope and the per-call filter as one `where` body. Every read, write and delete is built
+ * on top of this, which is what makes "tenant filters are applied in SQL" structural rather
+ * than a convention someone has to remember at each call site.
+ */
+export function conditionsSql(scope: VectorScope, filter?: MetadataFilter): SqlFragment {
+  const parts: SqlFragment[] = [];
+  if (scope.tenant !== undefined) parts.push(sql`"tenant" = ${scope.tenant}`);
+  for (const [key, values] of Object.entries(scope.allow ?? {})) {
+    parts.push(
+      values.length === 0
+        ? NEVER
+        : sql`"metadata" ->> ${key} in (${join(values.map((value) => sql`${value}`))})`,
+    );
+  }
+  for (const [key, value] of Object.entries(filter ?? {})) {
+    parts.push(sql`"metadata" ->> ${key} = ${value}`);
+  }
+  return parts.length === 0 ? ALWAYS : join(parts, ' and ');
+}
+
+/**
+ * `x db gen` emits this. The primary key is `(tenant, id)`, not `id`: it makes a cross-tenant
+ * overwrite impossible at the storage layer instead of relying on every upsert remembering to
+ * check. An unscoped store writes the empty tenant, which is a tenant like any other.
+ */
+export function ddlSql(target: PgVectorTable): string {
+  const table = identifier(target.table).text;
+  const language = literal(target.language).text;
+  return [
+    `create extension if not exists vector;`,
+    `create table if not exists ${table} (`,
+    `  tenant text not null default '',`,
+    `  id text not null,`,
+    `  embedding vector(${target.dimension}) not null,`,
+    `  content text not null,`,
+    `  metadata jsonb not null default '{}',`,
+    `  tsv tsvector generated always as (to_tsvector(${language}, content)) stored,`,
+    `  primary key (tenant, id)`,
+    `);`,
+    `create index if not exists ${indexName(target.table, 'embedding')}`,
+    `  on ${table} using hnsw (embedding vector_cosine_ops);`,
+    `create index if not exists ${indexName(target.table, 'tsv')} on ${table} using gin (tsv);`,
+    `create index if not exists ${indexName(target.table, 'metadata')}`,
+    `  on ${table} using gin (metadata jsonb_path_ops);`,
+  ].join('\n');
+}
+
+const indexName = (table: string, column: string): string =>
+  identifier(`${table}_${column}_idx`).text;
+
+export interface PgVectorRowInput {
+  readonly id: string;
+  readonly vector: Float32Array;
+  readonly text: string;
+  readonly metadata: Readonly<Record<string, string>>;
+}
+
+export function upsertSql(
+  target: PgVectorTable,
+  tenant: string,
+  records: readonly PgVectorRowInput[],
+): SqlFragment {
+  // `::text::jsonb`, not `::jsonb`: a bound string cast straight to jsonb is JSON-encoded a
+  // SECOND time and lands as a jsonb *string*, which reads back fine and makes every
+  // `metadata ->> key` filter match nothing. Found live, invisible to a unit test of the reads.
+  const rows = records.map(
+    (record) =>
+      sql`(${tenant}, ${record.id}, ${vectorLiteral(record.vector)}::vector, ${record.text}, ${JSON.stringify(record.metadata)}::text::jsonb)`,
+  );
+  return sql`insert into ${identifier(target.table)} ("tenant", "id", "embedding", "content", "metadata")
+values ${join(rows)}
+on conflict ("tenant", "id") do update set
+  "embedding" = excluded."embedding",
+  "content" = excluded."content",
+  "metadata" = excluded."metadata"`;
+}
+
+export interface PgSearchArgs {
+  readonly scope: VectorScope;
+  readonly filter?: MetadataFilter | undefined;
+  readonly k: number;
+}
+
+/**
+ * `<=>` is cosine DISTANCE, so the score is `1 - distance` — the same scale the memory store
+ * returns. The ordering stays on the raw distance, ascending, inside a subquery: HNSW answers
+ * `order by embedding <=> $1` and nothing else, and `order by 1 - (...) desc` is a seq scan.
+ */
+export function searchSql(
+  target: PgVectorTable,
+  vector: Float32Array,
+  args: PgSearchArgs,
+): SqlFragment {
+  return sql`select "id", "content", "metadata", 1 - distance as score
+from (
+  select "id", "content", "metadata", "embedding" <=> ${vectorLiteral(vector)}::vector as distance
+  from ${identifier(target.table)}
+  where ${conditionsSql(args.scope, args.filter)}
+  order by distance
+  limit ${args.k}
+) top
+order by distance`;
+}
+
+export function textSql(target: PgVectorTable, query: string, args: PgSearchArgs): SqlFragment {
+  return sql`select "id", "content", "metadata", ts_rank_cd("tsv", q) as score
+from ${identifier(target.table)}, websearch_to_tsquery(${target.language}::regconfig, ${query}) q
+where "tsv" @@ q and ${conditionsSql(args.scope, args.filter)}
+order by score desc
+limit ${args.k}`;
+}
+
+export interface PgHybridArgs extends PgSearchArgs {
+  readonly candidates: number;
+  readonly rrfK: number;
+}
+
+/**
+ * Reciprocal-rank fusion, done in SQL. Two candidate sets are ranked independently and fused by
+ * `1 / (rrfK + rank)` — identical to `fuse()` in `vector.ts`, so dev and production order hits
+ * the same way. Both CTEs carry the SAME scope conditions: fusing an unfiltered lexical ranking
+ * into a filtered dense one would leak the other tenant's rows through the back door.
+ */
+export function hybridSql(
+  target: PgVectorTable,
+  query: string,
+  vector: Float32Array,
+  args: PgHybridArgs,
+): SqlFragment {
+  const table = identifier(target.table);
+  const where = conditionsSql(args.scope, args.filter);
+  return sql`with dense as (
+  select "tenant", "id", row_number() over (order by distance) as rank
+  from (
+    select "tenant", "id", "embedding" <=> ${vectorLiteral(vector)}::vector as distance
+    from ${table}
+    where ${where}
+    order by distance
+    limit ${args.candidates}
+  ) top
+), lexical as (
+  select "tenant", "id", row_number() over (order by relevance desc) as rank
+  from (
+    select "tenant", "id", ts_rank_cd("tsv", q) as relevance
+    from ${table}, websearch_to_tsquery(${target.language}::regconfig, ${query}) q
+    where "tsv" @@ q and ${where}
+    order by relevance desc
+    limit ${args.candidates}
+  ) top
+), fused as (
+  select "tenant", "id", sum(1.0 / (${args.rrfK} + rank))::double precision as score
+  from (
+    select "tenant", "id", rank from dense
+    union all
+    select "tenant", "id", rank from lexical
+  ) ranked
+  group by "tenant", "id"
+)
+select d."id", d."content", d."metadata", f.score
+from fused f join ${table} d on d."tenant" = f."tenant" and d."id" = f."id"
+order by f.score desc, d."id" asc
+limit ${args.k}`;
+}
+
+export function deleteSql(
+  target: PgVectorTable,
+  scope: VectorScope,
+  ids: readonly string[],
+): SqlFragment {
+  return sql`delete from ${identifier(target.table)}
+where "id" in (${join(ids.map((id) => sql`${id}`))}) and ${conditionsSql(scope)}`;
+}