@ultimat3/ai 1.0.0

package/src/remote-embedder.ts

@@ -0,0 +1,143 @@
+// The production embedder: one HTTP client for the `/v1/embeddings` request shape.
+//
+// Anthropic ships no embeddings endpoint, and its documented partner speaks the same
+// `{ model, input[] }` -> `{ data: [{ index, embedding }] }` shape as every other hosted or
+// self-hosted embedder worth pointing at. So there is ONE remote embedder rather than one per
+// vendor: `baseUrl` selects the provider and nothing else changes. A second class per vendor
+// would be a second thing to learn for a difference that does not exist on the wire.
+
+import type { Embedder } from './embeddings';
+import { normalize } from './embeddings';
+import { AiKeyMissingError, AiTransportError, EmbedderDimMismatchError } from './errors';
+
+const API_KEY_ENV = 'EMBEDDINGS_API_KEY';
+const DEFAULT_BASE_URL = 'https://api.voyageai.com/v1';
+/** Providers cap a batch around 128 inputs; 96 leaves headroom for long texts. */
+const DEFAULT_BATCH_SIZE = 96;
+const DETAIL_LIMIT = 300;
+
+export interface RemoteEmbedderInput {
+  /** The provider's model id. Doubles as the embedder name, so a store records what wrote it. */
+  readonly name: string;
+  /**
+   * Declared once, checked on EVERY response. A provider that quietly changes width would
+   * otherwise poison a store one batch at a time, and cosine similarity does not complain.
+   */
+  readonly dimension: number;
+  /** Reads `EMBEDDINGS_API_KEY` when omitted. Absent at call time is a labelled throw. */
+  readonly apiKey?: string;
+  /** Any endpoint speaking the same shape. Defaults to Voyage. */
+  readonly baseUrl?: string;
+  /** Inputs per request. Larger calls are split; the provider's own cap is not the caller's. */
+  readonly batchSize?: number;
+  /** Injectable so a test can assert the request body without a network. Defaults to `fetch`. */
+  readonly fetch?: typeof fetch;
+}
+
+export class RemoteEmbedder implements Embedder {
+  readonly name: string;
+  readonly dimension: number;
+  private readonly config: RemoteEmbedderInput;
+
+  constructor(input: RemoteEmbedderInput) {
+    this.name = input.name;
+    this.dimension = input.dimension;
+    this.config = input;
+  }
+
+  /**
+   * Batches are issued in sequence, not in parallel: a 50k-chunk corpus fanned out at once
+   * reproduces the rate limit it is trying to get through, and order must survive either way.
+   */
+  async embed(texts: readonly string[]): Promise<readonly Float32Array[]> {
+    if (texts.length === 0) return [];
+    const size = this.config.batchSize ?? DEFAULT_BATCH_SIZE;
+    const vectors: Float32Array[] = [];
+    for (let start = 0; start < texts.length; start += size) {
+      vectors.push(...(await this.batch(texts.slice(start, start + size))));
+    }
+    return vectors;
+  }
+
+  private async batch(texts: readonly string[]): Promise<readonly Float32Array[]> {
+    const apiKey = this.config.apiKey ?? Bun.env[API_KEY_ENV];
+    if (apiKey === undefined || apiKey === '') {
+      throw new AiKeyMissingError({ provider: this.name, envVar: API_KEY_ENV });
+    }
+    const doFetch = this.config.fetch ?? fetch;
+    const response = await doFetch(`${this.config.baseUrl ?? DEFAULT_BASE_URL}/embeddings`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ model: this.name, input: texts }),
+    });
+    if (!response.ok) {
+      throw new AiTransportError({
+        provider: this.name,
+        status: response.status,
+        detail: (await response.text().catch(() => '')).slice(0, DETAIL_LIMIT),
+      });
+    }
+    return this.decode((await response.json()) as unknown, texts.length);
+  }
+
+  private decode(payload: unknown, expected: number): readonly Float32Array[] {
+    const data = asRecord(payload)?.['data'];
+    if (!Array.isArray(data) || data.length !== expected) {
+      throw this.malformed(`expected ${expected} embeddings, got ${countOf(data)}`);
+    }
+    // Keyed by the provider's own `index` rather than array position: the two agree today, and
+    // a store written in the wrong order is a silent relevance collapse if they ever stop.
+    const vectors = new Array<Float32Array | undefined>(expected);
+    for (let position = 0; position < data.length; position += 1) {
+      const entry = asRecord(data[position]);
+      const index = entry?.['index'];
+      const slot = typeof index === 'number' ? index : position;
+      if (!Number.isInteger(slot) || slot < 0 || slot >= expected) {
+        throw this.malformed(`embedding at position ${position} claims index ${String(index)}`);
+      }
+      vectors[slot] = this.vectorOf(entry?.['embedding'], position);
+    }
+    const missing = vectors.indexOf(undefined);
+    if (missing !== -1) throw this.malformed(`no embedding for input ${missing}`);
+    return vectors.filter((vector): vector is Float32Array => vector !== undefined);
+  }
+
+  /**
+   * L2 normalised on the way in, like every other embedder here, so `cosine` stays a dot
+   * product. Providers already return unit vectors, which makes this a no-op — but "already"
+   * is a property of today's provider, not of the interface.
+   */
+  private vectorOf(raw: unknown, position: number): Float32Array {
+    if (!Array.isArray(raw))
+      throw this.malformed(`embedding at position ${position} is not an array`);
+    if (raw.length !== this.dimension) {
+      throw new EmbedderDimMismatchError({
+        embedder: this.name,
+        expected: this.dimension,
+        received: raw.length,
+      });
+    }
+    const vector = new Float32Array(raw.length);
+    for (let i = 0; i < raw.length; i += 1) {
+      const value: unknown = raw[i];
+      if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw this.malformed(`embedding at position ${position} has a non-numeric component`);
+      }
+      vector[i] = value;
+    }
+    return normalize(vector);
+  }
+
+  private malformed(detail: string): AiTransportError {
+    return new AiTransportError({ provider: this.name, detail });
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}
+
+function countOf(data: unknown): string {
+  return Array.isArray(data) ? String(data.length) : 'no data array';
+}

