@iris-eval/mcp-server 0.8.2 → 0.9.0

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;

package/dist/instructions.js

@@ -0,0 +1,53 @@
+import { JUDGE_KEY_VARS, judgeStateLine } from './judge-enablement.js';
+export const INSTRUCTIONS_MAX_CHARS = 2600;
+function prose(items) {
+    if (items.length <= 1)
+        return items.join('');
+    return `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+}
+export function buildInstructions(i) {
+    const judgeHowTo = i.judge.enabled
+        ? 'They spend your key, never a shared one; the cap is refused before any spend.'
+        : `To enable them, put your own ${JUDGE_KEY_VARS.anthropic} or ${JUDGE_KEY_VARS.openai} in the env block of the iris-eval entry in your MCP client config and restart the session; iris://capabilities carries the full steps.`;
+    const critical = i.critical.length > 0 ? i.critical.join(', ') : 'none';
+    const text = [
+        'Iris evaluates what an AI agent wrote and what it did. It runs locally, stores traces and verdicts in SQLite, and sends nothing anywhere unless you enable the judge.',
+        `Three verbs. LOG an execution with log_trace (input, output, tool_calls, cost). EVALUATE with evaluate_output: ${i.ruleCount} deterministic rules in ${prose(i.categories)}. ` +
+            'Pass input so the relevance and hallucination rules can judge; pass tool_calls or a trace_id so the trajectory rules can judge; pass cost_usd so the cost rules can judge. ' +
+            'A rule with nothing to judge SKIPS and is named; it is never counted as a pass. INSPECT with get_traces and list_rules, or read a resource.',
+        `Reading a verdict. passed is the ship verdict: true only when score clears the threshold (${i.threshold} on this server) AND no critical rule failed. ` +
+            'verdict.basis says which layer decided (policy_gate, detector_veto, score_below_threshold, clean, or no_rules when nothing could be judged) and verdict.by names the rules. ' +
+            `Critical on this server: ${critical} (configurable; list_rules shows the effective value). ` +
+            'coverage says which evaluation questions were judged and why the others were not. A critical rule that could not judge is named in critical_skipped: treat that as UNKNOWN, not clean. ' +
+            'score is a quality gradient over the rules that ran; never read it alone as a safety signal.',
+        `The LLM judge (evaluate_with_llm_judge) and the citation verifier (verify_citations) are ${judgeStateLine(i.judge)}. ${judgeHowTo}`,
+        'Resources: iris://capabilities (what this server can judge, what each rule needs, judge state, limits), iris://proof (measured precision and recall per rule with 95% intervals), ' +
+            'iris://traces/{trace_id}, iris://evaluations/{id}, iris://dashboard/summary. Responses link what they created.',
+        'Do not use Iris to validate arbitrary JSON Schema, to screen inputs before they reach an agent (the injection rule reads output), or for semantic judgment without a key.',
+        'Errors from a tool return {"error":{"code","message","recovery":[]}} with isError true; follow recovery before retrying. ' +
+            'An argument the schema rejects comes back as plain text naming IRIS_INVALID_ARGUMENT and the valid arguments.',
+    ].join('\n\n');
+    if (text.length > INSTRUCTIONS_MAX_CHARS) {
+        throw new Error(`instructions are ${text.length} characters; the ceiling is ${INSTRUCTIONS_MAX_CHARS}`);
+    }
+    return text;
+}
+export 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 function evaluateMyAgentPrompt(what, version) {
+    const source = what === 'trace-file'
+        ? 'Read the trace file I point you at (a JSON object or array with input, output and tool_calls per run).'
+        : 'Take the agent output I give you, with the input that produced it and the tool calls if I have them.';
+    return [
+        `Evaluate my agent with Iris ${version}. Do these steps and report in plain words.`,
+        `1. ${source}`,
+        '2. Log each run with log_trace, then evaluate it with evaluate_output, passing input, tool_calls (or the trace_id) and cost_usd whenever you have them so the relevance, trajectory and cost rules can judge.',
+        '3. Read the verdict: passed is the ship verdict; verdict.basis and verdict.by say which rule decided; coverage says what was not judged and why; critical_skipped means UNKNOWN, not clean.',
+        '4. For anything that failed, follow the resource link to iris://evaluations/{id} and quote the rule, its message and its evidence (offsets into my output, never a paraphrase of what the rule matched).',
+        '5. Tell me: what passed, what failed and why, what was not judged and what input would let Iris judge it. If I ask for a semantic judgment and the judge is not enabled, give me the recovery steps from the error instead of searching for them.',
+    ].join('\n');
+}

