@iris-eval/mcp-server 0.8.2 → 0.10.0

package/dist/eval/text/normalise.js

@@ -0,0 +1,265 @@
+/*
+ * One normalisation pass, shared by every rule that matches text.
+ *
+ * The problem it solves is measured, not hypothetical. `npm run proof`
+ * publishes a transforms table: for every positive a critical rule catches,
+ * the text inside the evidence span is transformed the way an evader would
+ * transform it, and the rule is re-run. Before this module, `no_pii` kept
+ * 38% of its catches under a zero-width space, 22% under Cyrillic
+ * homoglyphs and **none at all** under full-width digits, and
+ * `no_blocklist_words` survived nothing but a change of case.
+ *
+ * What it does, in order, per grapheme cluster:
+ *   1. drops format characters that carry no meaning — zero-width spaces
+ *      and joiners, the soft hyphen, the byte-order mark;
+ *   2. NFKC-folds the cluster, which turns full-width and mathematical
+ *      alphanumerics into ASCII (４１１１ → 4111, 𝐩𝐚𝐬𝐬 → pass);
+ *   3. maps the confusables NFKC does NOT fold — Cyrillic and Greek letters
+ *      that are drawn like Latin ones (раssword with a Cyrillic а and р);
+ *   4. collapses every run of whitespace to ONE character — a newline when
+ *      the run contains one, a space otherwise. Line structure is meaning:
+ *      a forged "System:" line and a fenced block are line-shaped, and
+ *      flattening newlines to spaces measurably cost the injection rule
+ *      recall on three transforms. Horizontal runs carry no such meaning.
+ *
+ * What it deliberately does NOT do is leetspeak (0 → o, 1 → i). That
+ * substitution is correct for injection phrasing and catastrophic for
+ * everything else: it would turn a credit card number into letters and
+ * blind every digit-based detector. The injection rule applies it on top of
+ * this pass, to this pass's output, and owns it alone.
+ *
+ * Every rule that matches on `text` reports evidence through `map`, so a
+ * span still indexes the RAW output the caller sent — the arc-1 contract
+ * ("spans are offsets into the raw text") is what makes redaction and the
+ * transforms measurement correct, and normalising without a map would
+ * quietly break it.
+ */
+/** Format characters that carry no textual meaning and are pure evasion when they sit inside a token. */
+const DROPPED = new Set([
+    '​', // zero-width space
+    '‌', // zero-width non-joiner
+    '‍', // zero-width joiner
+    '‎', // left-to-right mark
+    '‏', // right-to-left mark
+    '⁠', // word joiner
+    '', // byte-order mark / zero-width no-break space
+    '­', // soft hyphen
+]);
+/**
+ * Letters that NFKC leaves alone but a reader cannot tell apart from Latin.
+ * Cyrillic first, then Greek; lowercase and uppercase where both are
+ * confusable. Deliberately conservative: only characters whose common
+ * rendering is indistinguishable in the fonts an agent's output is read in.
+ */
+const CONFUSABLES = new Map([
+    // Cyrillic → Latin
+    ['а', 'a'], ['А', 'A'],
+    ['е', 'e'], ['Е', 'E'],
+    ['о', 'o'], ['О', 'O'],
+    ['р', 'p'], ['Р', 'P'],
+    ['с', 'c'], ['С', 'C'],
+    ['х', 'x'], ['Х', 'X'],
+    ['у', 'y'], ['У', 'Y'],
+    ['к', 'k'], ['К', 'K'],
+    ['м', 'm'], ['М', 'M'],
+    ['н', 'h'], ['Н', 'H'],
+    ['т', 't'], ['Т', 'T'],
+    ['в', 'v'], ['В', 'B'],
+    ['і', 'i'], ['І', 'I'],
+    ['ј', 'j'], ['Ј', 'J'],
+    ['ѕ', 's'], ['Ѕ', 'S'],
+    ['б', '6'],
+    ['г', 'r'],
+    ['з', '3'],
+    ['һ', 'h'],
+    ['ҙ', 'z'],
+    // Greek → Latin
+    ['ο', 'o'], ['Ο', 'O'],
+    ['α', 'a'], ['Α', 'A'],
+    ['ε', 'e'], ['Ε', 'E'],
+    ['ρ', 'p'], ['Ρ', 'P'],
+    ['τ', 't'], ['Τ', 'T'],
+    ['ν', 'v'], ['Ν', 'N'],
+    ['υ', 'u'], ['Υ', 'Y'],
+    ['ι', 'i'], ['Ι', 'I'],
+    ['κ', 'k'], ['Κ', 'K'],
+    ['β', 'B'], ['Β', 'B'],
+    ['η', 'n'], ['Η', 'H'],
+    ['χ', 'x'], ['Χ', 'X'],
+    ['μ', 'u'], ['Μ', 'M'],
+    ['γ', 'y'], ['Ζ', 'Z'],
+    ['Φ', 'O'],
+    // Other scripts whose letters are drawn as Latin
+    ['ԁ', 'd'],
+    ['ԛ', 'q'],
+    ['ɡ', 'g'],
+    ['ẞ', 'S'],
+    ['ո', 'n'],
+    ['ս', 'u'],
+    ['օ', 'o'],
+]);
+/**
+ * Printable ASCII plus the newline. Nothing in that set folds, so the only
+ * thing that could change such a string is a whitespace RUN — which makes
+ * two linear scans a complete test for "this text is already normalised".
+ *
+ * This is the hot path and it is why the pass is affordable. Ordinary agent
+ * output is plain text; a one-megabyte payload of it used to cost a grapheme
+ * segmentation and a character-by-character rebuild, and the hostile-payload
+ * budget in the test battery caught exactly that.
+ */
+const PLAIN_TEXT = /^[\x20-\x7E\n]*$/;
+const WHITESPACE_RUN = /\s\s/;
+/** The result for text that is already in normal form: no copy, no map until asked. */
+function identity(raw) {
+    let cached;
+    return {
+        text: raw,
+        unchanged: true,
+        get map() {
+            if (cached === undefined) {
+                cached = new Int32Array(raw.length + 1);
+                for (let i = 0; i <= raw.length; i++)
+                    cached[i] = i;
+            }
+            return cached;
+        },
+    };
+}
+let segmenter;
+function graphemes(raw) {
+    if (typeof Intl?.Segmenter === 'function') {
+        segmenter ??= new Intl.Segmenter('en', { granularity: 'grapheme' });
+        return segmenter.segment(raw);
+    }
+    // Environments without Intl.Segmenter fall back to code points, which is
+    // correct for everything this pass folds and only differs on combining
+    // sequences it would leave alone anyway.
+    return [...raw];
+}
+const WHITESPACE = /\s/u;
+const LINE_BREAK = /[\n\r\u2028\u2029]/u;
+/** Folds `raw` for matching and returns the offset map that puts evidence back on the raw text. */
+export function normalise(raw) {
+    // Already in normal form: two linear scans and no allocation at all.
+    if (PLAIN_TEXT.test(raw) && !WHITESPACE_RUN.test(raw))
+        return identity(raw);
+    const out = [];
+    const offsets = [];
+    /** The whitespace run being accumulated: where it started, and whether it broke a line. */
+    let run = null;
+    let changed = false;
+    /** False as soon as one output character does not sit at its own raw offset. */
+    let identityMap = true;
+    const push = (chars, at) => {
+        for (const ch of chars) {
+            if (at !== out.length)
+                identityMap = false;
+            out.push(ch);
+            offsets.push(at);
+        }
+    };
+    /** Emits the pending whitespace run as one character: a newline if it broke a line, else a space. */
+    const flushRun = () => {
+        if (run === null)
+            return;
+        const ch = run.hadBreak ? '\n' : ' ';
+        if (raw.slice(run.at, run.at + 1) !== ch)
+            changed = true;
+        push(ch, run.at);
+        run = null;
+    };
+    const segments = graphemes(raw);
+    const iterate = (rawCluster, index) => {
+        /*
+         * Strip the format characters from INSIDE the cluster, not just from
+         * clusters that are one. A zero-width non-joiner between two digits
+         * binds into the neighbouring grapheme, so a whole-cluster test misses
+         * exactly the evasion this exists to fold.
+         */
+        let cluster = rawCluster;
+        if (cluster.length > 1 || DROPPED.has(cluster)) {
+            let stripped = '';
+            for (const ch of cluster)
+                if (!DROPPED.has(ch))
+                    stripped += ch;
+            if (stripped !== cluster) {
+                changed = true;
+                cluster = stripped;
+            }
+        }
+        if (cluster === '')
+            return;
+        if (WHITESPACE.test(cluster)) {
+            const hadBreak = LINE_BREAK.test(cluster);
+            if (run === null)
+                run = { at: index, hadBreak };
+            else {
+                run.hadBreak ||= hadBreak;
+                changed = true;
+            }
+            return;
+        }
+        flushRun();
+        let folded = cluster.normalize('NFKC');
+        if (folded !== cluster)
+            changed = true;
+        if (CONFUSABLES.size > 0) {
+            let mapped = '';
+            for (const ch of folded) {
+                const sub = CONFUSABLES.get(ch);
+                if (sub === undefined)
+                    mapped += ch;
+                else {
+                    mapped += sub;
+                    changed = true;
+                }
+            }
+            folded = mapped;
+        }
+        // A cluster that folds away entirely (a lone combining mark NFKC drops)
+        // contributes nothing; its offset is covered by the next kept character.
+        push(folded, index);
+    };
+    if (Array.isArray(segments)) {
+        let at = 0;
+        for (const cluster of segments) {
+            iterate(cluster, at);
+            at += cluster.length;
+        }
+    }
+    else {
+        for (const { segment, index } of segments)
+            iterate(segment, index);
+    }
+    flushRun();
+    const text = out.join('');
+    let cached;
+    return {
+        text,
+        unchanged: !changed && identityMap && text.length === raw.length,
+        get map() {
+            if (cached === undefined) {
+                cached = new Int32Array(offsets.length + 1);
+                cached.set(offsets);
+                cached[offsets.length] = raw.length;
+            }
+            return cached;
+        },
+    };
+}
+/**
+ * A span in normalised coordinates as a span in raw coordinates. Always
+ * widens rather than narrows: when characters were dropped between the last
+ * matched character and the next kept one, the raw span covers them, which
+ * is what a reader wants — the evasion is part of the evidence.
+ */
+export function toRawSpan(n, start, end) {
+    // The identity case never touches the map, so no array is built for the
+    // ordinary text that makes up almost every evaluation.
+    if (n.unchanged)
+        return [Math.max(0, start), Math.max(start, end)];
+    const s = Math.max(0, Math.min(start, n.map.length - 1));
+    const e = Math.max(s, Math.min(end, n.map.length - 1));
+    return [n.map[s], n.map[e]];
+}

