@hyperfixi/testing-framework 2.7.2 → 2.9.0

package/src/multilingual/cli.ts

@@ -10,6 +10,8 @@ import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { checkDbStamp, getDefaultDbPath } from '@hyperfixi/patterns-reference';
 import { TestOrchestrator } from './orchestrator';
+import { diagnoseCoverage } from './tools/diagnose-coverage';
+import { triageR1 } from './tools/triage-r1';
 import type { TestConfig, LanguageCode } from './types';
 
 /**
@@ -172,6 +174,17 @@ function parseArgs(): TestConfig {
         config.saveBaseline = true;
         break;
 
+      case '--diagnose-coverage':
+        // Read-only measurement pass; short-circuits main() before any gate.
+        config.diagnoseCoverage = true;
+        break;
+
+      case '--triage-r1':
+        // Read-only measurement pass; short-circuits main() before any gate.
+        // Combine with --languages to scope (en is force-loaded as reference).
+        config.triageR1 = true;
+        break;
+
       default:
         if (arg && arg.startsWith('-')) {
           console.error(`Unknown option: ${arg}`);
@@ -227,6 +240,15 @@ OPTIONS:
       --categories <cats>      Filter by categories (comma-separated)
       --limit <n>              Patterns per language in quick mode (default: 10)
       --save-baseline          Save current results as new baseline
+      --triage-r1              Itemize R1 role-fidelity misses per language
+                               (missing action.role:type entries vs the en
+                               reference, clustered; scope with --languages)
+      --diagnose-coverage      Report how often the semantic parser matched a
+                               pattern that ignored part of its input, per
+                               language, with sample dropped spans. Read-only:
+                               never gates and never writes a baseline. Run it
+                               before considering an input-coverage penalty in
+                               the confidence model.
   -h, --help                   Show this help message
 
 EXAMPLES:
@@ -257,6 +279,39 @@ async function main(): Promise<void> {
     // --save-baseline needs the regression reporter wired so it can persist.
     if (config.saveBaseline) config.regression = true;
 
+    // --diagnose-coverage is a measurement pass, not a gate: it reads the corpus,
+    // parses each row, and reports the `unconsumed-input` firing rate. It compares
+    // nothing against the baseline and writes nothing, so it runs before (and
+    // instead of) the regression machinery. It DOES execute dist/, so a stale
+    // build would mis-measure — warn rather than refuse, since no baseline is at
+    // risk.
+    if (config.diagnoseCoverage) {
+      const staleDists = findStaleDists();
+      if (staleDists.length > 0) {
+        console.warn(
+          `⚠ Stale dist/ in: ${staleDists.join(', ')} — these numbers describe the built\n` +
+            '  output, not your checkout. Rebuild first: npm run test:multilingual:build-deps\n'
+        );
+      }
+      await diagnoseCoverage(config);
+      process.exit(0);
+    }
+
+    // --triage-r1 is the same kind of measurement pass for R1 role fidelity:
+    // itemizes each language's missing `action.role:type` entries vs the en
+    // reference, clustered by entry (with the mistype pairing). Read-only.
+    if (config.triageR1) {
+      const staleDists = findStaleDists();
+      if (staleDists.length > 0) {
+        console.warn(
+          `⚠ Stale dist/ in: ${staleDists.join(', ')} — these numbers describe the built\n` +
+            '  output, not your checkout. Rebuild first: npm run test:multilingual:build-deps\n'
+        );
+      }
+      await triageR1(config);
+      process.exit(0);
+    }
+
     // DB freshness guard: refuse to run a regression/baseline compare against a
     // patterns.db generated from *different* source than is currently checked out
     // (the cross-branch "phantom regression" footgun). The committed baseline only
@@ -321,12 +376,11 @@ async function main(): Promise<void> {
     //    gap (newer feature patterns lack complete non-English coverage), so a
     //    100%-or-fail gate would never go green. A language fails the gate when
     //    its parse rate drops more than REGRESSION_TOLERANCE_PTS below baseline.
-    //    We deliberately gate on the RATE, not on per-pattern flips: a handful of
-    //    borderline-confidence patterns can flip pass/fail between builds without
-    //    a real regression (the per-pattern `newFailures` is kept for reporting
-    //    only). The baseline must be generated against a freshly `populate`d
-    //    patterns.db (CI re-populates), or every language reads as shifted.
-    //    Missing baseline → fail.
+    //    The rate is a COARSE signal by design; the per-pattern R5 ratchet below
+    //    is what catches a small number of patterns breaking (the rate alone
+    //    cannot — see its comment). The baseline must be generated against a
+    //    freshly `populate`d patterns.db (CI re-populates), or every language
+    //    reads as shifted. Missing baseline → fail.
     //  - otherwise: the normal absolute pass/fail (used by the quick-mode gate,
     //    which is genuinely expected at 100%).
     const REGRESSION_TOLERANCE_PTS = 2;
@@ -363,7 +417,20 @@ async function main(): Promise<void> {
         // un-regenerated baseline never retro-flags. avgFidelity is deterministic
         // (parse-derived, independent of the patterns.db confidence column), so the
         // tolerance can be tight.
-        const LOSSY_REGRESSION_TOLERANCE = 3;
+        // Tolerance 0 since 2026-07-25. It was 3, and that cushion was measured
+        // to be the gate's real blind spot: removing `את` from go.destination's
+        // markerLegacy.he — the literal #763 regression, which two vitest cases
+        // caught and the gate did not — produces exactly ONE faithful→lossy flip
+        // and nothing else. Even a nonsense he marker override produced only two.
+        // The parser degrades rather than returning null, so the parse-based
+        // signals (rate, R5) never fire for this class; the lossy flip is the
+        // only place it shows, and a cushion of 3 swallowed it.
+        // A faithful→lossy flip is binary and structural — the same argument that
+        // already puts R2/R4 at 0 — so unlike the avg* deltas it has no float or
+        // collation noise to absorb. The degenerate ratchet keeps its 3: it is a
+        // strictly coarser view of the same event, and a >50% structure loss
+        // never occurs without the lossy flip firing first.
+        const LOSSY_REGRESSION_TOLERANCE = 0;
         // 0.02 ≈ six single-pattern drops in a ~154-pattern language — absorbs any
         // rare populate jitter while still catching real per-language cluster
         // regressions (typically ≥0.03). The per-pattern lossy ratchet above is the
@@ -387,6 +454,19 @@ async function main(): Promise<void> {
           r => r.avgPrecisionDelta < -AVG_PRECISION_DROP_TOLERANCE
         );
 
+        // R0-recall-multiset ratchet: the mirror of the precision ratchet. Every
+        // signal above is computed on a deduped SET, so a parse that drops a
+        // REPEATED command scores a perfect 1.0 — reference `[bind, bind]`
+        // collapses to `{bind}`, which `[bind]` satisfies in full. That is exactly
+        // how `bind-two-way` recorded fidelity 1.0 in all 24 languages while every
+        // one of them parsed only the first of its two binds. Counting duplicates
+        // makes the drop visible. Deltas are 0 unless the baseline carries
+        // avgMultisetRecall, so an un-regenerated baseline never retro-flags.
+        const AVG_MULTISET_RECALL_DROP_TOLERANCE = 0.02;
+        const multisetRecallDrops = allResults.filter(
+          r => r.avgMultisetRecallDelta < -AVG_MULTISET_RECALL_DROP_TOLERANCE
+        );
+
         // R1 — role-fidelity ratchet (§8): same semantics as the avgFidelity
         // ratchet, on the role-recall signal (action.role:valueType vs the en
         // reference). Deltas are 0 unless the baseline carries avgRoleFidelity,
@@ -398,6 +478,20 @@ async function main(): Promise<void> {
           r => r.avgRoleFidelityDelta < -AVG_ROLE_FIDELITY_DROP_TOLERANCE
         );
 
+        // R3 — role-VALUE ratchet: same semantics as the role-fidelity ratchet,
+        // on the invariant-value signal (`action.role=value` multiset over the
+        // code-shaped subset: selectors, sigil refs, time literals,
+        // colon-qualified event names, URLs — compared VERBATIM vs the en
+        // reference). A drop means a translation started losing/corrupting an
+        // invariant value (`draggable` captured for `draggable:start`, the #633
+        // class) — invisible to every action/type-based signal above. Deltas
+        // are 0 unless the baseline carries avgValueRecall, so an
+        // un-regenerated baseline never retro-flags.
+        const AVG_VALUE_RECALL_DROP_TOLERANCE = 0.02;
+        const valueRecallDrops = allResults.filter(
+          r => r.avgValueRecallDelta < -AVG_VALUE_RECALL_DROP_TOLERANCE
+        );
+
         // R2 — execution ratchet (§8): curated-subset patterns whose jsdom DOM
         // effects matched the en reference in the baseline but diverge now.
         // Tolerance 0: execution is binary and the harness is deterministic
@@ -408,6 +502,80 @@ async function main(): Promise<void> {
           r.newExecutionFailures.map(id => `${r.language}/${id}`)
         );
 
+        // R5 — per-pattern parse ratchet: a pattern that parsed in the baseline
+        // no longer parses at all. Tolerance 0, and it is NOT redundant with the
+        // parse-rate signal above — every other signal is structurally incapable
+        // of seeing a small number of patterns break:
+        //   * parse rate is per-language, so at ~154 patterns one flip is a
+        //     0.65pt drop against a 2pt tolerance — you need ≥4 in ONE language.
+        //   * the five avg* ratchets never see it at all: orchestrator.ts skips
+        //     failed parses BEFORE scoring, so a failure leaves both numerator
+        //     and denominator. The delta is exactly 0.0000, not merely small.
+        //     (Perversely, a *lossy* pattern that degrades to not-parsing raises
+        //     avgFidelity, because its sub-1.0 score leaves the denominator.)
+        //   * the degenerate/lossy ratchets iterate patterns that DID parse.
+        //   * R2 covers 47 curated ids; R4's denominator excludes ~14% of the
+        //     corpus and is full-mode only.
+        // That gap is not hypothetical: #763's `markerOverride.he` change stopped
+        // `לך את back` (go-back, he) parsing, and the gate would have gone green.
+        // The tolerances elsewhere are cross-machine float/collation headroom for
+        // AVERAGES; a binary pass→fail flip has no such noise to absorb, so this
+        // one is 0. Guarded by the baseline carrying per-pattern `patterns` data
+        // (findNewFailures returns [] without it), so an un-regenerated baseline
+        // never retro-flags.
+        const parseRegressions = allResults.flatMap(r =>
+          r.newFailures.map(id => `${r.language}/${id}`)
+        );
+
+        // R4 — canonical-validity ratchet: render every authored foreign
+        // translation to English and parse the result on the real
+        // hyperscript.org engine, diffing the invalid (pattern, language)
+        // pairs against the committed allowlist
+        // (baselines/foreign-canonical-validity.json). Both directions fail:
+        // a NEW invalid pair is a validity regression; a stale entry (an
+        // allowlisted pair that now renders valid) must be pruned in the same
+        // change that cleared it (tools/regen-foreign-baseline.ts). Tolerance
+        // 0 — the render+parse is deterministic against a fresh DB, and the
+        // DB/dist freshness guards above already refused stale inputs. Reuses
+        // checkForeignRenderValidity + the allowlist VERBATIM, so this and the
+        // vitest gate (foreign-canonical-validity.test.ts) cannot disagree.
+        // Full-mode only (quick mode keeps its speed contract) and skipped
+        // with a warning when the allowlist is absent, so a checkout without
+        // the baseline never retro-flags.
+        let validityNewInvalid: string[] = [];
+        let validityStale: string[] = [];
+        let validityChecked = false;
+        if (config.mode !== 'quick') {
+          const validityBaselinePath = path.resolve(
+            path.dirname(fileURLToPath(import.meta.url)),
+            '../../baselines/foreign-canonical-validity.json'
+          );
+          if (!fs.existsSync(validityBaselinePath)) {
+            console.warn(`⚠ R4 validity ratchet skipped: no allowlist at ${validityBaselinePath}.`);
+          } else {
+            const { checkForeignRenderValidity, groupFailuresByPattern } =
+              await import('./foreign-canonical-validity');
+            const allowlist = JSON.parse(fs.readFileSync(validityBaselinePath, 'utf8')) as {
+              allowedInvalid: Record<string, string[]>;
+            };
+            const pairKey = (id: string, lang: string) => `${id}/${lang}`;
+            const allowed = new Set(
+              Object.entries(allowlist.allowedInvalid).flatMap(([id, langs]) =>
+                langs.map(l => pairKey(id, l))
+              )
+            );
+            const validity = await checkForeignRenderValidity();
+            const current = new Set(
+              Object.entries(groupFailuresByPattern(validity.failures)).flatMap(([id, langs]) =>
+                langs.map(l => pairKey(id, l))
+              )
+            );
+            validityNewInvalid = [...current].filter(p => !allowed.has(p)).sort();
+            validityStale = [...allowed].filter(p => !current.has(p)).sort();
+            validityChecked = true;
+          }
+        }
+
         let failed = false;
 
         if (regressed.length > 0) {
@@ -417,13 +585,29 @@ async function main(): Promise<void> {
           );
           for (const r of regressed) {
             const fails = r.newFailures.length
-              ? ` — newly failing: ${r.newFailures.join(', ')}`
+              ? ` — newly failing: ${r.newFailures.slice(0, 20).join(', ')}`
               : '';
             console.error(`   ${r.language}: ΔparseRate ${r.parseRateDelta.toFixed(1)}pts${fails}`);
           }
           failed = true;
         }
 
+        if (parseRegressions.length > 0) {
+          console.error(
+            `\n✗ Parse regression vs baseline (R5): ${parseRegressions.length} pattern(s) ` +
+              `parsed in the baseline and no longer parse at all:`
+          );
+          for (const p of parseRegressions.slice(0, 20)) console.error(`   ${p}`);
+          if (parseRegressions.length > 20) {
+            console.error(`   … and ${parseRegressions.length - 20} more`);
+          }
+          console.error(
+            `   (tolerance 0 — the percentage-based signals cannot see a handful of ` +
+              `broken patterns; if intentional, regenerate the baseline with --save-baseline)`
+          );
+          failed = true;
+        }
+
         if (fidelityRegressions.length > FIDELITY_REGRESSION_TOLERANCE) {
           console.error(
             `\n✗ Fidelity regression vs baseline: ${fidelityRegressions.length} faithful pass(es) ` +
@@ -453,11 +637,6 @@ async function main(): Promise<void> {
               `if intentional, regenerate the baseline with --save-baseline)`
           );
           failed = true;
-        } else if (lossyRegressions.length > 0) {
-          console.warn(
-            `\n⚠ ${lossyRegressions.length} correctness regression(s) within tolerance ` +
-              `(${LOSSY_REGRESSION_TOLERANCE}): ${lossyRegressions.join(', ')}`
-          );
         }
 
         if (fidelityDrops.length > 0) {
@@ -485,6 +664,21 @@ async function main(): Promise<void> {
           failed = true;
         }
 
+        if (multisetRecallDrops.length > 0) {
+          console.error(
+            `\n✗ avgMultisetRecall dropped > ${AVG_MULTISET_RECALL_DROP_TOLERANCE} in ` +
+              `${multisetRecallDrops.length} language(s) — a parse started dropping a ` +
+              `REPEATED command (invisible to the Set-based fidelity/roleFidelity):`
+          );
+          for (const r of multisetRecallDrops) {
+            console.error(
+              `   ${r.language}: ΔavgMultisetRecall ${r.avgMultisetRecallDelta.toFixed(4)}`
+            );
+          }
+          console.error(`   (if intentional, regenerate the baseline with --save-baseline)`);
+          failed = true;
+        }
+
         if (roleFidelityDrops.length > 0) {
           console.error(
             `\n✗ avgRoleFidelity dropped > ${AVG_ROLE_FIDELITY_DROP_TOLERANCE} in ` +
@@ -499,6 +693,19 @@ async function main(): Promise<void> {
           failed = true;
         }
 
+        if (valueRecallDrops.length > 0) {
+          console.error(
+            `\n✗ avgValueRecall dropped > ${AVG_VALUE_RECALL_DROP_TOLERANCE} in ` +
+              `${valueRecallDrops.length} language(s) — a parse started losing/corrupting ` +
+              `a language-invariant role VALUE (invisible to the action/type-based signals):`
+          );
+          for (const r of valueRecallDrops) {
+            console.error(`   ${r.language}: ΔavgValueRecall ${r.avgValueRecallDelta.toFixed(4)}`);
+          }
+          console.error(`   (if intentional, regenerate the baseline with --save-baseline)`);
+          failed = true;
+        }
+
         if (executionRegressions.length > 0) {
           console.error(
             `\n✗ Execution regression vs baseline (R2): ${executionRegressions.length} ` +
@@ -512,12 +719,38 @@ async function main(): Promise<void> {
           failed = true;
         }
 
+        if (validityNewInvalid.length > 0) {
+          console.error(
+            `\n✗ Canonical-validity regression (R4): ${validityNewInvalid.length} foreign ` +
+              `translation(s) now render English the hyperscript.org parser rejects:`
+          );
+          for (const p of validityNewInvalid) console.error(`   ${p}`);
+          console.error(
+            `   (triage with tools/triage-foreign-residual.ts; if the invalidity is ` +
+              `expected, allowlist it via tools/regen-foreign-baseline.ts)`
+          );
+          failed = true;
+        }
+
+        if (validityStale.length > 0) {
+          console.error(
+            `\n✗ Stale validity allowlist (R4): ${validityStale.length} allowlisted ` +
+              `pair(s) now render VALID — prune with tools/regen-foreign-baseline.ts:`
+          );
+          for (const p of validityStale) console.error(`   ${p}`);
+          failed = true;
+        }
+
         if (failed) {
           exitCode = 1;
         } else {
           console.log(
             `\n✓ No regression vs baseline ` +
-              `(parse-rate ${REGRESSION_TOLERANCE_PTS}pts, fidelity + correctness + execution ratchets).`
+              `(parse-rate ${REGRESSION_TOLERANCE_PTS}pts, per-pattern parse (R5) + ` +
+              `fidelity + correctness + ` +
+              `precision + multiset-recall + role + value + execution ratchets` +
+              (validityChecked ? ` + canonical validity (R4)` : '') +
+              `).`
           );
           exitCode = 0;
         }

package/src/multilingual/fidelity.test.ts

@@ -2,7 +2,9 @@ import { describe, it, expect } from 'vitest';
 import {
   collectActions,
   collectActionsMultiset,
+  collectRoleValueSignature,
   computeFidelity,
+  computeMultisetRecall,
   computePrecision,
   spuriousActions,
   FIDELITY_THRESHOLD,
@@ -119,6 +121,196 @@ describe('computePrecision', () => {
   });
 });
 
+describe('computeMultisetRecall', () => {
+  it('catches the dropped duplicate that Set-based recall is blind to', () => {
+    // The `bind-two-way` shape. EN `bind $n to #a bind $n to #b` is [bind, bind];
+    // a parse that truncates to the first command yields [bind]. Every Set-based
+    // signal reads this as perfect — which is why the row recorded fidelity 1.0
+    // across all 24 languages while every one of them dropped half its body.
+    const en = ['bind', 'bind'];
+    const truncated = ['bind'];
+
+    expect(computeFidelity(collectSet(en), collectSet(truncated))).toBe(1); // recall is fooled
+    expect(computePrecision(en, truncated)).toBe(1); // precision is fooled too
+    expect(computeMultisetRecall(en, truncated)).toBe(0.5); // this is not
+  });
+
+  it('scores a faithful (reordered) parse 1.0', () => {
+    expect(computeMultisetRecall(['bind', 'bind'], ['bind', 'bind'])).toBe(1);
+    expect(computeMultisetRecall(['add', 'on', 'remove'], ['on', 'remove', 'add'])).toBe(1);
+  });
+
+  it('is not fooled by an added duplicate (that is precision’s job)', () => {
+    // A candidate with a phantom extra still has full recall; precision catches it.
+    expect(computeMultisetRecall(['bind'], ['bind', 'bind'])).toBe(1);
+    expect(computePrecision(['bind'], ['bind', 'bind'])).toBe(0.5);
+  });
+
+  it('returns undefined when there is no reference to score against', () => {
+    expect(computeMultisetRecall([], ['bind'])).toBeUndefined();
+  });
+});
+
+/** The deduped Set signature `collectActions` produces, from a multiset. */
+function collectSet(actions: readonly string[]): string[] {
+  return [...new Set(actions)].sort();
+}
+
+describe('collectRoleValueSignature', () => {
+  it('emits every invariant-shaped value class, from a roles Map', () => {
+    const node = {
+      kind: 'event-handler',
+      action: 'on',
+      roles: new Map<string, unknown>([
+        ['event', { type: 'expression', raw: 'draggable:start' }], // colon-qualified (the #633 class)
+      ]),
+      body: [
+        {
+          kind: 'command',
+          action: 'toggle',
+          roles: new Map<string, unknown>([
+            ['patient', { type: 'selector', value: '.active', selectorKind: 'class' }],
+          ]),
+        },
+        {
+          kind: 'command',
+          action: 'set',
+          roles: new Map<string, unknown>([
+            ['destination', { type: 'expression', raw: ':x' }], // sigil ref
+          ]),
+        },
+        {
+          kind: 'command',
+          action: 'wait',
+          roles: new Map<string, unknown>([
+            ['duration', { type: 'literal', value: '200ms', dataType: 'duration' }],
+          ]),
+        },
+        {
+          kind: 'command',
+          action: 'fetch',
+          roles: new Map<string, unknown>([['source', { type: 'literal', value: '/api/data' }]]),
+        },
+      ],
+    };
+    expect(collectRoleValueSignature(node)).toEqual([
+      'fetch.source=/api/data',
+      'on.event=draggable:start',
+      'set.destination=:x',
+      'toggle.patient=.active',
+      'wait.duration=200ms',
+    ]);
+  });
+
+  it('excludes non-invariant values: references, prose, bare words, mixed raws, flags, property-paths', () => {
+    const node = {
+      kind: 'command',
+      action: 'put',
+      roles: new Map<string, unknown>([
+        ['destination', { type: 'reference', value: 'me' }], // fillSchemaDefaults noise
+        ['patient', { type: 'literal', value: 'Hello world', dataType: 'string' }], // legitimately translated
+        ['source', { type: 'expression', raw: 'startX' }], // bare identifier — v1 exclusion
+        ['modifier', { type: 'expression', raw: '次 .item' }], // native words + code mixed
+        ['condition', { type: 'expression', raw: '#modal exists' }], // selector-prefixed prose (if-exists class)
+        ['url', { type: 'literal', value: '/api/search?q=${my' }], // truncated template interpolation
+        ['flagRole', { type: 'flag', name: 'async', enabled: true }],
+        [
+          'pathRole',
+          { type: 'property-path', object: { type: 'reference', value: 'me' }, property: 'value' },
+        ],
+      ]),
+    };
+    expect(collectRoleValueSignature(node)).toEqual([]);
+  });
+
+  it('is a multiset — a dropped duplicate value is visible via computeMultisetRecall', () => {
+    // The bind-two-way shape: two `bind`s to two different sigil refs; a
+    // truncating parse keeps only the first. Both entries share NO key with a
+    // Set — but if both bound the SAME ref, dedup would hide the drop:
+    const twoBinds = {
+      action: 'compound',
+      statements: [
+        {
+          action: 'bind',
+          roles: new Map<string, unknown>([['source', { type: 'expression', raw: '$name' }]]),
+        },
+        {
+          action: 'bind',
+          roles: new Map<string, unknown>([['source', { type: 'expression', raw: '$name' }]]),
+        },
+      ],
+    };
+    const oneBind = {
+      action: 'bind',
+      roles: new Map<string, unknown>([['source', { type: 'expression', raw: '$name' }]]),
+    };
+    const ref = collectRoleValueSignature(twoBinds);
+    const cand = collectRoleValueSignature(oneBind);
+    expect(ref).toEqual(['bind.source=$name', 'bind.source=$name']);
+    expect(cand).toEqual(['bind.source=$name']);
+    expect(computeMultisetRecall(ref, cand)).toBe(0.5);
+  });
+
+  it('recurses into behavior-shaped nodes (eventHandlers + initBlock)', () => {
+    // No other walker test exercises these two CHILD_FIELDS; ad-hoc walkers
+    // that omit them see behavior bodies as empty.
+    const behavior = {
+      kind: 'behavior',
+      action: 'behavior',
+      roles: new Map<string, unknown>([['name', { type: 'expression', raw: 'Draggable' }]]),
+      eventHandlers: [
+        {
+          kind: 'event-handler',
+          action: 'on',
+          roles: new Map<string, unknown>([
+            ['event', { type: 'literal', value: 'draggable:start' }],
+          ]),
+          body: [
+            {
+              kind: 'command',
+              action: 'add',
+              roles: new Map<string, unknown>([
+                ['patient', { type: 'selector', value: '.dragging' }],
+              ]),
+            },
+          ],
+        },
+      ],
+      initBlock: [
+        {
+          kind: 'command',
+          action: 'set',
+          roles: new Map<string, unknown>([['destination', { type: 'expression', raw: '*width' }]]),
+        },
+      ],
+    };
+    expect(collectRoleValueSignature(behavior)).toEqual([
+      'add.patient=.dragging',
+      'on.event=draggable:start',
+      'set.destination=*width',
+    ]);
+  });
+
+  it('reads plain-object roles (synthetic/JSON-shaped nodes) too', () => {
+    const node = {
+      action: 'toggle',
+      roles: { patient: { type: 'selector', value: '#count' } },
+    };
+    expect(collectRoleValueSignature(node)).toEqual(['toggle.patient=#count']);
+  });
+
+  it('skips the structural compound wrapper and handles non-object input', () => {
+    const node = {
+      action: 'compound',
+      roles: new Map<string, unknown>([['patient', { type: 'selector', value: '.x' }]]),
+      statements: [{ action: 'toggle', roles: { patient: { type: 'selector', value: '.x' } } }],
+    };
+    expect(collectRoleValueSignature(node)).toEqual(['toggle.patient=.x']);
+    expect(collectRoleValueSignature(null)).toEqual([]);
+    expect(collectRoleValueSignature(undefined)).toEqual([]);
+  });
+});
+
 describe('spuriousActions', () => {
   it('lists the hallucinated commands a render/parse introduced', () => {
     expect(spuriousActions(['add', 'on', 'remove'], ['add', 'on', 'remove', 'toggle'])).toEqual([