package/dist/judge-enablement.d.ts

@@ -0,0 +1,34 @@
+export type JudgeProvider = 'anthropic' | 'openai';
+export declare const JUDGE_KEY_VARS: Readonly<Record<JudgeProvider, string>>;
+export declare const JUDGE_COST_CAP_VAR = "IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL";
+export declare const JUDGE_DEFAULT_COST_CAP_USD = 0.25;
+export interface JudgeState {
+    /** A key for at least one provider is present in this process's environment. */
+    enabled: boolean;
+    /** The provider Iris would pick when a call names no provider: the first one with a key. */
+    provider: JudgeProvider | null;
+    /** Every provider with a key present. */
+    providers: JudgeProvider[];
+    /** The per-call spend cap the judge refuses beyond, before any spend. */
+    costCapUsd: number;
+}
+/** The per-call cap from the environment, else the shipped default. */
+export declare function judgeCostCapUsd(): number;
+export declare function judgeState(): JudgeState;
+export declare const JUDGE_ENABLE_TITLE: string;
+/**
+ * The enable workflow, one step per entry, from judge-enablement.json.
+ * Rendered verbatim into the IRIS_JUDGE_NOT_ENABLED error's `recovery`,
+ * the capabilities resource's `howToEnable`, and (through the truthbase)
+ * the README, the judge doc and the skill files. Change the JSON and
+ * nowhere else.
+ */
+export declare const JUDGE_ENABLE_STEPS: readonly string[];
+/** The block as prose: the title in bold, then the numbered steps — the exact form every surface carries. */
+export declare function judgeEnableBlock(): string;
+/** Shared with scripts/claims/render-llms.mjs, which renders the same shape from .claims.json. */
+export declare function renderJudgeEnableBlock(title: string, steps: readonly string[]): string;
+/** The steps as an error's `recovery[]`, with the variable the call needed named first. */
+export declare function judgeRecovery(provider: JudgeProvider): string[];
+/** One line for the instructions and the self-test: what this process can see. */
+export declare function judgeStateLine(state: JudgeState): string;

package/dist/judge-enablement.js