package/src/runtime.ts

@@ -0,0 +1,77 @@
+// The ambient AI runtime an `llm()` action calls into: the gateway that serves every model
+// call, the embedder the semantic cache keys on, and one semantic cache per declared scope.
+//
+// Ambient rather than injected, for the same reason the budget ledger is: an `llm()`
+// declaration is evaluated at module scope, long before a provider, an API key or a request
+// exists. Boot installs one runtime, a test installs a fake, and there is no second way for
+// an action to reach a provider — which is what keeps budgets and cost accounting
+// un-bypassable rather than merely recommended.
+
+import type { SemanticCache } from '@ultimat3/cache';
+import { createMemorySemanticCache } from '@ultimat3/cache';
+import type { Embedder } from './embeddings';
+import { HashEmbedder } from './embeddings';
+import { AiGatewayMissingError } from './errors';
+import type { Gateway } from './gateway';
+
+export interface AiRuntimeInput {
+  readonly gateway: Gateway;
+  /**
+   * Keys the semantic cache. Defaults to `HashEmbedder`: deterministic, offline, and lexical
+   * rather than semantic — at the thresholds an LLM cache runs at that is a near-exact-match
+   * cache, which is the safe way to be wrong. Install a real embedder to get paraphrase hits.
+   */
+  readonly embedder?: Embedder;
+  /** One cache per scope key. Defaults to the in-memory driver; pgvector in production. */
+  readonly semanticCache?: (scope: string) => SemanticCache;
+}
+
+interface AiRuntime {
+  readonly gateway: Gateway;
+  readonly embedder: Embedder;
+  readonly semanticCache: (scope: string) => SemanticCache;
+}
+
+let runtime: AiRuntime | undefined;
+const caches = new Map<string, SemanticCache>();
+
+export function configureAi(input: AiRuntimeInput): void {
+  runtime = {
+    gateway: input.gateway,
+    embedder: input.embedder ?? new HashEmbedder(),
+    semanticCache: input.semanticCache ?? (() => createMemorySemanticCache()),
+  };
+  // A new runtime means a new embedder and a new gateway; vectors from the old one are not
+  // comparable to vectors from the new one, and a stale hit would answer the wrong question.
+  caches.clear();
+}
+
+/** The installed gateway. `prompt` names the caller so the miss says what was about to run. */
+export function aiGateway(prompt: string): Gateway {
+  if (runtime === undefined) throw new AiGatewayMissingError({ prompt });
+  return runtime.gateway;
+}
+
+export function aiEmbedder(): Embedder {
+  return runtime?.embedder ?? new HashEmbedder();
+}
+
+/**
+ * The cache for one scope. Scopes are separate CACHE INSTANCES, never a filter over a shared
+ * one: cosine similarity has no notion of a tenant, so two tenants asking near-identical
+ * questions of a shared cache is one tenant reading the other's answer. Partitioning is the
+ * only thing that makes that structurally impossible.
+ */
+export function semanticCacheFor(scope: string): SemanticCache {
+  const existing = caches.get(scope);
+  if (existing !== undefined) return existing;
+  const created = runtime?.semanticCache(scope) ?? createMemorySemanticCache();
+  caches.set(scope, created);
+  return created;
+}
+
+/** Test-only reset. Module-level state otherwise leaks between test files. */
+export function resetAiRuntime(): void {
+  runtime = undefined;
+  caches.clear();
+}

