@event4u/agent-config 9.9.0 → 9.11.0

package/src/scripts/_lib/payload_hash_drift.ts

@@ -0,0 +1,126 @@
+/**
+ * Payload-hash × cache-hit drift aggregator (pure, no-I/O).
+ *
+ * `road-to-cache-economy.md` Phase 3, step 6: the
+ * `orchestration` object's `payload_hash` and `cache_hit` fields are both
+ * `null`-by-default and read by nothing (per the roadmap's own defect list).
+ * This module is the reader: it joins the two fields recorded on the SAME
+ * audit-log-v1 line — `payload_hash` names which spawn-payload shape a
+ * dispatch used, `cache_hit` is the provider-reported prompt-cache hit for
+ * that dispatch — so prefix-stability drift becomes visible.
+ *
+ * Cohort split (the roadmap's own verify criterion — "a cohort dispatched
+ * with a deliberately unstable payload shows a lower read share than a
+ * stable one"):
+ *
+ * - STABLE cohort: every occurrence of a `payload_hash` AFTER its first —
+ *   a hash that repeats means the same payload shape was dispatched again,
+ *   so a cache hit on the repeat is the signal a stable prefix predicts.
+ * - UNSTABLE cohort: every `payload_hash` that occurs exactly once in the
+ *   window — a payload that never repeats can never show a repeat-hit, so
+ *   its (necessarily first-call) `cache_hit` value is the unstable-payload
+ *   baseline.
+ *
+ * A hash's FIRST occurrence is excluded from the stable cohort — nothing
+ * exists yet for a first call to hit, so counting it would understate the
+ * stable cohort's hit rate for a reason that has nothing to do with prefix
+ * stability.
+ *
+ * Zero recorded lines is a VALID state (both fields are lean-init
+ * extensions with no caller wiring a real value yet) — the aggregator
+ * returns a report with empty cohorts rather than failing, and the CLI
+ * wrapper states that plainly rather than presenting empty input as a green
+ * result.
+ */
+
+export interface PayloadHashLine {
+    payload_hash: string | null;
+    cache_hit: boolean | null;
+}
+
+export interface HashGroupStat {
+    payload_hash: string;
+    occurrences: number;
+    hit_count: number;
+    hit_rate: number;
+}
+
+export interface CohortStat {
+    n: number;
+    hit_count: number;
+    hit_rate: number | null;
+}
+
+export interface PayloadHashDriftReport {
+    total_lines: number;
+    /** Lines carrying both a non-null `payload_hash` and a boolean `cache_hit`. */
+    lines_with_data: number;
+    /** Per-hash breakdown, most-occurrences first. */
+    groups: HashGroupStat[];
+    stable_cohort: CohortStat;
+    unstable_cohort: CohortStat;
+    /** True only when BOTH cohorts have data AND the stable cohort's hit rate is strictly higher. */
+    drift_visible: boolean;
+}
+
+function emptyCohort(): CohortStat {
+    return { n: 0, hit_count: 0, hit_rate: null };
+}
+
+/**
+ * Aggregates already-parsed audit-log-v1 orchestration lines. `lines` order
+ * matters — it is read as chronological (the CLI wrapper reads
+ * `agents/runtime/state/audit/*.jsonl` in filename-sorted order, matching
+ * `readAuditLines`), since "first occurrence of a hash" is the only signal
+ * that decides which cohort an occurrence falls into.
+ */
+export function aggregatePayloadHashDrift(lines: readonly PayloadHashLine[]): PayloadHashDriftReport {
+    const withData = lines.filter((l) => l.payload_hash !== null && l.cache_hit !== null);
+
+    const byHash = new Map<string, boolean[]>();
+    for (const l of withData) {
+        const hash = l.payload_hash as string;
+        const arr = byHash.get(hash) ?? [];
+        arr.push(l.cache_hit as boolean);
+        byHash.set(hash, arr);
+    }
+
+    const groups: HashGroupStat[] = [];
+    const stable = emptyCohort();
+    const unstable = emptyCohort();
+
+    for (const [hash, hits] of byHash) {
+        const hitCount = hits.filter(Boolean).length;
+        groups.push({
+            payload_hash: hash,
+            occurrences: hits.length,
+            hit_count: hitCount,
+            hit_rate: hitCount / hits.length,
+        });
+
+        if (hits.length === 1) {
+            unstable.n += 1;
+            if (hits[0] === true) unstable.hit_count += 1;
+        } else {
+            // Every occurrence AFTER the first (repeat dispatches of the same payload shape).
+            const repeats = hits.slice(1);
+            stable.n += repeats.length;
+            stable.hit_count += repeats.filter(Boolean).length;
+        }
+    }
+
+    groups.sort((a, b) => b.occurrences - a.occurrences || a.payload_hash.localeCompare(b.payload_hash));
+    stable.hit_rate = stable.n > 0 ? stable.hit_count / stable.n : null;
+    unstable.hit_rate = unstable.n > 0 ? unstable.hit_count / unstable.n : null;
+
+    const driftVisible = stable.hit_rate !== null && unstable.hit_rate !== null && stable.hit_rate > unstable.hit_rate;
+
+    return {
+        total_lines: lines.length,
+        lines_with_data: withData.length,
+        groups,
+        stable_cohort: stable,
+        unstable_cohort: unstable,
+        drift_visible: driftVisible,
+    };
+}

