@ultimat3/ai 23.0.0 → 25.0.0

package/src/openai-provider.ts

@@ -12,11 +12,9 @@ import { isSecret, revealSecret } from '@ultimat3/core';
 import { detailOf, withoutKey } from './error-body';
 import { AiKeyMissingError, AiRequestInvalidError, AiTransportError } from './errors';
 import type { AiFetch } from './fetch-seam';
+import { resolveModel } from './model-resolve';
 import type { ModelId } from './models';
 import { chatCompletionBody } from './openai-body';
-// Imported for its registration side effect: a provider that cannot price what it serves throws
-// X_AI_MODEL_UNKNOWN at the first call, and the specs belong with the format that names them.
-import './openai-models';
 import type { ChatAnswer } from './openai-wire';
 import { ChatCompletionStream, parseChatCompletion } from './openai-wire';
 import type {
@@ -28,6 +26,7 @@ import type {
 } from './provider';
 import { costOf, estimateInputTokens, estimateTextTokens, requiresStreaming } from './provider';
 import { readSse } from './sse';
+import type { LlmToolCall } from './tools';
 
 const API_KEY_ENV = 'OPENAI_API_KEY';
 const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
@@ -75,7 +74,7 @@ export interface OpenAiProviderInput {
  *
  * ```ts
  * // OpenAI
- * openAiProvider({ apiKey: openAiKey, models: [...OPENAI_MODEL_IDS] })
+ * openAiProvider({ apiKey: openAiKey, models: [appModel] })   // ids your app registerModel-ed
  * // a company gateway, vLLM, Ollama — same class, one different field
  * openAiProvider({ apiKey: gatewayKey, baseUrl: 'https://llm.acme.internal/v1', models: ['acme-70b'] })
  * ```
@@ -87,23 +86,22 @@ export function openAiProvider(input: OpenAiProviderInput): Provider {
 class OpenAiProvider implements Provider {
   readonly name: string;
   readonly models: readonly ModelId[];
-  private readonly defaultModel: ModelId;
   private readonly config: OpenAiProviderInput;
 
-  constructor(config: OpenAiProviderInput) {
-    const [first] = config.models;
-    if (first === undefined) {
+  // `| undefined` for the reason `AnthropicProvider`'s is: no argument at all, from plain JS or a
+  // cast, is the empty-list boot mistake and gets its coded refusal, never a TypeError.
+  constructor(config: OpenAiProviderInput | undefined) {
+    if (config === undefined || (config.models ?? []).length === 0) {
       // A provider serving nothing can never be routed to, so it is a boot mistake that would
       // otherwise surface as "no provider serves <model>" — a true statement about the wrong thing.
       throw new AiRequestInvalidError({
         detail:
           'openAiProvider was given an empty models list, so the gateway can never route to it',
-        fix: 'pass models: [...OPENAI_MODEL_IDS] to openAiProvider, or the ids your endpoint serves',
+        fix: "openAiProvider({ …, models: ['<id>'] })   # the ids your endpoint serves, each one your app registerModel-ed",
       });
     }
     this.name = config.name ?? 'openai';
     this.models = config.models;
-    this.defaultModel = first;
     this.config = config;
   }
 
@@ -113,15 +111,12 @@ class OpenAiProvider implements Provider {
    * open socket past the HTTP timeout and fails after the completion was generated and billed.
    */
   async generate(request: GenerateRequest): Promise<GenerateResult> {
-    // Resolved BEFORE the transport question is asked. `requiresStreaming` clamps `maxTokens` to
-    // the model's `maxOutput`, and its own fallback for an absent model is the framework's
-    // `DEFAULT_MODEL` — a Claude id no OpenAI-format endpoint serves. Sized against that, a
-    // request naming no model was measured against somebody else's ceiling, seventy lines above
-    // `modelOf`'s comment saying this provider never does that.
-    const model = this.modelOf(request);
+    // Resolved BEFORE the socket: a direct call naming no model is refused here, never answered on
+    // this provider's first listed model — the app's three places are the only ones.
+    const model = resolveModel('provider', request.model);
     if (requiresStreaming({ ...request, model })) return this.assemble(request);
     const response = await this.send(
-      chatCompletionBody({ request, model, stream: false }),
+      chatCompletionBody({ request, model, stream: false, provider: this.name }),
       false,
       request.signal,
     );
@@ -130,9 +125,9 @@ class OpenAiProvider implements Provider {
   }
 
   async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
-    const model = this.modelOf(request);
+    const model = resolveModel('provider', request.model);
     const response = await this.send(
-      chatCompletionBody({ request, model, stream: true }),
+      chatCompletionBody({ request, model, stream: true, provider: this.name }),
       true,
       request.signal,
     );
@@ -171,7 +166,7 @@ class OpenAiProvider implements Provider {
 
   /** One parsed answer, priced. The only place `cost` is applied — the provider owns prices. */
   private result(request: GenerateRequest, model: ModelId, answer: ChatAnswer): GenerateResult {
-    const usage = answer.usage ?? estimatedUsage(request, answer.text);
+    const usage = answer.usage ?? estimatedUsage(request, answer.text, answer.toolCalls);
     return {
       model,
       text: answer.text,
@@ -183,15 +178,6 @@ class OpenAiProvider implements Provider {
     };
   }
 
-  /**
-   * The model this request is for. The gateway resolves one before it routes, so the fallback is
-   * only ever reached by a direct call — and it is this provider's first model, never the
-   * framework's `DEFAULT_MODEL`, which names a Claude id no OpenAI-format endpoint serves.
-   */
-  private modelOf(request: GenerateRequest): ModelId {
-    return request.model ?? this.defaultModel;
-  }
-
   /**
    * The one place a request leaves the process. A non-2xx becomes an `AiTransportError` carrying
    * its status, because the gateway decides whether to retry from that status and a body parsed as
@@ -269,11 +255,22 @@ class OpenAiProvider implements Provider {
  * reconciling a real call against zero, which refunds the reservation in full and turns the ledger
  * into a decoration. An estimate is wrong by a few percent in the safe direction; zero is wrong by
  * all of it.
+ *
+ * The tool calls are output too, and for an `llm()` answer they are ALL of it: the answer is one
+ * `respond` call with no text beside it, so counting `text` alone estimated it at zero.
  */
-export function estimatedUsage(request: GenerateRequest, text: string): TokenUsage {
+export function estimatedUsage(
+  request: GenerateRequest,
+  text: string,
+  toolCalls: readonly LlmToolCall[],
+): TokenUsage {
+  let output = estimateTextTokens(text);
+  for (const call of toolCalls) {
+    output += estimateTextTokens(call.name) + estimateTextTokens(JSON.stringify(call.input));
+  }
   return {
     inputTokens: estimateInputTokens(request),
-    outputTokens: estimateTextTokens(text),
+    outputTokens: output,
     cacheReadTokens: 0,
     cacheWriteTokens: 0,
   };

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;
 }
 
 /**
@@ -99,7 +104,10 @@ export function parseChatCompletion(raw: unknown, provider: string): ChatAnswer
   const choice = asRecord(Array.isArray(record['choices']) ? record['choices'][0] : undefined);
   if (choice === undefined) throw malformed(provider, 'the response carried no choices');
   const message = asRecord(choice['message']) ?? {};
-  const refusal = typeof message['refusal'] === 'string' ? message['refusal'] : undefined;
+  // Non-empty, as the stream decides it: a gateway that always serialises the field sends
+  // `"refusal": ""` beside a real answer, and that body must not refuse here and answer streamed.
+  const declined = message['refusal'];
+  const refusal = typeof declined === 'string' && declined !== '' ? declined : undefined;
   const finish = parseFinishReason(choice['finish_reason']);
   return {
     text: typeof message['content'] === 'string' ? message['content'] : '',

package/src/pg-vector-sql.ts

@@ -115,6 +115,8 @@ export interface PgSearchArgs {
  * `<=>` 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.
+ * Only the OUTER sort, over at most `k` rows, breaks a tie by `"id"` as `vector.ts` does — so
+ * which tied rows make the page at the `limit` boundary is still the index's call.
  */
 export function searchSql(
   target: PgVectorTable,
@@ -129,14 +131,14 @@ from (
   order by distance
   limit ${args.k}
 ) top
-order by distance`;
+order by distance, "id" asc`;
 }
 
 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
+order by score desc, "id" asc
 limit ${args.k}`;
 }
 
@@ -149,7 +151,9 @@ export interface PgHybridArgs extends PgSearchArgs {
  * 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.
+ * into a filtered dense one would leak the other tenant's rows through the back door. A rank is a
+ * position, so each window breaks a tie by `"id"` as `vector.ts` does; the dense candidate scan
+ * keeps its bare `order by distance`, the shape HNSW answers.
  */
 export function hybridSql(
   target: PgVectorTable,
@@ -160,7 +164,7 @@ export function hybridSql(
   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
+  select "tenant", "id", row_number() over (order by distance, "id" asc) as rank
   from (
     select "tenant", "id", "embedding" <=> ${vectorLiteral(vector)}::vector as distance
     from ${table}
@@ -169,12 +173,12 @@ export function hybridSql(
     limit ${args.candidates}
   ) top
 ), lexical as (
-  select "tenant", "id", row_number() over (order by relevance desc) as rank
+  select "tenant", "id", row_number() over (order by relevance desc, "id" asc) 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
+    order by relevance desc, "id" asc
     limit ${args.candidates}
   ) top
 ), fused as (
@@ -211,7 +215,7 @@ export function deleteSql(
   ids: readonly string[],
 ): SqlFragment {
   // `in ()` is a syntax error, so an empty list takes the same constant an empty allow-list does.
-  // `PgVectorStore.delete` returns before it gets here, but this function is exported from
+  // `PostgresVectorStore.delete` returns before it gets here, but this function is exported from
   // `index.ts` — an app compiling the statement itself is a caller too.
   const byId = ids.length === 0 ? NEVER : sql`"id" in (${join(ids.map((id) => sql`${id}`))})`;
   return sql`delete from ${identifier(target.table)}

package/src/pg-vector.ts

@@ -24,9 +24,9 @@ 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 {
+export interface PostgresVectorStoreInput {
   /** The table. Also the store's name in errors, and the stem of every index name. */
   readonly name: string;
   readonly dimension: number;
@@ -49,18 +49,18 @@ interface HitRow {
   readonly score: unknown;
 }
 
-export class PgVectorStore implements VectorStore {
+export class PostgresVectorStore implements VectorStore {
   readonly name: string;
   readonly dimension: number;
   readonly scope: VectorScope;
-  private readonly input: PgVectorStoreInput;
+  private readonly input: PostgresVectorStoreInput;
   private readonly target: PgVectorTable;
 
-  constructor(input: PgVectorStoreInput) {
+  constructor(input: PostgresVectorStoreInput) {
     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,11 +75,11 @@ 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({
+  scoped(scope: VectorScope): PostgresVectorStore {
+    return new PostgresVectorStore({
       ...this.input,
       scope: narrowScope(this.name, this.scope, scope),
     });
@@ -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
@@ -176,6 +179,14 @@ export class PgVectorStore implements VectorStore {
   }
 }
 
+/**
+ * The one way to build the pgvector-backed store — the twin of `memoryVectorStore()`. The class is
+ * a type in the barrel only (`X_FACTORY_NAME_SPELLING`), so `new` is never a second spelling.
+ */
+export function postgresVectorStore(input: PostgresVectorStoreInput): PostgresVectorStore {
+  return new PostgresVectorStore(input);
+}
+
 function toHit(row: HitRow): SearchHit {
   return {
     id: row.id,

package/src/prompt-fence.ts

@@ -0,0 +1,128 @@
+// The data fences of a prompt template: which XML-style tag pairs enclose each `{{slot}}`, and the
+// neutraliser `render` applies to the prompt those values were assembled into. A fence is the template's declaration
+// that a slot is DATA; a value that writes the fence's own closer would end it early and speak as
+// the prompt (#689), so that closer is broken — never deleted, the model still reads every word.
+
+/** `<name>` or `<name attr="…">` — a fence opener. Self-closing and closing tags are not openers. */
+const OPEN = /<([A-Za-z_][\w.-]*)(?:\s[^<>]*)?(?<!\/)>/g;
+/** `</name>`, as the template author writes it. */
+const CLOSE = /<\/([A-Za-z_][\w.-]*)\s*>/g;
+/**
+ * A `{{slot}}`. The ONE pattern: `render` substitutes by it and `fenceMap` keys offsets by it, so
+ * the two can never disagree about where a slot is.
+ */
+export const SLOT = /\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g;
+
+interface TagMark {
+  readonly name: string;
+  readonly at: number;
+}
+
+const marks = (template: string, pattern: RegExp): readonly TagMark[] =>
+  [...template.matchAll(pattern)].map((match) => ({ name: match[1] ?? '', at: match.index }));
+
+/**
+ * The fences enclosing the offset `at`, outermost first. A tag encloses it when its LAST opener
+ * before `at` is not closed before `at`, and a closer follows — read per name, never as a stack, so
+ * a stray `<note>` in prose fences nothing and cannot unbalance the real fences around it.
+ */
+function enclosing(
+  opens: readonly TagMark[],
+  closes: readonly TagMark[],
+  at: number,
+): readonly string[] {
+  const found: TagMark[] = [];
+  for (const name of new Set(opens.map((mark) => mark.name))) {
+    const opener = opens.findLast((mark) => mark.name === name && mark.at < at);
+    if (opener === undefined) continue;
+    const named = closes.filter((mark) => mark.name === name);
+    const closedBefore = named.some((mark) => mark.at > opener.at && mark.at < at);
+    if (!closedBefore && named.some((mark) => mark.at > at)) found.push(opener);
+  }
+  return found.sort((a, b) => a.at - b.at).map((mark) => mark.name);
+}
+
+/**
+ * Each FENCED slot occurrence's offset, mapped to the closers its value must not keep: every fence
+ * the template draws, not only the ones around it. A title is no safer for writing `</post_body>`
+ * than `</post_title>` — a model reads tags in order, and a forged closer of a later fence is one
+ * more place the data seems to end.
+ */
+export function fenceMap(template: string): ReadonlyMap<number, readonly string[]> {
+  const opens = marks(template, OPEN);
+  const closes = marks(template, CLOSE);
+  const drawn = [...new Set(opens.map((mark) => mark.name))].filter((name) =>
+    closes.some(
+      (close) => close.name === name && opens.some((o) => o.name === name && o.at < close.at),
+    ),
+  );
+  const map = new Map<number, readonly string[]>();
+  for (const slot of template.matchAll(SLOT)) {
+    if (enclosing(opens, closes, slot.index).length > 0) map.set(slot.index, drawn);
+  }
+  return map;
+}
+
+/**
+ * Per slot name, the fences enclosing EVERY occurrence of it — so one bare occurrence reports the
+ * slot as unfenced, which is what an app's own test asserts against ("is `body` data?").
+ */
+export function promptFences(template: string): Readonly<Record<string, readonly string[]>> {
+  const opens = marks(template, OPEN);
+  const closes = marks(template, CLOSE);
+  const out: Record<string, readonly string[]> = {};
+  for (const slot of template.matchAll(SLOT)) {
+    const name = slot[1] ?? '';
+    const here = enclosing(opens, closes, slot.index);
+    // Own keys only: a slot named `constructor` must not read Object.prototype's.
+    const before = Object.hasOwn(out, name) ? out[name] : undefined;
+    out[name] = before === undefined ? here : before.filter((tag) => here.includes(tag));
+  }
+  return out;
+}
+
+const escapeName = (name: string): string => name.replace(/[.-]/g, '\\$&');
+
+/** Where a fenced slot's value landed in the rendered prompt: `[start, end)`. */
+export interface FencedSpan {
+  readonly start: number;
+  readonly end: number;
+}
+
+/**
+ * Break every closer of `fences` in the ASSEMBLED prompt that a fenced value wrote any character
+ * of. Per value was not enough: `{{a}}{{b}}` with `</post_` and `body>` rebuilt a whole closer from
+ * two halves, and a value ending `</post_` beside template text `body>` completed one. So the scan
+ * runs over the rendered text, and a closer the template wrote alone — no value inside it — stands.
+ *
+ * A closer is `<`, `/` and the name, any case, whitespace either side of the slash, and ANYTHING
+ * after the name that does not continue it: `</post_body foo=1>`, `</post_body/>` and a bare
+ * `</post_body` read as one to a lenient model. `<\/name` is the shape `assembleContext` uses for
+ * `</document>`: the marker is broken, the text survives.
+ */
+export function neutraliseFenced(
+  rendered: string,
+  spans: readonly FencedSpan[],
+  fences: readonly string[],
+): string {
+  if (fences.length === 0 || spans.length === 0) return rendered;
+  const closer = new RegExp(`<\\s*\\/\\s*(?:${fences.map(escapeName).join('|')})(?![\\w.-])`, 'gi');
+  let out = '';
+  let from = 0;
+  for (const match of rendered.matchAll(closer)) {
+    const start = match.index;
+    const end = start + match[0].length;
+    if (!spans.some((span) => span.start < end && span.end > start)) continue;
+    const slash = rendered.indexOf('/', start);
+    out += `${rendered.slice(from, slash)}\\`;
+    from = slash;
+  }
+  return out + rendered.slice(from);
+}
+
+/**
+ * A value that is data from its first character to its last — a retrieved document, not a slot in
+ * a template. The same pass as `neutraliseFenced`, one span wide: one neutraliser in this package.
+ */
+export const neutraliseFences = (value: string, fences: readonly string[]): string =>
+  neutraliseFenced(value, [{ start: 0, end: value.length }], fences);

package/src/prompt.ts

@@ -12,6 +12,7 @@
 import { canonicalJson } from '@ultimat3/core';
 import { AiPromptRenderError, AiPromptVersionError } from './errors';
 import type { Effort, ModelId, ThinkingMode } from './models';
+import { type FencedSpan, fenceMap, neutraliseFenced, SLOT } from './prompt-fence';
 import type { JsonSchema } from './tools';
 
 /** Template variables. Values are stringified at render time with no formatting magic. */
@@ -21,7 +22,11 @@ export interface DefinePromptInput<V extends PromptVars> {
   readonly id: string;
   /** Semver-ish, author-assigned. Must change whenever `template` changes. */
   readonly version: string;
-  /** `{{name}}` placeholders. Every key in `V` must appear; unfilled ones throw. */
+  /**
+   * `{{name}}` placeholders. Every key in `V` must appear; unfilled ones throw. A slot inside an
+   * XML-style tag pair (`<post_body>\n{{body}}\n</post_body>`) is fenced DATA: render breaks every
+   * fence closer in the value, so user text cannot end the fence and pose as instructions.
+   */
   readonly template: string;
   /** Optional system prompt. Part of the hash — it changes behaviour. */
   readonly system?: string;
@@ -58,7 +63,10 @@ export interface Prompt<V extends PromptVars = PromptVars> {
   readonly model: ModelId | undefined;
   readonly effort: Effort | undefined;
   readonly thinking: ThinkingMode | undefined;
-  /** Substitute variables. Throws on an unfilled placeholder. */
+  /**
+   * Substitute variables. In a fenced slot every fence closer the template draws is broken, never
+   * deleted (`prompt-fence.ts`). Throws on an unfilled placeholder.
+   */
   render(vars: V): string;
   /** `id@version` — the identity an eval result is filed under. */
   readonly ref: string;
@@ -67,7 +75,7 @@ export interface Prompt<V extends PromptVars = PromptVars> {
 const registry = new Map<string, Prompt>();
 
 export function definePrompt<V extends PromptVars>(input: DefinePromptInput<V>): Prompt<V> {
-  const hash = contentHash(input);
+  const hash = promptHash(input);
   const key = `${input.id}@${input.version}`;
   const existing = registry.get(key);
   if (existing !== undefined && existing.hash !== hash) {
@@ -78,6 +86,8 @@ export function definePrompt<V extends PromptVars>(input: DefinePromptInput<V>):
     });
   }
 
+  // Read once, at declaration: the fences are the template's, and a render is a hot path.
+  const fences = fenceMap(input.template);
   const prompt: Prompt<V> = {
     id: input.id,
     version: input.version,
@@ -90,7 +100,7 @@ export function definePrompt<V extends PromptVars>(input: DefinePromptInput<V>):
     effort: input.effort,
     thinking: input.thinking,
     ref: key,
-    render: (vars) => render(input.template, vars, key),
+    render: (vars) => render(input.template, vars, key, fences),
   };
   registry.set(key, prompt as Prompt);
   return prompt;
@@ -126,11 +136,23 @@ export function resetPrompts(): void {
   registry.clear();
 }
 
-const PLACEHOLDER = /\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g;
-
-function render(template: string, vars: PromptVars, ref: string): string {
+function render(
+  template: string,
+  vars: PromptVars,
+  ref: string,
+  fences: ReadonlyMap<number, readonly string[]>,
+): string {
   const missing: string[] = [];
-  const out = template.replace(PLACEHOLDER, (_match, name: string) => {
+  const spans: FencedSpan[] = [];
+  let names: readonly string[] = [];
+  let out = '';
+  let from = 0;
+  // Assembled by hand rather than `replace`: the fence pass below needs where each fenced value
+  // LANDED, because a closer can be built across two values or a value and the template beside it.
+  for (const match of template.matchAll(SLOT)) {
+    out += template.slice(from, match.index);
+    from = match.index + match[0].length;
+    const name = match[1] ?? '';
     // `Object.hasOwn`, never `vars[name] === undefined`: a plain object inherits `constructor`,
     // `toString` and `valueOf`, so `{{constructor}}` in a template rendered JS SOURCE into the
     // prompt instead of raising the unfilled-slot error this file promises — and that source was
@@ -139,16 +161,24 @@ function render(template: string, vars: PromptVars, ref: string): string {
     const value = Object.hasOwn(vars, name) ? vars[name] : undefined;
     if (value === undefined) {
       missing.push(name);
-      return '';
+      continue;
+    }
+    const text = String(value);
+    const fenced = fences.get(match.index);
+    if (fenced !== undefined) {
+      spans.push({ start: out.length, end: out.length + text.length });
+      names = fenced;
     }
-    return String(value);
-  });
+    out += text;
+  }
+  out += template.slice(from);
   if (missing.length > 0) {
     // Loud, like an i18n miss: a silently blank variable is a prompt that reads fine and
     // means something else.
     throw new AiPromptRenderError({ ref, missing });
   }
-  return out;
+  // A fenced slot is data; no closer a value wrote any part of survives.
+  return neutraliseFenced(out, spans, names);
 }
 
 /**
@@ -161,7 +191,7 @@ function render(template: string, vars: PromptVars, ref: string): string {
  * An absent schema stays the empty string rather than becoming `canonicalJson(undefined)`'s
  * `null` — that is what keeps every hash already recorded in a baseline the same value.
  */
-export function contentHash<V extends PromptVars>(input: DefinePromptInput<V>): string {
+export function promptHash<V extends PromptVars>(input: DefinePromptInput<V>): string {
   const fields = [
     `id:${input.id}`,
     `version:${input.version}`,