package/src/scorers.ts

@@ -0,0 +1,107 @@
+// What a scorer is, and the built-in ones.
+//
+// A scorer returns 0..1 for one answer. Deterministic scorers are preferred and cheap; a judge
+// 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 type { Gateway } from './gateway';
+import type { Prompt } from './prompt';
+
+/** A scorer returns 0..1. Deterministic scorers are preferred; judges are a last resort. */
+export interface Scorer {
+  readonly name: string;
+  score(input: { output: string; expected?: string }): Promise<number> | number;
+}
+
+/** Scores outside 0..1 are a scorer bug; clamping keeps one from skewing a whole run's mean. */
+export const clampScore = (n: number): number => (n < 0 ? 0 : n > 1 ? 1 : n);
+
+/** Exact match after trimming. The strictest and cheapest scorer; prefer it when it fits. */
+export const exact: Scorer = {
+  name: 'exact',
+  score: ({ output, expected }) => (output.trim() === (expected ?? '').trim() ? 1 : 0),
+};
+
+/** Case-insensitive substring. For "did it mention X" without pinning the phrasing. */
+export const contains: Scorer = {
+  name: 'contains',
+  score: ({ output, expected }) =>
+    expected !== undefined && output.toLowerCase().includes(expected.toLowerCase()) ? 1 : 0,
+};
+
+/** Output parses as JSON. Pairs with a prompt that declares an `output` schema. */
+export const jsonValid: Scorer = {
+  name: 'json-valid',
+  score: ({ output }) => {
+    try {
+      JSON.parse(output);
+      return 1;
+    } catch {
+      return 0;
+    }
+  },
+};
+
+/** Output parses AND satisfies the required keys of `schema`. */
+export function jsonSchemaValid(required: readonly string[]): Scorer {
+  return {
+    name: 'json-schema-valid',
+    score: ({ output }) => {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(output);
+      } catch {
+        return 0;
+      }
+      if (typeof parsed !== 'object' || parsed === null) return 0;
+      const record = parsed as Record<string, unknown>;
+      const present = required.filter((key) => record[key] !== undefined).length;
+      return required.length === 0 ? 1 : present / required.length;
+    },
+  };
+}
+
+/** Graded numeric closeness — 1 at exact, 0 at or beyond `tolerance`. */
+export function numericTolerance(tolerance: number): Scorer {
+  return {
+    name: 'numeric-tolerance',
+    score: ({ output, expected }) => {
+      const got = Number.parseFloat(output.trim());
+      const want = Number.parseFloat((expected ?? '').trim());
+      if (Number.isNaN(got) || Number.isNaN(want)) return 0;
+      const delta = Math.abs(got - want);
+      return delta >= tolerance ? 0 : 1 - delta / tolerance;
+    },
+  };
+}
+
+/**
+ * LLM-as-judge. The judge prompt is itself a versioned artifact, so a judge change is a new
+ * hash and every score it produced is re-attributable. A judge whose prompt drifts silently
+ * is a measuring instrument that lies.
+ */
+export function llmJudge(input: {
+  readonly gateway: Gateway;
+  readonly judge: Prompt<{ output: string; expected: string }>;
+  readonly maxTokens?: number;
+}): Scorer {
+  return {
+    name: `llm-judge@${input.judge.hash}`,
+    async score({ output, expected }) {
+      const generated = await input.gateway.generate({
+        messages: [
+          {
+            role: 'user',
+            content: input.judge.render({ output, expected: expected ?? '' }),
+          },
+        ],
+        maxTokens: input.maxTokens ?? 256,
+        ...(input.judge.system !== undefined ? { system: input.judge.system } : {}),
+        ...(input.judge.model !== undefined ? { model: input.judge.model } : {}),
+      });
+      // The judge is asked for a bare 0..1; anything else scores 0 rather than guessing.
+      const parsed = Number.parseFloat(generated.text.trim());
+      return Number.isNaN(parsed) ? 0 : clampScore(parsed);
+    },
+  };
+}

