@startsimpli/llm 0.4.16 → 0.4.17

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@startsimpli/llm",
-  "version": "0.4.16",
+  "version": "0.4.17",
   "description": "Generic LLM service infrastructure — provider abstraction, retry logic, JSON extraction",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./translation": "./src/translation/index.ts"
   },
   "files": [
     "src",
@@ -15,7 +16,8 @@
     "access": "public"
   },
   "dependencies": {
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "@startsimpli/i18n": "^0.1.3"
   },
   "devDependencies": {
     "@types/node": "^20.19.39",

package/src/translation/__fixtures__/golden-pairs.ts

@@ -0,0 +1,243 @@
+/**
+ * THE SYNTHETIC GOLDEN SET (bd startsim-bfem, decision 1).
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * READ THIS BEFORE TRUSTING A TARGET STRING BELOW.
+ *
+ * Every `targetText` here is CONSTRUCTED, not translated. Nobody on our side
+ * reads Arabic or Chinese, so authoring convincing prose in either was never on
+ * the table — and pretending otherwise would put unreviewable text in the repo
+ * that a future reader mistakes for a reference.
+ *
+ * What these strings ARE: scaffolds built so the mechanical checks have
+ * something TRUE to assert. Each one carries, verbatim, the things a check
+ * looks for — the approved glossary term, the do-not-translate brand, every
+ * number and date — wrapped in filler that is honestly marked as filler
+ * (`نص تجريبي` / `示例文本`, both meaning roughly "sample text"). They are not
+ * fluent, they are not idiomatic, and no conclusion about translation QUALITY
+ * may be drawn from them. They pin down INVARIANTS, which is all the design
+ * permits a test to assert anyway (`startsim-bfem`, decision 2: assert
+ * relations between input and output, never the output itself).
+ *
+ * `provenance: 'reviewed'` is reserved for the two honest pairs — one per
+ * locale — that a named target-language reviewer contributes once. There are
+ * none yet: that is the `startsim-r9q8` blocker, and it is a people problem.
+ * Until then every pair here reads `constructed`, and a reader who cannot read
+ * the language can tell the difference by looking at one field.
+ * ────────────────────────────────────────────────────────────────────────────
+ *
+ * THE REAL SET LIVES OUTSIDE THIS REPOSITORY — 200 stratified segments in the
+ * client's own tenant, per `startsim-r9q8`. It never enters git. This set is
+ * its proxy and SHARES ITS SHAPE on purpose: the same assertions must run over
+ * either, or the synthetic set stops being a proxy and becomes a second thing
+ * to maintain.
+ *
+ * TWO LOCALES, ONE RTL AND ONE LTR, AND THAT IS THE ENFORCEMENT MECHANISM.
+ * `startsim-jb1z` bans naming a language in the engine. A test that needs to
+ * know which locale it is running has caught a leak — so every suite here is
+ * driven by `describe.each(GOLDEN_SETS)` over one shared body. EN→ZH is not
+ * decoration either: OGMC needs it, and it is the pair whose reviewer already
+ * exists.
+ */
+
+import type { GlossaryTerm, Locale, TranslationSegment } from '../types';
+
+/** How a target string came to exist. See the header. */
+export type PairProvenance = 'constructed' | 'reviewed';
+
+export interface GoldenPair {
+  /** Stable across locales, so one test body can ask both sets for the same case. */
+  id: string;
+  /** What this pair exists to exercise. */
+  covers: string;
+  sourceText: string;
+  targetText: string;
+  provenance: PairProvenance;
+}
+
+export interface GoldenSet {
+  sourceLocale: Locale;
+  targetLocale: Locale;
+  /**
+   * Present so a TEST can label its own output, never so the ENGINE can branch.
+   * Nothing in `packages/llm/src/translation/` may read this field — the engine
+   * takes direction from `dirFor()` at render time or not at all.
+   */
+  rtl: boolean;
+  glossary: GlossaryTerm[];
+  pairs: GoldenPair[];
+}
+
+/** The source side is shared: the same English drives both target locales. */
+const SOURCE_LOCALE = 'en';
+
+const SOURCES = {
+  plain: 'The quarterly report is ready for your review.',
+  glossaryTerm: 'Please review the settlement agreement before Friday.',
+  doNotTranslate: 'Contact Northwind Logistics about the delay.',
+  numerics: 'Revenue grew 12.5% to $4,200,000 on 2026-03-31.',
+  numberOnly: '2,750',
+  empty: '',
+  quoteAndNewline: 'She said "we accept the terms".\nThe contract is enclosed.',
+} as const;
+
+/** The one brand string that must survive verbatim into every target. */
+export const DNT_BRAND = 'Northwind Logistics';
+
+/** The numerics the `numerics` pair must round-trip, as a multiset. */
+export const NUMERICS_IN_FIXTURE = ['12.5%', '$4,200,000', '2026-03-31'] as const;
+
+const AR: GoldenSet = {
+  sourceLocale: SOURCE_LOCALE,
+  targetLocale: 'ar',
+  rtl: true,
+  glossary: [
+    { source: 'settlement agreement', target: 'اتفاقية التسوية', binding: true },
+    { source: DNT_BRAND, target: DNT_BRAND, binding: true, doNotTranslate: true },
+  ],
+  pairs: [
+    {
+      id: 'plain',
+      covers: 'a plain sentence with nothing special in it',
+      sourceText: SOURCES.plain,
+      targetText: 'نص تجريبي: التقرير ربع السنوي جاهز للمراجعة.',
+      provenance: 'constructed',
+    },
+    {
+      id: 'glossary-term',
+      covers: 'a binding glossary term that must appear in its approved form',
+      sourceText: SOURCES.glossaryTerm,
+      targetText: 'نص تجريبي: يرجى مراجعة اتفاقية التسوية قبل يوم الجمعة.',
+      provenance: 'constructed',
+    },
+    {
+      id: 'do-not-translate',
+      covers: 'a brand name that must survive verbatim',
+      sourceText: SOURCES.doNotTranslate,
+      targetText: `نص تجريبي: يرجى الاتصال بـ ${DNT_BRAND} بشأن التأخير.`,
+      provenance: 'constructed',
+    },
+    {
+      id: 'numerics',
+      covers: 'a percentage, a currency amount and an ISO date',
+      sourceText: SOURCES.numerics,
+      targetText: 'نص تجريبي: نمت الإيرادات 12.5% إلى $4,200,000 في 2026-03-31.',
+      provenance: 'constructed',
+    },
+    {
+      id: 'number-only',
+      covers: 'a segment that is nothing but a number',
+      sourceText: SOURCES.numberOnly,
+      targetText: '2,750',
+      provenance: 'constructed',
+    },
+    {
+      id: 'empty',
+      covers: 'an empty segment — the caller handed us nothing',
+      sourceText: SOURCES.empty,
+      targetText: '',
+      provenance: 'constructed',
+    },
+    {
+      id: 'quote-and-newline',
+      covers: 'an embedded quotation mark and a newline — the XML-block escaping case',
+      sourceText: SOURCES.quoteAndNewline,
+      targetText: 'نص تجريبي: قالت «نقبل الشروط».\nالعقد مرفق.',
+      provenance: 'constructed',
+    },
+  ],
+};
+
+const ZH: GoldenSet = {
+  sourceLocale: SOURCE_LOCALE,
+  targetLocale: 'zh',
+  rtl: false,
+  glossary: [
+    { source: 'settlement agreement', target: '和解协议', binding: true },
+    { source: DNT_BRAND, target: DNT_BRAND, binding: true, doNotTranslate: true },
+  ],
+  pairs: [
+    {
+      id: 'plain',
+      covers: 'a plain sentence with nothing special in it',
+      sourceText: SOURCES.plain,
+      targetText: '示例文本：季度报告已可供审阅。',
+      provenance: 'constructed',
+    },
+    {
+      id: 'glossary-term',
+      covers: 'a binding glossary term that must appear in its approved form',
+      sourceText: SOURCES.glossaryTerm,
+      targetText: '示例文本：请在星期五之前审阅和解协议。',
+      provenance: 'constructed',
+    },
+    {
+      id: 'do-not-translate',
+      covers: 'a brand name that must survive verbatim',
+      sourceText: SOURCES.doNotTranslate,
+      targetText: `示例文本：请联系 ${DNT_BRAND} 了解延误情况。`,
+      provenance: 'constructed',
+    },
+    {
+      id: 'numerics',
+      covers: 'a percentage, a currency amount and an ISO date',
+      sourceText: SOURCES.numerics,
+      targetText: '示例文本：收入增长 12.5% 至 $4,200,000，日期为 2026-03-31。',
+      provenance: 'constructed',
+    },
+    {
+      id: 'number-only',
+      covers: 'a segment that is nothing but a number',
+      sourceText: SOURCES.numberOnly,
+      targetText: '2,750',
+      provenance: 'constructed',
+    },
+    {
+      id: 'empty',
+      covers: 'an empty segment — the caller handed us nothing',
+      sourceText: SOURCES.empty,
+      targetText: '',
+      provenance: 'constructed',
+    },
+    {
+      id: 'quote-and-newline',
+      covers: 'an embedded quotation mark and a newline — the XML-block escaping case',
+      sourceText: SOURCES.quoteAndNewline,
+      targetText: '示例文本：她说“我们接受这些条款”。\n合同已附上。',
+      provenance: 'constructed',
+    },
+  ],
+};
+
+/**
+ * THE LOADER. One entry point, shared with the real set — the point of the
+ * split is that the same assertions run over either.
+ */
+export const GOLDEN_SETS: readonly GoldenSet[] = [AR, ZH];
+
+export function goldenSet(targetLocale: Locale): GoldenSet {
+  const found = GOLDEN_SETS.find((set) => set.targetLocale === targetLocale);
+  if (!found) throw new Error(`no golden set for target locale ${targetLocale}`);
+  return found;
+}
+
+export function pairIn(set: GoldenSet, id: string): GoldenPair {
+  const found = set.pairs.find((pair) => pair.id === id);
+  if (!found) throw new Error(`no golden pair '${id}' in ${set.targetLocale}`);
+  return found;
+}
+
+/** The set as translation input — ids are the pair ids, which are opaque here. */
+export function segmentsOf(set: GoldenSet): TranslationSegment[] {
+  return set.pairs.map((pair) => ({ id: pair.id, text: pair.sourceText }));
+}
+
+/** A well-formed provider response for `set`, as the engine should receive it. */
+export function envelopeFor(
+  set: GoldenSet,
+  ids: readonly string[] = set.pairs.map((pair) => pair.id),
+): string {
+  return JSON.stringify({
+    segments: ids.map((id) => ({ id, text: pairIn(set, id).targetText })),
+  });
+}

package/src/translation/__tests__/batch-contract.test.ts

@@ -0,0 +1,247 @@
+/**
+ * THE BATCH AND ID-ECHO CONTRACT (bd startsim-ob4d, RED items 1–7, 13, 15).
+ *
+ * `startsim-yfot` states the contract and this file is its enforcement. The
+ * rules being pinned down, in the design's own terms:
+ *
+ *   1. Ids are OPAQUE and round-trip byte-for-byte.
+ *   2. The returned id set EQUALS the requested id set.
+ *   3. A MISSING id fails only its own segment, which is re-queued.
+ *   4. An UNKNOWN id fails the WHOLE batch. Never map positionally.
+ *   5. DUPLICATE ids fail the whole batch.
+ *   6. ORDER is not part of the contract — reassembly is by id.
+ *   7. EMPTY output for a present id is a failure, not an empty translation.
+ *
+ * Rules 4 and 5 are the ones that look like parse pedantry and are not. A model
+ * that invents an id has attributed text to a segment that did not ask for it,
+ * and in a product sold on "one client's material never appears against
+ * another's" that is a correctness alarm.
+ *
+ * EVERY CASE RUNS TWICE, over an RTL and an LTR target, from ONE body. That is
+ * `startsim-bfem`'s enforcement of `startsim-jb1z`'s naming ban: a test that
+ * needs to know which locale it is running has caught a leak.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  createTranslationService,
+  parseTranslationEnvelope,
+  planBatches,
+  type TranslationRoute,
+} from '../index';
+import { DEFAULT_BATCH_LIMITS, type TranslationSegment } from '../types';
+import {
+  GOLDEN_SETS,
+  envelopeFor,
+  pairIn,
+  segmentsOf,
+  type GoldenSet,
+} from '../__fixtures__/golden-pairs';
+import { stubProvider } from './stub-provider';
+
+/**
+ * A route literal rather than `resolveTranslationRoute(...)`, so a failure in
+ * THIS file always means the batch contract is unimplemented — never that
+ * configuration parsing is. Routing has its own suite.
+ */
+function walledRoute(): TranslationRoute {
+  return {
+    posture: 'walled',
+    provider: 'stub',
+    model: 'stub-model',
+    allowedModels: ['stub-model'],
+    fallback: false,
+  };
+}
+
+function requestFor(set: GoldenSet) {
+  return {
+    segments: segmentsOf(set),
+    sourceLocale: set.sourceLocale,
+    targetLocale: set.targetLocale,
+    glossary: set.glossary,
+  };
+}
+
+describe.each(GOLDEN_SETS)(
+  'batch + id echo [$sourceLocale→$targetLocale]',
+  (set: GoldenSet) => {
+    const ids = set.pairs.map((pair) => pair.id);
+
+    it('packs every segment into exactly ONE provider call', async () => {
+      // The batching rule made enforceable. `packages/llm/README.md`: "Pack N
+      // items into one prompt with echoed ids — never loop".
+      const provider = stubProvider(envelopeFor(set));
+      const service = createTranslationService(walledRoute(), { provider });
+
+      const result = await service.translate(requestFor(set));
+
+      expect(provider.calls).toHaveLength(1);
+      expect(result.providerCalls).toBe(1);
+    });
+
+    it('returns every requested id, byte-identical', async () => {
+      const provider = stubProvider(envelopeFor(set));
+      const service = createTranslationService(walledRoute(), { provider });
+
+      const result = await service.translate(requestFor(set));
+
+      // Set equality, not containment: no more, no fewer.
+      expect([...result.translated.map((s) => s.id)].sort()).toEqual([...ids].sort());
+    });
+
+    it('fails ONLY the missing segment and re-queues it individually', async () => {
+      const kept = ids.filter((id) => id !== 'glossary-term');
+      // First call omits one id; the re-queued single-segment call answers it.
+      const provider = stubProvider([
+        envelopeFor(set, kept),
+        envelopeFor(set, ['glossary-term']),
+      ]);
+      const service = createTranslationService(walledRoute(), { provider });
+
+      const result = await service.translate(requestFor(set));
+
+      expect(result.requeued).toContain('glossary-term');
+      // One difficult sentence must not cost the document.
+      for (const id of kept) {
+        expect(result.translated.map((s) => s.id)).toContain(id);
+      }
+      expect(provider.calls.length).toBeGreaterThan(1);
+    });
+
+    it('fails the WHOLE batch on an unknown id, and maps nothing positionally', async () => {
+      const forged = JSON.stringify({
+        segments: [
+          // Same COUNT and same ORDER as the request, so a positional mapper
+          // would sail straight through this and produce a plausible document.
+          ...ids.slice(1).map((id) => ({ id, text: pairIn(set, id).targetText })),
+          { id: 'id-the-caller-never-sent', text: pairIn(set, ids[0]!).targetText },
+        ],
+      });
+      const provider = stubProvider(forged);
+      const service = createTranslationService(walledRoute(), { provider });
+
+      await expect(service.translate(requestFor(set))).rejects.toThrow(
+        /unknown_id/,
+      );
+    });
+
+    it('fails the WHOLE batch on a duplicate id', async () => {
+      const duplicated = JSON.stringify({
+        segments: [
+          ...ids.map((id) => ({ id, text: pairIn(set, id).targetText })),
+          { id: ids[0], text: pairIn(set, ids[0]!).targetText },
+        ],
+      });
+      const provider = stubProvider(duplicated);
+      const service = createTranslationService(walledRoute(), { provider });
+
+      await expect(service.translate(requestFor(set))).rejects.toThrow(
+        /duplicate_id/,
+      );
+    });
+
+    it('treats empty text for a present id as a failure, not an empty translation', async () => {
+      // A blank string is how a silent truncation looks.
+      const blanked = JSON.stringify({
+        segments: ids.map((id) => ({
+          id,
+          text: id === 'plain' ? '' : pairIn(set, id).targetText,
+        })),
+      });
+      const provider = stubProvider(blanked);
+      const service = createTranslationService(walledRoute(), { provider });
+
+      const result = await service.translate(requestFor(set));
+
+      expect(result.translated.map((s) => s.id)).not.toContain('plain');
+      expect(result.failed).toContainEqual({ id: 'plain', reason: 'empty_text' });
+    });
+
+    it('reassembles correctly when the model returns the segments reordered', async () => {
+      // Order is NOT part of the contract — asserting it would be asserting
+      // model behaviour we do not control. Reassembly is by id.
+      const reversed = JSON.stringify({
+        segments: [...ids].reverse().map((id) => ({ id, text: pairIn(set, id).targetText })),
+      });
+      const provider = stubProvider(reversed);
+      const service = createTranslationService(walledRoute(), { provider });
+
+      const result = await service.translate(requestFor(set));
+
+      for (const pair of set.pairs) {
+        const got = result.translated.find((s) => s.id === pair.id);
+        expect(got?.targetText).toBe(pair.targetText);
+      }
+    });
+
+    it('parses a well-formed envelope without inventing or dropping an id', () => {
+      // The parser on its own, so a batch failure can be localised to it.
+      const parsed = parseTranslationEnvelope(envelopeFor(set), ids);
+
+      expect(parsed.ok).toBe(true);
+      if (!parsed.ok) return;
+      expect(parsed.missing).toEqual([]);
+      expect(parsed.empty).toEqual([]);
+      expect(parsed.segments.map((s) => s.id).sort()).toEqual([...ids].sort());
+    });
+  },
+);
+
+/**
+ * Batching is cut by SIZE, not by count, and the reason is written into the
+ * corpus package it is copied from: "a corpus that grew a transcript overnight
+ * turns yesterday's working slice into today's gateway timeout, and the only
+ * symptom is a 504 with no clue in it."
+ *
+ * Locale-independent by nature — these are character counts.
+ */
+describe('planBatches — cut by character budget', () => {
+  const seg = (id: string, chars: number): TranslationSegment => ({
+    id,
+    text: 'x'.repeat(chars),
+  });
+
+  it('cuts a batch when the character budget is reached', () => {
+    const batches = planBatches(
+      [seg('a', 1_500), seg('b', 1_500), seg('c', 1_500)],
+      { maxCharsPerBatch: 3_200, maxSegmentsPerBatch: 25 },
+    );
+
+    expect(batches.length).toBeGreaterThan(1);
+    expect(batches[0]!.map((s) => s.id)).toEqual(['a', 'b']);
+  });
+
+  it('always includes at least one segment, even when it alone exceeds the budget', () => {
+    // Otherwise an oversized segment is skipped forever — `takeWithinBudget`'s
+    // rule, for exactly the same reason.
+    const batches = planBatches([seg('huge', 50_000), seg('small', 10)], {
+      maxCharsPerBatch: 4_000,
+      maxSegmentsPerBatch: 25,
+    });
+
+    expect(batches[0]).toHaveLength(1);
+    expect(batches[0]![0]!.id).toBe('huge');
+    expect(batches.flat().map((s) => s.id)).toContain('small');
+  });
+
+  it('honours the hard segment ceiling so an id list cannot dominate the call', () => {
+    // A page of one-line table cells must not become a 300-item echo list.
+    const many = Array.from({ length: 60 }, (_, i) => seg(`cell-${i}`, 5));
+
+    const batches = planBatches(many, { maxCharsPerBatch: 4_000, maxSegmentsPerBatch: 25 });
+
+    for (const batch of batches) expect(batch.length).toBeLessThanOrEqual(25);
+    // Nothing is lost in the cutting.
+    expect(batches.flat()).toHaveLength(60);
+  });
+
+  it('loses no segment and duplicates none, whatever the budget', () => {
+    const segments = Array.from({ length: 37 }, (_, i) => seg(`s-${i}`, 200));
+
+    const flat = planBatches(segments, DEFAULT_BATCH_LIMITS).flat();
+
+    expect(flat.map((s) => s.id)).toEqual(segments.map((s) => s.id));
+  });
+});