@hyperfixi/testing-framework 2.11.1 → 3.0.0

package/CHANGELOG.md

@@ -7,6 +7,126 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-09-03
+
+Full notes: [GitHub Releases](https://github.com/codetalcott/hyperfixi/releases/tag/v3.0.0).
+
+One major, two themes. `@lokascript/i18n`'s grammar transformer is gone,
+because `@lokascript/semantic` overtook it on every row of the translation
+corpus (#973–#1001). And the engine-migration plan
+(`docs-internal/ENGINE_MIGRATION_PLAN.md`) is complete: its last arc deleted
+the exported dead code it had been carrying and collapsed the browser bundle
+lineup to two names (#1099–#1105).
+
+### ⚠ BREAKING
+
+- **`@lokascript/i18n` no longer translates** (#1001). `translate()`, `toLocale()`,
+  `toEnglish()`, `GrammarTransformer` and `createTransformer` are deleted; the
+  package is per-language vocabulary and grammar profiles. Migrate to
+  `import { translate } from '@lokascript/semantic'` (same signature; it throws
+  on unparseable input where the transformer returned nonsense). The classic-i18n
+  browser bundle, `@hyperscript-tools/i18n` and `@lokascript/types-browser` drop
+  the same members (#998, #999); the patterns corpus writer is semantic-only (#1000).
+- **The prebuilt browser bundles are two names** (#1105): `hyperfixi-hx.js`
+  (small: hybrid parser, blocks, expressions, htmx v1/v2 attributes) and
+  `hyperfixi.js` (everything); `hyperfixi-hx-v4.js` and
+  `hyperfixi-multilingual.js` stay as separate products. `hyperfixi-lite.js`,
+  `-lite-plus.js`, `-minimal.js`, `-standard.js` and their `./browser/*`
+  exports are gone — use `hyperfixi-hx.js`, `hyperfixi.js`, or the Vite
+  plugin, which picks the tier itself. `./browser/hybrid-complete` remains as
+  the plugin's internal fallback.
+- **Exported dead code deleted from `@hyperfixi/core`** — none had a
+  production caller: the six `@deprecated` `features/` families and the
+  modular bundle's `features` namespace (#1099); `Lexer`/`Tokens` (#1100 —
+  use `tokenize`); the `unified-types` `Validator`, the `types.d.ts` shim and
+  `registry/multilingual` (#1101); the `async` command (#1102 — it was
+  unreachable from parsed hyperscript; the manifest is 58 commands);
+  `ContextProviderRegistry`, the context-provider `Proxy`, the registry's
+  `context` slot and the plugin `contextProviders` field (#1104 — set
+  request-scoped values as `context.locals`).
+
+### Fixed
+
+- **A small bundle fails loudly on a command it lacks and names `hyperfixi.js`**
+  (#1103). The hybrid parser had been dropping an unrecognised word silently;
+  making it loud also exposed and fixed three silent mis-parses in the hybrid
+  bundles: unquoted `fetch /api/data` fetched `/`, `send custom:event` sent
+  `custom` to `me`, and `repeat forever` ran zero iterations.
+- **English→foreign rendering is gated** (#931–#972, #953): 3105/3105 corpus
+  renders parse on the canonical engine; the bare (handler-less) surface has its
+  own gate. `as JSON` stays part of the value (#991); a flattened loop header
+  closes (#992).
+- Plugins report their real versions (#926); `analyze_content` is unshadowed in
+  the MCP server (#927); four dependency advisories resolved; the `domain-flow`
+  → `server-bridge` route contract is pinned (#1000s).
+
+### Changed
+
+- `hyperfixi.js` and `hyperfixi-hx-v4.js` carry the 24-language render
+  vocabulary (~19 KB gzip each) so `translate` works in the browser (#931).
+- Deprecated `@lokascript/domain-*` references repoint to `@lokascript/domains`.
+
+## [2.11.1] - 2026-08-25
+
+Patch release. Fixes the release workflow itself: the build now runs **after**
+the version sync, so a published tarball carries its own version rather than
+the previous one, and `version.ts` is committed (#925). Also lands the
+agent-loop A/B benchmark with an isolated generator (#924).
+
+## [2.11.0] - 2026-08-24
+
+Full notes: [GitHub Releases](https://github.com/codetalcott/hyperfixi/releases/tag/v2.11.0).
+
+### Changed
+
+- **The domain-DSL family moved out** (#909). Twelve packages left this
+  monorepo: the ten publishable `@lokascript/domain-*` packages (bdd,
+  behaviorspec, config, flow, jsx, learn, llm, sql, todo, voice) plus the
+  private `domain-toolkit` and `mcp-multilingual-intent`. They now ship as
+  **`@lokascript/domains`**, one subpath export per domain, from the
+  [lokascript-domains](https://github.com/codetalcott/lokascript-domains)
+  repository.
+
+  All ten published names are **deprecated on npm**, each naming its
+  replacement subpath (`@lokascript/domain-sql` → "import from
+  `@lokascript/domains/sql`"). Existing installs keep working — deprecation is
+  a warning, not a removal — they simply stop receiving updates. The
+  pre-deletion tree is preserved at the `moved/domain-family` tag.
+
+  _Migration:_ replace nine dependencies with one, and change
+  `from '@lokascript/domain-x'` to `from '@lokascript/domains/x'`. The root
+  entry absorbed `domain-config` and exports `createDomainRegistry`,
+  `registerAllDomains` and `DOMAIN_PRIORITY`.
+
+### Added
+
+- **"Show in My Language"** — LSP request plus VSCode command (#921).
+- **Verified-translation badge** in the compilation service (#920).
+- **`scoreFidelity` / `@lokascript/semantic/fidelity`** (#919).
+- **Inert-shape warnings** (#918) and surfaced unconsumed-input warnings (#916)
+  in the compilation service.
+- **The agent-loop benchmark** and the silent-failure finding it produced
+  (#915), and the MCP server's agent-era roadmap (#914).
+- **Element-collection write-back** for hypermedia tables, with gallery
+  examples and four system fixes (#904).
+- **The comprehensive Playwright tier now runs in CI** (#908) alongside
+  `quick`. It had never run: 122 specs, hiding four real bugs — a detached
+  `startViewTransition`, untracked reads of unset globals, concurrent effects
+  clobbering dependency capture, and `put` stringifying DocumentFragments
+  (#905).
+
+### Fixed
+
+- **The `hyperscript-adapter` review arc** (#895–#902): whole-string
+  translation first, taking canonical validity from 2849/3105 to **3105/3105**
+  (#899); a host-parser validity gate so an invalid render falls back to the
+  author's text (#900); the dead split-statement fallback deleted after
+  measuring 0 outputs (#901); and the slim divergence set burned 6 → 1 via
+  schema marker data, repairing 39 body-dropping corpus rows (#902).
+- **`qu take.recipient`** — the R1 tail's last `take` row (#910).
+- **The release workflows** no longer reference the moved-out domain family
+  (#922).
+
 ## [2.10.0] - 2026-08-01
 
 Full notes: [GitHub Releases](https://github.com/codetalcott/hyperfixi/releases/tag/v2.10.0).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperfixi/testing-framework",
-  "version": "2.11.1",
+  "version": "3.0.0",
   "description": "Cross-platform behavior testing suite for LokaScript applications",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -40,7 +40,7 @@
     "analyze-failures": "tsx src/multilingual/tools/analyze-failures.ts",
     "typecheck": "tsc --noEmit",
     "test:check": "VITEST_QUIET=1 bash ../../scripts/vitest-run.sh --reporter=dot",
-    "test:canonical": "FOREIGN_CANONICAL_VALIDITY=1 VITEST_TIMEOUT=300 bash ../../scripts/vitest-run.sh --reporter=dot src/multilingual/canonical-validity.test.ts src/multilingual/foreign-canonical-validity.test.ts",
+    "test:canonical": "FOREIGN_CANONICAL_VALIDITY=1 VITEST_TIMEOUT=300 bash ../../scripts/vitest-run.sh --reporter=dot src/multilingual/canonical-validity.test.ts src/multilingual/foreign-canonical-validity.test.ts src/multilingual/render-fidelity.test.ts src/multilingual/bare-render-fidelity.test.ts",
     "test:shipped-sources": "VITEST_TIMEOUT=300 bash ../../scripts/vitest-run.sh --reporter=dot src/multilingual/shipped-sources-validity.test.ts"
   },
   "keywords": [
@@ -57,17 +57,17 @@
   "author": "LokaScript Contributors",
   "license": "MIT",
   "dependencies": {
-    "@hyperfixi/core": "^2.11.1",
-    "@hyperfixi/patterns-reference": "^2.11.1",
-    "@lokascript/compilation-service": "^2.11.1",
-    "@lokascript/i18n": "^2.11.1",
-    "@lokascript/semantic": "^2.11.1",
+    "@hyperfixi/core": "^3.0.0",
+    "@hyperfixi/patterns-reference": "^3.0.0",
+    "@lokascript/compilation-service": "^3.0.0",
+    "@lokascript/i18n": "^3.0.0",
+    "@lokascript/semantic": "^3.0.0",
     "diff": "^8.0.3",
     "esbuild": "^0.28.0",
     "happy-dom": "^20.10.6",
     "jsdom": "^30.0.0",
     "playwright": "^1.40.0",
-    "puppeteer": "^24.26.1",
+    "puppeteer": "^25.9.0",
     "tsx": "^4.23.1",
     "url-parse": "^1.5.10",
     "vite": "^8.1.4"

package/src/multilingual/bare-render-fidelity.test.ts

@@ -0,0 +1,100 @@
+/**
+ * BARE-surface en→foreign render-fidelity ratchet (see bare-render-fidelity.ts
+ * for why this exists and why it is not redundant with the wrapped gate).
+ *
+ * Identical assertions to `render-fidelity.test.ts`, over handler-STRIPPED
+ * corpus bodies. The allowlist is seeded at the level measured when the gate
+ * landed, so it starts green; it is a record of what is known-broken, not a
+ * target, and completing a fix means deleting entries.
+ *
+ * Needs FOREIGN_CANONICAL_VALIDITY=1 and a freshly populated patterns.db, the
+ * same contract the two sibling gates carry.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { describe, it, expect, beforeAll } from 'vitest';
+import { checkBareRenderFidelity } from './bare-render-fidelity';
+import { groupFailuresByPattern, type RenderFidelityResult } from './render-fidelity';
+
+interface AllowlistDoc {
+  checked: number;
+  clean: number;
+  cleanPct: number;
+  allowedFailures: Record<string, string[]>;
+}
+
+const baselinePath = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../baselines/bare-render-fidelity.json'
+);
+const allowlist = JSON.parse(readFileSync(baselinePath, 'utf8')) as AllowlistDoc;
+const key = (id: string, language: string) => `${id} ${language}`;
+const allowed = new Set(
+  Object.entries(allowlist.allowedFailures).flatMap(([id, langs]) => langs.map(l => key(id, l)))
+);
+
+const DB_FRESHLY_POPULATED = process.env.FOREIGN_CANONICAL_VALIDITY === '1';
+
+describe.skipIf(!DB_FRESHLY_POPULATED)('bare-surface english→foreign render-fidelity gate', () => {
+  let result: RenderFidelityResult;
+
+  beforeAll(async () => {
+    result = await checkBareRenderFidelity();
+  }, 300_000);
+
+  it('scores a non-empty bare corpus in every language (sanity: guards a false green)', () => {
+    // A derivation that stopped finding handler bodies — a changed handler head
+    // shape, a broken strip — would otherwise report zero failures and pass.
+    expect(result.checked).toBeGreaterThan(2500);
+    expect(result.clean).toBeGreaterThan(0);
+  });
+
+  it('does not regress the measured clean rate', () => {
+    const cleanPct = (100 * result.clean) / result.checked;
+    expect(
+      cleanPct,
+      `clean rate fell to ${cleanPct.toFixed(2)}% from the committed ${allowlist.cleanPct}%`
+    ).toBeGreaterThanOrEqual(allowlist.cleanPct - 0.01);
+  });
+
+  it('produces no NEW failing (pattern, language) bare render outside the allowlist', () => {
+    const unexpected = result.failures.filter(f => !allowed.has(key(f.id, f.language)));
+    expect(
+      unexpected,
+      unexpected.length
+        ? `\nNew BARE render-fidelity failures (fix it, or allowlist the pair):\n` +
+            unexpected
+              .map(
+                f =>
+                  `  [${f.id}] (${f.language})\n      en:  ${f.english.split('\n')[0]}\n` +
+                  `      out: ${f.rendered.split('\n')[0] || '<render threw>'}\n` +
+                  `      lost: ${[...f.missingActions.map(a => `action:${a}`), ...f.missingRoles].join(', ')}`
+              )
+              .join('\n')
+        : ''
+    ).toEqual([]);
+  });
+
+  it('has no stale allowlist pairs (a now-passing pair must be removed so the list ratchets down)', () => {
+    const stillFailing = new Set(result.failures.map(f => key(f.id, f.language)));
+    const stale: string[] = [];
+    for (const [id, langs] of Object.entries(allowlist.allowedFailures)) {
+      for (const language of langs) {
+        if (!stillFailing.has(key(id, language))) stale.push(`${id}/${language}`);
+      }
+    }
+    expect(
+      stale,
+      stale.length
+        ? `\nThese allowlisted pairs now render faithfully bare — prune them from ` +
+            `baselines/bare-render-fidelity.json (regenerate with ` +
+            `tools/regen-bare-render-fidelity-baseline.ts):\n  ${stale.join('\n  ')}`
+        : ''
+    ).toEqual([]);
+  });
+
+  it('keeps the committed allowlist grouping in sync with the live failure set', () => {
+    expect(groupFailuresByPattern(result.failures)).toEqual(allowlist.allowedFailures);
+  });
+});

package/src/multilingual/bare-render-fidelity.ts

@@ -0,0 +1,105 @@
+/**
+ * BARE-surface en→foreign render-fidelity gate.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Every corpus row that exercises a command wraps it in an event handler, so
+ * the eleven multilingual signals, `render-fidelity`, and 8,800 unit tests are
+ * all blind to the PLAIN form of the same command. That blindness is not
+ * theoretical: measured 2026-08-27, `hyperfixi.translate('toggle .active on
+ * #panel', 'en', 'bn')` produced a surface that did not parse back AT ALL — the
+ * plainest two-role toggle there is — and neither did tl/vi's bare `set the
+ * *background-color of #theme to "#ff6600"`. Both were pre-existing, both were
+ * found by hand, and nothing in CI could have reported either.
+ *
+ * It matters because the bare form is a first-class public surface: MCP
+ * `translate_code`, `hyperfixi.translate`/`getAllTranslations`, core's
+ * `MultilingualHyperscript` and the VS Code "Show in my language" badge are all
+ * routinely handed a single command with no handler around it.
+ *
+ * WHAT IT ASSERTS
+ * ---------------
+ * Exactly what `render-fidelity` asserts — render the English into each
+ * language, parse it back, require that no action and no role went missing —
+ * but over the HANDLER-STRIPPED body of each corpus pattern instead of the
+ * whole row. Same ratchet shape, same allowlist contract, and it delegates to
+ * `checkRenderFidelity` so the two can never drift in how they score.
+ *
+ * NOT REDUNDANT. Of the 69 failing pairs this gate sees today, **37 are
+ * invisible to the wrapped gate** — they pass wrapped and fail bare, because a
+ * fused per-command handler pattern binds a role the standalone pattern misses.
+ * Four of the 37 do not parse back at all.
+ *
+ * DERIVED, NOT HAND-PICKED. The corpus supplies the constructs; there is no
+ * command list to maintain here. A hand-written one would drift exactly the way
+ * `scripts/test-check-all.sh` and the ci.yml job lists did.
+ *
+ * DB DEPENDENCY. Same as the wrapped gate: the SET of corpus rows depends on a
+ * fresh `populate`, so this runs only when the caller asserts one.
+ */
+import { getAllPatterns } from '@hyperfixi/patterns-reference';
+import { parseSemantic } from '@lokascript/semantic';
+import { checkRenderFidelity, type RenderFidelityResult } from './render-fidelity';
+
+/** A corpus row reduced to the body of its event handler. */
+export interface BareBody {
+  readonly id: string;
+  readonly rawCode: string;
+}
+
+/**
+ * Strip a leading `on <event> [from <source>] ` handler head.
+ *
+ * Deliberately only the simple head: a row whose handler carries modifiers this
+ * does not recognize keeps its head, still parses as a handler, and is dropped
+ * by the guard in {@link deriveBareBodies} rather than being scored wrongly.
+ */
+function stripHandlerHead(english: string): string | null {
+  const match = /^on\s+\S+(\s+from\s+\S+)?\s+/.exec(english);
+  if (!match) return null;
+  const body = english.slice(match[0].length).trim();
+  return body.length > 0 ? body : null;
+}
+
+/**
+ * Reduce the corpus to the handler bodies that are meaningful bare.
+ *
+ * Three exclusions, each because the row has no bare surface to score:
+ *  - no handler head (a `behavior`/`socket`/`eventsource` block, or already bare);
+ *  - the stripped body does not parse as English at all;
+ *  - the stripped body STILL parses as an event handler. A block-shaped body
+ *    (`if … end`) re-anchors as one, which leaks a phantom `on` action into the
+ *    reference that then "goes missing" on the round trip for reasons that have
+ *    nothing to do with the bare surface. Measured: 7 rows, and they accounted
+ *    for 24 of the 61 apparent bare-only failures before the guard existed.
+ */
+export function deriveBareBodies(
+  patterns: ReadonlyArray<{ id: string; rawCode: string }>
+): BareBody[] {
+  const bodies: BareBody[] = [];
+  for (const pattern of patterns) {
+    const body = stripHandlerHead(pattern.rawCode);
+    if (!body) continue;
+    let reference;
+    try {
+      reference = parseSemantic(body, 'en')?.node ?? null;
+    } catch {
+      continue;
+    }
+    if (!reference) continue;
+    if ((reference as { action?: string }).action === 'on') continue;
+    bodies.push({ id: pattern.id, rawCode: body });
+  }
+  return bodies;
+}
+
+/** Score every corpus handler BODY, bare, in every language. */
+export async function checkBareRenderFidelity(opts?: {
+  languages?: readonly string[];
+}): Promise<RenderFidelityResult> {
+  const patterns = await getAllPatterns({ limit: 1000 });
+  const bodies = deriveBareBodies(patterns);
+  return opts?.languages
+    ? checkRenderFidelity({ languages: opts.languages, patterns: bodies })
+    : checkRenderFidelity({ patterns: bodies });
+}

package/src/multilingual/fidelity.ts

@@ -19,5 +19,6 @@ export {
   computePrecision,
   spuriousActions,
   collectRoleSignature,
+  collectRoleSignatureStrict,
   collectRoleValueSignature,
 } from '@lokascript/semantic/fidelity';

package/src/multilingual/render-fidelity.test.ts

@@ -0,0 +1,126 @@
+/**
+ * English→foreign render-fidelity ratchet (see render-fidelity.ts for why).
+ *
+ * Renders every corpus pattern's English source into each of the 23 languages,
+ * parses it back, and requires that no action and no role from the English
+ * reference went missing. Two ratchet assertions, at (pattern, language)
+ * granularity, mirroring the foreign→English gate:
+ *   1. no NEW failing pair appears outside the committed allowlist;
+ *   2. no allowlisted pair has silently started passing (stale entries must be
+ *      removed, so the list only ever shrinks).
+ *
+ * The allowlist was seeded at 75.97% clean — the level measured when the gate
+ * landed — so it starts green. It is a record of what is known-broken, not a
+ * target: completing a renderer fix means deleting entries from it.
+ *
+ * DB DEPENDENCY — corrected 2026-08-26 after CI disagreed with local.
+ * The gate renders `rawCode`, and that text is stable, but the SET of rows is
+ * not: `populate` re-runs `discoverPatterns` and finds examples the committed
+ * (frozen) patterns.db lacks — 3588 pairs against a fresh DB versus 3542
+ * against the committed one, which moved the clean rate 75.89% vs 75.97% and
+ * failed this gate on its own first CI run. So it carries the same guard as the
+ * foreign gate: it runs only when the caller asserts a fresh populate, and the
+ * baseline is seeded from that state.
+ *
+ * Regenerate after an intentional renderer change with
+ * `npm run populate --prefix packages/patterns-reference` followed by
+ * `npx tsx tools/regen-render-fidelity-baseline.ts`, and commit the result.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { describe, it, expect, beforeAll } from 'vitest';
+import {
+  checkRenderFidelity,
+  groupFailuresByPattern,
+  type RenderFidelityResult,
+} from './render-fidelity';
+
+interface AllowlistDoc {
+  checked: number;
+  clean: number;
+  cleanPct: number;
+  allowedFailures: Record<string, string[]>;
+}
+
+const baselinePath = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../baselines/render-fidelity.json'
+);
+const allowlist = JSON.parse(readFileSync(baselinePath, 'utf8')) as AllowlistDoc;
+const key = (id: string, language: string) => `${id} ${language}`;
+const allowed = new Set(
+  Object.entries(allowlist.allowedFailures).flatMap(([id, langs]) => langs.map(l => key(id, l)))
+);
+
+// Same contract as the foreign gate: a plain `vitest run` on a stale checkout
+// skips rather than reporting phantom drift. `npm run test:canonical` and the CI
+// multilingual job both set this, after populating.
+const DB_FRESHLY_POPULATED = process.env.FOREIGN_CANONICAL_VALIDITY === '1';
+
+describe.skipIf(!DB_FRESHLY_POPULATED)('english→foreign render-fidelity gate', () => {
+  let result: RenderFidelityResult;
+
+  beforeAll(async () => {
+    result = await checkRenderFidelity();
+  }, 300_000);
+
+  it('scores a non-empty corpus in every language (sanity: guards a false green)', () => {
+    // A corpus that failed to load would otherwise report zero failures and pass.
+    expect(result.checked).toBeGreaterThan(3000);
+    expect(result.clean).toBeGreaterThan(0);
+  });
+
+  it('does not regress the measured clean rate', () => {
+    // The headline number, kept honest independently of the pair-level lists:
+    // it may rise freely, but a drop means a render got worse somewhere the
+    // per-pair assertions might net out to zero.
+    const cleanPct = (100 * result.clean) / result.checked;
+    expect(
+      cleanPct,
+      `clean rate fell to ${cleanPct.toFixed(2)}% from the committed ${allowlist.cleanPct}%`
+    ).toBeGreaterThanOrEqual(allowlist.cleanPct - 0.01);
+  });
+
+  it('produces no NEW failing (pattern, language) render outside the allowlist', () => {
+    const unexpected = result.failures.filter(f => !allowed.has(key(f.id, f.language)));
+    expect(
+      unexpected,
+      unexpected.length
+        ? `\nNew render-fidelity failures (fix the renderer, or allowlist the pair):\n` +
+            unexpected
+              .map(
+                f =>
+                  `  [${f.id}] (${f.language})\n      en:  ${f.english.split('\n')[0]}\n` +
+                  `      out: ${f.rendered.split('\n')[0] || '<render threw>'}\n` +
+                  `      lost: ${[...f.missingActions.map(a => `action:${a}`), ...f.missingRoles].join(', ')}`
+              )
+              .join('\n')
+        : ''
+    ).toEqual([]);
+  });
+
+  it('has no stale allowlist pairs (a now-passing pair must be removed so the list ratchets down)', () => {
+    const stillFailing = new Set(result.failures.map(f => key(f.id, f.language)));
+    const stale: string[] = [];
+    for (const [id, langs] of Object.entries(allowlist.allowedFailures)) {
+      for (const language of langs) {
+        if (!stillFailing.has(key(id, language))) stale.push(`${id}/${language}`);
+      }
+    }
+    expect(
+      stale,
+      stale.length
+        ? `\nThese allowlisted pairs now render faithfully — prune them from ` +
+            `baselines/render-fidelity.json (regenerate with ` +
+            `tools/regen-render-fidelity-baseline.ts):\n  ${stale.join('\n  ')}`
+        : ''
+    ).toEqual([]);
+  });
+
+  it('keeps the committed allowlist grouping in sync with the live failure set', () => {
+    // Structural cross-check: redundant with the two assertions above, but it
+    // yields a single clear diff when regeneration is needed.
+    expect(groupFailuresByPattern(result.failures)).toEqual(allowlist.allowedFailures);
+  });
+});

package/src/multilingual/render-fidelity.ts

@@ -0,0 +1,204 @@
+/**
+ * English→foreign RENDER-fidelity gate.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Nothing gated this direction. The multilingual ratchet scores the STORED
+ * `pattern_translations` rows, which @lokascript/i18n's GrammarTransformer
+ * writes — it never calls `render(node, L)` at all. `canonical-validity` is
+ * en→en and `foreign-canonical-validity` is foreign→en, both of which pass.
+ * So `render(parse(en), L)` — the function behind MCP `translate_code`,
+ * `hyperfixi.translate`, `getAllTranslations`, core's `MultilingualHyperscript`
+ * and the VS Code "Show in my language" badge — was measured by nothing.
+ *
+ * When it was finally measured (2026-08-26) it was 73.3% structurally clean
+ * against the English reference where the i18n-written corpus was 97.0%.
+ * `README.md`, `AGENTS.md` and the MCP server instructions all attach a
+ * structural-fidelity guarantee to exactly this direction.
+ *
+ * WHAT IT ASSERTS
+ * ---------------
+ * For every corpus pattern and every non-English language: render the English
+ * source into that language, parse it back, and require that no ACTION and no
+ * ROLE from the English reference went missing. Failures are recorded per
+ * (pattern, language) against a committed allowlist that may only shrink —
+ * the same ratchet shape as `foreign-canonical-validity`.
+ *
+ * The allowlist is seeded at the level measured when the gate landed, so it
+ * lands green and every later improvement is a deletion from it. It is a
+ * record of what is known-broken, not a target.
+ *
+ * DB DEPENDENCY. The rendered text comes from `rawCode`, which is stable, but
+ * the SET of rows is not: `populate` re-runs `discoverPatterns` and finds
+ * examples the committed (frozen) patterns.db lacks. Measured 2026-08-26:
+ * 3588 pairs against a fresh DB, 3542 against the committed one — enough to
+ * move the clean rate (75.89% vs 75.97%) and fail the ratchet spuriously. So
+ * this gate needs a freshly populated DB, exactly like the foreign one, and
+ * its test carries the matching guard.
+ *
+ * STRICT ROLE SIGNATURES. Scoring uses `collectRoleSignatureStrict`, which
+ * ignores roles the matcher injected as schema defaults. Without that, a
+ * render that drops `to me` and a parser that puts `destination: me` back are
+ * indistinguishable, and a role-dropping render scores as faithful. Both sides
+ * are filtered, so a role implicit in the reference and in the candidate
+ * cancels out.
+ */
+import { getAllPatterns } from '@hyperfixi/patterns-reference';
+import { parseSemantic, render, type SemanticNode } from '@lokascript/semantic';
+// Via the local shim, the path every other gate in this directory uses.
+import { collectActions, collectRoleSignatureStrict } from './fidelity';
+
+/**
+ * The 23 non-English corpus languages. Mirrors `FOREIGN_LANGUAGES` in
+ * foreign-canonical-validity.ts; kept as its own list because this gate can run
+ * over a language the corpus has no authored translations for.
+ */
+export const RENDER_LANGUAGES = [
+  'ar',
+  'bn',
+  'de',
+  'es',
+  'fr',
+  'he',
+  'hi',
+  'id',
+  'it',
+  'ja',
+  'ko',
+  'ms',
+  'pl',
+  'pt',
+  'qu',
+  'ru',
+  'sw',
+  'th',
+  'tl',
+  'tr',
+  'uk',
+  'vi',
+  'zh',
+] as const;
+
+export interface RenderFidelityFailure {
+  readonly id: string;
+  readonly language: string;
+  readonly english: string;
+  readonly rendered: string;
+  /** Actions present in the English reference and absent after the round trip. */
+  readonly missingActions: readonly string[];
+  /** `action.role:valueType` entries present in the reference and absent after. */
+  readonly missingRoles: readonly string[];
+  /** Set when the rendered surface could not be parsed back at all. */
+  readonly unparseable?: boolean;
+}
+
+export interface RenderFidelityResult {
+  readonly checked: number;
+  readonly clean: number;
+  readonly failures: readonly RenderFidelityFailure[];
+}
+
+function safeParse(code: string, language: string): SemanticNode | null {
+  try {
+    return parseSemantic(code, language)?.node ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Render every corpus pattern into every language and score the round trip.
+ *
+ * A pattern whose English source does not itself parse is skipped rather than
+ * counted as a failure — it has no reference to compare against, and that is a
+ * parser question this gate does not ask.
+ */
+export async function checkRenderFidelity(opts?: {
+  languages?: readonly string[];
+  patterns?: ReadonlyArray<{ id: string; rawCode: string }>;
+}): Promise<RenderFidelityResult> {
+  const languages = opts?.languages ?? RENDER_LANGUAGES;
+  const patterns = opts?.patterns ?? (await getAllPatterns({ limit: 1000 }));
+
+  const failures: RenderFidelityFailure[] = [];
+  let checked = 0;
+  let clean = 0;
+
+  for (const pattern of patterns) {
+    // A pattern whose English source does not parse has no reference to compare
+    // against, so it is skipped rather than counted as a failure — that is a
+    // parser question, asked by other gates, not this one. This is also what
+    // excludes the non-translatable HTML-markup rows: they are not hyperscript,
+    // so they never parse, and there is no rendering decision to score.
+    const reference = safeParse(pattern.rawCode, 'en');
+    if (!reference) continue;
+
+    const refActions = collectActions(reference);
+    const refRoles = collectRoleSignatureStrict(reference);
+
+    for (const language of languages) {
+      checked++;
+      let rendered = '';
+      try {
+        rendered = render(reference, language);
+      } catch {
+        failures.push({
+          id: pattern.id,
+          language,
+          english: pattern.rawCode,
+          rendered: '',
+          missingActions: refActions,
+          missingRoles: refRoles,
+          unparseable: true,
+        });
+        continue;
+      }
+
+      const roundTripped = safeParse(rendered, language);
+      if (!roundTripped) {
+        failures.push({
+          id: pattern.id,
+          language,
+          english: pattern.rawCode,
+          rendered,
+          missingActions: refActions,
+          missingRoles: refRoles,
+          unparseable: true,
+        });
+        continue;
+      }
+
+      const gotActions = new Set(collectActions(roundTripped));
+      const gotRoles = new Set(collectRoleSignatureStrict(roundTripped));
+      const missingActions = refActions.filter(a => !gotActions.has(a));
+      const missingRoles = refRoles.filter(r => !gotRoles.has(r));
+
+      if (missingActions.length === 0 && missingRoles.length === 0) {
+        clean++;
+      } else {
+        failures.push({
+          id: pattern.id,
+          language,
+          english: pattern.rawCode,
+          rendered,
+          missingActions,
+          missingRoles,
+        });
+      }
+    }
+  }
+
+  return { checked, clean, failures };
+}
+
+/** Group failures as `{ patternId: [language, …] }` — the committed allowlist shape. */
+export function groupFailuresByPattern(
+  failures: readonly RenderFidelityFailure[]
+): Record<string, string[]> {
+  const grouped: Record<string, string[]> = {};
+  for (const failure of failures) {
+    (grouped[failure.id] ??= []).push(failure.language);
+  }
+  for (const languages of Object.values(grouped)) languages.sort();
+  return Object.fromEntries(Object.entries(grouped).sort(([a], [b]) => a.localeCompare(b)));
+}

package/src/multilingual/shipped-sources-validity.ts

@@ -29,6 +29,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { extractHyperscriptFromMarkup } from '@hyperfixi/patterns-reference';
@@ -95,7 +96,40 @@ function keyFor(file: string, source: string): string {
   return `${file}::${createHash('sha1').update(source).digest('hex').slice(0, 10)}`;
 }
 
-function walk(dir: string, acc: string[] = []): string[] {
+/**
+ * The files git actually tracks under `repoRoot`, as absolute paths.
+ *
+ * This gate walks the working TREE, and a working tree is not a clean checkout:
+ * `examples/vite-plugin-multilingual/` is GITIGNORED, so a local run saw a
+ * source CI could never see. That is unfixable from the allowlist — with an
+ * entry for it the gate failed in CI as a STALE entry, and without one it
+ * failed locally as a NEW finding. No allowlist state satisfies both, so the
+ * DENOMINATOR is what has to agree.
+ *
+ * The sibling `shipped-examples-execution` gate already derives its corpus this
+ * way, and its comment records that the lesson cost **#862** — it "failed on
+ * every clean checkout the first time CI ran it" for exactly this reason. This
+ * gate was simply never brought into line; it cost another CI round-trip on
+ * 2026-08-31 before anyone noticed the two disagreed.
+ *
+ * git being unavailable THROWS rather than falling back to the full tree, which
+ * is the sibling's convention and for its stated reason: a silent fallback
+ * would resurrect the drift this exists to kill.
+ */
+function trackedFiles(repoRoot: string): Set<string> {
+  const out = execFileSync('git', ['-C', repoRoot, 'ls-files', '-z'], {
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return new Set(
+    out
+      .split('\0')
+      .filter(Boolean)
+      .map(rel => path.join(repoRoot, rel))
+  );
+}
+
+function walk(dir: string, acc: string[] = [], tracked?: Set<string>): string[] {
   let entries: fs.Dirent[];
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -107,8 +141,12 @@ function walk(dir: string, acc: string[] = []): string[] {
       continue;
     }
     const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) walk(full, acc);
-    else if (/\.(html|md)$/.test(entry.name)) acc.push(full);
+    if (entry.isDirectory()) walk(full, acc, tracked);
+    else if (/\.(html|md)$/.test(entry.name)) {
+      // Skip anything git does not track, so local and CI score the same set.
+      if (tracked && !tracked.has(full)) continue;
+      acc.push(full);
+    }
   }
   return acc;
 }
@@ -135,8 +173,9 @@ export function collectShippedSources(
   const roots = opts?.roots ?? DEFAULT_ROOTS;
   const out: ShippedSource[] = [];
 
+  const tracked = trackedFiles(repoRoot);
   for (const root of roots) {
-    for (const full of walk(path.join(repoRoot, root))) {
+    for (const full of walk(path.join(repoRoot, root), [], tracked)) {
       const rel = path.relative(repoRoot, full);
       if (EXCLUDED.some(e => e.match(rel))) continue;
       const text = fs.readFileSync(full, 'utf8');

package/src/vocab/batch3-roundtrip.test.ts

@@ -22,8 +22,7 @@
  */
 
 import { describe, expect, it } from 'vitest';
-import { parseSemantic } from '@lokascript/semantic';
-import { GrammarTransformer } from '@lokascript/i18n';
+import { parseSemantic, translate } from '@lokascript/semantic';
 
 /** Verbatim (action, role, value) triples from a parse tree. */
 function triples(node: unknown, acc: string[] = [], depth = 0): string[] {
@@ -51,12 +50,40 @@ function triples(node: unknown, acc: string[] = [], depth = 0): string[] {
   return acc;
 }
 
+/**
+ * Renders with @lokascript/semantic, not @lokascript/i18n's `GrammarTransformer`
+ * (retired 2026-08-28). The assertions are unchanged and still pass: what they
+ * pin is the VOCABULARY, and `lexicon-parity.test.ts` gates semantic's lexicons
+ * against i18n's dictionaries, so the two renderers agree on exactly these words
+ * — verified on this file's cases before the swap (de `markieren`, ar `ظلل`,
+ * bn `#row কে ক্লোন`, id `tutupkan #modal`, vi `thêm vào đầu "x" vào #list`:
+ * byte-identical from both).
+ */
 function renderAndParse(en: string, lang: string): { render: string; triples: string[] } {
-  const render = new GrammarTransformer('en', lang).transform(en);
+  const render = translate(en, 'en', lang);
   const result = parseSemantic(render, lang);
   return { render, triples: result.node ? triples(result.node) : [] };
 }
 
+/**
+ * The three EVENT-NAME classes that used to live here — reset, submit and
+ * qu change — are gone with the renderer that made them observable.
+ *
+ * They asserted that i18n's DICTIONARY event word appears in the rendered
+ * surface (it `reimpostare`, ko `재설정`, pl `zresetuj`, ru `сбросить`,
+ * qu `musuqchay`, …). @lokascript/semantic deliberately does NOT localize an
+ * event name: `localizeEventName` keeps a curated denylist of events that must
+ * stay English to round-trip, so it renders `on reset`, `on submit`, `on change`
+ * verbatim. Migrated as-is, those tests would have asserted only that an English
+ * event name comes back as itself — true, and about nothing.
+ *
+ * The dictionary words themselves still ship (they feed the keyword providers on
+ * the PARSE side) and are still gated, by the V1-V4 vocab consistency check
+ * (`testing-framework/src/vocab/cli.ts validate`) and `lexicon-parity.test.ts`.
+ * What is no longer covered is their appearance in a RENDER, because nothing
+ * renders from them any more.
+ */
+
 describe('Batch 3 — select class (dict word was the pick keyword)', () => {
   it('de: `select #note` renders markieren and parses back as select', () => {
     const { render, triples: t } = renderAndParse('select #note', 'de');
@@ -97,51 +124,6 @@ describe('Batch 3 — wrong-verb class (dict word was another command)', () => {
   });
 });
 
-describe('Batch 3 — reset class (broken/wrong-event listener)', () => {
-  it.each([
-    ['it', 'reimpostare'],
-    ['ko', '재설정'],
-    ['pl', 'zresetuj'],
-    ['pt', 'redefinir'],
-    ['ru', 'сбросить'],
-    ['uk', 'скинути'],
-    ['qu', 'musuqchay'],
-  ])('%s: on-reset render captures on.event="reset" (canonical)', (langCode, word) => {
-    const { render, triples: t } = renderAndParse('on reset log "done"', langCode);
-    expect(render).toContain(word);
-    expect(t).toContain('on.event=reset');
-  });
-});
-
-describe('Batch 3 — submit class (dict word was the send verb)', () => {
-  it.each([
-    ['es', 'envío'],
-    ['pl', 'wysłaniu'],
-    ['tr', 'gönderme'],
-    ['vi', 'nộp'],
-    ['qu', 'apaykachay'],
-  ])(
-    '%s: corpus-shaped on-submit render captures on.event="submit", not "send"',
-    (langCode, word) => {
-      const { render, triples: t } = renderAndParse(
-        'on submit add @disabled to <button/> in me put "Submitting..." into <button/> in me',
-        langCode
-      );
-      expect(render).toContain(word);
-      expect(t).toContain('on.event=submit');
-      expect(t).not.toContain('on.event=send');
-    }
-  );
-});
-
-describe('Batch 3 — qu change (dict word was the toggle verb)', () => {
-  it('qu: on-change render captures on.event="change", not "toggle"', () => {
-    const { render, triples: t } = renderAndParse('on change log "x"', 'qu');
-    expect(render).toContain('kambiay');
-    expect(t).toContain('on.event=change');
-  });
-});
-
 describe('Batch 3 — it blur (noun form dropped the command patient)', () => {
   it('it: blur command render captures blur.patient', () => {
     const { render, triples: t } = renderAndParse('on keydown[key=="Escape"] blur me', 'it');