package/src/sse.ts

@@ -0,0 +1,81 @@
+// Single responsibility: framing a Server-Sent Events byte stream into `{ event, data }`
+// frames. Protocol level only — nothing here knows what an Anthropic message looks like.
+//
+// Hand written rather than a dependency: the part of the SSE spec that matters to a provider
+// stream is a boundary search and a field split, and the only interesting property — that a
+// frame may arrive split at any byte offset — is exactly what a library would hide.
+
+export interface SseFrame {
+  /** The `event:` field, or `message` when the frame omits one — the spec's default. */
+  readonly event: string;
+  /** Every `data:` line of the frame, joined with `\n` as the spec requires. */
+  readonly data: string;
+}
+
+/** `\r\n\r\n`, `\n\n` and `\r\r` all end a frame. A lone trailing `\r` is not yet a boundary. */
+const BOUNDARY = /\r\n\r\n|\n\n|\r\r/;
+const LINE = /\r\n|\n|\r/;
+
+/**
+ * Split what has arrived so far into complete frames plus the unterminated remainder. Pure and
+ * synchronous, so a test can feed it a stream chopped at any offset — which is the only thing
+ * a network does that a fixture does not.
+ */
+export function decodeSse(buffer: string): { readonly frames: readonly SseFrame[]; rest: string } {
+  const frames: SseFrame[] = [];
+  let rest = buffer;
+  for (;;) {
+    const boundary = BOUNDARY.exec(rest);
+    if (boundary === null) break;
+    const frame = frameOf(rest.slice(0, boundary.index));
+    if (frame !== undefined) frames.push(frame);
+    rest = rest.slice(boundary.index + boundary[0].length);
+  }
+  return { frames, rest };
+}
+
+/** One frame's block of lines. `undefined` for a heartbeat comment, which carries no data. */
+function frameOf(block: string): SseFrame | undefined {
+  let event = 'message';
+  const data: string[] = [];
+  for (const line of block.split(LINE)) {
+    // A line starting with `:` is a comment — providers send them to hold the socket open.
+    if (line === '' || line.startsWith(':')) continue;
+    const colon = line.indexOf(':');
+    const field = colon === -1 ? line : line.slice(0, colon);
+    const raw = colon === -1 ? '' : line.slice(colon + 1);
+    const value = raw.startsWith(' ') ? raw.slice(1) : raw;
+    if (field === 'event') event = value;
+    if (field === 'data') data.push(value);
+  }
+  if (data.length === 0) return undefined;
+  return { event, data: data.join('\n') };
+}
+
+/**
+ * Read a response body as SSE frames. The trailing partial buffer IS flushed as a final frame:
+ * a stream cut mid-message must fail loudly at the consumer that parses it, and dropping the
+ * tail silently would turn a truncated answer into a complete-looking one.
+ */
+export async function* readSse(body: ReadableStream<Uint8Array>): AsyncGenerator<SseFrame> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const decoded = decodeSse(buffer);
+      buffer = decoded.rest;
+      for (const frame of decoded.frames) yield frame;
+    }
+    buffer += decoder.decode();
+    const tail = frameOf(buffer);
+    if (tail !== undefined) yield tail;
+  } finally {
+    // Releases the socket when a consumer abandons the stream half way — `for await` runs
+    // this through the generator's `return()`, so an early `break` does not leak a connection.
+    await reader.cancel().catch(() => undefined);
+  }
+}

