@startsimpli/llm 0.4.16 → 0.4.17

package/src/translation/index.ts

@@ -0,0 +1,784 @@
+/**
+ * The translation engine (bd startsim-h1q8, GREEN over bd startsim-ob4d's RED).
+ *
+ * The contract lives in `./types` and did not move to implement this: every
+ * signature here is the one bd startsim-ob4d pinned. The tests in `./__tests__`
+ * are the specification — read them before changing anything in this file.
+ *
+ * WHAT MAY NEVER APPEAR IN THIS DIRECTORY:
+ *   - a literal model id used to ROUTE (bd startsim-7oh1 — ids live in
+ *     configuration). The one deny-list below is vendor *terms* data, not a
+ *     routing decision, and it is overridable from the environment.
+ *   - a branch on a locale code (bd startsim-jb1z — locales are data). Enforced
+ *     by a source scan in `__tests__/quality-gates.test.ts`.
+ *   - a call to the vendor Batch API or Files API (bd startsim-hopl — neither
+ *     is zero-retention eligible; "batching" here means N segments in ONE prompt)
+ *   - client text or a raw provider response in a log line, an error message or
+ *     a stack. Enforced by `__tests__/route-confidentiality.test.ts`.
+ */
+
+import { stripIsolates } from '@startsimpli/i18n/bidi';
+
+import {
+  DEFAULT_BATCH_LIMITS,
+  type BatchLimits,
+  type EnvelopeResult,
+  type GlossaryTerm,
+  type MechanicalChecks,
+  type MemoryUnit,
+  type PromptContext,
+  type RetentionPosture,
+  type SegmentedDocument,
+  type StructuredDocument,
+  type DocumentNode,
+  type TermCheck,
+  type TranslatedSegment,
+  type TranslationDeps,
+  type TranslationFailure,
+  type TranslationRequest,
+  type TranslationResult,
+  type TranslationRoute,
+  type TranslationSegment,
+  type TranslationService,
+} from './types';
+
+export * from './types';
+
+/**
+ * The prompt's identity, recorded on every unit alongside the provider and
+ * model. The regression harness reruns when this tuple changes and at no other
+ * time (`startsim-bfem`).
+ */
+export const PROMPT_VERSION = 'translate/v1';
+
+/** Thrown by every stub here until GREEN lands. Never caught by product code. */
+export class TranslationNotImplementedError extends Error {
+  constructor(what: string) {
+    super(
+      `${what} is not implemented (bd startsim-ob4d is RED; bd startsim-h1q8 implements it)`,
+    );
+    this.name = 'TranslationNotImplementedError';
+  }
+}
+
+/**
+ * A deployment that cannot legally or safely serve. Raised at BOOT, never on
+ * the first client document.
+ */
+export class TranslationConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'TranslationConfigError';
+  }
+}
+
+/**
+ * A `walled` route whose configured provider would not answer.
+ *
+ * This is a SUCCESSFUL refusal, not a bug: crossing to another vendor under
+ * different retention terms would breach the guarantee the product is sold on
+ * (`startsim-hopl`). The job is retried later against the same provider.
+ */
+export class WalledRouteUnavailableError extends Error {
+  constructor(provider: string) {
+    super(`walled route: ${provider} is unavailable and this posture forbids fallback`);
+    this.name = 'WalledRouteUnavailableError';
+  }
+}
+
+/** A provider response that could not be parsed after every permitted retry. */
+export class EnvelopeParseError extends Error {
+  readonly reason: string;
+  constructor(reason: string) {
+    // The MESSAGE CARRIES NO RESPONSE TEXT. That is the whole discipline: the
+    // failure path is where the confidentiality guarantee actually breaks.
+    super(`translation envelope rejected: ${reason}`);
+    this.name = 'EnvelopeParseError';
+    this.reason = reason;
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  structure — deterministic by construction, because it never reaches a model
+// ---------------------------------------------------------------------------
+
+/**
+ * A node's address in the tree, used as its segment id.
+ *
+ * Derived from POSITION, not content, and recomputed identically when the
+ * skeleton is walked again — which is what makes `segmentDocument` and
+ * `reassembleDocument` a round trip rather than two functions that agree by
+ * luck. The caller never sees these ids unless it segments a document; the
+ * engine's own segment ids stay opaque per `startsim-jb1z`.
+ */
+function nodePath(prefix: string, index: number): string {
+  return prefix === '' ? `n${index}` : `${prefix}.${index}`;
+}
+
+/** A leaf carries text. `translatable: false` marks a product code, id, or similar. */
+function isTranslatableLeaf(node: DocumentNode): boolean {
+  return typeof node.text === 'string' && node.translatable !== false;
+}
+
+/** Pull the translatable leaves out of a document, leaving a reassemblable skeleton. */
+export function segmentDocument(document: StructuredDocument): SegmentedDocument {
+  const segments: TranslationSegment[] = [];
+
+  const walk = (nodes: readonly DocumentNode[], prefix: string): void => {
+    nodes.forEach((node, index) => {
+      const id = nodePath(prefix, index);
+      if (isTranslatableLeaf(node)) segments.push({ id, text: node.text as string });
+      if (node.children) walk(node.children, id);
+    });
+  };
+  walk(document.nodes, '');
+
+  // The skeleton is the document itself, untouched. Structure never enters the
+  // model, so there is nothing to strip out of it — reassembly replaces leaf
+  // text by id and returns the same shape.
+  return { segments, skeleton: cloneDocument(document) };
+}
+
+function cloneDocument(document: StructuredDocument): StructuredDocument {
+  return { nodes: document.nodes.map(cloneNode) };
+}
+
+function cloneNode(node: DocumentNode): DocumentNode {
+  const copy: DocumentNode = { kind: node.kind };
+  if (node.text !== undefined) copy.text = node.text;
+  if (node.translatable !== undefined) copy.translatable = node.translatable;
+  if (node.children !== undefined) copy.children = node.children.map(cloneNode);
+  return copy;
+}
+
+/** Put translated leaves back. Returns the ORIGINAL shape, by id, never by order. */
+export function reassembleDocument(
+  skeleton: StructuredDocument,
+  translations: ReadonlyMap<string, string>,
+): StructuredDocument {
+  const walk = (nodes: readonly DocumentNode[], prefix: string): DocumentNode[] =>
+    nodes.map((node, index) => {
+      const id = nodePath(prefix, index);
+      const copy = cloneNode(node);
+      if (isTranslatableLeaf(node)) {
+        const replacement = translations.get(id);
+        // A leaf with no translation keeps its source text: a partial result is
+        // a readable document with gaps, never a document with holes in it.
+        if (replacement !== undefined) copy.text = replacement;
+      }
+      if (node.children) copy.children = walk(node.children, id);
+      return copy;
+    });
+
+  return { nodes: walk(skeleton.nodes, '') };
+}
+
+// ---------------------------------------------------------------------------
+//  batching — the contract, not an optimisation
+// ---------------------------------------------------------------------------
+
+/**
+ * Cut `segments` into calls by CHARACTER budget, always at least one segment
+ * per batch even when that one exceeds the budget alone — otherwise an
+ * oversized segment is skipped forever
+ * (`packages/integrations/src/corpus/extract.ts`'s `takeWithinBudget` rule).
+ */
+export function planBatches(
+  segments: readonly TranslationSegment[],
+  limits: BatchLimits = DEFAULT_BATCH_LIMITS,
+): TranslationSegment[][] {
+  const batches: TranslationSegment[][] = [];
+  let current: TranslationSegment[] = [];
+  let chars = 0;
+
+  for (const segment of segments) {
+    const size = segment.text.length;
+    const wouldExceedChars = current.length > 0 && chars + size > limits.maxCharsPerBatch;
+    const wouldExceedCount = current.length >= limits.maxSegmentsPerBatch;
+
+    if (wouldExceedChars || wouldExceedCount) {
+      batches.push(current);
+      current = [];
+      chars = 0;
+    }
+
+    current.push(segment);
+    chars += size;
+  }
+
+  if (current.length > 0) batches.push(current);
+  return batches;
+}
+
+// ---------------------------------------------------------------------------
+//  prompt + envelope
+// ---------------------------------------------------------------------------
+
+const SYSTEM_PROMPT = [
+  'You are a professional translator.',
+  'Translate ONLY the text inside each <segment> element of <input>.',
+  'Return STRICT JSON and nothing else, in this exact shape:',
+  '{"segments":[{"id":"<the id you were given>","text":"<the translation>"}]}',
+  'Rules:',
+  '- Echo every id back EXACTLY as given. Never invent an id, never merge or split segments.',
+  '- Return one entry per requested segment, no more and no fewer.',
+  '- Preserve every number, date, currency amount and percentage exactly as written.',
+  '- Preserve line breaks inside a segment.',
+  '- <glossary> gives binding terminology: when a source term appears, its approved target form MUST appear in your translation.',
+  '- Terms marked do-not-translate MUST be reproduced verbatim in the source script.',
+  '- <memory> holds ALREADY-APPROVED example translations. They are reference only. NEVER translate them and never include them in your output.',
+  '- If a segment is empty, return it as an empty string.',
+].join('\n');
+
+/** Escape the five XML entities so a quote or angle bracket in client text cannot break a block. */
+function escapeXml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * The glossary terms that actually OCCUR in this batch.
+ *
+ * The prompt scales with the TEXT, not with the glossary: a client with a
+ * 4,000-term glossary must not pay for all of it on a two-line page.
+ */
+function termsOccurringIn(
+  batch: readonly TranslationSegment[],
+  glossary: readonly GlossaryTerm[] | undefined,
+): GlossaryTerm[] {
+  if (!glossary?.length) return [];
+  const haystack = batch.map((segment) => segment.text).join('\n').toLowerCase();
+  return glossary.filter((term) => haystack.includes(term.source.toLowerCase()));
+}
+
+/**
+ * One call's user prompt: XML-ish blocks, mirroring the corpus package's
+ * `renderAnswerPrompt`. XML rather than JSON *input* because the payload is
+ * long free text full of quotes and newlines.
+ *
+ * ONLY the glossary terms occurring in THIS batch are injected. See `startsim-yfot`.
+ */
+export function renderTranslatePrompt(
+  batch: readonly TranslationSegment[],
+  context: PromptContext,
+): string {
+  const blocks: string[] = [
+    `<task source_locale="${escapeXml(context.sourceLocale)}" target_locale="${escapeXml(context.targetLocale)}">`,
+    `Translate from ${escapeXml(context.sourceLocale)} to ${escapeXml(context.targetLocale)}.`,
+    '</task>',
+  ];
+
+  const terms = termsOccurringIn(batch, context.glossary);
+  if (terms.length > 0) {
+    blocks.push('<glossary>');
+    for (const term of terms) {
+      blocks.push(
+        term.doNotTranslate
+          ? `  <term do_not_translate="true">${escapeXml(term.source)}</term>`
+          : `  <term source="${escapeXml(term.source)}">${escapeXml(term.target)}</term>`,
+      );
+    }
+    blocks.push('</glossary>');
+  }
+
+  // Examples sit in their OWN block, before the input. `startsim-yfot` names the
+  // model translating its own examples as the likeliest prompt-level failure.
+  const examples = context.memoryExamples ?? [];
+  if (examples.length > 0) {
+    blocks.push('<memory note="approved examples — reference only, do NOT translate these">');
+    for (const example of examples) {
+      blocks.push('  <example>');
+      blocks.push(`    <from>${escapeXml(example.sourceText)}</from>`);
+      blocks.push(`    <to>${escapeXml(example.targetText)}</to>`);
+      blocks.push('  </example>');
+    }
+    blocks.push('</memory>');
+  }
+
+  blocks.push('<input>');
+  for (const segment of batch) {
+    blocks.push(`  <segment id="${escapeXml(segment.id)}">${escapeXml(segment.text)}</segment>`);
+  }
+  blocks.push('</input>');
+
+  return blocks.join('\n');
+}
+
+/** The JSON object a well-formed response carries. */
+interface RawEnvelope {
+  segments?: unknown;
+}
+
+/**
+ * Pull the JSON object out of a response that may be fenced or prefaced.
+ * Returns null when there is nothing parseable — which is `malformed`.
+ */
+function parseJsonObject(raw: string): RawEnvelope | null {
+  const attempt = (text: string): RawEnvelope | null => {
+    try {
+      const value: unknown = JSON.parse(text);
+      return value && typeof value === 'object' && !Array.isArray(value)
+        ? (value as RawEnvelope)
+        : null;
+    } catch {
+      return null;
+    }
+  };
+
+  const direct = attempt(raw.trim());
+  if (direct) return direct;
+
+  // A fenced or prefaced object is a formatting slip, not a correctness alarm —
+  // recover it rather than burning a retry. Anything else is malformed.
+  const first = raw.indexOf('{');
+  const last = raw.lastIndexOf('}');
+  if (first >= 0 && last > first) return attempt(raw.slice(first, last + 1));
+  return null;
+}
+
+/** Parse and police one provider response against the ids that were requested. */
+export function parseTranslationEnvelope(
+  raw: string,
+  requestedIds: readonly string[],
+): EnvelopeResult {
+  const envelope = parseJsonObject(raw);
+  if (!envelope || !Array.isArray(envelope.segments)) {
+    return { ok: false, reason: 'malformed', offendingIds: [] };
+  }
+
+  const requested = new Set(requestedIds);
+  const segments: TranslationSegment[] = [];
+  const empty: string[] = [];
+  const seen = new Set<string>();
+  const duplicates: string[] = [];
+  const unknown: string[] = [];
+
+  for (const entry of envelope.segments) {
+    if (!entry || typeof entry !== 'object') {
+      return { ok: false, reason: 'malformed', offendingIds: [] };
+    }
+    const { id, text } = entry as { id?: unknown; text?: unknown };
+    if (typeof id !== 'string') {
+      return { ok: false, reason: 'malformed', offendingIds: [] };
+    }
+
+    // An UNKNOWN or DUPLICATE id means the model attributed text to a segment
+    // that did not ask for it. In a product sold on "one client's material never
+    // appears against another's" that is a correctness alarm, not a parse slip.
+    if (!requested.has(id)) {
+      unknown.push(id);
+      continue;
+    }
+    if (seen.has(id)) {
+      duplicates.push(id);
+      continue;
+    }
+    seen.add(id);
+
+    // A MISSING `text` key is structurally broken. An EMPTY STRING is a value:
+    // the caller may legitimately have handed us an empty segment, and only the
+    // caller — which holds the source — can tell those apart. The service does
+    // that comparison; the parser stays source-blind.
+    if (typeof text !== 'string') {
+      empty.push(id);
+      continue;
+    }
+    segments.push({ id, text });
+  }
+
+  if (unknown.length > 0) return { ok: false, reason: 'unknown_id', offendingIds: unknown };
+  if (duplicates.length > 0) {
+    return { ok: false, reason: 'duplicate_id', offendingIds: duplicates };
+  }
+
+  const missing = requestedIds.filter((id) => !seen.has(id));
+  return { ok: true, segments, missing, empty };
+}
+
+// ---------------------------------------------------------------------------
+//  mechanical checks — source-to-output, no target-language reader required
+// ---------------------------------------------------------------------------
+
+/**
+ * Ordered longest-first so a date is one token rather than three numbers, and a
+ * currency amount is not shredded into its groups. Order IS the algorithm here.
+ */
+const NUMERIC_PATTERN =
+  /\d{4}-\d{2}-\d{2}|[$€£¥]\s?\d[\d,]*(?:\.\d+)?|\d[\d,]*(?:\.\d+)?\s?%|\d[\d,]*(?:\.\d+)?/g;
+
+/** Numbers, dates, currency amounts and percentages, as a comparable multiset. */
+export function extractNumerics(text: string): string[] {
+  return text.match(NUMERIC_PATTERN) ?? [];
+}
+
+/** Multiset difference: what is in `source` that `target` does not cover. */
+function missingFrom(source: readonly string[], target: readonly string[]): string[] {
+  const remaining = new Map<string, number>();
+  for (const value of target) remaining.set(value, (remaining.get(value) ?? 0) + 1);
+
+  const missing: string[] = [];
+  for (const value of source) {
+    const left = remaining.get(value) ?? 0;
+    if (left > 0) remaining.set(value, left - 1);
+    else missing.push(value);
+  }
+  return missing;
+}
+
+function occursIn(haystack: string, needle: string): boolean {
+  return needle.length > 0 && haystack.toLowerCase().includes(needle.toLowerCase());
+}
+
+export function runMechanicalChecks(
+  sourceText: string,
+  targetText: string,
+  glossary: readonly GlossaryTerm[],
+): MechanicalChecks {
+  const glossaryAdherence: TermCheck[] = [];
+  const doNotTranslate: TermCheck[] = [];
+
+  for (const term of glossary) {
+    // Only terms that actually OCCURRED can be adhered to or missed. Scoring a
+    // term that was never in the source would make every document look bad.
+    if (!occursIn(sourceText, term.source)) continue;
+
+    if (term.doNotTranslate) {
+      // Verbatim, so case-sensitive: a brand is a brand.
+      doNotTranslate.push({ term: term.source, present: targetText.includes(term.source) });
+    } else {
+      glossaryAdherence.push({ term: term.source, present: occursIn(targetText, term.target) });
+    }
+  }
+
+  const missingNumerics = missingFrom(extractNumerics(sourceText), extractNumerics(targetText));
+
+  const ok =
+    glossaryAdherence.every((check) => check.present) &&
+    doNotTranslate.every((check) => check.present) &&
+    missingNumerics.length === 0;
+
+  return { glossaryAdherence, doNotTranslate, missingNumerics, ok };
+}
+
+// ---------------------------------------------------------------------------
+//  routing
+// ---------------------------------------------------------------------------
+
+/**
+ * Models the vendor designates as requiring retention, which therefore CANNOT
+ * run under a zero-retention arrangement (`startsim-hopl`).
+ *
+ * This is the one place a model id is named, and it is deliberate: this is
+ * vendor TERMS data — a legal fact about a model — not a routing decision, and
+ * `startsim-7oh1`'s ban is on selecting models by hardcoded id. It is
+ * overridable from the environment so a terms change is a config change, and it
+ * is enforced only on the `walled` posture, where the guarantee is being sold.
+ */
+const DEFAULT_COVERED_MODELS = ['claude-fable-5', 'claude-mythos-5'] as const;
+
+function splitList(value: string | undefined): string[] {
+  return (value ?? '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+}
+
+function isPosture(value: string | undefined): value is RetentionPosture {
+  return value === 'walled' || value === 'open';
+}
+
+/**
+ * Resolve the deployment's route from configuration and VALIDATE it.
+ *
+ * Throws `TranslationConfigError` when the configured model is outside the
+ * allow-list, or is a Covered Model on a walled deployment.
+ */
+export function resolveTranslationRoute(
+  env: Record<string, string | undefined>,
+): TranslationRoute {
+  const posture = env.TRANSLATION_POSTURE;
+  if (!isPosture(posture)) {
+    throw new TranslationConfigError(
+      `TRANSLATION_POSTURE must be 'walled' or 'open' (got ${posture ?? 'nothing'})`,
+    );
+  }
+
+  const provider = env.TRANSLATION_PROVIDER?.trim();
+  if (!provider) throw new TranslationConfigError('TRANSLATION_PROVIDER is not set');
+
+  const model = env.TRANSLATION_MODEL?.trim();
+  if (!model) throw new TranslationConfigError('TRANSLATION_MODEL is not set');
+
+  const allowedModels = splitList(env.TRANSLATION_ALLOWED_MODELS);
+  const coveredModels = env.TRANSLATION_COVERED_MODELS
+    ? splitList(env.TRANSLATION_COVERED_MODELS)
+    : [...DEFAULT_COVERED_MODELS];
+
+  // Posture decides fallback. A deployment does not get to ask for it.
+  const fallback = posture === 'walled' ? false : env.TRANSLATION_FALLBACK === 'true';
+
+  const route: TranslationRoute = { posture, provider, model, allowedModels, fallback };
+  assertRouteIsServable(route, coveredModels);
+  return route;
+}
+
+/**
+ * The boot gate, shared by `resolveTranslationRoute` and
+ * `createTranslationService` — a route built by hand must clear the same bar as
+ * one read from the environment, or the gate is advisory.
+ */
+function assertRouteIsServable(
+  route: TranslationRoute,
+  coveredModels: readonly string[] = DEFAULT_COVERED_MODELS,
+): void {
+  if (route.posture === 'walled' && route.fallback) {
+    throw new TranslationConfigError(
+      'walled posture forbids fallback: crossing to another vendor would breach the retention guarantee',
+    );
+  }
+
+  if (route.posture === 'walled' && route.allowedModels.length === 0) {
+    throw new TranslationConfigError(
+      'walled posture requires an explicit model allow-list (TRANSLATION_ALLOWED_MODELS)',
+    );
+  }
+
+  if (route.allowedModels.length > 0 && !route.allowedModels.includes(route.model)) {
+    throw new TranslationConfigError(
+      `model ${route.model} is outside this deployment's allow-list`,
+    );
+  }
+
+  if (route.posture === 'walled' && coveredModels.includes(route.model)) {
+    throw new TranslationConfigError(
+      `model ${route.model} requires vendor-side retention and cannot serve a walled deployment`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  the service
+// ---------------------------------------------------------------------------
+
+const NO_OP_LOGGER = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
+
+/** Exact-match memory key. Locales are part of it; neither is ever compared to a literal. */
+function memoryKey(sourceText: string, source: string, target: string): string {
+  return `${source}${target}${sourceText}`;
+}
+
+function buildMemoryIndex(memory: readonly MemoryUnit[] | undefined): Map<string, string> {
+  const index = new Map<string, string>();
+  for (const unit of memory ?? []) {
+    index.set(memoryKey(unit.sourceText, unit.sourceLocale, unit.targetLocale), unit.targetText);
+  }
+  return index;
+}
+
+/**
+ * Build the service for a route. Single-provider by construction on a walled
+ * posture — this deliberately does NOT reuse `LLMService.getProvider()`'s
+ * "fall back to any available" behaviour, which would cross a retention
+ * boundary silently.
+ */
+export function createTranslationService(
+  route: TranslationRoute,
+  deps: TranslationDeps,
+): TranslationService {
+  // Fail the BOOT, not the first client document.
+  assertRouteIsServable(route);
+
+  const logger = deps.logger ?? NO_OP_LOGGER;
+  const limits = deps.limits ?? DEFAULT_BATCH_LIMITS;
+  const maxEnvelopeRetries = deps.maxEnvelopeRetries ?? 1;
+
+  const provenance = {
+    provider: route.provider,
+    model: route.model,
+    promptVersion: PROMPT_VERSION,
+  };
+
+  /**
+   * One provider call for one batch, with the id-echo contract enforced.
+   *
+   * A malformed envelope is worth asking again for — models drift into prose.
+   * An unknown or duplicate id is NOT: it is a correctness alarm and retrying
+   * would just roll the dice on client material.
+   */
+  async function callBatch(
+    batch: readonly TranslationSegment[],
+    request: TranslationRequest,
+  ): Promise<{ parsed: Extract<EnvelopeResult, { ok: true }>; calls: number }> {
+    const ids = batch.map((segment) => segment.id);
+    const basePrompt = renderTranslatePrompt(batch, {
+      sourceLocale: request.sourceLocale,
+      targetLocale: request.targetLocale,
+      glossary: request.glossary,
+      memoryExamples: request.memory,
+    });
+
+    let calls = 0;
+    for (let attempt = 0; attempt <= maxEnvelopeRetries; attempt += 1) {
+      const userPrompt =
+        attempt === 0
+          ? basePrompt
+          : `${basePrompt}\n\n<correction>Your previous reply was not valid JSON. Reply with ONLY the JSON object described in the system prompt.</correction>`;
+
+      const response = await deps.provider.generate(userPrompt, SYSTEM_PROMPT, {
+        model: route.model,
+      });
+      calls += 1;
+
+      const parsed = parseTranslationEnvelope(response.content, ids);
+      if (parsed.ok) return { parsed, calls };
+
+      if (parsed.reason === 'unknown_id' || parsed.reason === 'duplicate_id') {
+        // Ids are the caller's own opaque labels, never client text — safe to log.
+        logger.error('translation envelope rejected', {
+          reason: parsed.reason,
+          offendingIds: parsed.offendingIds,
+          provider: route.provider,
+        });
+        throw new EnvelopeParseError(parsed.reason);
+      }
+
+      logger.warn('translation envelope unparseable', {
+        reason: parsed.reason,
+        attempt: attempt + 1,
+        segments: batch.length,
+        provider: route.provider,
+      });
+    }
+
+    throw new EnvelopeParseError('malformed');
+  }
+
+  async function translate(request: TranslationRequest): Promise<TranslationResult> {
+    // The refusal comes BEFORE any call. On a walled posture an unavailable
+    // provider is a successful refusal: the job retries later against the SAME
+    // provider rather than crossing to one under different terms.
+    if (!deps.provider.isAvailable()) {
+      if (route.posture === 'walled') throw new WalledRouteUnavailableError(route.provider);
+      throw new Error(`translation provider ${route.provider} is unavailable`);
+    }
+
+    const glossary = request.glossary ?? [];
+    const memoryIndex = buildMemoryIndex(request.memory);
+
+    const translated: TranslatedSegment[] = [];
+    const failed: TranslationFailure[] = [];
+    const requeued: string[] = [];
+    let providerCalls = 0;
+
+    const finish = (segment: TranslationSegment, rawTarget: string, fromMemory: boolean): void => {
+      // Isolates are applied at RENDER time (`startsim-jb1z`). A stored string
+      // carrying U+2066–U+2069 is invisible on screen, very visible in a diff,
+      // and breaks exact memory matching forever after.
+      const targetText = stripIsolates(rawTarget);
+
+      // An empty target is a failure ONLY when the source had something in it.
+      // An empty source legitimately yields an empty target.
+      if (segment.text.trim().length > 0 && targetText.trim().length === 0) {
+        failed.push({ id: segment.id, reason: 'empty_text' });
+        return;
+      }
+
+      translated.push({
+        id: segment.id,
+        targetText,
+        provenance,
+        fromMemory,
+        checks: runMechanicalChecks(segment.text, targetText, glossary),
+      });
+    };
+
+    // An exact memory hit costs nothing, which is exactly why it is checked
+    // first and why the effective provider rate falls as the memory fills.
+    const pending: TranslationSegment[] = [];
+    for (const segment of request.segments) {
+      const hit = memoryIndex.get(
+        memoryKey(segment.text, request.sourceLocale, request.targetLocale),
+      );
+      if (hit !== undefined) finish(segment, hit, true);
+      else pending.push(segment);
+    }
+
+    if (pending.length === 0) {
+      return { translated, failed, requeued, providerCalls };
+    }
+
+    const byId = new Map(request.segments.map((segment) => [segment.id, segment]));
+
+    for (const batch of planBatches(pending, limits)) {
+      const { parsed, calls } = await callBatch(batch, request);
+      providerCalls += calls;
+
+      for (const returned of parsed.segments) {
+        const source = byId.get(returned.id);
+        if (source) finish(source, returned.text, false);
+      }
+
+      // A structurally blank entry is not an empty translation, it is a broken one.
+      for (const id of parsed.empty) failed.push({ id, reason: 'empty_text' });
+
+      // One difficult sentence must not cost the document: a missing id is
+      // re-queued ALONE, where it gets the model's whole attention.
+      for (const id of parsed.missing) {
+        const source = byId.get(id);
+        if (!source) continue;
+        requeued.push(id);
+
+        try {
+          const retry = await callBatch([source], request);
+          providerCalls += retry.calls;
+          const answer = retry.parsed.segments.find((segment) => segment.id === id);
+          if (answer) finish(source, answer.text, false);
+          else failed.push({ id, reason: 'missing_id' });
+        } catch (error) {
+          // DELIBERATE ASYMMETRY, not an accident of where the try/catch landed:
+          // a failure in the MAIN batch propagates out of translate() and fails
+          // the call, because it is the whole document. A failure in a re-queue
+          // is best effort and fails only ITS segment, because the rest of the
+          // document already translated and throwing it away would be worse.
+          //
+          // The reason is `missing_id`, never `mechanical_check`: no translation
+          // was produced on this path, so there is no quality verdict to report,
+          // and a reviewer told `mechanical_check` would go looking for a bad
+          // translation that does not exist.
+          logger.warn('re-queued segment failed', {
+            id,
+            reason: error instanceof EnvelopeParseError ? error.reason : 'provider_error',
+            provider: route.provider,
+          });
+          failed.push({
+            id,
+            reason: error instanceof EnvelopeParseError ? 'missing_id' : 'provider_error',
+          });
+        }
+      }
+    }
+
+    logger.info('translation batch complete', {
+      requested: request.segments.length,
+      translated: translated.length,
+      failed: failed.length,
+      requeued: requeued.length,
+      providerCalls,
+      provider: route.provider,
+      model: route.model,
+    });
+
+    return { translated, failed, requeued, providerCalls };
+  }
+
+  return { translate, route };
+}