claude-translator 1.3.0 → 2.0.0

package/scripts/providers/openai.mjs

@@ -22,18 +22,44 @@
  * so a weaker guarantee here costs retries, not correctness. The rung is chosen by
  * config (`jsonMode`) and falls back automatically when the server rejects a request
  * for mentioning `response_format`.
+ *
+ * ── Sampling is not universal either ─────────────────────────────────────────
+ * The same "one adapter, many servers" problem applies to `temperature`. Reasoning
+ * models reject it outright — GPT-5.x answers a `temperature: 0.2` with
+ * 400 "Unsupported value: 'temperature' … Only the default (1) is supported" — and
+ * they take a reasoning budget instead. That is handled twice over, deliberately:
+ * proactively by the model table below, and reactively by `unsupportedParam()`, so a
+ * model family nobody has heard of yet degrades instead of failing the whole run.
  */
 
 const API = 'https://api.openai.com/v1';
 
 export const id = 'openai';
 export const label = 'OpenAI-compatible';
-export const defaultModel = 'gpt-4o-mini';
+export const defaultModel = 'gpt-5.6-luna';
 export const envKeys = ['OPENAI_API_KEY', 'OPENAI_COMPATIBLE_API_KEY'];
 
 /** Local servers accept any key, but some reject a missing Authorization header. */
 export const keyOptional = true;
 