package/src/tools.ts

@@ -0,0 +1,116 @@
+// Project framework `action`s into LLM tool definitions.
+//
+// This is the SAME projection @ultimat3/mcp performs, in a different wire format: an
+// in-app agent calling a tool through the gateway and an external agent calling it over
+// MCP both end at `action.run`, so they authorize identically. There is no "LLM
+// permissions" concept in Ultimate, because there is no second authz system.
+//
+// The JSON Schema type and the projectable-primitive shape are declared here rather than
+// imported from @ultimat3/mcp: that package is the same tier, so importing it would be a
+// boundary error. Both packages describe the same structural contract.
+
+import type { Actor } from '@ultimat3/core';
+
+/** 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;
+}
+
+/** Anthropic Messages API tool definition shape (`tools[]` on a request). */
+export interface LlmTool {
+  readonly name: string;
+  readonly description: string;
+  readonly input_schema: JsonSchema;
+  /**
+   * Strict mode guarantees the model's `input` validates against the schema exactly.
+   * Requires `additionalProperties: false` plus `required` — which every projected action
+   * schema already has, so it is on by default.
+   */
+  readonly strict?: boolean;
+}
+
+/** A tool call the model asked for, as it arrives in a `tool_use` content block. */
+export interface LlmToolCall {
+  readonly id: string;
+  readonly name: string;
+  readonly input: Record<string, unknown>;
+}
+
+/** The result sent back as a `tool_result` block. `isError` is an expected failure. */
+export interface LlmToolResult {
+  readonly toolUseId: string;
+  readonly content: string;
+  readonly isError?: boolean;
+}
+
+/**
+ * The surface a projectable primitive must expose. Structurally identical to
+ * @ultimat3/mcp's `ProjectablePrimitive` — one contract, two wire formats.
+ */
+export interface ProjectableAction {
+  readonly name: string;
+  readonly description?: string;
+  readonly mcp?: { readonly expose?: boolean; readonly description?: string };
+  readonly inputJsonSchema?: JsonSchema;
+  run(args: { input: unknown; actor: Actor }): Promise<unknown>;
+}
+
+const EMPTY_SCHEMA: JsonSchema = { type: 'object', properties: {}, additionalProperties: false };
+
+/** One action → one LLM tool definition. Opt-in via `mcp.expose`, same flag as MCP. */
+export function toLlmTool(action: ProjectableAction): LlmTool {
+  return {
+    name: action.name,
+    description:
+      action.mcp?.description ?? action.description ?? `Run the "${action.name}" action.`,
+    input_schema: action.inputJsonSchema ?? EMPTY_SCHEMA,
+    strict: true,
+  };
+}
+
+/** Every exposed action as a tool definition, in stable name order. */
+export function toLlmTools(actions: readonly ProjectableAction[]): readonly LlmTool[] {
+  return actions
+    .filter((a) => a.mcp?.expose === true)
+    .map(toLlmTool)
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+/**
+ * Execute a model-requested tool call against the projected actions. The actor comes from
+ * the request context, NOT from the model — a model cannot name the identity it acts as.
+ */
+export async function runLlmToolCall(
+  actions: readonly ProjectableAction[],
+  call: LlmToolCall,
+  actor: Actor,
+): Promise<LlmToolResult> {
+  const action = actions.find((a) => a.name === call.name && a.mcp?.expose === true);
+  if (action === undefined) {
+    return { toolUseId: call.id, content: `unknown tool: ${call.name}`, isError: true };
+  }
+  try {
+    const output = await action.run({ input: call.input, actor });
+    return { toolUseId: call.id, content: JSON.stringify(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 };
+  }
+}
+
+function describeFailure(error: unknown): string {
+  if (typeof error !== 'object' || error === null) return 'tool failed';
+  const e = error as { code?: unknown; cause?: unknown; fix?: unknown };
+  if (typeof e.code !== 'string') return 'tool failed';
+  const cause = typeof e.cause === 'string' ? e.cause : 'unknown';
+  const fix = typeof e.fix === 'string' ? e.fix : '';
+  return fix === '' ? `${e.code}: ${cause}` : `${e.code}: ${cause} (fix: ${fix})`;
+}

package/src/vector-scope.ts

@@ -0,0 +1,76 @@
+// The security envelope a vector store carries: the tenant it is bound to, and the metadata
+// values a policy leaves visible. Kept separate from the stores because both the in-memory dev
+// store and the Postgres one must enforce the SAME envelope — a leak that only reproduces in
+// 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 { VectorScopeWidenedError } from './errors';
+
+export interface VectorScope {
+  /** Bound tenant. Present ⇒ every read, write and delete carries `tenant = <this>`. */
+  readonly tenant?: string | undefined;
+  /**
+   * A policy projected onto metadata: per key, the exact values that stay visible. Default
+   * deny — a row missing the key is invisible, and an empty list matches nothing at all.
+   */
+  readonly allow?: Readonly<Record<string, readonly string[]>> | undefined;
+}
+
+/** The store as constructed: every tenant, every row. The backfill and migration path. */
+export const UNSCOPED: VectorScope = Object.freeze({});
+
+/** The tenant column value a row carries when its store had no tenant bound. */
+export const NO_TENANT = '';
+
+export function tenantOf(scope: VectorScope): string {
+  return scope.tenant ?? NO_TENANT;
+}
+
+/**
+ * Derive a narrower scope. Tenants may be SET once, never changed; allow-lists intersect, so a
+ * derived scope can add a key or shrink a list but can never restore a value the parent removed.
+ */
+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);
+  return {
+    ...(tenant === undefined ? {} : { tenant }),
+    ...(allow === undefined ? {} : { allow }),
+  };
+}
+
+function narrowTenant(
+  store: string,
+  base: string | undefined,
+  next: string | undefined,
+): string | undefined {
+  if (next === undefined) return base;
+  if (base === undefined || base === next) return next;
+  throw new VectorScopeWidenedError({ store, held: base, requested: next });
+}
+
+function narrowAllow(
+  base: Readonly<Record<string, readonly string[]>> | undefined,
+  next: Readonly<Record<string, readonly string[]>> | undefined,
+): Readonly<Record<string, readonly string[]>> | undefined {
+  if (next === undefined) return base;
+  const merged: Record<string, readonly string[]> = { ...(base ?? {}) };
+  for (const [key, values] of Object.entries(next)) {
+    const held = merged[key];
+    merged[key] = held === undefined ? values : values.filter((value) => held.includes(value));
+  }
+  return merged;
+}
+
+/** Whether one stored row survives the scope. The in-memory twin of the SQL conditions. */
+export function scopeAdmits(
+  scope: VectorScope,
+  tenant: string,
+  metadata: Readonly<Record<string, string>>,
+): boolean {
+  if (scope.tenant !== undefined && scope.tenant !== tenant) return false;
+  return Object.entries(scope.allow ?? {}).every(([key, values]) => {
+    const value = metadata[key];
+    return value !== undefined && values.includes(value);
+  });
+}