package/dist/eval/text/sentences.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Named sentencesOf, not sentencesOf: the hallucination rule in
+ * src/eval/rules/safety.ts has its own sentencesOf that also breaks on
+ * every newline, because it wants per-line units for grounding checks. The
+ * two are not the same job and unifying them would move that rule's
+ * numbers, so it is a separate measured change, not a rename.
+ *
+ * Splits `text` into sentences. Never returns an empty sentence; a text with
+ * no terminator is one sentence. Line breaks do not split on their own — a
+ * wrapped paragraph is one sentence — but a blank line does, because a new
+ * block is a new thought and a bullet list is not one long sentence.
+ */
+export declare function sentencesOf(text: string): string[];
+/** How many sentences the text contains. The one number `sentence_count` reports. */
+export declare function countSentences(text: string): number;

package/dist/eval/text/sentences.js

@@ -0,0 +1,149 @@
+/*
+ * One sentence splitter, for the two rules that count or walk sentences.
+ *
+ * Both had their own, and both were wrong in the same way. `sentence_count`
+ * split on `/[.!?]+/`, so "The latency is 3.5 seconds." counted as two
+ * sentences and "Dr. Chen approved it." as two more; the arc-zero review
+ * measured the damage at 43% of that rule's family. `topic_consistency`
+ * split on a full stop followed by whitespace, which fixes the decimal only
+ * when the decimal has no space after it and never fixes the abbreviation.
+ *
+ * A sentence ends at `.`, `!` or `?` when what follows looks like the start
+ * of a new sentence and what precedes is not one of the things that ends in
+ * a full stop without ending a sentence:
+ *
+ *   - never between digits, so 3.5 and 1.2.3 stay whole;
+ *   - never after a closed list of abbreviations (Dr, Mr, Mrs, Ms, e.g,
+ *     i.e, vs, etc, No, Fig, St, Inc, Ltd, Jr, Sr, approx, cf, al);
+ *   - never after a single capital letter, which is an initial (J. Smith);
+ *   - only when the next non-space character starts a sentence: an
+ *     uppercase letter, an opening quote or bracket, or a digit.
+ *
+ * The list is closed on purpose. An open-ended abbreviation heuristic
+ * (a short token ending in a full stop) swallows real sentence ends —
+ * "It was fun. Then we left." — and this splitter is used to COUNT, where
+ * missing a break is as wrong as inventing one.
+ */
+/**
+ * Abbreviations that are essentially never the last word of a sentence, so
+ * the full stop after them is punctuation and not an end. Lowercase, no
+ * trailing stop.
+ */
+const ALWAYS_ABBREVIATION = new Set([
+    'dr', 'mr', 'mrs', 'ms', 'prof', 'sr', 'jr', 'st', 'mt',
+    'e.g', 'i.e', 'vs', 'al', 'cf', 'approx', 'est',
+    'dept', 'univ', 'a.m', 'p.m', 'u.s', 'u.k',
+]);
+/**
+ * Abbreviations that are ALSO ordinary sentence endings — "shipped in Oct.
+ * The rollout held" ends a sentence; "shipped on Oct. 5" does not. What
+ * separates them is what follows: a number means the abbreviation is being
+ * used as a label, anything else means the sentence ended. Guessing either
+ * way unconditionally is wrong about half the time, and this splitter is
+ * used to COUNT, where a missed break costs exactly as much as an invented
+ * one.
+ */
+const ABBREVIATION_BEFORE_NUMBER = new Set([
+    'no', 'fig', 'eq', 'ch', 'vol', 'pp', 'etc',
+    'inc', 'ltd', 'co', 'corp',
+    'jan', 'feb', 'mar', 'apr', 'jun', 'jul', 'aug', 'sep', 'sept', 'oct', 'nov', 'dec',
+]);
+const TERMINATORS = new Set(['.', '!', '?']);
+/** True when the character can open a new sentence. */
+function opensSentence(ch) {
+    if (ch === undefined)
+        return false;
+    if (ch >= 'A' && ch <= 'Z')
+        return true;
+    if (ch >= '0' && ch <= '9')
+        return true;
+    return '"‘’“”\'([{*_#-—'.includes(ch);
+}
+const isDigit = (ch) => ch !== undefined && ch >= '0' && ch <= '9';
+/** The token immediately before `at`, lowercased, without its trailing stop. */
+function precedingToken(text, at) {
+    let i = at - 1;
+    while (i >= 0 && !/[\s(["']/.test(text[i]))
+        i--;
+    return text.slice(i + 1, at).toLowerCase();
+}
+/**
+ * Named sentencesOf, not sentencesOf: the hallucination rule in
+ * src/eval/rules/safety.ts has its own sentencesOf that also breaks on
+ * every newline, because it wants per-line units for grounding checks. The
+ * two are not the same job and unifying them would move that rule's
+ * numbers, so it is a separate measured change, not a rename.
+ *
+ * Splits `text` into sentences. Never returns an empty sentence; a text with
+ * no terminator is one sentence. Line breaks do not split on their own — a
+ * wrapped paragraph is one sentence — but a blank line does, because a new
+ * block is a new thought and a bullet list is not one long sentence.
+ */
+export function sentencesOf(text) {
+    const out = [];
+    let start = 0;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        // A blank line ends a sentence whatever came before it.
+        if (ch === '\n' && /^\s*\n/.test(text.slice(i + 1))) {
+            const piece = text.slice(start, i).trim();
+            if (piece.length > 0)
+                out.push(piece);
+            start = i + 1;
+            continue;
+        }
+        if (!TERMINATORS.has(ch))
+            continue;
+        // 3.5 — a full stop between digits is a decimal point.
+        if (ch === '.' && isDigit(text[i - 1]) && isDigit(text[i + 1]))
+            continue;
+        // Run past a cluster of terminators ("What?!").
+        let end = i;
+        while (end + 1 < text.length && TERMINATORS.has(text[end + 1]))
+            end++;
+        // Closing quotes and brackets belong to the sentence that ends here.
+        let after = end + 1;
+        while (after < text.length && '"’”\')]}'.includes(text[after]))
+            after++;
+        // What comes next has to look like a new sentence.
+        let next = after;
+        while (next < text.length && /[ \t\r\n]/.test(text[next]))
+            next++;
+        /*
+         * No whitespace after the stop is usually a mid-token full stop — a
+         * version (v0.10.0), a filename (package.json), a hostname
+         * (iris-eval.com/proof) — and must not break. The exception is a
+         * following CAPITAL, which is a missing space between two sentences
+         * ("...ready.Ship it") and not a token: no filename or version has one.
+         */
+        if (next === after && next < text.length && !(text[next] >= 'A' && text[next] <= 'Z'))
+            continue;
+        if (next < text.length && !opensSentence(text[next]))
+            continue;
+        // Dr. Chen — an abbreviation, not an end.
+        if (ch === '.') {
+            const token = precedingToken(text, i);
+            if (ALWAYS_ABBREVIATION.has(token))
+                continue;
+            // Oct. 5 is a date; "in Oct. The rollout held" is two sentences.
+            if (ABBREVIATION_BEFORE_NUMBER.has(token) && isDigit(text[next]))
+                continue;
+            // A single capital letter is an initial: J. Smith.
+            if (token.length === 1 && /[a-z]/i.test(token))
+                continue;
+        }
+        const piece = text.slice(start, after).trim();
+        if (piece.length > 0)
+            out.push(piece);
+        start = after;
+        i = after - 1;
+    }
+    const tail = text.slice(start).trim();
+    if (tail.length > 0)
+        out.push(tail);
+    return out;
+}
+/** How many sentences the text contains. The one number `sentence_count` reports. */
+export function countSentences(text) {
+    return sentencesOf(text).length;
+}

package/dist/eval/verdict.d.ts

@@ -0,0 +1,34 @@
+import type { Coverage, EvalResult, EvalRule, EvalRuleResult, Need, Provenance, Verdict } from '../types/eval.js';
+import type { EffectiveCriticality } from './criticality.js';
+/**
+ * The basis of the verdict under the shipped composer (a weighted mean plus
+ * the critical veto). `passed` is `state === 'pass'` and equals the engine's
+ * own `passed` for every result; the basis says which layer decided.
+ */
+export declare function deriveVerdict(result: Pick<EvalResult, 'passed' | 'score' | 'rule_results' | 'insufficient_data' | 'critical_failures' | 'rules_evaluated'>, threshold: number): Verdict;
+/**
+ * Which evaluation questions were judged, which were not and why. At write
+ * time the engine passes the inputs the call carried; at read time they are
+ * reconstructed as the union of what the rules saw (a rule that saw an input
+ * proves the call carried it; one that did not cannot prove the reverse).
+ */
+export declare function deriveCoverage(ruleResults: readonly EvalRuleResult[], present?: ReadonlySet<Need>): Coverage;
+/** The critical rules that skipped — derived from the stamped flags on every read, never a column. */
+export declare function deriveCriticalSkipped(ruleResults: readonly EvalRuleResult[]): string[] | undefined;
+/** sha256 over the rules that ran — name, definition version, kind, effective criticality, weight — so two evaluations under the same ruleset hash the same. */
+export declare function rulesetHash(rules: readonly EvalRule[], resolve: (rule: EvalRule) => EffectiveCriticality): string;
+/** sha256 over the evaluation configuration that shapes a verdict. */
+export declare function configHash(config: {
+    threshold: number;
+    ruleThresholds?: Record<string, unknown>;
+    criticalRules?: readonly string[];
+    nonCriticalRules?: readonly string[];
+}): string;
+export declare function buildProvenance(input: {
+    irisVersion: string;
+    rulesetHash: string;
+    configHash: string;
+    threshold: number;
+    ruleThresholds?: Record<string, unknown>;
+    judgedAt: string;
+}): Provenance;

package/dist/eval/verdict.js

@@ -0,0 +1,131 @@
+/*
+ * The verdict, the coverage and the provenance — computed once, derived on
+ * read, never fabricated.
+ *
+ * Arc zero (2026-09-05) found the same fact encoded three ways
+ * (`insufficient_data`, `critical_skipped`, `rule_results[].budgetExceeded`),
+ * the verdict's basis nowhere (a reader could not tell a veto from a low
+ * score without knowing the rule library), coverage counted in rules rather
+ * than evaluation questions, and no stored evaluation carrying the version,
+ * ruleset or thresholds that produced it — "why did this pass on that day"
+ * was unanswerable from Iris alone.
+ *
+ * This module answers those from what the engine already knows. It changes
+ * no verdict: `deriveVerdict` names the basis of today's arithmetic
+ * (`passed` here equals the engine's `passed`, and a test proves it); the
+ * compose-by-kind release replaces the arithmetic and keeps the shape.
+ */
+import { createHash } from 'node:crypto';
+import { RULE_QUESTION_IDS } from './questions.js';
+import { NEEDS } from './failure-classes.js';
+import { publishedProvenance } from './accuracy.js';
+/**
+ * The basis of the verdict under the shipped composer (a weighted mean plus
+ * the critical veto). `passed` is `state === 'pass'` and equals the engine's
+ * own `passed` for every result; the basis says which layer decided.
+ */
+export function deriveVerdict(result, threshold) {
+    const evaluated = result.rules_evaluated ?? result.rule_results.filter((r) => !r.skipped).length;
+    if (result.insufficient_data || evaluated === 0) {
+        return { state: 'unknown', passed: false, basis: 'no_rules', by: [], risk: null };
+    }
+    const vetoes = result.critical_failures ?? [];
+    if (vetoes.length > 0) {
+        const kinds = new Map(result.rule_results.map((r) => [r.ruleName, r.kind]));
+        const allPolicies = vetoes.every((name) => kinds.get(name) === 'policy');
+        return { state: 'fail', passed: false, basis: allPolicies ? 'policy_gate' : 'detector_veto', by: [...vetoes], risk: null };
+    }
+    if (result.score < threshold) {
+        const by = result.rule_results.filter((r) => !r.skipped && !r.passed).map((r) => r.ruleName);
+        return { state: 'fail', passed: false, basis: 'score_below_threshold', by, risk: null };
+    }
+    return { state: 'pass', passed: true, basis: 'clean', by: [], risk: null };
+}
+/**
+ * Which evaluation questions were judged, which were not and why. At write
+ * time the engine passes the inputs the call carried; at read time they are
+ * reconstructed as the union of what the rules saw (a rule that saw an input
+ * proves the call carried it; one that did not cannot prove the reverse).
+ */
+export function deriveCoverage(ruleResults, present) {
+    const inputs = {};
+    const seen = new Set(present ?? []);
+    if (!present)
+        for (const r of ruleResults)
+            for (const n of r.saw ?? [])
+                seen.add(n);
+    for (const n of NEEDS)
+        inputs[n] = seen.has(n);
+    const questions = [];
+    for (const id of RULE_QUESTION_IDS) {
+        const rows = ruleResults.filter((r) => r.question === id);
+        if (rows.length === 0) {
+            questions.push({ id, status: 'not_applicable', why: 'no rule that answers this question ran in the selected bundles' });
+            continue;
+        }
+        if (rows.some((r) => !r.skipped)) {
+            questions.push({ id, status: 'judged' });
+            continue;
+        }
+        const defeated = rows.filter((r) => r.skipClass === 'defeated').map((r) => r.ruleName);
+        const broken = rows.filter((r) => r.skipClass === 'config_invalid').map((r) => r.ruleName);
+        if (defeated.length > 0) {
+            questions.push({ id, status: 'unjudged', why: `defeated: ${defeated.join(', ')} could not judge this output (sandbox budget)` });
+            continue;
+        }
+        if (broken.length > 0) {
+            questions.push({ id, status: 'unjudged', why: `config_invalid: ${broken.join(', ')} has a broken definition` });
+            continue;
+        }
+        const missing = new Set();
+        for (const r of rows) {
+            const saw = new Set(r.saw ?? []);
+            // The rule's needs are not on the result; what it lacked is what its
+            // skip reason names. Prefer the structured form when the stamp gave
+            // us `saw`: anything in NEEDS the call did not carry and this rule's
+            // family is known to read. Fall back to the skip reason text.
+            if (r.skipReason)
+                missing.add(r.skipReason);
+            else
+                for (const n of NEEDS)
+                    if (!saw.has(n) && !seen.has(n))
+                        missing.add(n);
+        }
+        questions.push({ id, status: 'unjudged', why: `not supplied: ${[...missing].join('; ')}` });
+    }
+    return { inputs, questions };
+}
+/** The critical rules that skipped — derived from the stamped flags on every read, never a column. */
+export function deriveCriticalSkipped(ruleResults) {
+    if (!ruleResults.some((r) => r.critical !== undefined))
+        return undefined;
+    const names = ruleResults.filter((r) => r.skipped && r.critical).map((r) => r.ruleName);
+    return names.length > 0 ? names : undefined;
+}
+/** sha256 over the rules that ran — name, definition version, kind, effective criticality, weight — so two evaluations under the same ruleset hash the same. */
+export function rulesetHash(rules, resolve) {
+    const rows = rules
+        .map((r) => [r.name, r.version ?? 0, r.kind ?? '', resolve(r).critical ? 1 : 0, r.weight])
+        .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    return createHash('sha256').update(JSON.stringify(rows)).digest('hex').slice(0, 16);
+}
+/** sha256 over the evaluation configuration that shapes a verdict. */
+export function configHash(config) {
+    const stable = JSON.stringify({
+        threshold: config.threshold,
+        ruleThresholds: Object.fromEntries(Object.entries(config.ruleThresholds ?? {}).sort(([a], [b]) => (a < b ? -1 : 1))),
+        criticalRules: [...(config.criticalRules ?? [])].sort(),
+        nonCriticalRules: [...(config.nonCriticalRules ?? [])].sort(),
+    });
+    return createHash('sha256').update(stable).digest('hex').slice(0, 16);
+}
+export function buildProvenance(input) {
+    return {
+        irisVersion: input.irisVersion,
+        rulesetHash: input.rulesetHash,
+        configHash: input.configHash,
+        thresholds: { default: input.threshold, ...(input.ruleThresholds ? { perRule: input.ruleThresholds } : {}) },
+        corpusVersion: publishedProvenance().corpusVersion,
+        judgedAt: input.judgedAt,
+    };
+}

package/dist/index.js

@@ -6,6 +6,7 @@ import { PKG_VERSION } from './config/defaults.js';
 import { createStorage } from './storage/index.js';
 import { withDemoIngestGuard } from './storage/demo-guard.js';
 import { createIrisServer } from './server.js';
+import { runRetentionSweep, scheduleRetentionSweep } from './retention.js';
 import { createStdioTransport } from './transport/stdio.js';
 import { createHttpTransport } from './transport/http.js';
 import { createDashboardServer } from './dashboard/server.js';
@@ -290,34 +291,10 @@ async function main() {
         logger.info(`Loaded ${enabled.length} deployed custom rule(s) from ${customRuleStore.pathFor(LOCAL_TENANT)}`);
     }
     const httpServers = [];
-    // Run data retention cleanup on startup.
-    //
-    // For OSS single-tenant installs we explicitly scope cleanup to
-    // LOCAL_TENANT. Cloud will enumerate all tenants (TenantRegistry) and
-    // call this per-tenant so retention applies uniformly; the adapter
-    // method already scopes DELETEs by tenant, so the behavior scales
-    // cleanly.
-    if (config.retention.days > 0) {
-        try {
-            const deletedTraces = await storage.deleteTracesOlderThan(LOCAL_TENANT, config.retention.days);
-            /*
-             * Evaluations too (#372). Deleting a trace only NULLs trace_id on
-             * its evaluations, so every eval row — output_text verbatim,
-             * including whatever no_pii flagged — used to outlive the retention
-             * window indefinitely while the traces around it were swept.
-             */
-            const deletedEvals = await storage.deleteEvalResultsOlderThan(LOCAL_TENANT, config.retention.days);
-            if (deletedTraces + deletedEvals > 0) {
-                // Fold the WAL into the main file and truncate it, so the swept
-                // rows do not survive as readable text in iris.db-wal.
-                await storage.checkpoint();
-                logger.info(`Retention cleanup: deleted ${deletedTraces} trace(s) and ${deletedEvals} evaluation(s) older than ${config.retention.days} days`);
-            }
-        }
-        catch (err) {
-            logger.warn(`Retention cleanup skipped: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
+    // Retention: one sweep at boot and the same sweep on a timer that never
+    // holds the process open (src/retention.ts).
+    await runRetentionSweep(storage, config, logger);
+    scheduleRetentionSweep(storage, config, logger);
     if (config.transport.type === 'http') {
         const { transport, httpServer } = await createHttpTransport(mcpServer, config, logger);
         httpServers.push(httpServer);

package/dist/instructions.d.ts

@@ -0,0 +1,17 @@
+import type { JudgeState } from './judge-enablement.js';
+export declare const INSTRUCTIONS_MAX_CHARS = 2600;
+export interface InstructionsInput {
+    ruleCount: number;
+    categories: readonly string[];
+    threshold: number;
+    critical: readonly string[];
+    judge: JudgeState;
+}
+export declare function buildInstructions(i: InstructionsInput): string;
+export declare const EVALUATE_MY_AGENT_PROMPT = "evaluate-my-agent";
+/**
+ * The prompt a client shows as a slash command: a walk of log → evaluate →
+ * read → explain, in plain words, carrying the version so a cached copy
+ * cannot outlive a bump. Rendered from the same facts as the instructions.
+ */
+export declare function evaluateMyAgentPrompt(what: 'output' | 'trace-file', version: string): string;