@hyperfixi/testing-framework 2.7.2 → 2.8.0

package/src/vocab/checks.test.ts

@@ -0,0 +1,362 @@
+/**
+ * Each check is proven against a seeded disagreement (fires) and a seeded
+ * agreement (stays silent) — never "does it run".
+ */
+
+import { describe, expect, it } from 'vitest';
+import { runChecks } from './checks';
+import { buildLedger } from './report';
+import type { Finding, LangVocab, VocabModel } from './types';
+import { findingKey } from './types';
+
+function lang(partial: Partial<LangVocab>): LangVocab {
+  return {
+    language: 'xx',
+    keywords: {},
+    roleMarkers: {},
+    schemaMarkers: [],
+    grammarMarkers: [],
+    ...partial,
+  };
+}
+
+const model = (l: Partial<LangVocab>): VocabModel => ({ languages: [lang(l)] });
+
+const of = (findings: Finding[], check: string, tier?: string) =>
+  findings.filter(f => f.check === check && (!tier || f.tier === tier));
+
+describe('V1 — profile keywords vs i18n dictionary', () => {
+  it('fires an error when the dictionary translates a concept differently', () => {
+    const findings = runChecks(
+      model({
+        keywords: { toggle: { primary: 'alternar', alternatives: ['conmutar'] } },
+        dictionary: { commands: { toggle: 'cambiar' } },
+      })
+    );
+    const errors = of(findings, 'V1', 'error');
+    expect(errors).toHaveLength(1);
+    expect(errors[0].key).toBe('toggle');
+    expect(errors[0].message).toContain('cambiar');
+  });
+
+  it('accepts a dictionary value matching an alternative form (set containment, not 1:1)', () => {
+    const findings = runChecks(
+      model({
+        keywords: { toggle: { primary: 'alternar', alternatives: ['conmutar'] } },
+        dictionary: { commands: { toggle: 'Conmutar' } }, // case difference must normalize away
+      })
+    );
+    expect(of(findings, 'V1', 'error')).toHaveLength(0);
+  });
+
+  it('V1b: warns on a profile concept missing from the dictionary, infos on dictionary-only keys', () => {
+    const findings = runChecks(
+      model({
+        keywords: { toggle: { primary: 'alternar' } },
+        dictionary: { commands: { add: 'añadir' } },
+      })
+    );
+    expect(of(findings, 'V1b', 'warn').map(f => f.key)).toEqual(['toggle']);
+    expect(of(findings, 'V1b', 'info').map(f => f.key)).toEqual(['add']);
+  });
+
+  it('stays silent without a dictionary (no S3 surface for the language)', () => {
+    const findings = runChecks(model({ keywords: { toggle: { primary: 'x' } } }));
+    expect(of(findings, 'V1')).toHaveLength(0);
+    expect(of(findings, 'V1b')).toHaveLength(0);
+  });
+});
+
+describe('V2 — role markers three-way', () => {
+  it('fires an error when the grammar renders a marker the parse side does not know', () => {
+    const findings = runChecks(
+      model({
+        roleMarkers: { destination: { primary: 'e' } },
+        schemaMarkers: [{ action: 'set', role: 'destination', marker: 'de', kind: 'override' }],
+        grammarMarkers: [{ form: 'ya', role: 'destination' }], // the tr allomorph class
+      })
+    );
+    const errors = of(findings, 'V2', 'error');
+    expect(errors).toHaveLength(1);
+    expect(errors[0].key).toBe('destination:ya');
+  });
+
+  it('accepts a grammar form known via a schema variant (union across S1+S2)', () => {
+    const findings = runChecks(
+      model({
+        roleMarkers: { destination: { primary: 'e' } },
+        schemaMarkers: [{ action: 'set', role: 'destination', marker: 'ya', kind: 'variant' }],
+        grammarMarkers: [
+          { form: 'ya', role: 'destination' },
+          { form: 'e', role: 'destination' },
+        ],
+      })
+    );
+    expect(of(findings, 'V2', 'error')).toHaveLength(0);
+  });
+
+  it('downgrades to info when the role has no parse-side markers at all', () => {
+    const findings = runChecks(model({ grammarMarkers: [{ form: 'на', role: 'locative' }] }));
+    expect(of(findings, 'V2', 'error')).toHaveLength(0);
+    expect(of(findings, 'V2', 'info')).toHaveLength(1);
+  });
+
+  it('accepts an event marker known only via the hardcoded SOV table (surface #6)', () => {
+    const withoutSurface6 = runChecks(
+      model({
+        roleMarkers: { event: { primary: 'に' } },
+        grammarMarkers: [{ form: 'で', role: 'event' }], // the ja class from the first ledger
+      })
+    );
+    expect(of(withoutSurface6, 'V2', 'error')).toHaveLength(1);
+
+    const withSurface6 = runChecks(
+      model({
+        roleMarkers: { event: { primary: 'に' } },
+        grammarMarkers: [{ form: 'で', role: 'event' }],
+        sovEventMarkers: ['で'],
+      })
+    );
+    expect(of(withSurface6, 'V2', 'error')).toHaveLength(0);
+  });
+
+  it('warns when the profile canonical marker never appears among the grammar forms', () => {
+    const findings = runChecks(
+      model({
+        roleMarkers: { destination: { primary: 'zu', alternatives: ['nach'] } },
+        grammarMarkers: [{ form: 'nach', role: 'destination' }],
+      })
+    );
+    const warns = of(findings, 'V2', 'warn');
+    expect(warns).toHaveLength(1);
+    expect(warns[0].key).toBe('destination:primary');
+  });
+});
+
+describe('V3 — event names', () => {
+  it('fires an error when the dictionary and eventNameTranslations disagree on an event', () => {
+    const findings = runChecks(
+      model({
+        eventTranslations: { クリック: 'click' },
+        dictionary: { events: { click: '押す' } },
+      })
+    );
+    const errors = of(findings, 'V3', 'error');
+    expect(errors).toHaveLength(1);
+    expect(errors[0].key).toBe('click');
+  });
+
+  it('accepts agreement (any native form recognized for the event)', () => {
+    const findings = runChecks(
+      model({
+        eventTranslations: { クリック: 'click', おす: 'click' },
+        dictionary: { events: { click: 'クリック' } },
+      })
+    );
+    expect(of(findings, 'V3', 'error')).toHaveLength(0);
+  });
+
+  it('V3b: infos when a language has no eventNameTranslations table', () => {
+    const findings = runChecks(model({ dictionary: { events: { click: 'klik' } } }));
+    expect(of(findings, 'V3b', 'info')).toHaveLength(1);
+    expect(of(findings, 'V3', 'error')).toHaveLength(0);
+  });
+});
+
+describe('V3c — dictionary events NOT covered by eventNameTranslations', () => {
+  // The gap this closes: V3's `continue` branch skips any dict event whose
+  // English key is absent from S5b, so a broken form there was invisible
+  // (id tekan_mouse/lepas_mouse, zh 鼠标进入, fr sourisappuyée).
+  const base = { eventTranslations: { クリック: 'click' } }; // covered lang, but no mousedown key
+
+  it('warns (broken-listener) when the uncovered form resolves to nothing', () => {
+    const findings = runChecks(
+      model({ ...base, dictionary: { events: { mousedown: 'tekan_mouse' } } })
+    );
+    const warns = of(findings, 'V3c', 'warn');
+    expect(warns).toHaveLength(1);
+    expect(warns[0].key).toBe('mousedown');
+    expect(warns[0].message).toContain('broken-listener');
+  });
+
+  it('warns (wrong-event) when S5b maps the form to a DIFFERENT event', () => {
+    const findings = runChecks(
+      model({
+        eventTranslations: { 鼠标进入: 'mouseover' },
+        dictionary: { events: { mouseenter: '鼠标进入' } },
+      })
+    );
+    const warns = of(findings, 'V3c', 'warn');
+    expect(warns).toHaveLength(1);
+    expect(warns[0].key).toBe('mouseenter');
+    expect(warns[0].message).toContain('"mouseover"');
+    expect(warns[0].message).toContain('wrong-event');
+  });
+
+  it('stays silent when the tokenizer keyword table resolves the form (parse authority)', () => {
+    // sw panya_juu: S5b says mouseover, but the tokenizer deliberately maps
+    // it to mouseup for the corpus — tokenizer wins, no warn.
+    const findings = runChecks(
+      model({
+        eventTranslations: { 'panya juu': 'mouseover' },
+        dictionary: { events: { mouseup: 'panya_juu' } },
+        normalizeWord: w => (w === 'panya_juu' ? 'mouseup' : undefined),
+      })
+    );
+    expect(of(findings, 'V3c')).toHaveLength(0);
+  });
+
+  it('stays silent for denylisted (intentionally-English) pairs', () => {
+    const findings = runChecks(
+      model({
+        ...base,
+        dictionary: { events: { mousedown: 'kaput_form' } },
+        eventDenylist: new Set(['mousedown']),
+      })
+    );
+    expect(of(findings, 'V3c')).toHaveLength(0);
+  });
+
+  it('stays silent for English passthrough forms', () => {
+    const findings = runChecks(model({ ...base, dictionary: { events: { keyup: 'keyup' } } }));
+    expect(of(findings, 'V3c')).toHaveLength(0);
+  });
+
+  it('stays silent when S5b covers the form under the SAME event via underscore↔space', () => {
+    const findings = runChecks(
+      model({
+        eventTranslations: { クリック: 'click', 'tekan tombol': 'keydown' },
+        dictionary: { events: { keydown: 'tekan_tombol' } },
+      })
+    );
+    expect(of(findings, 'V3c')).toHaveLength(0);
+  });
+
+  it('never fires for a language without an eventNameTranslations table (V3b owns that)', () => {
+    const findings = runChecks(model({ dictionary: { events: { mousedown: 'tekan_mouse' } } }));
+    expect(of(findings, 'V3c')).toHaveLength(0);
+  });
+});
+
+describe('V4 — tokenizer classification', () => {
+  const classify = (word: string) => (word === 'kaydır' ? 'identifier' : 'keyword');
+
+  it('fires an error when a vocab word does not classify as keyword/particle', () => {
+    const findings = runChecks(
+      model({
+        keywords: { scroll: { primary: 'kaydır' } },
+        classify,
+      })
+    );
+    const errors = of(findings, 'V4', 'error');
+    expect(errors).toHaveLength(1);
+    expect(errors[0].key).toBe('kaydır');
+    expect(errors[0].message).toContain("'identifier'");
+  });
+
+  it('collects from all four sources and dedupes the word into one finding', () => {
+    const findings = runChecks(
+      model({
+        keywords: { scroll: { primary: 'kaydır' } },
+        roleMarkers: { patient: { primary: 'kaydır' } },
+        schemaMarkers: [{ action: 'go', role: 'patient', marker: 'kaydır', kind: 'override' }],
+        grammarMarkers: [{ form: 'kaydır', role: 'patient' }],
+        classify,
+      })
+    );
+    const errors = of(findings, 'V4', 'error');
+    expect(errors).toHaveLength(1);
+    expect(errors[0].source).toContain('profile.keywords.scroll');
+  });
+
+  it('accepts particles and skips multi-word forms', () => {
+    const findings = runChecks(
+      model({
+        roleMarkers: { patient: { primary: 'を' }, event: { primary: 'do not' } },
+        classify: () => 'particle',
+      })
+    );
+    expect(of(findings, 'V4')).toHaveLength(0);
+  });
+
+  it('stays silent without a tokenizer', () => {
+    const findings = runChecks(model({ keywords: { scroll: { primary: 'kaydır' } } }));
+    expect(of(findings, 'V4')).toHaveLength(0);
+  });
+});
+
+describe('check filter + ledger/waivers', () => {
+  const disagreeing = (): VocabModel =>
+    model({
+      keywords: { toggle: { primary: 'a' } },
+      dictionary: { commands: { toggle: 'b' } },
+    });
+
+  it('--check filters to the requested checks only', () => {
+    const findings = runChecks(disagreeing(), ['V4']);
+    expect(findings).toHaveLength(0);
+  });
+
+  it('waivers suppress exactly the keyed error and flag stale keys', () => {
+    const findings = runChecks(disagreeing());
+    const key = findingKey(of(findings, 'V1', 'error')[0]);
+    const ledger = buildLedger(findings, [
+      { key, reason: 'legit morphology divergence' },
+      { key: 'V1|zz|ghost', reason: 'stale' },
+    ]);
+    expect(ledger.unwaivedErrors).toBe(0);
+    expect(ledger.findings.find(f => findingKey(f) === key)?.waived).toBe(
+      'legit morphology divergence'
+    );
+    expect(ledger.staleWaivers).toEqual(['V1|zz|ghost']);
+  });
+
+  it('class waivers (wildcard segments) cover every finding in the class', () => {
+    const twoLangs: VocabModel = {
+      languages: [
+        lang({
+          language: 'es',
+          keywords: { toggle: { primary: 'a' } },
+          dictionary: { commands: { toggle: 'b' } },
+        }),
+        lang({
+          language: 'fr',
+          keywords: { toggle: { primary: 'c' } },
+          dictionary: { commands: { toggle: 'd' } },
+        }),
+      ],
+    };
+    const findings = runChecks(twoLangs);
+    expect(of(findings, 'V1', 'error')).toHaveLength(2);
+
+    const ledger = buildLedger(findings, [
+      { key: 'V1|*|*', reason: 'pending Arc B reconciliation' },
+    ]);
+    expect(ledger.unwaivedErrors).toBe(0);
+    expect(
+      ledger.findings
+        .filter(f => f.waived)
+        .map(f => f.language)
+        .sort()
+    ).toEqual(['es', 'fr']);
+    expect(ledger.staleWaivers).toHaveLength(0);
+  });
+
+  it('a wildcard waiver matching nothing is stale', () => {
+    const findings = runChecks(disagreeing());
+    const ledger = buildLedger(findings, [{ key: 'V3|*|*', reason: 'nothing here' }]);
+    expect(ledger.staleWaivers).toEqual(['V3|*|*']);
+  });
+
+  it('waivers never apply to warn/info tiers', () => {
+    const findings = runChecks(
+      model({ keywords: { toggle: { primary: 'a' } }, dictionary: { commands: {} } })
+    );
+    const warn = of(findings, 'V1b', 'warn')[0];
+    const ledger = buildLedger(findings, [{ key: findingKey(warn), reason: 'nope' }]);
+    expect(
+      ledger.findings.find(f => f.check === 'V1b' && f.tier === 'warn')?.waived
+    ).toBeUndefined();
+    expect(ledger.staleWaivers).toHaveLength(1);
+  });
+});