package/src/scripts/_lib/preservation_migration.ts

@@ -0,0 +1,291 @@
+/**
+ * Preservation-conformance verifier for safety-floor rule edits.
+ *
+ * `check_safety_floor_untouched` blocks every edit to the four safety-floor
+ * rules. That is right for substantive edits and wrong for a P4 migration, which
+ * moves lookup material into a `load_context:` target without losing anything.
+ * This module decides which one a diff is — by CHECKING, never by trusting a
+ * label, a commit message, or a contributor's word. A migration that cannot be
+ * proven conformant is treated as substantive and blocked (fail-closed).
+ *
+ * The contract it enforces is `preservation-guard`'s: every paragraph, list
+ * item, and fenced block from the source survives — either still in the rule
+ * (telegraph condensation is allowed, so matching is fuzzy) or verbatim in one
+ * of the rule's declared `load_context:` targets (a migration is a move, so
+ * matching there is near-exact). Iron Law sections are stricter still: their
+ * headings must survive at the same level and their fenced blocks byte-for-byte.
+ *
+ * Pure functions over strings — no git, no fs — so the whole decision is unit
+ * testable without manufacturing commits. That absence is why the guard it
+ * serves shipped inert for months.
+ */
+
+/** A structural unit of a markdown body: heading, paragraph, list item, or fence. */
+export interface Unit {
+    kind: 'heading' | 'paragraph' | 'list-item' | 'fence';
+    /** Heading depth (1-6) for `heading`, else 0. */
+    level: number;
+    /** Raw text as it appeared, minus the trailing newline. */
+    raw: string;
+    /** Normalised form used for comparison. */
+    norm: string;
+}
+
+/** Strip frontmatter; return the body. */
+export function strip_frontmatter(text: string): string {
+    const m = /^---\n[\s\S]*?\n---\n/.exec(text);
+    return m === null ? text : text.slice(m[0].length);
+}
+
+/** `load_context:` targets declared in a rule's frontmatter, in order. */
+export function load_context_targets(text: string): string[] {
+    const fm = /^---\n([\s\S]*?)\n---\n/.exec(text);
+    if (fm === null) return [];
+    const out: string[] = [];
+    let inBlock = false;
+    for (const line of fm[1]!.split('\n')) {
+        if (/^load_context:\s*$/.test(line)) {
+            inBlock = true;
+            continue;
+        }
+        if (inBlock) {
+            const item = /^\s*-\s+(.+?)\s*$/.exec(line);
+            if (item !== null) {
+                out.push(item[1]!.replace(/^["']|["']$/g, ''));
+                continue;
+            }
+            if (/^\S/.test(line)) inBlock = false;
+        }
+    }
+    return out;
+}
+
+/**
+ * Normalise a unit for comparison.
+ *
+ * Deliberately blind to the three things a legitimate migration changes and
+ * nothing else: heading depth (an H2 becomes an H3 under a host section), link
+ * targets (relative paths are rewritten for the new location), and whitespace.
+ * Everything that carries obligation — words, emphasis, negations — is compared
+ * as written.
+ */
+export function normalise(raw: string): string {
+    return raw
+        .replace(/^#{1,6}\s+/gm, '') // heading depth
+        .replace(/\]\([^)]*\)/g, ']()') // link targets
+        .replace(/^\s*[-*+]\s+/gm, '') // list markers
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+
+/** Split a markdown body into structural units. Fenced blocks stay intact. */
+export function parse_units(body: string): Unit[] {
+    const lines = body.split('\n');
+    const units: Unit[] = [];
+    let para: string[] = [];
+
+    const flush = (): void => {
+        if (para.length === 0) return;
+        const raw = para.join('\n');
+        if (raw.trim() !== '') units.push({ kind: 'paragraph', level: 0, raw, norm: normalise(raw) });
+        para = [];
+    };
+
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i]!;
+        const fence = /^(\s*)(`{3,}|~{3,})/.exec(line);
+        if (fence !== null) {
+            flush();
+            const marker = fence[2]!;
+            const block = [line];
+            i += 1;
+            while (i < lines.length) {
+                block.push(lines[i]!);
+                if (lines[i]!.trimStart().startsWith(marker)) break;
+                i += 1;
+            }
+            const raw = block.join('\n');
+            units.push({ kind: 'fence', level: 0, raw, norm: raw.replace(/\s+$/gm, '') });
+            continue;
+        }
+        const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+        if (heading !== null) {
+            flush();
+            units.push({
+                kind: 'heading',
+                level: heading[1]!.length,
+                raw: line,
+                norm: normalise(line),
+            });
+            continue;
+        }
+        const item = /^\s*[-*+]\s+/.test(line) || /^\s*\d+\.\s+/.test(line);
+        if (item) {
+            flush();
+            units.push({ kind: 'list-item', level: 0, raw: line, norm: normalise(line) });
+            continue;
+        }
+        if (line.trim() === '') {
+            flush();
+            continue;
+        }
+        para.push(line);
+    }
+    flush();
+    return units;
+}
+
+/** Dice coefficient over character bigrams — cheap, order-sensitive enough. */
+export function similarity(a: string, b: string): number {
+    if (a === b) return 1;
+    if (a.length < 2 || b.length < 2) return a === b ? 1 : 0;
+    const grams = (s: string): Map<string, number> => {
+        const m = new Map<string, number>();
+        for (let i = 0; i < s.length - 1; i += 1) {
+            const g = s.slice(i, i + 2);
+            m.set(g, (m.get(g) ?? 0) + 1);
+        }
+        return m;
+    };
+    const ga = grams(a);
+    const gb = grams(b);
+    let overlap = 0;
+    for (const [g, n] of ga) overlap += Math.min(n, gb.get(g) ?? 0);
+    return (2 * overlap) / (a.length - 1 + b.length - 1);
+}
+
+/** A unit still present in the rule after telegraph condensation. */
+const KEPT_IN_RULE = 0.6;
+/** A unit moved into a context file — a move, so near-verbatim. */
+const MOVED_TO_CONTEXT = 0.9;
+
+export interface Finding {
+    code:
+        | 'iron-law-heading-lost'
+        | 'iron-law-fence-changed'
+        | 'passage-lost'
+        | 'unexplained-addition';
+    detail: string;
+}
+
+/** Units belonging to an Iron Law section (heading matches, until the next same-or-shallower heading). */
+export function iron_law_units(units: readonly Unit[]): Unit[] {
+    const out: Unit[] = [];
+    let depth: number | null = null;
+    for (const u of units) {
+        if (u.kind === 'heading') {
+            if (/^(the\s+)?iron\s+law/i.test(u.norm)) {
+                depth = u.level;
+                out.push(u);
+                continue;
+            }
+            if (depth !== null && u.level <= depth) depth = null;
+        }
+        if (depth !== null) out.push(u);
+    }
+    return out;
+}
+
+export interface VerifyInput {
+    /** Rule file content before the change. */
+    base_rule: string;
+    /** Rule file content after the change. */
+    head_rule: string;
+    /** Declared `load_context` target path → content AFTER the change. */
+    head_contexts: ReadonlyMap<string, string>;
+    /** Same targets, content BEFORE — so only ADDED context text counts as a landing site. */
+    base_contexts: ReadonlyMap<string, string>;
+}
+
+/**
+ * Decide whether a safety-floor rule edit is a preservation-conforming
+ * migration. Returns [] when it is; otherwise every reason it is not.
+ */
+export function verify_migration(input: VerifyInput): Finding[] {
+    const findings: Finding[] = [];
+    const baseUnits = parse_units(strip_frontmatter(input.base_rule));
+    const headUnits = parse_units(strip_frontmatter(input.head_rule));
+
+    // ── Iron Law: headings survive at depth, fences survive byte-for-byte ──
+    const baseIron = iron_law_units(baseUnits);
+    const headIron = iron_law_units(headUnits);
+    for (const u of baseIron) {
+        if (u.kind === 'heading') {
+            const hit = headIron.some((h) => h.kind === 'heading' && h.norm === u.norm && h.level === u.level);
+            if (!hit) {
+                findings.push({
+                    code: 'iron-law-heading-lost',
+                    detail: `${u.raw.trim()} — must survive verbatim at the same level`,
+                });
+            }
+        } else if (u.kind === 'fence') {
+            const hit = headIron.some((h) => h.kind === 'fence' && h.raw === u.raw);
+            if (!hit) {
+                findings.push({
+                    code: 'iron-law-fence-changed',
+                    detail: `fenced block under ${u.raw.split('\n')[0] ?? ''} changed — Iron Law fences are byte-exact`,
+                });
+            }
+        }
+    }
+
+    // ── Landing sites: only text ADDED to a DECLARED context counts ──
+    //
+    // The declared set is re-derived here from the rule's own frontmatter rather
+    // than trusted from the caller. A migration is only legitimate into a file
+    // the rule actually points readers at; dropping a passage into some other
+    // file leaves it unreachable from the rule and is a loss, not a move.
+    const declared = load_context_targets(input.head_rule);
+    const isDeclared = (p: string): boolean =>
+        declared.some((rel) => p === rel || p.endsWith(`/${rel}`));
+    const landing: string[] = [];
+    for (const [path, head] of input.head_contexts) {
+        if (!isDeclared(path)) continue;
+        const before = new Set(parse_units(strip_frontmatter(input.base_contexts.get(path) ?? '')).map((u) => u.norm));
+        for (const u of parse_units(strip_frontmatter(head))) {
+            if (!before.has(u.norm)) landing.push(u.norm);
+        }
+    }
+
+    // ── Every base unit survives: in the rule (fuzzy) or in a context (near-exact) ──
+    const headNorms = headUnits.map((u) => u.norm);
+    const usedHead = new Set<number>();
+    for (const u of baseUnits) {
+        let bestIdx = -1;
+        let best = 0;
+        for (let i = 0; i < headNorms.length; i += 1) {
+            if (usedHead.has(i)) continue;
+            const s = similarity(u.norm, headNorms[i]!);
+            if (s > best) {
+                best = s;
+                bestIdx = i;
+            }
+        }
+        if (best >= KEPT_IN_RULE) {
+            usedHead.add(bestIdx);
+            continue;
+        }
+        const moved = landing.some((l) => similarity(u.norm, l) >= MOVED_TO_CONTEXT);
+        if (!moved) {
+            findings.push({
+                code: 'passage-lost',
+                detail: `${u.kind}: ${u.raw.trim().slice(0, 90)}… — not kept in the rule and not found in any declared load_context target`,
+            });
+        }
+    }
+
+    // ── Nothing genuinely new in the rule: a migration only removes ──
+    for (let i = 0; i < headUnits.length; i += 1) {
+        if (usedHead.has(i)) continue;
+        const u = headUnits[i]!;
+        const back = baseUnits.some((b) => similarity(b.norm, u.norm) >= KEPT_IN_RULE);
+        if (!back) {
+            findings.push({
+                code: 'unexplained-addition',
+                detail: `${u.kind}: ${u.raw.trim().slice(0, 90)}… — new content in a safety-floor rule is a substantive edit, not a migration`,
+            });
+        }
+    }
+
+    return findings;
+}

package/src/scripts/_lib/retrieval_sanitize.ts

@@ -3,8 +3,8 @@
  * (road-to-retrieval-substrate-hardening B6).
  *
  * Corpus content — especially user-ingested knowledge chunks under
- * `agents/memory/knowledge/` — flows into the agent context via `retrieve_v1`
- * / `memory_get_v1`. An attacker (or a compromised ingested source) can embed
+ * `agents/memory/knowledge/` — flows into the agent context on the retrieval
+ * read surfaces. An attacker (or a compromised ingested source) can embed
  * hidden-instruction vectors (bidi controls, zero-width chars, Unicode Tag
  * block) or control-char noise that the model may act on — the untrusted-input
  * / lethal-trifecta injection surface. This floor strips those vectors from
@@ -15,12 +15,49 @@
  * layer + unbounded length; visible content is the agent's to read as data.
  * Codepoint classes are shared with `lint_hidden_unicode` (one source of truth
  * for what counts as a hidden-instruction vector).
+ *
+ * WHERE IT ACTUALLY RUNS — measured end-to-end, not asserted. Keep this list
+ * honest: an earlier version of this header named surfaces by intent, and the
+ * legacy-envelope gap below went unnoticed for exactly that reason. Every
+ * claim here is backed by a probe row in
+ * `agents/evidence/reports/sanitize-floor-wiring.md`:
+ *
+ *   - `retrieve_v1()`     — yes (`memory_lookup.ts` calls `sanitize_entry`)
+ *   - `memory_get_v1()`   — yes (same)
+ *   - MCP `memory_lookup` / `memory_get` tools — inherited from the two above
+ *   - `retrieve()` / `retrieve_with_meta()` — yes, since the S0.0 wiring fix;
+ *     before it they emitted every vector intact, and so did the CLI default
+ *     (`--envelope legacy`), which is the path the rules document
+ *   - inter-agent channels (`ai_team` / `ai_council` model replies) — the
+ *     inbound parse choke point only; the subagent boundary itself is a HOST
+ *     primitive this package cannot reach (see the report, § S0.0b)
+ *
+ * Anything not on that list is uncovered. Do not widen the list without a
+ * probe row to back it.
  */
 import { _classify } from '../lint_hidden_unicode.js';
+import { TOKEN_RE, classifyToken } from './confusables.js';
 
 /** Hard per-field length cap — bounds a runaway/adversarial body. */
 export const MAX_FIELD_CHARS = 8192;
 
+/**
+ * Invisible fillers — render as blank but are not whitespace, so they sit in
+ * neither the zero-width nor the bidi set and survived the original floor
+ * (measured: `agents/evidence/reports/encoding-channel-coverage.md` row 18).
+ *
+ * These are the ONLY channel Phase 1 chose to strip rather than flag: invisible
+ * by nature, with no legitimate role in this corpus, so folding them into the
+ * existing invisible set carries no corruption risk. Every other uncovered
+ * channel is a flag, because rewriting visible text can corrupt legitimate
+ * content.
+ */
+const _INVISIBLE_FILLERS: ReadonlySet<number> = new Set([
+    0x3164, // HANGUL FILLER
+    0x115f, // HANGUL CHOSEONG FILLER
+    0x1160, // HANGUL JUNGSEONG FILLER
+]);
+
 /** True for a C0/C1 control char that is NOT a benign whitespace (\t, \n). */
 function _isStrippableControl(cp: number): boolean {
     if (cp === 0x09 || cp === 0x0a) return false; // keep tab + newline
@@ -42,11 +79,138 @@ export function sanitize_text(s: string): string {
         if (cp === undefined) continue;
         if (_classify(cp) !== null) continue; // hidden-instruction vector → drop
         if (_isStrippableControl(cp)) continue; // control-char noise → drop
+        if (_INVISIBLE_FILLERS.has(cp)) continue; // blank-but-not-whitespace → drop
         out += ch;
     }
     return out.length > MAX_FIELD_CHARS ? out.slice(0, MAX_FIELD_CHARS) : out;
 }
 
+// ---------------------------------------------------------------------------
+// Visible-layer scanner — FLAG ONLY, never rewrites
+// ---------------------------------------------------------------------------
+//
+// `sanitize_text` strips the invisible layer. This reports the VISIBLE layer,
+// which the floor deliberately does not touch: folding a confusable to a Latin
+// skeleton, or NFKC-normalising a math-alphanumeric run, corrupts any body that
+// legitimately contains mixed script, CJK punctuation, or a ligature. Phase 1
+// measured each channel and chose flag-not-rewrite for every one of these:
+// `agents/evidence/reports/encoding-channel-coverage.md` § Disposition.
+//
+// Deterministic and pure: no model call, no network, no I/O. Safe to run in CI
+// and on a request path.
+//
+// Not scanned, deliberately, with the reason recorded so it is not mistaken for
+// an oversight:
+//   - confusable whitespace (NBSP, figure space) — pervasive in real prose
+//   - HTML/XML entities — decoding them would CREATE the payload
+//   - nested multibase (base64) — legitimate throughout this repo; semantic,
+//     not structural
+//   - structured-data key ordering — not a codepoint channel at all, and
+//     reordering keys would break the byte-identical v1 envelope contract
+//   - word-order permutation — carrier text with legitimate word order is
+//     indistinguishable from permuted text without semantics
+
+/** Codepoint thresholds — a run is the signal; a single occurrence is not. */
+const _VS_RUN_MIN = 3;
+const _COMBINING_RUN_MIN = 5;
+
+export interface EncodingFinding {
+    /** Stable channel id, matching the frozen corpus labels. */
+    readonly channel: string;
+    /** Why it fired, with the concrete evidence (codepoint or token). */
+    readonly detail: string;
+}
+
+function _isVariationSelector(cp: number): boolean {
+    return (cp >= 0xfe00 && cp <= 0xfe0f) || (cp >= 0xe0100 && cp <= 0xe01ef);
+}
+
+function _isCombiningMark(cp: number): boolean {
+    return cp >= 0x0300 && cp <= 0x036f;
+}
+
+/**
+ * Report visible-layer encoding signals in a string. Never mutates it.
+ *
+ * The confusable signature is NOT reimplemented here — it is the shared
+ * `classifyToken` from `_lib/confusables.ts`, the single definition this
+ * package's authoring-time linter also uses, so the two surfaces cannot drift
+ * apart on what counts as a homoglyph.
+ */
+export function scan_encoding_findings(s: string): EncodingFinding[] {
+    const out: EncodingFinding[] = [];
+
+    // Longest run of variation selectors / combining marks anywhere in the
+    // string. A run is what distinguishes steganography from legitimate use:
+    // U+FE0F is the emoji presentation selector and diacritics are normal in
+    // many languages, so a single occurrence is never the signal.
+    let vsRun = 0;
+    let vsMax = 0;
+    let cmRun = 0;
+    let cmMax = 0;
+    let hasMathAlnum = false;
+    let hasFullwidth = false;
+    for (const ch of s) {
+        const cp = ch.codePointAt(0);
+        if (cp === undefined) continue;
+        if (_isVariationSelector(cp)) {
+            vsRun += 1;
+            vsMax = Math.max(vsMax, vsRun);
+        } else {
+            vsRun = 0;
+        }
+        if (_isCombiningMark(cp)) {
+            cmRun += 1;
+            cmMax = Math.max(cmMax, cmRun);
+        } else {
+            cmRun = 0;
+        }
+        if (cp >= 0x1d400 && cp <= 0x1d7ff) hasMathAlnum = true;
+        if (cp >= 0xff01 && cp <= 0xff5e) hasFullwidth = true;
+    }
+    if (vsMax >= _VS_RUN_MIN) {
+        out.push({
+            channel: 'variation-selector-run',
+            detail: `variation-selector run x${vsMax} (steganography signature)`,
+        });
+    }
+    if (cmMax >= _COMBINING_RUN_MIN) {
+        out.push({
+            channel: 'combining-mark-run',
+            detail: `combining-mark run x${cmMax} on one base character`,
+        });
+    }
+    if (hasMathAlnum) {
+        out.push({
+            channel: 'math-alphanumeric',
+            detail: 'Mathematical Alphanumeric Symbols used as letters (U+1D400–1D7FF)',
+        });
+    }
+    if (hasFullwidth) {
+        out.push({
+            channel: 'fullwidth-forms',
+            detail: 'Halfwidth/Fullwidth Forms used as ASCII letters (U+FF01–FF5E)',
+        });
+    }
+
+    // Mixed-script confusable tokens — shared signature, one table in the tree.
+    for (const m of s.matchAll(TOKEN_RE)) {
+        const verdict = classifyToken(m[0]);
+        if (verdict !== null) {
+            const script = verdict.startsWith('latin+greek') ? 'greek' : 'cyrillic';
+            out.push({ channel: `confusable-${script}`, detail: `${m[0]} — ${verdict}` });
+        }
+    }
+
+    // Punycode / IDN in a text-expected field. Flagged, never rewritten:
+    // `xn--` labels are valid DNS and rewriting one would break a real link.
+    for (const m of s.matchAll(/\bxn--[a-z0-9-]+/gi)) {
+        out.push({ channel: 'punycode-idn', detail: `punycode label ${m[0]}` });
+    }
+
+    return out;
+}
+
 /**
  * Return a shallow copy of a retrieval entry with every string value (and
  * one level of string-array values) sanitized. Non-string values pass through