@@ -0,0 +1,78 @@
+/*
+ * The judge is a user-keyed feature (founder ruling, 2026-09-04): an end
+ * user enables it by supplying their own provider key, and every surface
+ * that mentions it has to say so in the same words — the error a tool
+ * returns without a key, the capabilities resource, the server
+ * instructions, the self-test, the README and the docs. The words live
+ * once, in judge-enablement.json beside this file: the runtime imports
+ * it, the truthbase generator copies it into .claims.json, the skill files
+ * render it as a slot, and tests/judge-enablement-surfaces.test.ts asserts
+ * the README and the judge doc carry the same block verbatim.
+ *
+ * What "enabled" means: a key for at least one provider reached THIS
+ * process's environment. That is the only fact Iris can check, and it is
+ * the fact users get wrong — a key exported in a shell is not passed to
+ * the child process an MCP client spawns unless the client's config says
+ * so. Step 2 exists because of that.
+ */
+import enable from './judge-enablement.json' with { type: 'json' };
+export const JUDGE_KEY_VARS = {
+    anthropic: 'IRIS_ANTHROPIC_API_KEY',
+    openai: 'IRIS_OPENAI_API_KEY',
+};
+export const JUDGE_COST_CAP_VAR = 'IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL';
+export const JUDGE_DEFAULT_COST_CAP_USD = 0.25;
+/** The per-call cap from the environment, else the shipped default. */
+export function judgeCostCapUsd() {
+    const raw = process.env.IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL;
+    if (raw) {
+        const parsed = Number(raw);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return JUDGE_DEFAULT_COST_CAP_USD;
+}
+export function judgeState() {
+    // Literal reads on purpose: the docs contract and the manifest parity
+    // test grep `process.env.IRIS_*` to learn what the server reads.
+    const present = {
+        anthropic: Boolean(process.env.IRIS_ANTHROPIC_API_KEY),
+        openai: Boolean(process.env.IRIS_OPENAI_API_KEY),
+    };
+    const providers = Object.keys(JUDGE_KEY_VARS).filter((p) => present[p]);
+    return {
+        enabled: providers.length > 0,
+        provider: providers[0] ?? null,
+        providers,
+        costCapUsd: judgeCostCapUsd(),
+    };
+}
+export const JUDGE_ENABLE_TITLE = enable.title;
+/**
+ * The enable workflow, one step per entry, from judge-enablement.json.
+ * Rendered verbatim into the IRIS_JUDGE_NOT_ENABLED error's `recovery`,
+ * the capabilities resource's `howToEnable`, and (through the truthbase)
+ * the README, the judge doc and the skill files. Change the JSON and
+ * nowhere else.
+ */
+export const JUDGE_ENABLE_STEPS = enable.steps;
+/** The block as prose: the title in bold, then the numbered steps — the exact form every surface carries. */
+export function judgeEnableBlock() {
+    return renderJudgeEnableBlock(JUDGE_ENABLE_TITLE, JUDGE_ENABLE_STEPS);
+}
+/** Shared with scripts/claims/render-llms.mjs, which renders the same shape from .claims.json. */
+export function renderJudgeEnableBlock(title, steps) {
+    return [`**${title}**`, ...steps.map((s, i) => `${i + 1}. ${s}`)].join('\n');
+}
+/** The steps as an error's `recovery[]`, with the variable the call needed named first. */
+export function judgeRecovery(provider) {
+    return [`Set ${JUDGE_KEY_VARS[provider]} for the process that runs Iris.`, ...JUDGE_ENABLE_STEPS];
+}
+/** One line for the instructions and the self-test: what this process can see. */
+export function judgeStateLine(state) {
+    if (state.enabled) {
+        const list = state.providers.join(' and ');
+        return `enabled (${list} key found in this process; each call is capped at ${state.costCapUsd} USD)`;
+    }
+    return `not enabled (no ${JUDGE_KEY_VARS.anthropic} or ${JUDGE_KEY_VARS.openai} reached this process)`;
+}

package/dist/judge-enablement.json

@@ -0,0 +1,10 @@
+{
+    "title": "Enable the LLM judge (optional; the deterministic rules never need it)",
+    "steps": [
+        "Get an API key from Anthropic or OpenAI.",
+        "Put it in the environment of the process that runs Iris, not only your shell. Claude Code, Claude Desktop, Cursor and most MCP clients: the \"env\" block of the iris-eval entry in your MCP config — \"iris-eval\": { \"command\": \"npx\", \"args\": [\"-y\", \"@iris-eval/mcp-server\"], \"env\": { \"IRIS_ANTHROPIC_API_KEY\": \"sk-ant-...\" } } (IRIS_OPENAI_API_KEY for an OpenAI key). Docker: -e IRIS_ANTHROPIC_API_KEY=... on the run command. HTTP or CI: export it before starting iris-mcp.",
+        "Restart the MCP session. A running process never sees a variable set after it started.",
+        "Confirm from inside your client: read iris://capabilities — judge.enabled must be true there. A key exported in your shell is not passed to the process your client spawns unless its config lists it. On a machine, `npx @iris-eval/mcp-server --self-test` prints the judge line for that shell, and GET /api/v1/health reports judge.enabled on a running dashboard.",
+        "Spend guard: each call is capped by IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL (default 0.25 USD) and refused before any spend if the worst case would exceed it. Iris calls the provider directly with your key and never proxies it."
+    ]
+}

package/dist/preferences.d.ts

@@ -22,9 +22,9 @@ export declare const PreferencesSchema: z.ZodObject<{
     firstSeen: z.ZodOptional<z.ZodString>;
     dismissedBanners: z.ZodDefault<z.ZodArray<z.ZodString>>;
     theme: z.ZodDefault<z.ZodEnum<{
+        system: "system";
         light: "light";
         dark: "dark";
-        system: "system";
     }>>;
     momentFilters: z.ZodDefault<z.ZodObject<{
         agentName: z.ZodOptional<z.ZodString>;

package/dist/prompts.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const PROMPT_NAMES: readonly ["evaluate-my-agent"];
+export declare function registerPrompts(server: McpServer, version: string): void;

package/dist/prompts.js

@@ -0,0 +1,29 @@
+/*
+ * The one prompt: `evaluate-my-agent`. A client that supports prompts
+ * shows it as a slash command; a client that does not never sees it, and
+ * nothing in the README depends on it. Rendered from the same facts as
+ * the server instructions (src/instructions.ts) and carrying the version,
+ * so a cached copy cannot outlive a bump.
+ */
+import { z } from 'zod';
+import { EVALUATE_MY_AGENT_PROMPT, evaluateMyAgentPrompt } from './instructions.js';
+export const PROMPT_NAMES = [EVALUATE_MY_AGENT_PROMPT];
+export function registerPrompts(server, version) {
+    server.registerPrompt(EVALUATE_MY_AGENT_PROMPT, {
+        title: 'Evaluate my agent',
+        description: 'A walk through logging an agent run, evaluating it and reading the verdict with Iris, in plain words.',
+        argsSchema: {
+            what: z
+                .string()
+                .optional()
+                .describe('"output" (default): you have an agent output to hand; "trace-file": you have a file of runs to evaluate'),
+        },
+    }, ({ what }) => ({
+        messages: [
+            {
+                role: 'user',
+                content: { type: 'text', text: evaluateMyAgentPrompt(what === 'trace-file' ? 'trace-file' : 'output', version) },
+            },
+        ],
+    }));
+}

package/dist/resources/index.d.ts

@@ -1,3 +1,6 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { IStorageAdapter } from '../types/query.js';
-export declare function registerAllResources(server: McpServer, storage: IStorageAdapter): void;
+import type { Capabilities } from '../capabilities.js';
+/** The MCP resource-not-found code (the spec reserves -32002 for it). */
+export declare const RESOURCE_NOT_FOUND = -32002;
+export declare function registerAllResources(server: McpServer, storage: IStorageAdapter, capabilities: () => Capabilities): void;

package/dist/resources/index.js

@@ -1,6 +1,66 @@
-import { registerDashboardSummaryResource } from './dashboard-summary.js';
-import { registerTraceDetailResource } from './trace-detail.js';
-export function registerAllResources(server, storage) {
-    registerDashboardSummaryResource(server, storage);
-    registerTraceDetailResource(server, storage);
+/*
+ * The resources, registered the way the SDK wants them: fixed URIs with
+ * registerResource, parameterised ones with a ResourceTemplate (so a
+ * client's resources/templates/list shows the shape, and the SDK parses
+ * the variable instead of the handler splitting a path). A resource that
+ * does not exist is the protocol's resource-not-found error, never a 200
+ * body with an "error" key a client would have to sniff for.
+ */
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpError } from '@modelcontextprotocol/sdk/types.js';
+import { ruleProof } from '../capabilities.js';
+import { publishedProvenance, publishedRuleNames } from '../eval/accuracy.js';
+import { toEvaluationResponse } from '../eval/response.js';
+import { LOCAL_TENANT } from '../types/tenant.js';
+import { CAPABILITIES_RESOURCE_URI, DASHBOARD_SUMMARY_RESOURCE_URI, EVALUATION_RESOURCE_TEMPLATE, PROOF_RESOURCE_URI, TRACE_RESOURCE_TEMPLATE, } from './uris.js';
+/** The MCP resource-not-found code (the spec reserves -32002 for it). */
+export const RESOURCE_NOT_FOUND = -32002;
+function notFound(uri, what) {
+    return new McpError(RESOURCE_NOT_FOUND, `Resource not found: ${uri} — no ${what} with that id is stored for this tenant`, { uri });
+}
+const json = (uri, body) => ({
+    contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(body, null, 2) }],
+});
+export function registerAllResources(server, storage, capabilities) {
+    server.registerResource('capabilities', CAPABILITIES_RESOURCE_URI, {
+        title: 'Capabilities',
+        description: 'What this server can judge: the rule roster with what each rule needs and its published accuracy, the judge state with the steps that enable it, the citation verifier posture, the dashboard address, the limits, and the tools, resources and prompts registered.',
+        mimeType: 'application/json',
+    }, async (uri) => json(uri.href, capabilities()));
+    server.registerResource('proof', PROOF_RESOURCE_URI, {
+        title: 'Proof',
+        description: 'The published accuracy of every measured built-in rule (the same numbers as https://iris-eval.com/proof): precision and recall on the proof corpus with 95% intervals, the confusion counts, positive predictive value at four prevalences, and the corpus version and labelling the numbers come from.',
+        mimeType: 'application/json',
+    }, async (uri) => {
+        const prov = publishedProvenance();
+        const rules = {};
+        for (const name of publishedRuleNames())
+            rules[name] = ruleProof(name);
+        return json(uri.href, {
+            corpusVersion: prov.corpusVersion,
+            release: prov.release,
+            labelling: prov.labelling,
+            method: 'Each rule is run over its proof-corpus family; precision and recall carry Wilson 95% intervals; ppvAt is the positive predictive value at the stated prevalence, from the same counts. Reproduce with `npm run proof` in the repository.',
+            rules,
+        });
+    });
+    server.registerResource('dashboard-summary', DASHBOARD_SUMMARY_RESOURCE_URI, { title: 'Dashboard summary', description: 'Dashboard summary with key metrics and trends for the last hour', mimeType: 'application/json' }, async (uri) => json(uri.href, await storage.getDashboardSummary(LOCAL_TENANT)));
+    server.registerResource('trace-detail', new ResourceTemplate(TRACE_RESOURCE_TEMPLATE, { list: undefined }), { title: 'Trace', description: 'One stored trace with its spans and every evaluation linked to it', mimeType: 'application/json' }, async (uri, variables) => {
+        const traceId = String(variables.trace_id ?? '');
+        const trace = await storage.getTrace(LOCAL_TENANT, traceId);
+        if (!trace)
+            throw notFound(uri.href, 'trace');
+        const [spans, evals] = await Promise.all([
+            storage.getSpansByTraceId(LOCAL_TENANT, traceId),
+            storage.getEvalsByTraceId(LOCAL_TENANT, traceId),
+        ]);
+        return json(uri.href, { trace, spans, evals: evals.map((e) => toEvaluationResponse(e, { traceId })) });
+    });
+    server.registerResource('evaluation-detail', new ResourceTemplate(EVALUATION_RESOURCE_TEMPLATE, { list: undefined }), { title: 'Evaluation', description: 'One stored evaluation, in the same shape evaluate_output returned it: verdict, coverage, provenance and every rule result with its evidence', mimeType: 'application/json' }, async (uri, variables) => {
+        const id = String(variables.id ?? '');
+        const result = await storage.getEvalById(LOCAL_TENANT, id);
+        if (!result)
+            throw notFound(uri.href, 'evaluation');
+        return json(uri.href, toEvaluationResponse(result, { traceId: result.trace_id }));
+    });
 }

package/dist/resources/uris.d.ts

@@ -0,0 +1,12 @@
+export declare const CAPABILITIES_RESOURCE_URI = "iris://capabilities";
+export declare const PROOF_RESOURCE_URI = "iris://proof";
+export declare const DASHBOARD_SUMMARY_RESOURCE_URI = "iris://dashboard/summary";
+export declare const TRACE_RESOURCE_TEMPLATE = "iris://traces/{trace_id}";
+export declare const EVALUATION_RESOURCE_TEMPLATE = "iris://evaluations/{id}";
+export declare const RESOURCE_URIS: readonly ["iris://capabilities", "iris://proof", "iris://dashboard/summary", "iris://traces/{trace_id}", "iris://evaluations/{id}"];
+/** The URI of one stored trace / evaluation, from its template. */
+export declare const traceUri: (traceId: string) => string;
+export declare const evaluationUri: (id: string) => string;
+/** Fixed URIs (resources/list) versus templates (resources/templates/list). */
+export declare const FIXED_RESOURCE_URIS: readonly ["iris://capabilities", "iris://proof", "iris://dashboard/summary"];
+export declare const RESOURCE_TEMPLATES: readonly ["iris://traces/{trace_id}", "iris://evaluations/{id}"];

package/dist/resources/uris.js

@@ -0,0 +1,24 @@
+/*
+ * Every resource URI this server registers, as literals: the capabilities
+ * object lists them, the docs contract checks prose against them, and a
+ * test asserts the list equals what resources/list and
+ * resources/templates/list return.
+ */
+export const CAPABILITIES_RESOURCE_URI = 'iris://capabilities';
+export const PROOF_RESOURCE_URI = 'iris://proof';
+export const DASHBOARD_SUMMARY_RESOURCE_URI = 'iris://dashboard/summary';
+export const TRACE_RESOURCE_TEMPLATE = 'iris://traces/{trace_id}';
+export const EVALUATION_RESOURCE_TEMPLATE = 'iris://evaluations/{id}';
+export const RESOURCE_URIS = [
+    CAPABILITIES_RESOURCE_URI,
+    PROOF_RESOURCE_URI,
+    DASHBOARD_SUMMARY_RESOURCE_URI,
+    TRACE_RESOURCE_TEMPLATE,
+    EVALUATION_RESOURCE_TEMPLATE,
+];
+/** The URI of one stored trace / evaluation, from its template. */
+export const traceUri = (traceId) => TRACE_RESOURCE_TEMPLATE.replace('{trace_id}', traceId);
+export const evaluationUri = (id) => EVALUATION_RESOURCE_TEMPLATE.replace('{id}', id);
+/** Fixed URIs (resources/list) versus templates (resources/templates/list). */
+export const FIXED_RESOURCE_URIS = [CAPABILITIES_RESOURCE_URI, PROOF_RESOURCE_URI, DASHBOARD_SUMMARY_RESOURCE_URI];
+export const RESOURCE_TEMPLATES = [TRACE_RESOURCE_TEMPLATE, EVALUATION_RESOURCE_TEMPLATE];

package/dist/retention.d.ts

@@ -0,0 +1,20 @@
+import type { IrisConfig } from './types/config.js';
+import type { IStorageAdapter } from './types/query.js';
+export interface RetentionLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+}
+export interface SweepOutcome {
+    deletedTraces: number;
+    deletedEvals: number;
+}
+/**
+ * One sweep for the local tenant. Never throws — a failed sweep is logged
+ * and the server keeps serving; the next tick tries again.
+ */
+export declare function runRetentionSweep(storage: IStorageAdapter, config: IrisConfig, logger: RetentionLogger): Promise<SweepOutcome | null>;
+/**
+ * The timer. Returns the handle (already unref'd) so a caller can clear it
+ * on shutdown, or null when retention or the timer is disabled.
+ */
+export declare function scheduleRetentionSweep(storage: IStorageAdapter, config: IrisConfig, logger: RetentionLogger): NodeJS.Timeout | null;