+/**
+ * Model families that reject sampling parameters and take `reasoning_effort` instead.
+ *
+ * Kept to a prefix match on purpose. This adapter points at dozens of servers, and a
+ * local model whose id merely CONTAINS "gpt-5" must not be caught by it — `qwen2.5:14b`
+ * and friends still get `temperature` exactly as before.
+ */
+const REASONING = [/^gpt-5/i, /^o[1-9](-|$)/i];
+const isReasoning = (model) => REASONING.some((re) => re.test(String(model)));
+
+/**
+ * Parameters this adapter is willing to drop and retry without. Nothing else is
+ * droppable, so a 400 that happens to contain the word "unsupported" can never make the
+ * pipeline silently discard something load-bearing. `response_format` is deliberately
+ * absent — it has its own ladder in `unsupportedJsonMode()`.
+ */
+const DROPPABLE = ['temperature', 'reasoning_effort', 'top_p'];
+
 const RESPONSE_SCHEMA = {
   type: 'object',
   properties: {
@@ -51,16 +77,28 @@ const RESPONSE_SCHEMA = {
   additionalProperties: false,
 };
 
-export function request({ model, system, items, temperature, key, baseUrl, jsonMode }) {
+export function request({ model, system, items, temperature, key, baseUrl, jsonMode, drop }) {
+  const dropped = drop ?? new Set();
   const body = {
     model,
-    temperature,
     messages: [
       { role: 'system', content: system },
       { role: 'user', content: JSON.stringify(items) },
     ],
   };
 
+  // Reasoning models: no sampling parameter, and no reasoning budget either. Bulk
+  // segment translation is a low-reasoning task, so paying for thinking tokens on every
+  // batch of forty is pure waste — the same call `anthropic.mjs` makes when it pins the
+  // thinking tiers to `effort: 'low'`. `temperature` is omitted rather than sent as 1 so
+  // the server applies its own default; sending a value it merely tolerates would be a
+  // claim we have no reason to make.
+  if (isReasoning(model)) {
+    if (!dropped.has('reasoning_effort')) body.reasoning_effort = 'none';
+  } else if (!dropped.has('temperature')) {
+    body.temperature = temperature;
+  }
+
   const mode = jsonMode ?? 'schema';
   if (mode === 'schema') {
     body.response_format = {
@@ -111,9 +149,31 @@ export const unwrap = (parsed) => parsed?.translations ?? parsed;
  */
 export function unsupportedJsonMode(status, errText) {
   if (status !== 400 && status !== 404 && status !== 422) return false;
+  if (unsupportedParam(status, errText)) return false; // a sampling complaint, not a schema one
   return /response_format|json_schema|json_object|not supported|unrecognized|unknown.*field/i.test(errText);
 }
 
+/**
+ * A rejection caused by ONE request parameter rather than by the request being wrong.
+ * Returns the parameter's name so `translate.mjs` can retry without it, or null.
+ *
+ * The bar is deliberately high: the error must read like a capability complaint AND name
+ * a parameter this adapter actually sends and is willing to lose. Anything looser would
+ * let a genuine 400 ("model not found") be mistaken for a recoverable one, and the run
+ * would keep quietly degrading its own request instead of telling the user.
+ *
+ * Real messages this must catch:
+ *   400 "Unsupported value: 'temperature' does not support 0.2 with this model.
+ *        Only the default (1) is supported."
+ *   400 "Unrecognized request argument supplied: reasoning_effort"
+ */
+export function unsupportedParam(status, errText) {
+  if (status !== 400 && status !== 422) return null;
+  const text = String(errText ?? '');
+  if (!/unsupported|unrecognized|unknown|not supported|does not support/i.test(text)) return null;
+  return DROPPABLE.find((p) => new RegExp(`\\b${p}\\b`).test(text)) ?? null;
+}
+
 /** Unknown by design: this adapter points at dozens of providers, and local ones are free. */
 export function pricing() {
   return null;

package/scripts/providers/providers.test.mjs

@@ -131,6 +131,86 @@ test('openai: default host and bearer auth', () => {
   assert.equal(r.body.messages[1].content, JSON.stringify(ITEMS));
 });
 
+// ── Reasoning models reject sampling ─────────────────────────────────────────
+// GPT-5.x answers `temperature: 0.2` with a 400 and takes reasoning_effort instead.
+// Both halves are asserted: what the reasoning models get, and — just as important —
+// that nothing else changed for the models and local servers that were working.
+
+test('openai: a reasoning model gets no temperature and no reasoning budget', () => {
+  const r = openai.request({ ...ARGS, model: 'gpt-5.6-luna' });
+  assert.equal(r.body.temperature, undefined, 'GPT-5.x returns 400 on any temperature but 1');
+  assert.equal(r.body.reasoning_effort, 'none', 'bulk translation must not pay for reasoning');
+});
+
+test('openai: the o-series is treated the same way', () => {
+  for (const model of ['o1', 'o3-mini', 'o4-mini']) {
+    const r = openai.request({ ...ARGS, model });
+    assert.equal(r.body.temperature, undefined, `${model} rejects sampling params`);
+    assert.equal(r.body.reasoning_effort, 'none');
+  }
+});
+
+test('openai: a pinned gpt-4o-mini still gets temperature, unchanged', () => {
+  const r = openai.request({ ...ARGS, model: 'gpt-4o-mini' });
+  assert.equal(r.body.temperature, 0.2);
+  assert.equal(r.body.reasoning_effort, undefined);
+});
+
+test('openai: a local model is never caught by the reasoning rule', () => {
+  // The match is anchored, so an id that merely CONTAINS "gpt-5" must not match —
+  // a local server would reject reasoning_effort and lose its sampling parameter.
+  for (const model of ['qwen2.5:14b', 'llama3.1:70b', 'my-finetune-of-gpt-5']) {
+    const r = openai.request({ ...ARGS, model });
+    assert.equal(r.body.temperature, 0.2, `${model} must keep sampling`);
+    assert.equal(r.body.reasoning_effort, undefined, `${model} must not be sent a reasoning budget`);
+  }
+});
+
+test('openai: request honours an explicit drop set', () => {
+  const noTemp = openai.request({ ...ARGS, model: 'gpt-4o-mini', drop: new Set(['temperature']) });
+  assert.equal(noTemp.body.temperature, undefined);
+
+  const noEffort = openai.request({ ...ARGS, model: 'gpt-5.6-luna', drop: new Set(['reasoning_effort']) });
+  assert.equal(noEffort.body.reasoning_effort, undefined);
+  assert.equal(noEffort.body.temperature, undefined, 'dropping the budget must not re-add sampling');
+});
+
+test('openai: unsupportedParam names the one parameter to drop', () => {
+  // The messages OpenAI actually returns.
+  assert.equal(
+    // Copied verbatim from a real 400 returned by gpt-5.6-luna on 2026-08-25.
+    openai.unsupportedParam(400, "Unsupported value: 'temperature' does not support 0.2 with this model. Only the default (1) value is supported."),
+    'temperature'
+  );
+  assert.equal(
+    openai.unsupportedParam(400, 'Unrecognized request argument supplied: reasoning_effort'),
+    'reasoning_effort'
+  );
+
+  // A genuine bad request must NOT be mistaken for a recoverable one, or the pipeline
+  // would quietly strip its own parameters instead of surfacing the real problem.
+  assert.equal(openai.unsupportedParam(400, 'model not found'), null);
+  assert.equal(openai.unsupportedParam(401, 'invalid api key'), null);
+  assert.equal(openai.unsupportedParam(429, 'rate limited'), null);
+  // Names a parameter we never send, so there is nothing to usefully drop.
+  assert.equal(openai.unsupportedParam(400, "Unsupported parameter: 'frequency_penalty'"), null);
+});
+
+test('openai: the two capability hooks never both claim the same error', () => {
+  const cases = [
+    "Unsupported value: 'temperature' does not support 0.2 with this model.",
+    'Unrecognized request argument supplied: reasoning_effort',
+    "Unknown field 'response_format'",
+    'json_schema is not supported',
+  ];
+  for (const text of cases) {
+    const json = openai.unsupportedJsonMode(400, text);
+    const param = openai.unsupportedParam(400, text);
+    assert.ok(!(json && param), `both hooks claimed: ${text}`);
+    assert.ok(json || param, `neither hook claimed a capability error: ${text}`);
+  }
+});
+
 test('openai: a custom host is used verbatim — this is how local models work', () => {
   const r = openai.request({ ...ARGS, model: 'qwen2.5:14b', baseUrl: 'http://localhost:11434/v1' });
   assert.equal(r.url, 'http://localhost:11434/v1/chat/completions');

package/scripts/roles.mjs

@@ -0,0 +1,142 @@
+/**
+ * Element context — telling the translator WHAT a string is, not just what it says.
+ *
+ * The prompt has always ended rule 5 with "Headings stay headings; button labels stay
+ * short." That sentence was unenforceable: the model received `{ id, text }` and had no
+ * way to tell a <button> from a paragraph. Every string looked like prose.
+ *
+ * extract.mjs already knows the answer — it walks the DOM and has `node.tagName` in hand
+ * at the moment it records a unit. It simply threw it away. This module turns that tag
+ * into a short label the model can act on.
+ *
+ * ── Why a separate field, not a richer `kind` ────────────────────────────────
+ * build-locales.mjs switches on `seg.kind === 'block' | 'jsonld' | startsWith('attr:')`
+ * to decide how to escape a replacement. A value like 'block:button' would fall through
+ * to escHtml and print literal &lt;0&gt; placeholder tokens as visible text on every
+ * localized page — silent corruption that no test catches. So `kind` is untouched and
+ * `el` is new.
+ *
+ * ── Why this costs nothing ───────────────────────────────────────────────────
+ * Ordinary prose returns null and the field is omitted from the payload entirely. Only
+ * the strings where the answer changes the translation carry it.
+ */
+
+/**
+ * Block-level elements whose register genuinely differs from body copy.
+ *
+ * <a> is the interesting entry. It is an INLINE element in extract.mjs, so a link inside
+ * a sentence is absorbed into the surrounding block as a <0>…</0> placeholder and never
+ * recorded on its own. An <a> that DOES surface as its own unit is therefore a standalone
+ * link — a call to action or a nav item — which makes it a high-precision signal rather
+ * than noise.
+ */
+const BLOCK_ROLES = {
+  button: 'button',
+  a: 'button',
+  h1: 'heading',
+  h2: 'heading',
+  h3: 'heading',
+  h4: 'heading',
+  h5: 'heading',
+  h6: 'heading',
+  title: 'page title',
+  label: 'form label',
+  legend: 'form label',
+  summary: 'expander label',
+  th: 'table header',
+  figcaption: 'caption',
+  option: 'menu option',
+  optgroup: 'menu option',
+};
+
+/** Attribute-sourced strings. The attribute name IS the role. */
+const ATTR_ROLES = {
+  'attr:alt': 'image alt text',
+  'attr:placeholder': 'input placeholder',
+  'attr:aria-label': 'accessible label',
+  'attr:aria-description': 'accessible description',
+  'attr:title': 'tooltip',
+};
+
+/**
+ * Meta tags carry their key in `el` as `meta:<key>`, because `kind` flattens every one of
+ * them to `attr:content` and a description behaves nothing like an og:title.
+ */
+const META_ROLES = {
+  description: 'meta description',
+  'og:description': 'social share description',
+  'twitter:description': 'social share description',
+  'og:title': 'social share title',
+  'twitter:title': 'social share title',
+  'og:site_name': 'site name',
+  'og:image:alt': 'image alt text',
+  'twitter:image:alt': 'image alt text',
+};
+
+/**
+ * The label for one unit, or null when it is ordinary prose.
+ *
+ * @param {{kind?: string, el?: string|null}} unit  a record from i18n/source.json
+ */
+export function roleOf(unit) {
+  if (!unit || typeof unit !== 'object') return null;
+  const { kind, el } = unit;
+
+  // A conflicting element cleared the hint at extraction time. Saying nothing is correct
+  // here — a confident wrong answer is worse than no answer.
+  if (el === null || el === undefined) {
+    return kind === 'jsonld' ? 'structured data' : null;
+  }
+
+  if (typeof el === 'string' && el.startsWith('meta:')) {
+    return META_ROLES[el.slice(5)] ?? 'page metadata';
+  }
+
+  if (typeof kind === 'string' && kind.startsWith('attr:')) {
+    return ATTR_ROLES[kind] ?? null;
+  }
+
+  if (kind === 'jsonld') return 'structured data';
+
+  return BLOCK_ROLES[el] ?? null;
+}
+
+/**
+ * The guidance block appended to the system prompt, listing only the roles actually
+ * present in this batch. Empty string when the batch is all prose, so a run that
+ * translates nothing but paragraphs pays not a single extra token.
+ */
+export function rolePrompt(roles) {
+  const present = [...new Set(roles.filter(Boolean))].sort();
+  if (!present.length) return '';
+
+  const ADVICE = {
+    button: 'A control the user clicks. Keep it at or near the source length — it sits in a fixed-width box. Use whatever construction your language uses on buttons, which is often not the imperative: an infinitive, a verbal noun, or a bare noun may all read better than a literal command. No final period.',
+    'form label': 'Names a field. Short, nominal, no final period.',
+    'expander label': 'A short clickable summary. Keep it terse.',
+    heading: 'A headline. Keep it headline-shaped and roughly the source length; do not expand it into a sentence.',
+    'page title': 'The browser tab and search-result title. Under about 60 characters if the language allows.',
+    'meta description': 'Search-result copy. One or two sentences, under about 155 characters, written to be read in a results page.',
+    'social share title': 'A share-card headline. Short and concrete.',
+    'social share description': 'A share-card summary. One sentence.',
+    'image alt text': 'Describes an image for someone who cannot see it. Plain and factual, no "image of".',
+    'input placeholder': 'Example text inside an empty field. Very short.',
+    'accessible label': 'Read aloud by a screen reader. Say what the control does.',
+    'accessible description': 'Extra screen-reader detail. One short phrase.',
+    tooltip: 'A hover hint. One short phrase.',
+    'table header': 'A column heading. Very short, nominal.',
+    caption: 'A figure caption. One short sentence.',
+    'menu option': 'One choice in a dropdown. Very short.',
+    'site name': 'The name of the site. Usually left unchanged.',
+    'page metadata': 'Metadata, not body copy. Keep it compact.',
+    'structured data': 'A search-engine structured-data value. Plain text, no markup, no added punctuation.',
+  };
+
+  return [
+    `CONTEXT`,
+    `Some items carry an "el" field naming what the string is on the page. It is not part`,
+    `of the text and must not be translated or echoed. Where it appears, honour it:`,
+    ...present.map((r) => `   - ${r}: ${ADVICE[r] ?? 'Keep the register appropriate to this element.'}`),
+    `Items with no "el" field are body copy — translate them normally.`,
+  ].join('\n');
+}

package/scripts/roles.test.mjs

@@ -0,0 +1,140 @@
+/**
+ * Element-context contract tests. No network, no key, no model.
+ *
+ * The prompt has always said "button labels stay short" while the model had no way to
+ * know what a button was. These tests pin the mapping that finally makes that actionable,
+ * and — more importantly — pin the cases where the tool must say NOTHING rather than
+ * guess.
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { roleOf, rolePrompt } from './roles.mjs';
+
+const unit = (el, kind = 'block') => ({ kind, el });
+
+// ── Controls ─────────────────────────────────────────────────────────────────
+
+test('a button is a button', () => {
+  assert.equal(roleOf(unit('button')), 'button');
+});
+
+test('a standalone <a> is treated as a call to action', () => {
+  // <a> is INLINE in extract.mjs, so a link inside a sentence is absorbed into the
+  // surrounding block as a placeholder and never recorded on its own. An <a> that DOES
+  // surface as its own unit is a standalone link — a CTA or a nav item.
+  assert.equal(roleOf(unit('a')), 'button');
+});
+
+test('headings at every level map to one role', () => {
+  for (const h of ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']) {
+    assert.equal(roleOf(unit(h)), 'heading', h);
+  }
+});
+
+test('form and table furniture get their own roles', () => {
+  assert.equal(roleOf(unit('label')), 'form label');
+  assert.equal(roleOf(unit('legend')), 'form label');
+  assert.equal(roleOf(unit('summary')), 'expander label');
+  assert.equal(roleOf(unit('th')), 'table header');
+  assert.equal(roleOf(unit('figcaption')), 'caption');
+  assert.equal(roleOf(unit('option')), 'menu option');
+  assert.equal(roleOf(unit('title')), 'page title');
+});
+
+// ── Prose says nothing ───────────────────────────────────────────────────────
+
+test('ordinary prose returns null so the field is omitted entirely', () => {
+  for (const el of ['p', 'div', 'span', 'li', 'td', 'blockquote', 'section']) {
+    assert.equal(roleOf(unit(el)), null, el);
+  }
+});
+
+test('an unknown element is prose, not a guess', () => {
+  assert.equal(roleOf(unit('marquee')), null);
+  assert.equal(roleOf(unit('my-web-component')), null);
+});
+
+// ── The collision case ───────────────────────────────────────────────────────
+
+test('a cleared element yields no hint at all', () => {
+  // extract.mjs sets el to null when the same string appears as both a button and a
+  // paragraph. Saying nothing is correct: a confident wrong answer is worse than none.
+  assert.equal(roleOf(unit(null)), null);
+  assert.equal(roleOf({ kind: 'block' }), null, 'a missing el behaves like a cleared one');
+});
+
+// ── Attributes ───────────────────────────────────────────────────────────────
+
+test('attribute roles come from the attribute, not the element', () => {
+  assert.equal(roleOf({ kind: 'attr:alt', el: 'img' }), 'image alt text');
+  assert.equal(roleOf({ kind: 'attr:placeholder', el: 'input' }), 'input placeholder');
+  assert.equal(roleOf({ kind: 'attr:aria-label', el: 'button' }), 'accessible label');
+  assert.equal(roleOf({ kind: 'attr:title', el: 'abbr' }), 'tooltip');
+});
+
+test('an unmapped attribute is silent rather than mislabelled', () => {
+  assert.equal(roleOf({ kind: 'attr:data-thing', el: 'div' }), null);
+});
+
+// ── Meta tags ────────────────────────────────────────────────────────────────
+
+test('meta tags are distinguished by key, which kind alone cannot express', () => {
+  // Every meta tag arrives as kind "attr:content"; the key travels in el.
+  assert.equal(roleOf({ kind: 'attr:content', el: 'meta:description' }), 'meta description');
+  assert.equal(roleOf({ kind: 'attr:content', el: 'meta:og:title' }), 'social share title');
+  assert.equal(roleOf({ kind: 'attr:content', el: 'meta:og:description' }), 'social share description');
+  assert.equal(roleOf({ kind: 'attr:content', el: 'meta:og:image:alt' }), 'image alt text');
+});
+
+test('an unrecognised meta key still says "not body copy"', () => {
+  assert.equal(roleOf({ kind: 'attr:content', el: 'meta:custom:thing' }), 'page metadata');
+});
+
+// ── JSON-LD ──────────────────────────────────────────────────────────────────
+
+test('structured data is labelled even though it has no element', () => {
+  assert.equal(roleOf({ kind: 'jsonld', el: null }), 'structured data');
+});
+
+// ── Defensive ────────────────────────────────────────────────────────────────
+
+test('junk input never throws', () => {
+  for (const junk of [null, undefined, 'string', 42, []]) {
+    assert.doesNotThrow(() => roleOf(junk));
+  }
+  assert.equal(roleOf(null), null);
+});
+
+// ── The prompt block ─────────────────────────────────────────────────────────
+
+test('a batch of pure prose produces no prompt text and costs no tokens', () => {
+  assert.equal(rolePrompt([]), '');
+  assert.equal(rolePrompt([null, null, undefined]), '');
+});
+
+test('only the roles present in the batch are described', () => {
+  const p = rolePrompt(['button', 'heading']);
+  assert.match(p, /- button:/);
+  assert.match(p, /- heading:/);
+  assert.ok(!/image alt text/.test(p), 'roles absent from the batch must not be described');
+});
+
+test('duplicates collapse, so forty buttons describe the role once', () => {
+  const p = rolePrompt(Array(40).fill('button'));
+  assert.equal((p.match(/- button:/g) ?? []).length, 1);
+});
+
+test('the button advice does not demand the imperative', () => {
+  // Languages differ: German UI prefers a verbal noun, French the infinitive. Ordering a
+  // literal imperative everywhere is precisely the defect this feature exists to avoid.
+  const p = rolePrompt(['button']);
+  assert.match(p, /not the imperative/i);
+  assert.match(p, /fixed-width/);
+});
+
+test('the prompt tells the model el is metadata, not text to translate', () => {
+  const p = rolePrompt(['button']);
+  assert.match(p, /must not be translated or echoed/);
+});

package/scripts/tqa-score.mjs

@@ -0,0 +1,127 @@
+/**
+ * TQA scoring primitives — the parts with no I/O, no network and no config, so they can
+ * be tested directly. tqa.mjs owns the run; this file owns the arithmetic and the
+ * sampling, which are the parts a reader is entitled to check.
+ */
+
+/**
+ * Severity weights. These are the conventional MQM values — minor 1, major 5,
+ * critical 10 — kept rather than tuned, so a score here means the same thing it means
+ * in any other MQM report.
+ */
+export const WEIGHT = { minor: 1, major: 5, critical: 10 };
+
+/**
+ * The typology offered to the judge. Deliberately short: a long taxonomy produces
+ * category-shopping and inconsistent labelling between runs, and the categories that
+ * matter for web localization are these.
+ */
+export const CATEGORIES = [
+  'accuracy/mistranslation',
+  'accuracy/omission',
+  'accuracy/addition',
+  'accuracy/untranslated',
+  'fluency/grammar',
+  'fluency/spelling',
+  'fluency/register',
+  'fluency/awkward',
+  'terminology/inconsistent',
+  'terminology/glossary',
+  'locale/number-date-currency',
+  'style/tone',
+  'markup/placeholder',
+];
+
+// ── Deterministic sampling ───────────────────────────────────────────────────
+
+/** mulberry32 — a small seeded PRNG, so a reported score can be reproduced exactly. */
+export function rng(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+export const words = (s) => (String(s).trim().match(/\S+/g) ?? []).length;
+
+/**
+ * Stratified sample, weighted by how often a unit appears on the site.
+ *
+ * A uniform sample over-represents the long tail of one-off strings and under-represents
+ * the header, footer and nav that every visitor reads on every page. `count` is already
+ * recorded by extract.mjs, so weighting by it costs nothing and makes the score reflect
+ * what people actually see. Strata are frequency terciles, sampled proportionally.
+ */
+export function stratifiedSample(units, n, seed) {
+  if (units.length <= n) return units.slice();
+  const rand = rng(seed);
+  const sorted = units.slice().sort((a, b) => (b.count ?? 1) - (a.count ?? 1));
+  const third = Math.ceil(sorted.length / 3);
+  const strata = [sorted.slice(0, third), sorted.slice(third, third * 2), sorted.slice(third * 2)];
+
+  const picked = [];
+  strata.forEach((stratum, i) => {
+    if (!stratum.length) return;
+    // The most-repeated third gets half the sample; the rest split the remainder.
+    const share = i === 0 ? 0.5 : 0.25;
+    const want = Math.min(stratum.length, Math.max(1, Math.round(n * share)));
+    const pool = stratum.slice();
+    for (let k = 0; k < want && pool.length; k++) {
+      picked.push(pool.splice(Math.floor(rand() * pool.length), 1)[0]);
+    }
+  });
+  return picked.slice(0, n);
+}
+
+
+/**
+ * MQM score for a set of assessed units.
+ */
+export function score(assessed) {
+  const totalWords = assessed.reduce((n, a) => n + a.words, 0);
+  let penalty = 0;
+  const byCategory = {};
+  const bySeverity = { minor: 0, major: 0, critical: 0 };
+
+  for (const a of assessed) {
+    for (const e of a.errors) {
+      penalty += WEIGHT[e.severity];
+      bySeverity[e.severity]++;
+      byCategory[e.category] = (byCategory[e.category] ?? 0) + 1;
+    }
+  }
+  const mqm = totalWords ? 100 - (penalty / totalWords) * 100 : 100;
+  return {
+    mqm: Math.round(mqm * 100) / 100,
+    penalty,
+    totalWords,
+    unitsAssessed: assessed.length,
+    unitsClean: assessed.filter((a) => a.errors.length === 0).length,
+    bySeverity,
+    byCategory,
+  };
+}
+
+
+/** Parse the judge's per-unit payload. Anything unreadable is dropped, never guessed. */
+export function parseErrors(raw) {
+  if (typeof raw !== 'string') return null;
+  const text = raw.trim();
+  if (!text) return [];
+  try {
+    const parsed = JSON.parse(text);
+    if (!Array.isArray(parsed)) return null;
+    return parsed
+      .map((e) => ({
+        category: String(e.c ?? e.category ?? '').trim(),
+        severity: String(e.s ?? e.severity ?? '').trim().toLowerCase(),
+        note: String(e.n ?? e.note ?? '').trim(),
+      }))
+      .filter((e) => WEIGHT[e.severity] !== undefined);
+  } catch {
+    return null;
+  }
+}