package/src/vocab/checks.ts

@@ -0,0 +1,311 @@
+/**
+ * The V1–V4 cross-surface consistency checks
+ * (check matrix: docs-internal/HANDOFF_vocab-consistency.md).
+ *
+ * Tiering rule of thumb: a CONFLICT between two surfaces is an error; a
+ * MISSING entry is warn/info depending on the pair's direction of authority.
+ * Comparison is always over normalized form SETS with containment — never
+ * naive 1:1 string equality (markers have allomorphs and alternatives).
+ */
+
+import type { CheckId, Finding, LangVocab, VocabModel } from './types';
+import { formSet, norm } from './types';
+
+const ACCEPTED_TOKEN_KINDS = new Set(['keyword', 'particle']);
+
+/** Look an English concept key up across all dictionary categories. */
+function findInDictionary(
+  dictionary: NonNullable<LangVocab['dictionary']>,
+  concept: string
+): { category: string; value: string } | undefined {
+  for (const [category, entries] of Object.entries(dictionary)) {
+    const value = entries[concept];
+    if (value !== undefined) return { category, value };
+  }
+  return undefined;
+}
+
+/** V1/V1b — S1 profile keywords ↔ S3 i18n dictionary. */
+function checkKeywords(lang: LangVocab, findings: Finding[]): void {
+  if (!lang.dictionary) return;
+
+  const dictKeys = new Set<string>();
+  for (const entries of Object.values(lang.dictionary)) {
+    for (const key of Object.keys(entries)) dictKeys.add(key);
+  }
+
+  for (const [concept, entry] of Object.entries(lang.keywords)) {
+    const hit = findInDictionary(lang.dictionary, concept);
+    if (!hit) {
+      findings.push({
+        check: 'V1b',
+        tier: 'warn',
+        language: lang.language,
+        key: concept,
+        message: `profile concept "${concept}" (${entry.primary}) has no i18n dictionary entry`,
+        source: `profile.keywords.${concept}`,
+      });
+      continue;
+    }
+    const forms = formSet(entry);
+    if (forms.size > 0 && !forms.has(norm(hit.value))) {
+      findings.push({
+        check: 'V1',
+        tier: 'error',
+        language: lang.language,
+        key: concept,
+        message: `"${concept}": profile says "${entry.primary}"${
+          entry.alternatives?.length ? ` (alts: ${entry.alternatives.join(', ')})` : ''
+        } but dictionary ${hit.category} says "${hit.value}"`,
+        source: `dictionary.${hit.category}.${concept}`,
+      });
+    }
+  }
+
+  // Dictionary-only keys: S3 legitimately holds render vocabulary S1 never
+  // needs — coverage note, not a defect.
+  for (const key of dictKeys) {
+    if (!(key in lang.keywords)) {
+      findings.push({
+        check: 'V1b',
+        tier: 'info',
+        language: lang.language,
+        key,
+        message: `dictionary key "${key}" has no profile concept (dictionary-only vocabulary)`,
+      });
+    }
+  }
+}
+
+/** V2 — role markers three-way: S1 profile ↔ S2 schemas ↔ S4 grammar profile. */
+function checkRoleMarkers(lang: LangVocab, findings: Finding[]): void {
+  // Parse-side union per role: profile markers + every schema override/variant.
+  const parseSet = new Map<string, Set<string>>();
+  const add = (role: string, word: string) => {
+    if (!word) return;
+    let set = parseSet.get(role);
+    if (!set) parseSet.set(role, (set = new Set()));
+    set.add(norm(word));
+  };
+  for (const [role, entry] of Object.entries(lang.roleMarkers)) {
+    for (const f of formSet(entry)) add(role, f);
+  }
+  for (const sm of lang.schemaMarkers) add(sm.role, sm.marker);
+  // Surface #6: hardcoded SOV event markers count as parse-side knowledge for
+  // the event role (they live in semantic-parser.ts, not in any vocab file).
+  for (const marker of lang.sovEventMarkers ?? []) add('event', marker);
+
+  // Render-side forms per role (S4).
+  const renderSet = new Map<string, Set<string>>();
+  for (const gm of lang.grammarMarkers) {
+    let set = renderSet.get(gm.role);
+    if (!set) renderSet.set(gm.role, (set = new Set()));
+    set.add(norm(gm.form));
+    for (const a of gm.alternatives ?? []) if (a) set.add(norm(a));
+  }
+
+  // Error: the transformer renders a marker the parse side does not know for
+  // that role (the tr `ya`-vs-`e` class). Only when the parse side HAS
+  // markers for the role — an entirely unmarked role is a coverage note.
+  for (const [role, forms] of renderSet) {
+    const parse = parseSet.get(role);
+    for (const form of forms) {
+      if (!parse || parse.size === 0) {
+        findings.push({
+          check: 'V2',
+          tier: 'info',
+          language: lang.language,
+          key: `${role}:${form}`,
+          message: `grammar renders "${form}" for role ${role}, which has no parse-side markers at all`,
+          source: `grammar.${role}`,
+        });
+      } else if (!parse.has(form)) {
+        findings.push({
+          check: 'V2',
+          tier: 'error',
+          language: lang.language,
+          key: `${role}:${form}`,
+          message: `grammar renders "${form}" for role ${role} but neither the profile role marker nor any schema override/variant knows it (parse side: ${[...parse].join(', ')})`,
+          source: `grammar.${role}`,
+        });
+      }
+    }
+  }
+
+  // Warn: the profile's canonical marker never appears among the grammar
+  // forms for a role the grammar does render — the two canonical copies
+  // disagree even if parsing still succeeds via alternatives.
+  for (const [role, entry] of Object.entries(lang.roleMarkers)) {
+    const render = renderSet.get(role);
+    if (!render || !entry.primary) continue;
+    if (!render.has(norm(entry.primary))) {
+      findings.push({
+        check: 'V2',
+        tier: 'warn',
+        language: lang.language,
+        key: `${role}:primary`,
+        message: `profile canonical marker "${entry.primary}" for role ${role} is not among the grammar forms (${[...render].join(', ')})`,
+        source: `profile.roleMarkers.${role}`,
+      });
+    }
+  }
+}
+
+/** V3/V3b — event names: S5b eventNameTranslations ↔ S3 dictionary `events`. */
+function checkEventNames(lang: LangVocab, findings: Finding[]): void {
+  if (!lang.eventTranslations) {
+    findings.push({
+      check: 'V3b',
+      tier: 'info',
+      language: lang.language,
+      key: 'coverage',
+      message: `language has no eventNameTranslations table (native event words fall back to English)`,
+    });
+    return;
+  }
+  const events = lang.dictionary?.events;
+  if (!events) return;
+
+  // Invert S5b: English event → set of native forms.
+  const englishToNatives = new Map<string, Set<string>>();
+  for (const [native, english] of Object.entries(lang.eventTranslations)) {
+    let set = englishToNatives.get(english);
+    if (!set) englishToNatives.set(english, (set = new Set()));
+    set.add(norm(native));
+  }
+
+  for (const [english, native] of Object.entries(events)) {
+    const natives = englishToNatives.get(english);
+    if (!natives) {
+      // V3c — S5b has NO entry for this event, so V3 above is blind here: a
+      // broken dictionary event word hides exactly in this branch (id
+      // tekan_mouse/lepas_mouse — corpus-live, zh 鼠标进入, fr sourisappuyée).
+      // Verify the dict form still resolves to the canonical event on the
+      // parse side. Warn-tier: never gates, no waivers.
+      checkUncoveredEvent(lang, english, native, findings);
+      continue;
+    }
+    if (!natives.has(norm(native))) {
+      findings.push({
+        check: 'V3',
+        tier: 'error',
+        language: lang.language,
+        key: english,
+        message: `event "${english}": dictionary renders "${native}" but eventNameTranslations only recognizes ${[...natives].map(n => `"${n}"`).join(', ')}`,
+        source: `dictionary.events.${english}`,
+      });
+    }
+  }
+}
+
+/**
+ * V3c — coverage companion to V3: a dictionary event whose English key is
+ * ABSENT from eventNameTranslations. V3 compares only covered events, so a
+ * dict form here can be arbitrarily broken without any signal (the S5b
+ * coverage-gap family: V3's own `continue` branch). Resolution order follows
+ * the Batch 2 verdict — the TOKENIZER keyword table is the parse authority
+ * (clears deliberate mappings like sw panya_juu→mouseup); S5b under another
+ * key is the wrong-event signal (zh 鼠标进入→mouseover). Denylisted pairs are
+ * intentionally English — never flagged.
+ */
+function checkUncoveredEvent(
+  lang: LangVocab,
+  english: string,
+  native: string,
+  findings: Finding[]
+): void {
+  if (lang.eventDenylist?.has(english)) return;
+  const dictNorm = norm(native);
+  const englishNorm = norm(english);
+  if (dictNorm === englishNorm) return; // English passthrough always round-trips
+
+  // 1) Parse authority: single-token keyword-table normalization.
+  let resolved: string | undefined;
+  if (!/\s/.test(native) && lang.normalizeWord) {
+    const n = lang.normalizeWord(native);
+    if (n && norm(n) !== dictNorm) resolved = norm(n);
+  }
+  // 2) S5b under a DIFFERENT English key (underscore↔space tolerant).
+  if (!resolved && lang.eventTranslations) {
+    const spaced = dictNorm.replace(/_/g, ' ');
+    for (const [nat, eng] of Object.entries(lang.eventTranslations)) {
+      const natNorm = norm(nat);
+      if (natNorm === dictNorm || natNorm === spaced) {
+        resolved = norm(eng);
+        break;
+      }
+    }
+  }
+
+  if (resolved === englishNorm) return; // round-trips; S5b just lacks the row (alias candidate)
+
+  findings.push({
+    check: 'V3c',
+    tier: 'warn',
+    language: lang.language,
+    key: english,
+    message: resolved
+      ? `event "${english}": dictionary renders "${native}" but the parse side resolves it to "${resolved}" (S5b has no ${english} entry — V3-invisible) — wrong-event listener risk`
+      : `event "${english}": dictionary renders "${native}" which the parse side does not resolve to any event (S5b has no ${english} entry — V3-invisible) — broken-listener risk`,
+    source: `dictionary.events.${english}`,
+  });
+}
+
+/** V4 — every parse/render vocab word must classify as keyword/particle in that language's tokenizer. */
+function checkTokenizerClassification(lang: LangVocab, findings: Finding[]): void {
+  if (!lang.classify) return;
+
+  // (word → sources) — dedupe so one bad word yields one finding.
+  const words = new Map<string, string[]>();
+  const collect = (word: string | undefined, source: string) => {
+    if (!word) return;
+    if (/\s/.test(word)) return; // classifyToken is word-level; multi-word forms are out of its scope
+    const list = words.get(word);
+    if (list) list.push(source);
+    else words.set(word, [source]);
+  };
+
+  for (const [concept, entry] of Object.entries(lang.keywords)) {
+    collect(entry.primary, `profile.keywords.${concept}`);
+    for (const a of entry.alternatives ?? []) collect(a, `profile.keywords.${concept}`);
+  }
+  for (const [role, entry] of Object.entries(lang.roleMarkers)) {
+    collect(entry.primary, `profile.roleMarkers.${role}`);
+    for (const a of entry.alternatives ?? []) collect(a, `profile.roleMarkers.${role}`);
+  }
+  for (const sm of lang.schemaMarkers) {
+    collect(sm.marker, `schema.${sm.action}.${sm.role}`);
+  }
+  for (const gm of lang.grammarMarkers) {
+    collect(gm.form, `grammar.${gm.role}`);
+    for (const a of gm.alternatives ?? []) collect(a, `grammar.${gm.role}`);
+  }
+
+  for (const [word, sources] of words) {
+    const kind = lang.classify(word);
+    if (!ACCEPTED_TOKEN_KINDS.has(kind)) {
+      findings.push({
+        check: 'V4',
+        tier: 'error',
+        language: lang.language,
+        key: word,
+        message: `"${word}" classifies as '${kind}' (not keyword/particle) — it cannot tokenize as vocabulary`,
+        source:
+          sources.slice(0, 3).join(', ') +
+          (sources.length > 3 ? ` (+${sources.length - 3} more)` : ''),
+      });
+    }
+  }
+}
+
+export function runChecks(model: VocabModel, checks?: readonly CheckId[]): Finding[] {
+  const enabled = (id: CheckId) => !checks || checks.includes(id);
+  const findings: Finding[] = [];
+  for (const lang of model.languages) {
+    if (enabled('V1') || enabled('V1b')) checkKeywords(lang, findings);
+    if (enabled('V2')) checkRoleMarkers(lang, findings);
+    if (enabled('V3') || enabled('V3b') || enabled('V3c')) checkEventNames(lang, findings);
+    if (enabled('V4')) checkTokenizerClassification(lang, findings);
+  }
+  return checks ? findings.filter(f => checks.includes(f.check)) : findings;
+}