package/dist/retention.js

@@ -0,0 +1,44 @@
+import { LOCAL_TENANT } from './types/tenant.js';
+/**
+ * One sweep for the local tenant. Never throws — a failed sweep is logged
+ * and the server keeps serving; the next tick tries again.
+ */
+export async function runRetentionSweep(storage, config, logger) {
+    if (config.retention.days <= 0)
+        return null;
+    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`);
+        }
+        return { deletedTraces, deletedEvals };
+    }
+    catch (err) {
+        logger.warn(`Retention cleanup skipped: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+/**
+ * The timer. Returns the handle (already unref'd) so a caller can clear it
+ * on shutdown, or null when retention or the timer is disabled.
+ */
+export function scheduleRetentionSweep(storage, config, logger) {
+    const hours = config.retention.sweepIntervalHours;
+    if (config.retention.days <= 0 || !(hours > 0))
+        return null;
+    const timer = setInterval(() => {
+        void runRetentionSweep(storage, config, logger);
+    }, hours * 60 * 60 * 1000);
+    timer.unref();
+    return timer;
+}

package/dist/self-test.d.ts

@@ -1,5 +1,6 @@
 export declare const SELF_TEST_STEPS: {
     readonly configuredHome: "configured IRIS_HOME is writable";
+    readonly judge: "judge key in this shell";
     readonly tempHome: "create isolated temp home";
     readonly storage: "initialize storage";
     readonly trace: "log a trace";