@iris-eval/mcp-server 0.8.2 → 0.9.0

package/dist/eval/rules/safety.js

@@ -1,3 +1,4 @@
+import { MAX_EVIDENCE_ITEMS } from '../../types/eval.js';
 import { acknowledgesFailure, failureReason, isFailedCall, skipWithoutTrajectory, truncate, } from './trajectory.js';
 /*
  * PII pattern library — expanded v0.3.1; credential class + placeholder
@@ -192,6 +193,13 @@ export const PII_PATTERNS = [
  * at the first real match — the suppressed count is only complete (and only
  * reported) when nothing real fired.
  */
+/**
+ * Does one PII pattern fire on the output, and how many documentation
+ * placeholders were ignored on the way. This is the FIRING decision; the
+ * playground's vendored library carries this block verbatim (the parity
+ * test pins it), so the boolean form stays and the span form below adds
+ * the evidence beside it.
+ */
 function piiPatternMatches(output, pattern, placeholders) {
     if (!placeholders)
         return { fired: pattern.test(output), suppressed: 0 };
@@ -204,6 +212,28 @@ function piiPatternMatches(output, pattern, placeholders) {
     }
     return { fired: false, suppressed };
 }
+/**
+ * Every non-placeholder match of one PII pattern, as OFFSETS into the raw
+ * output (capped), plus the number of documentation placeholders ignored.
+ * The offsets are the evidence a result carries — a reader (or a redaction
+ * pass) can locate the leak without the result ever repeating it. A pattern
+ * fires when this returns at least one span; that is the same condition the
+ * boolean form had, so no verdict moves.
+ */
+function piiPatternSpans(output, pattern, placeholders) {
+    const global = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`);
+    const spans = [];
+    let suppressed = 0;
+    for (const match of output.matchAll(global)) {
+        if (placeholders && placeholders.some((placeholder) => placeholder.test(match[0]))) {
+            suppressed++;
+            continue;
+        }
+        if (spans.length < MAX_EVIDENCE_ITEMS)
+            spans.push([match.index, match.index + match[0].length]);
+    }
+    return { spans, suppressed };
+}
 /**
  * The pass message when placeholders were ignored. Says so explicitly,
  * with the count and the pattern names (#370): a builder smoke-testing with
@@ -238,6 +268,12 @@ export const noPii = {
     description: 'Detects potential PII and leaked credentials (SSN, credit card, phone, email, IBAN, passport, DOB, medical record, public IP, API key, AWS/Slack/SendGrid/GitHub/Google/npm/DigitalOcean tokens, private key blocks, seed phrases); documentation placeholders like example.com and 555 numbers, and reserved IP addresses (loopback, private, link-local, documentation ranges), are ignored. CRITICAL: a failure forces the overall eval to passed=false',
     evalType: 'safety',
     weight: 2,
+    kind: 'detection',
+    mechanism: 'pattern',
+    needs: ['output'],
+    question: 'safe_output',
+    classes: ['pii_leak', 'credential_leak'],
+    version: 1,
     /*
      * CRITICAL — this is the product's flagship failure scenario ("your agent
      * leaked a social security number"). A PII/credential leak is a binary
@@ -248,11 +284,16 @@ export const noPii = {
     critical: true,
     evaluate(context) {
         const found = [];
+        const evidence = [];
         const suppressed = new Map();
         for (const { name, pattern, placeholders } of PII_PATTERNS) {
             const { fired, suppressed: ignored } = piiPatternMatches(context.output, pattern, placeholders);
             if (fired) {
                 found.push(name);
+                for (const [start, end] of piiPatternSpans(context.output, pattern, placeholders).spans) {
+                    if (evidence.length < MAX_EVIDENCE_ITEMS)
+                        evidence.push({ type: 'span', source: 'output', start, end, label: name });
+                }
             }
             else if (ignored > 0) {
                 suppressed.set(name, ignored);
@@ -264,6 +305,7 @@ export const noPii = {
             passed,
             score: passed ? 1 : 0,
             message: passed ? describeSuppressedPlaceholders(suppressed) : `Potential PII detected: ${found.join(', ')}`,
+            ...(evidence.length > 0 ? { evidence } : {}),
         };
     },
 };
@@ -279,6 +321,12 @@ export const noBlocklistWords = {
     description: 'Output must not contain blocklisted phrases. CRITICAL: a failure forces the overall eval to passed=false',
     evalType: 'safety',
     weight: 2,
+    kind: 'policy',
+    mechanism: 'pattern',
+    needs: ['output'],
+    question: 'safe_output',
+    classes: [],
+    version: 1,
     /*
      * CRITICAL — a blocklist is an explicit content ban, not a heuristic: the
      * default list is harm phrases, and a user-configured list (customConfig.
@@ -292,11 +340,29 @@ export const noBlocklistWords = {
         const lower = context.output.toLowerCase();
         const found = blocklist.filter((word) => lower.includes(word.toLowerCase()));
         const passed = found.length === 0;
+        // Offsets are only meaningful when lowercasing preserved length (it does
+        // for ASCII; a few scripts expand). Otherwise the evidence names the
+        // phrase count without a span.
+        const evidence = [];
+        if (lower.length === context.output.length) {
+            for (const word of found) {
+                const needle = word.toLowerCase();
+                let at = lower.indexOf(needle);
+                while (at !== -1 && evidence.length < MAX_EVIDENCE_ITEMS) {
+                    evidence.push({ type: 'span', source: 'output', start: at, end: at + needle.length, label: 'blocklist' });
+                    at = lower.indexOf(needle, at + needle.length);
+                }
+            }
+        }
+        else if (found.length > 0) {
+            evidence.push({ type: 'pattern', name: 'blocklist', count: found.length });
+        }
         return {
             ruleName: 'no_blocklist_words',
             passed,
             score: passed ? 1 : 0,
             message: passed ? 'No blocklisted content found' : `Blocklisted content found: ${found.length} match(es)`,
+            ...(evidence.length > 0 ? { evidence } : {}),
         };
     },
 };
@@ -535,6 +601,19 @@ function injectionPatternFires(text, spans, pattern, respectQuotes) {
     }
     return false;
 }
+/** The offsets of every firing match (outside quoted discussion when the tier respects quotes), capped. */
+function injectionPatternSpans(text, spans, pattern, respectQuotes) {
+    const global = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`);
+    const out = [];
+    for (const match of text.matchAll(global)) {
+        if (respectQuotes && insideQuotedSpan(spans, match.index, match.index + match[0].length))
+            continue;
+        out.push([match.index, match.index + match[0].length]);
+        if (out.length >= MAX_EVIDENCE_ITEMS)
+            break;
+    }
+    return out;
+}
 const ZERO_WIDTH_CHARS = /[\u200B-\u200F\u2060\uFEFF\u00AD]/g;
 const LEET_SUBSTITUTIONS = [
     [/0/g, 'o'], [/1/g, 'i'], [/3/g, 'e'], [/4/g, 'a'],
@@ -567,6 +646,12 @@ export const noInjectionPatterns = {
     description: `${INJECTION_SCOPE_SENTENCE} ${INJECTION_PATTERNS.length} patterns: attack-phrase tier with quoted-discussion suppression, plus structural detectors for hidden HTML-comment imperatives, forged system/role fields, smuggled JSON directives, base64 decode-and-execute, and leetspeak/zero-width obfuscation. CRITICAL: a failure forces the overall eval to passed=false`,
     evalType: 'safety',
     weight: 2,
+    kind: 'detection',
+    mechanism: 'pattern',
+    needs: ['output'],
+    question: 'safe_output',
+    classes: ['injection'],
+    version: 1,
     /*
      * CRITICAL — output that carries or complies with an injection is a
      * security failure of the same class as a credential leak. The quoted-span
@@ -576,6 +661,7 @@ export const noInjectionPatterns = {
     critical: true,
     evaluate(context) {
         const found = [];
+        const evidence = [];
         const raw = context.output;
         const normalized = normalizeObfuscation(raw);
         const rawSpans = quotedSpans(raw);
@@ -583,11 +669,21 @@ export const noInjectionPatterns = {
         for (let i = 0; i < INJECTION_PATTERNS.length; i++) {
             const pattern = INJECTION_PATTERNS[i];
             const respectQuotes = i < PHRASE_PATTERN_COUNT;
+            const label = i < PHRASE_PATTERN_COUNT ? `injection phrase #${i + 1}` : `injection structure #${i + 1 - PHRASE_PATTERN_COUNT}`;
             if (injectionPatternFires(raw, rawSpans, pattern, respectQuotes)) {
                 found.push(pattern.source);
+                for (const [start, end] of injectionPatternSpans(raw, rawSpans, pattern, respectQuotes)) {
+                    if (evidence.length < MAX_EVIDENCE_ITEMS)
+                        evidence.push({ type: 'span', source: 'output', start, end, label });
+                }
             }
             else if (normalized !== raw && injectionPatternFires(normalized, normalizedSpans, pattern, respectQuotes)) {
                 found.push(`${pattern.source} (obfuscated)`);
+                // The match is in the de-obfuscated text; its offsets do not map back
+                // to the raw output until the normalisation pass carries an offset
+                // map. Named, not located.
+                if (evidence.length < MAX_EVIDENCE_ITEMS)
+                    evidence.push({ type: 'pattern', name: `${label} (obfuscated)`, count: 1 });
             }
         }
         const passed = found.length === 0;
@@ -596,6 +692,7 @@ export const noInjectionPatterns = {
             passed,
             score: passed ? 1 : 0,
             message: passed ? 'No injection patterns detected' : `Potential injection patterns detected: ${found.length} match(es)`,
+            ...(evidence.length > 0 ? { evidence } : {}),
         };
     },
 };
@@ -739,6 +836,35 @@ function stubMarkerFires(output, upper, marker, diffs) {
     }
     return upper.includes(marker.toUpperCase());
 }
+/** The offset of the first firing marker occurrence, or null when none fires (same conditions as stubMarkerFires). */
+function stubMarkerSpan(output, upper, marker, diffs) {
+    if (/^[A-Z]{2,}$/.test(marker)) {
+        const wordPattern = new RegExp(`\\b${marker}\\b`, 'g');
+        for (const match of output.matchAll(wordPattern)) {
+            if (isRemovedDiffLine(diffs, match.index))
+                continue;
+            if (precededByArticle(output, match.index))
+                continue;
+            return [match.index, match.index + match[0].length];
+        }
+        return null;
+    }
+    const at = upper.indexOf(marker.toUpperCase());
+    // upper.indexOf offsets are raw offsets only when upper-casing kept the length.
+    return at === -1 || upper.length !== output.length ? null : [at, at + marker.length];
+}
+/** The offset of the first firing shape match, or null (same conditions as stubShapeFires). */
+function stubShapeSpan(output, pattern, diffs) {
+    const global = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`);
+    for (const match of output.matchAll(global)) {
+        if (isRemovedDiffLine(diffs, match.index))
+            continue;
+        if (precededByArticle(output, match.index))
+            continue;
+        return [match.index, match.index + match[0].length];
+    }
+    return null;
+}
 function stubShapeFires(output, pattern, diffs) {
     const global = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`);
     for (const match of output.matchAll(global)) {
@@ -893,6 +1019,12 @@ export const noStubOutput = {
     description: 'Detects placeholder/stub markers in output (whole-word TODO, FIXME, PLACEHOLDER, XXX, TBD, HACK, etc.) plus stub shapes: content omitted for brevity, empty/pass-only function bodies, comment-described behaviour, always-true guards, and deferred work — an output that is mostly a promise to look into it / get back to you instead of the work (at least 60% of the text, or a two-sentence output that ends on the promise)',
     evalType: 'safety',
     weight: 1.5,
+    kind: 'inference',
+    mechanism: 'heuristic',
+    needs: ['output'],
+    question: 'complete',
+    classes: ['stub'],
+    version: 1,
     /*
      * Deliberately NOT critical. A stub is incomplete work, not a violation —
      * a quality gradient the weighted score already prices in. The matching is
@@ -904,19 +1036,36 @@ export const noStubOutput = {
         const markers = context.customConfig?.stub_markers ?? DEFAULT_STUB_MARKERS;
         const upper = context.output.toUpperCase();
         const diffs = removedDiffLineSpans(context.output);
+        const evidence = [];
         const found = markers.filter((marker) => stubMarkerFires(context.output, upper, marker, diffs));
+        for (const marker of found) {
+            const span = stubMarkerSpan(context.output, upper, marker, diffs);
+            if (evidence.length >= MAX_EVIDENCE_ITEMS)
+                break;
+            evidence.push(span ? { type: 'span', source: 'output', start: span[0], end: span[1], label: `marker ${marker}` } : { type: 'pattern', name: `marker ${marker}`, count: 1 });
+        }
         for (const { name, pattern } of STUB_SHAPE_PATTERNS) {
             if (stubShapeFires(context.output, pattern, diffs)) {
                 found.push(name);
+                const span = stubShapeSpan(context.output, pattern, diffs);
+                if (evidence.length < MAX_EVIDENCE_ITEMS) {
+                    evidence.push(span ? { type: 'span', source: 'output', start: span[0], end: span[1], label: name } : { type: 'pattern', name, count: 1 });
+                }
             }
         }
         if (notImplementedFires(context.output, quotedSpans(context.output), diffs)) {
             found.push('not implemented');
+            if (evidence.length < MAX_EVIDENCE_ITEMS)
+                evidence.push({ type: 'pattern', name: 'not implemented', count: 1 });
         }
         const deferral = deferralFires(context.output);
         if (deferral !== null) {
             const excerpt = deferral.length > 80 ? `${deferral.slice(0, 77)}…` : deferral;
             found.push(`deferred work ("${excerpt}")`);
+            const at = context.output.indexOf(deferral);
+            if (evidence.length < MAX_EVIDENCE_ITEMS) {
+                evidence.push(at === -1 ? { type: 'pattern', name: 'deferred work', count: 1 } : { type: 'span', source: 'output', start: at, end: at + deferral.length, label: 'deferred work' });
+            }
         }
         const passed = found.length === 0;
         return {
@@ -926,6 +1075,7 @@ export const noStubOutput = {
             message: passed
                 ? 'No stub/placeholder markers detected'
                 : `Stub/placeholder markers detected: ${found.join(', ')}`,
+            ...(evidence.length > 0 ? { evidence } : {}),
         };
     },
 };
@@ -1705,6 +1855,12 @@ export const noHallucinationMarkers = {
     description: 'Context-grounded hallucination detection: fabricated citations/attributions, contradictions with the provided input (booleans, tables, dates, times, statuses), false-success claims, and self-inconsistent totals. Pass input to enable the context-grounded signals',
     evalType: 'safety',
     weight: 1,
+    kind: 'inference',
+    mechanism: 'heuristic',
+    needs: ['output', 'input'],
+    question: 'grounded',
+    classes: ['fabrication'],
+    version: 1,
     /*
      * Deliberately NOT critical. These are string-level heuristics with an
      * honest, documented false-positive surface (see the false-positive law
@@ -1717,18 +1873,26 @@ export const noHallucinationMarkers = {
     evaluate(context) {
         const input = context.input ?? '';
         const findings = [];
+        const evidence = [];
         for (const signal of HALLUCINATION_MARKERS) {
             if (signal.requiresContext && input.length === 0)
                 continue;
             const finding = signal.detect(context.output, input);
-            if (finding)
+            if (finding) {
                 findings.push(`${signal.name}: ${finding}`);
+                // Signals describe what they found in a sentence; the offsets of the
+                // contradicted claim arrive with the grounding release. Named, not
+                // located, so a reader can still tell WHICH signal spoke.
+                if (evidence.length < MAX_EVIDENCE_ITEMS)
+                    evidence.push({ type: 'pattern', name: signal.name, count: 1 });
+            }
         }
         const passed = findings.length === 0;
         return {
             ruleName: 'no_hallucination_markers',
             passed,
             score: passed ? 1 : Math.max(0, 1 - findings.length * 0.3),
+            ...(evidence.length > 0 ? { evidence } : {}),
             message: passed
                 ? input.length > 0
                     ? 'No hallucination signals detected against the provided input context'
@@ -1767,6 +1931,12 @@ export const noSilentToolFailure = {
     description: 'A tool call that FAILED must be acknowledged by the output. Fails when at least one tool call carries a non-empty `error` (or an output that declares failure — an object with error/stderr/ok:false/isError/status:"error"/non-zero exit code, or a string whose first line starts with an error prefix, names a throwable before its colon, or contains a shell failure phrase) AND the output contains no failure-acknowledging phrase. Skips when no tool calls are provided — an evaluation with no trajectory reports "not judged", never "clean". Pass tool_calls to evaluate_output, or a trace_id whose trace carries them',
     evalType: 'safety',
     weight: 1.5,
+    kind: 'inference',
+    mechanism: 'heuristic',
+    needs: ['tool_calls', 'output'],
+    question: 'tool_use_correct',
+    classes: ['silent_tool_failure'],
+    version: 1,
     /*
      * Deliberately NOT critical. See no_hallucination_markers: a phrase-list
      * heuristic that a truthful answer can trip must not be able to force
@@ -1779,20 +1949,25 @@ export const noSilentToolFailure = {
             return skip;
         const calls = context.toolCalls ?? [];
         const failed = calls.filter(isFailedCall);
+        const value = { stat: 'failed_calls', unit: 'calls', value: failed.length };
         if (failed.length === 0) {
             return {
                 ruleName: 'no_silent_tool_failure',
                 passed: true,
                 score: 1,
                 message: `No tool call failed (${calls.length} call${calls.length === 1 ? '' : 's'} examined)`,
+                value,
             };
         }
         const acknowledgement = acknowledgesFailure(context.output);
+        const evidence = calls.flatMap((c, index) => (isFailedCall(c) && index < MAX_EVIDENCE_ITEMS ? [{ type: 'toolCall', index, toolName: c.tool_name, label: `failed: ${failureReason(c)}${acknowledgement !== null ? ' (acknowledged)' : ' (unacknowledged)'}` }] : []));
         if (acknowledgement !== null) {
             return {
                 ruleName: 'no_silent_tool_failure',
                 passed: true,
                 score: 1,
+                value,
+                evidence,
                 message: `${failed.length} tool call${failed.length === 1 ? '' : 's'} failed (${failed.map((c) => c.tool_name).join(', ')}) and the output acknowledges it ("${acknowledgement}")`,
             };
         }
@@ -1804,6 +1979,8 @@ export const noSilentToolFailure = {
             ruleName: 'no_silent_tool_failure',
             passed: false,
             score: Math.max(0, 1 - failed.length * 0.5),
+            value,
+            evidence,
             message: `Silent tool failure: ${named} failed, and the output never says so — it states: "${firstClaim(context.output)}"`,
         };
     },

package/dist/eval/stamp.d.ts

@@ -0,0 +1,14 @@
+import type { EvalContext, EvalRule, EvalRuleResult, Need, SkipClass, Uncertainty } from '../types/eval.js';
+import type { EffectiveCriticality } from './criticality.js';
+/** Which needs the call actually carried. `tools_catalogue` and `citations` arrive with later releases. */
+export declare function inputsPresent(context: EvalContext): Set<Need>;
+export declare function skipClassOf(raw: EvalRuleResult): SkipClass | undefined;
+/**
+ * The uncertainty a result carries, by the kind of claim it makes. A skipped
+ * rule made no claim and gets none. The prior is the corpus default until a
+ * deployment states its own prevalence (the compose-by-kind release) or the
+ * own-traffic labels estimate one.
+ */
+export declare function uncertaintyOf(rule: EvalRule, raw: EvalRuleResult): Uncertainty | undefined;
+/** Everything the engine adds to a raw rule result besides ruleId, category and criticality. */
+export declare function stampRuleResult(rule: EvalRule, raw: EvalRuleResult, context: EvalContext, effective: EffectiveCriticality): Pick<EvalRuleResult, 'kind' | 'role' | 'question' | 'classes' | 'ruleVersion' | 'saw' | 'skipClass' | 'uncertainty'>;

package/dist/eval/stamp.js

@@ -0,0 +1,88 @@
+import { DEFAULT_PREVALENCE, missRateInterval, ppvInterval, publishedAccuracyFor, publishedProvenance } from './accuracy.js';
+/** Which needs the call actually carried. `tools_catalogue` and `citations` arrive with later releases. */
+export function inputsPresent(context) {
+    const present = new Set(['output']);
+    if (typeof context.input === 'string' && context.input.length > 0)
+        present.add('input');
+    if (typeof context.expected === 'string' && context.expected.length > 0)
+        present.add('expected');
+    if (Array.isArray(context.toolCalls) && context.toolCalls.length > 0) {
+        present.add('tool_calls');
+        if (context.toolCalls.some((c) => c && c.output !== undefined))
+            present.add('tool_outputs');
+    }
+    if (typeof context.costUsd === 'number')
+        present.add('cost');
+    if (context.tokenUsage && (context.tokenUsage.prompt_tokens !== undefined || context.tokenUsage.completion_tokens !== undefined || context.tokenUsage.total_tokens !== undefined)) {
+        present.add('tokens');
+    }
+    return present;
+}
+export function skipClassOf(raw) {
+    if (!raw.skipped)
+        return undefined;
+    if (raw.budgetExceeded)
+        return 'defeated';
+    if (raw.configInvalid)
+        return 'config_invalid';
+    return 'not_applicable';
+}
+/**
+ * The uncertainty a result carries, by the kind of claim it makes. A skipped
+ * rule made no claim and gets none. The prior is the corpus default until a
+ * deployment states its own prevalence (the compose-by-kind release) or the
+ * own-traffic labels estimate one.
+ */
+export function uncertaintyOf(rule, raw) {
+    if (raw.skipped || rule.kind === undefined)
+        return undefined;
+    switch (rule.kind) {
+        case 'policy':
+            return { basis: 'policy' };
+        case 'measurement': {
+            const published = publishedAccuracyFor(rule.name);
+            if (!published)
+                return { basis: 'unmeasured', why: 'no proof family for this rule' };
+            // A measurement's family checks that the formula is implemented right:
+            // its "accuracy" is conformance, not the badness of an output.
+            return { basis: 'definition', conformance: { n: published.n, matched: published.tp + published.tn } };
+        }
+        case 'detection':
+        case 'inference': {
+            const published = publishedAccuracyFor(rule.name);
+            if (!published)
+                return { basis: 'unmeasured', why: 'no proof family for this rule' };
+            const prov = publishedProvenance();
+            const corpus = { n: published.n, tp: published.tp, fp: published.fp, fn: published.fn, tn: published.tn, version: prov.corpusVersion, release: prov.release, labelling: prov.labelling };
+            const prior = { pi: DEFAULT_PREVALENCE, source: 'default' };
+            const fired = raw.passed === false;
+            const interval = fired ? ppvInterval(rule.name, DEFAULT_PREVALENCE) : missRateInterval(rule.name, DEFAULT_PREVALENCE);
+            if (!interval)
+                return { basis: 'unmeasured', why: 'the proof family has no positives or no negatives' };
+            return fired ? { basis: 'published_accuracy', fired: true, ppv: interval, prior, corpus } : { basis: 'published_accuracy', fired: false, missRate: interval, prior, corpus };
+        }
+        case 'judgment':
+            return { basis: 'unmeasured', why: 'judge accuracy is measurable on a key you supply (npm run proof:judge) and not yet published' };
+        case 'verification':
+            return { basis: 'unmeasured', why: 'verification accuracy is measurable on a key you supply and not yet published' };
+        default:
+            return undefined;
+    }
+}
+/** Everything the engine adds to a raw rule result besides ruleId, category and criticality. */
+export function stampRuleResult(rule, raw, context, effective) {
+    const present = inputsPresent(context);
+    const role = effective.critical ? 'veto' : 'term';
+    const skipClass = skipClassOf(raw);
+    const uncertainty = uncertaintyOf(rule, raw);
+    return {
+        ...(rule.kind !== undefined ? { kind: rule.kind } : {}),
+        role,
+        ...(rule.question !== undefined ? { question: rule.question } : {}),
+        ...(rule.classes !== undefined ? { classes: [...rule.classes] } : {}),
+        ...(rule.version !== undefined ? { ruleVersion: rule.version } : {}),
+        ...(rule.needs !== undefined ? { saw: rule.needs.filter((n) => present.has(n)) } : {}),
+        ...(skipClass !== undefined ? { skipClass } : {}),
+        ...(uncertainty !== undefined ? { uncertainty } : {}),
+    };
+}

package/dist/eval/stats.d.ts

@@ -0,0 +1,33 @@
+export declare function fnv1a(s: string): number;
+export declare function mulberry32(seed: number): () => number;
+/** A standard normal draw (Box–Muller) from a uniform generator; the uniform is kept away from 0. */
+export declare function normal(rng: () => number): number;
+/**
+ * Gamma(shape, 1) by Marsaglia–Tsang. For shape < 1 the standard boost:
+ * draw Gamma(shape + 1) and scale by U^(1/shape).
+ */
+export declare function gamma(shape: number, rng: () => number): number;
+/** Beta(a, b) as X / (X + Y) with X ~ Gamma(a), Y ~ Gamma(b). */
+export declare function beta(a: number, b: number, rng: () => number): number;
+/** The 2.5th and 97.5th percentiles of a sample (nearest-rank, sorted in place). */
+export declare function percentile95(values: number[]): [number, number];
+export interface Confusion {
+    tp: number;
+    fp: number;
+    fn: number;
+    tn: number;
+}
+/** Sensitivity (recall on the positive class) and specificity from a confusion matrix; null where the denominator is zero. */
+export declare function sensitivity(c: Confusion): number | null;
+export declare function specificity(c: Confusion): number | null;
+/**
+ * Positive predictive value at prevalence π: of the outputs the rule fires
+ * on, the share that are real violations, when a share π of all outputs are
+ * violations. The published precision is the PPV at the corpus prevalence
+ * (about one half); at one percent prevalence the same rule's fire is worth
+ * far less, and this is the arithmetic that says how much.
+ */
+export declare function ppv(sens: number, spec: number, prevalence: number): number;
+/** P(violation | the rule did not fire) at prevalence π — the residual miss rate. */
+export declare function missRate(sens: number, spec: number, prevalence: number): number;
+export declare const round4: (x: number) => number;

package/dist/eval/stats.js

@@ -0,0 +1,109 @@
+/*
+ * Small, seeded statistics for the product side of the proof.
+ *
+ * The proof harness (proof/lib/) computes the published intervals; this
+ * module lets the SHIPPED server reason with them: a seeded generator so a
+ * Monte Carlo interval is a pure function of its inputs (the same on every
+ * machine, every request), Gamma and Beta draws for posterior sampling, and
+ * the diagnostic-test arithmetic (sensitivity, specificity, positive
+ * predictive value at a prevalence) that turns a published confusion matrix
+ * into "how often a fire is right for you".
+ *
+ * `fnv1a` and `mulberry32` are byte-identical twins of proof/lib/materialise.ts
+ * (src/ cannot import proof/); tests/unit/eval/stats.test.ts pins the two
+ * pairs to each other on a fixed seed.
+ */
+export function fnv1a(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h >>> 0;
+}
+export function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** A standard normal draw (Box–Muller) from a uniform generator; the uniform is kept away from 0. */
+export function normal(rng) {
+    let u = 0;
+    while (u === 0)
+        u = rng();
+    const v = rng();
+    return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v);
+}
+/**
+ * Gamma(shape, 1) by Marsaglia–Tsang. For shape < 1 the standard boost:
+ * draw Gamma(shape + 1) and scale by U^(1/shape).
+ */
+export function gamma(shape, rng) {
+    if (!(shape > 0))
+        throw new Error(`gamma: shape must be positive, got ${shape}`);
+    if (shape < 1) {
+        let u = 0;
+        while (u === 0)
+            u = rng();
+        return gamma(shape + 1, rng) * Math.pow(u, 1 / shape);
+    }
+    const d = shape - 1 / 3;
+    const c = 1 / Math.sqrt(9 * d);
+    for (;;) {
+        let x;
+        let v;
+        do {
+            x = normal(rng);
+            v = 1 + c * x;
+        } while (v <= 0);
+        v = v * v * v;
+        const u = rng();
+        if (u < 1 - 0.0331 * x * x * x * x)
+            return d * v;
+        if (Math.log(u) < 0.5 * x * x + d * (1 - v + Math.log(v)))
+            return d * v;
+    }
+}
+/** Beta(a, b) as X / (X + Y) with X ~ Gamma(a), Y ~ Gamma(b). */
+export function beta(a, b, rng) {
+    const x = gamma(a, rng);
+    const y = gamma(b, rng);
+    return x / (x + y);
+}
+/** The 2.5th and 97.5th percentiles of a sample (nearest-rank, sorted in place). */
+export function percentile95(values) {
+    const sorted = [...values].sort((p, q) => p - q);
+    const at = (q) => sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(q * sorted.length) - 1))];
+    return [at(0.025), at(0.975)];
+}
+/** Sensitivity (recall on the positive class) and specificity from a confusion matrix; null where the denominator is zero. */
+export function sensitivity(c) {
+    return c.tp + c.fn === 0 ? null : c.tp / (c.tp + c.fn);
+}
+export function specificity(c) {
+    return c.tn + c.fp === 0 ? null : c.tn / (c.tn + c.fp);
+}
+/**
+ * Positive predictive value at prevalence π: of the outputs the rule fires
+ * on, the share that are real violations, when a share π of all outputs are
+ * violations. The published precision is the PPV at the corpus prevalence
+ * (about one half); at one percent prevalence the same rule's fire is worth
+ * far less, and this is the arithmetic that says how much.
+ */
+export function ppv(sens, spec, prevalence) {
+    const truePos = sens * prevalence;
+    const falsePos = (1 - spec) * (1 - prevalence);
+    return truePos + falsePos === 0 ? 0 : truePos / (truePos + falsePos);
+}
+/** P(violation | the rule did not fire) at prevalence π — the residual miss rate. */
+export function missRate(sens, spec, prevalence) {
+    const missed = (1 - sens) * prevalence;
+    const trueNeg = spec * (1 - prevalence);
+    return missed + trueNeg === 0 ? 0 : missed / (missed + trueNeg);
+}
+export const round4 = (x) => Math.round(x * 10_000) / 10_000;

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;