@iris-eval/mcp-server 0.5.1 → 0.6.0

package/dist/index.js

@@ -2,7 +2,9 @@
 import { parseArgs } from 'node:util';
 import { z } from 'zod';
 import { loadConfig } from './config/index.js';
+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 { createStdioTransport } from './transport/stdio.js';
 import { createHttpTransport } from './transport/http.js';
@@ -35,6 +37,8 @@ const CliSchema = z
     demo: z.boolean().optional(),
     'demo-clear': z.boolean().optional(),
     'self-test': z.boolean().optional(),
+    purge: z.boolean().optional(),
+    version: z.boolean().optional(),
     help: z.boolean().optional(),
 })
     .strict();
@@ -65,6 +69,8 @@ try {
             demo: { type: 'boolean', default: false },
             'demo-clear': { type: 'boolean', default: false },
             'self-test': { type: 'boolean', default: false },
+            purge: { type: 'boolean', default: false },
+            version: { type: 'boolean', default: false },
             help: { type: 'boolean', short: 'h', default: false },
         },
         strict: true,
@@ -74,6 +80,16 @@ catch (err) {
     process.stderr.write(`iris-mcp: ${err.message}\nRun \`iris-mcp --help\` for usage.\n`);
     process.exit(2);
 }
+/*
+ * --version answers on stdout, bare, before anything else: the README's
+ * "check your version" recipe pointed at a flag that did not exist and a
+ * --help banner that printed no version (#369). Bare so `iris-mcp
+ * --version` composes in scripts the way `npm --version` does.
+ */
+if (parsed.values.version) {
+    process.stdout.write(`${PKG_VERSION}\n`);
+    process.exit(0);
+}
 const validation = CliSchema.safeParse(parsed.values);
 if (!validation.success) {
     const issues = validation.error.issues
@@ -85,7 +101,7 @@ if (!validation.success) {
 const values = validation.data;
 if (values.help) {
     process.stderr.write(`
-Iris — MCP-Native Agent Eval Server
+Iris — MCP-Native Agent Eval Server v${PKG_VERSION}
 
 Usage: iris-mcp [options]
 
@@ -107,9 +123,16 @@ Options:
                            transport). Idempotent: re-running reuses the seeded data.
   --demo-clear             Delete the demo database (and its sidecar files), then exit.
                            Your real traces are not touched.
-  --self-test              Run the offline install diagnostic and exit: storage round-trip,
-                           deterministic evals, dashboard + rebinding guard — all inside an
+  --self-test              Run the offline install diagnostic and exit: the configured IRIS_HOME
+                           is created and probed for writability, then storage round-trip,
+                           deterministic evals, dashboard + rebinding guard run inside an
                            isolated temp home. Exit code 0 = healthy, 1 = a check failed.
+  --purge                  Delete EVERY stored trace, span and evaluation from the configured
+                           database, compact the file and truncate the write-ahead log so the
+                           deleted text does not linger on disk, then exit. Deployed rules, the
+                           audit log and preferences are kept. Not reversible. Stop any running
+                           Iris server first — the file is compacted in place.
+  --version                Print the version and exit
   -h, --help               Show this help message
 
 Environment variables (CLI flags take precedence):
@@ -139,11 +162,31 @@ Environment variables (CLI flags take precedence):
   IRIS_OTEL_TIMEOUT_MS                 Per-export timeout (default: 15000)
   RATE_LIMIT_SALT                      (waitlist API only — required when website is deployed)
 
-Dashboard preferences (~/.iris/preferences.json):
+Dashboard preferences ($IRIS_HOME/preferences.json, default ~/.iris/preferences.json):
   Edit autoLaunch: false to permanently disable first-run dashboard auto-launch.
 `);
     process.exit(0);
 }
+/*
+ * The mode flags are mutually exclusive, and the check runs before any of
+ * them so a refused combination exits without touching the filesystem —
+ * `--self-test --purge` must not quietly run only the first one it sees.
+ */
+const modeFlags = ['demo', 'demo-clear', 'self-test', 'purge'].filter((flag) => values[flag]);
+if (modeFlags.length > 1) {
+    process.stderr.write(`iris-mcp: ${modeFlags.map((flag) => `--${flag}`).join(' and ')} cannot be combined.\nRun \`iris-mcp --help\` for usage.\n`);
+    process.exit(2);
+}
+/*
+ * `--purge --dashboard` used to run the purge and drop the dashboard flag
+ * on the floor. A flag that changes nothing is the same fault as a
+ * misspelled tool argument: the caller asked for something and got no
+ * sign it was ignored. (v0.6.0 acceptance pass.)
+ */
+if (values.purge && values.dashboard) {
+    process.stderr.write('iris-mcp: --purge exits as soon as the purge finishes and cannot be combined with --dashboard (nothing would be served).\nRun `iris-mcp --help` for usage.\n');
+    process.exit(2);
+}
 /*
  * --self-test exits BEFORE loadConfig() runs at module scope below —
  * deliberately. The diagnostic builds its own isolated IRIS_HOME and
@@ -154,14 +197,6 @@ if (values['self-test']) {
     const { runSelfTest } = await import('./self-test.js');
     process.exit(await runSelfTest());
 }
-/*
- * Demo-mode flag validation happens before loadConfig so a refused
- * combination exits without touching the filesystem.
- */
-if (values.demo && values['demo-clear']) {
-    process.stderr.write('iris-mcp: --demo and --demo-clear cannot be combined.\nRun `iris-mcp --help` for usage.\n');
-    process.exit(2);
-}
 if (values.demo && values['db-path']) {
     process.stderr.write('iris-mcp: --demo always serves its own database (demo.db under your iris home) and cannot be combined with --db-path.\n' +
         'Run `iris-mcp --demo` alone, or drop --demo to use your own database.\n');
@@ -193,6 +228,39 @@ const config = loadConfig({
     dashboardHost: values['dashboard-host'],
 });
 const logger = createLogger(config);
+/*
+ * --purge (#372): the retention sweep only ever trimmed by age, and
+ * deleting iris.db by hand left every row readable in iris.db-wal. This
+ * is the one-command answer to "remove everything Iris stored about my
+ * agents" — every trace, span and evaluation for the local tenant,
+ * followed by VACUUM + a TRUNCATE checkpoint so the text is gone from the
+ * main file and the write-ahead log alike. Rules, audit log and
+ * preferences are not storage rows and stay. Prints what it removed and
+ * exits 0; runs against the configured database, never the demo one
+ * (--demo-clear handles that).
+ */
+async function runPurge() {
+    const storage = createStorage(config);
+    await storage.initialize();
+    try {
+        const { traces, evalResults } = await storage.purge(LOCAL_TENANT);
+        process.stderr.write(`iris-mcp: purged ${traces} trace(s) and ${evalResults} evaluation(s) from "${config.storage.path}" ` +
+            '(database compacted, write-ahead log truncated). Deployed rules, audit log and preferences were kept.\n');
+    }
+    finally {
+        await storage.close();
+    }
+}
+if (values.purge) {
+    try {
+        await runPurge();
+        process.exit(0);
+    }
+    catch (err) {
+        process.stderr.write(`iris-mcp: purge failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+}
 async function main() {
     logger.info(`Starting Iris MCP server v${config.server.version}`);
     // F-006: fail fast on HTTP+dashboard port collision. See validatePortConfig.
@@ -231,9 +299,19 @@ async function main() {
     // cleanly.
     if (config.retention.days > 0) {
         try {
-            const deleted = await storage.deleteTracesOlderThan(LOCAL_TENANT, config.retention.days);
-            if (deleted > 0) {
-                logger.info(`Retention cleanup: deleted ${deleted} trace(s) older than ${config.retention.days} days`);
+            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) {
@@ -332,6 +410,8 @@ ${line}
 ${counts}
   Demo database: "${summary.dbPath}"
   Your real trace database is untouched — demo data never mixes with it.
+  Trace ingest (POST /api/v1/traces) is refused in demo mode: start the
+  real server (iris-mcp --dashboard) to store your own traces.
 
   Worth clicking into:
     - a PII leak (a synthetic SSN in an agent reply) caught by the safety rules
@@ -367,7 +447,13 @@ async function runDemo() {
     else {
         logger.info(`Seeded demo database with ${seedSummary.traceCount} traces at ${seedSummary.dbPath}`);
     }
-    const storage = createStorage(config);
+    /*
+     * Ingest is refused in demo mode: demo.db is disposable by design and
+     * --demo-clear deletes it wholesale, so a capture client pointed at the
+     * demo dashboard's port would have its real traces silently stored next
+     * to the fake ones and later destroyed (storage/demo-guard.ts).
+     */
+    const storage = withDemoIngestGuard(createStorage(config));
     await storage.initialize();
     const customRuleStore = createCustomRuleStore({
         pathFor: () => demoCustomRulesPath(),

package/dist/middleware/rate-limit.d.ts

@@ -1,3 +1,28 @@
 import type { IrisConfig } from '../types/config.js';
 export declare function createApiRateLimiter(config: Pick<IrisConfig, 'security'>): import("express-rate-limit").RateLimitRequestHandler;
+/**
+ * Mounted directly in front of the session layer, so every request that
+ * is about to be AUTHORIZED — cookie check, Bearer check, the `?key=`
+ * exchange — has passed a per-IP ceiling first (CodeQL
+ * js/missing-rate-limiting on the session middleware). Same figure as the
+ * API limiter with its own counter; static assets share it, which a
+ * dashboard page load (a few dozen requests) never approaches.
+ */
+export declare function createAuthGateRateLimiter(config: Pick<IrisConfig, 'security'>): import("express-rate-limit").RateLimitRequestHandler;
+/**
+ * JSON-RPC 2.0 application error code for "rate limited". The reserved
+ * server range is -32000..-32099; the MCP SDK uses -32000/-32001 for
+ * connection-closed and request-timeout, so this sits clear of both.
+ * Mirrors HTTP 429 in the low digits so a log line reads at a glance.
+ */
+export declare const JSON_RPC_RATE_LIMITED = -32029;
+/**
+ * The MCP endpoint speaks JSON-RPC, so its 429 must too (#373). The stock
+ * express-rate-limit body — `{ "error": "Too many requests" }` — is not a
+ * JSON-RPC message: a strict client (the reference SDK included) fails to
+ * parse the response and surfaces a PROTOCOL error, and the one thing the
+ * caller needed to learn — wait, then retry — is exactly what got lost. The
+ * envelope below echoes the request id when the body carried one, names
+ * the limit and the wait, and points at the config key that raises it.
+ */
 export declare function createMcpRateLimiter(config: Pick<IrisConfig, 'security'>): import("express-rate-limit").RateLimitRequestHandler;

package/dist/middleware/rate-limit.js

@@ -8,12 +8,64 @@ export function createApiRateLimiter(config) {
         message: { error: 'Too many requests, please try again later' },
     });
 }
-export function createMcpRateLimiter(config) {
+/**
+ * Mounted directly in front of the session layer, so every request that
+ * is about to be AUTHORIZED — cookie check, Bearer check, the `?key=`
+ * exchange — has passed a per-IP ceiling first (CodeQL
+ * js/missing-rate-limiting on the session middleware). Same figure as the
+ * API limiter with its own counter; static assets share it, which a
+ * dashboard page load (a few dozen requests) never approaches.
+ */
+export function createAuthGateRateLimiter(config) {
     return rateLimit({
         windowMs: 60_000,
-        limit: config.security.rateLimit.mcp,
+        limit: config.security.rateLimit.api,
         standardHeaders: 'draft-7',
         legacyHeaders: false,
         message: { error: 'Too many requests, please try again later' },
     });
 }
+/**
+ * JSON-RPC 2.0 application error code for "rate limited". The reserved
+ * server range is -32000..-32099; the MCP SDK uses -32000/-32001 for
+ * connection-closed and request-timeout, so this sits clear of both.
+ * Mirrors HTTP 429 in the low digits so a log line reads at a glance.
+ */
+export const JSON_RPC_RATE_LIMITED = -32029;
+/**
+ * The MCP endpoint speaks JSON-RPC, so its 429 must too (#373). The stock
+ * express-rate-limit body — `{ "error": "Too many requests" }` — is not a
+ * JSON-RPC message: a strict client (the reference SDK included) fails to
+ * parse the response and surfaces a PROTOCOL error, and the one thing the
+ * caller needed to learn — wait, then retry — is exactly what got lost. The
+ * envelope below echoes the request id when the body carried one, names
+ * the limit and the wait, and points at the config key that raises it.
+ */
+export function createMcpRateLimiter(config) {
+    const limit = config.security.rateLimit.mcp;
+    return rateLimit({
+        windowMs: 60_000,
+        limit,
+        standardHeaders: 'draft-7',
+        legacyHeaders: false,
+        handler: (req, res) => {
+            const body = req.body;
+            const requestId = body !== null && typeof body === 'object' && !Array.isArray(body) && 'id' in body
+                ? body.id
+                : null;
+            const id = typeof requestId === 'string' || typeof requestId === 'number' ? requestId : null;
+            const resetTime = req.rateLimit?.resetTime;
+            const retryAfterSeconds = resetTime instanceof Date ? Math.max(1, Math.ceil((resetTime.getTime() - Date.now()) / 1000)) : 60;
+            res.status(429).json({
+                jsonrpc: '2.0',
+                id,
+                error: {
+                    code: JSON_RPC_RATE_LIMITED,
+                    message: `Rate limit exceeded: this MCP endpoint allows ${limit} requests per minute. ` +
+                        `Retry in ${retryAfterSeconds}s, or raise security.rateLimit.mcp in config.json for an interactive session.`,
+                    data: { limit, windowMs: 60_000, retryAfterSeconds },
+                },
+            });
+        },
+    });
+}

package/dist/self-test.d.ts

@@ -1,4 +1,5 @@
 export declare const SELF_TEST_STEPS: {
+    readonly configuredHome: "configured IRIS_HOME is writable";
     readonly tempHome: "create isolated temp home";
     readonly storage: "initialize storage";
     readonly trace: "log a trace";
@@ -15,4 +16,17 @@ export declare const SELF_TEST_STEPS: {
 export declare const SELF_TEST_PASS_VERDICT = "\u2713 PASS \u2014 this install works";
 export declare const SELF_TEST_FAIL_VERDICT = "\u2717 FAIL";
 export type WriteLine = (line: string) => void;
+/**
+ * The configured-home probe (#371). Exercises the exact calls the real
+ * server makes at startup, in order: create IRIS_HOME (same helper and
+ * mode as loadConfig), create the database directory when IRIS_DB_PATH
+ * points elsewhere, write-and-unlink a probe file in each, and — only if
+ * the real database already exists — open it and take a write lock
+ * (BEGIN IMMEDIATE … ROLLBACK), which fails on a read-only file or a
+ * non-database exactly as the first INSERT would, without migrating or
+ * changing anything. A missing database is not created: the server
+ * creates it on first run, and the writable-directory probe is what
+ * proves that it can.
+ */
+export declare function probeConfiguredHome(home: string, dbPath: string): string;
 export declare function runSelfTest(write?: WriteLine): Promise<number>;

package/dist/self-test.js

@@ -11,10 +11,20 @@
  *
  * Isolation is the load-bearing property. The diagnostic creates its own
  * scratch IRIS_HOME and scrubs every IRIS_* env var that feeds
- * loadConfig(), so it NEVER opens (or migrates!) the user's real iris.db,
- * never reads their config.json, and never honours an IRIS_API_KEY that
- * would 401 its own probes. The scratch home is removed and the env
- * restored before returning — pass or fail.
+ * loadConfig(), so it never MIGRATES or writes rows into the user's real
+ * iris.db, never reads their config.json, and never honours an
+ * IRIS_API_KEY that would 401 its own probes. The scratch home is removed
+ * and the env restored before returning — pass or fail.
+ *
+ * Isolation is not the same as ignorance, though. The first check runs
+ * BEFORE the scrub, against the CONFIGURED home: it creates the directory
+ * the server would create, proves it can write there, and — when the real
+ * database already exists — opens it and takes (then releases) a write
+ * lock without changing a byte. #371: the diagnostic used to print PASS
+ * against an IRIS_HOME the server could not write, because every check
+ * ran in the temp home; the real server then died on startup with a raw
+ * EPERM stack. A diagnostic that cannot fail the way the product fails is
+ * not a diagnostic.
  *
  * Budget: everything is in-process or loopback. No LLM calls, no network
  * beyond 127.0.0.1, and the whole sequence completes in well under the
@@ -23,11 +33,13 @@
  * Exit contract: 0 = every check passed, 1 = any check failed. index.ts
  * runs this BEFORE loadConfig() so the normal boot path never executes.
  */
-import { mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
 import { request as httpRequest } from 'node:http';
-import { loadConfig } from './config/index.js';
+import Database from 'better-sqlite3';
+import { ensureIrisDirectory, loadConfig } from './config/index.js';
 import { PKG_VERSION } from './config/defaults.js';
 import { createStorage } from './storage/index.js';
 import { createDashboardServer } from './dashboard/server.js';
@@ -44,6 +56,7 @@ const CROSS = '✗';
  * files, per the usual drift rule.
  */
 export const SELF_TEST_STEPS = {
+    configuredHome: 'configured IRIS_HOME is writable',
     tempHome: 'create isolated temp home',
     storage: 'initialize storage',
     trace: 'log a trace',
@@ -114,16 +127,77 @@ function probe(port, path, headers = {}) {
     });
 }
 const stdoutLine = (line) => process.stdout.write(`${line}\n`);
+function errorCode(err) {
+    const code = err?.code;
+    return typeof code === 'string' ? code : err instanceof Error ? err.message : String(err);
+}
+/**
+ * The configured-home probe (#371). Exercises the exact calls the real
+ * server makes at startup, in order: create IRIS_HOME (same helper and
+ * mode as loadConfig), create the database directory when IRIS_DB_PATH
+ * points elsewhere, write-and-unlink a probe file in each, and — only if
+ * the real database already exists — open it and take a write lock
+ * (BEGIN IMMEDIATE … ROLLBACK), which fails on a read-only file or a
+ * non-database exactly as the first INSERT would, without migrating or
+ * changing anything. A missing database is not created: the server
+ * creates it on first run, and the writable-directory probe is what
+ * proves that it can.
+ */
+export function probeConfiguredHome(home, dbPath) {
+    ensureIrisDirectory(home, 'IRIS_HOME');
+    probeWritable(home, 'IRIS_HOME');
+    const dbDir = dirname(dbPath);
+    if (dbDir !== home) {
+        ensureIrisDirectory(dbDir, 'the database directory (IRIS_DB_PATH / --db-path)');
+        probeWritable(dbDir, 'the database directory');
+    }
+    if (!existsSync(dbPath)) {
+        return `${home} (database ${dbPath} will be created on first run)`;
+    }
+    let db;
+    try {
+        db = new Database(dbPath, { fileMustExist: true });
+        db.exec('BEGIN IMMEDIATE');
+        db.exec('ROLLBACK');
+    }
+    catch (err) {
+        throw new Error(`database "${dbPath}" exists but cannot be opened for writing (${errorCode(err)}) — the server would fail ` +
+            'at startup with the same error. Fix the file permissions, or point IRIS_DB_PATH / --db-path at a writable location.');
+    }
+    finally {
+        db?.close();
+    }
+    return `${home} (database ${dbPath} opens for writing)`;
+}
+function probeWritable(dir, what) {
+    const probeFile = join(dir, `.iris-self-test-${randomBytes(4).toString('hex')}`);
+    try {
+        writeFileSync(probeFile, 'iris self-test write probe\n', { mode: 0o600 });
+    }
+    catch (err) {
+        throw new Error(`${what} "${dir}" is not writable (${errorCode(err)}) — the server would fail at startup with the same error. ` +
+            'Point IRIS_HOME at a directory this user can write, or fix the permissions on that path.');
+    }
+    try {
+        unlinkSync(probeFile);
+    }
+    catch {
+        // Written but not removable: unusual (sticky bit, AV lock). Not a
+        // startup blocker, so not a failure; the file is tiny and named for
+        // what it is.
+    }
+}
 export async function runSelfTest(write = stdoutLine) {
     write(`Iris self-test v${PKG_VERSION}`);
     write('');
     /*
      * Resolved BEFORE the env scrub: this is where a normal (non-self-test)
      * run of this install would keep its data, which is the line the user
-     * actually wants from a diagnostic. The self-test itself never touches
-     * this path.
+     * actually wants from a diagnostic — and the target of the configured-
+     * home probe below. The isolated checks never touch these paths.
      */
-    const userStoragePath = process.env.IRIS_DB_PATH ?? join(irisHome(), 'iris.db');
+    const userHome = irisHome();
+    const userStoragePath = process.env.IRIS_DB_PATH ?? join(userHome, 'iris.db');
     const savedEnv = {};
     for (const key of SCRUBBED_ENV_VARS) {
         savedEnv[key] = process.env[key];
@@ -137,14 +211,18 @@ export async function runSelfTest(write = stdoutLine) {
     let traceId = '';
     const insertedIds = [];
     const failedSteps = [];
+    let halted = false;
     /*
      * Steps run strictly in order and stop at the first failure — each one
      * depends on the state the previous one built, so a cascade of
      * follow-on crosses would only bury the real cause. Cleanup runs
-     * unconditionally afterwards.
+     * unconditionally afterwards. A step marked `independent` still fails
+     * the run but does not halt it: the configured-home probe has no
+     * successors that depend on it, and the user is better served by ALSO
+     * learning whether the install itself works.
      */
-    const step = async (label, fn) => {
-        if (failedSteps.length > 0)
+    const step = async (label, fn, opts) => {
+        if (halted)
             return;
         try {
             const detail = await fn();
@@ -152,9 +230,14 @@ export async function runSelfTest(write = stdoutLine) {
         }
         catch (err) {
             failedSteps.push(label);
+            if (!opts?.independent)
+                halted = true;
             write(`${CROSS} ${label} — ${err instanceof Error ? err.message : String(err)}`);
         }
     };
+    await step(SELF_TEST_STEPS.configuredHome, () => probeConfiguredHome(userHome, userStoragePath), {
+        independent: true,
+    });
     await step(SELF_TEST_STEPS.tempHome, () => {
         tempHome = mkdtempSync(join(tmpdir(), 'iris-self-test-'));
         for (const key of SCRUBBED_ENV_VARS) {
@@ -321,6 +404,7 @@ export async function runSelfTest(write = stdoutLine) {
     }
     write('');
     write(`version   ${PKG_VERSION}`);
+    write(`home      ${userHome}`);
     write(`storage   ${userStoragePath}`);
     write(failedSteps.length === 0
         ? SELF_TEST_PASS_VERDICT

package/dist/storage/demo-guard.d.ts

@@ -0,0 +1,8 @@
+import type { IStorageAdapter } from '../types/query.js';
+export declare const DEMO_INGEST_REFUSED_MESSAGE: string;
+export declare class DemoIngestRefusedError extends Error {
+    /** Read by the dashboard's error handler: a client fault, not a server one. */
+    readonly status = 403;
+    constructor();
+}
+export declare function withDemoIngestGuard(storage: IStorageAdapter): IStorageAdapter;

package/dist/storage/demo-guard.js

@@ -0,0 +1,53 @@
+/*
+ * Demo mode must not quietly become someone's production store.
+ *
+ * `--demo` serves the dashboard — and with it POST /api/v1/traces — against
+ * demo.db, a seeded, DISPOSABLE database that `--demo-clear` deletes
+ * outright. A reader following the README top to bottom could start the
+ * demo, point their capture client at the port it printed, watch real
+ * traces land beside the fake ones, and later lose all of them to the
+ * cleanup command the banner recommends. Nothing warned at any step.
+ *
+ * The guard wraps the demo store so every WRITE of trace or eval data is
+ * refused with a message that says what demo mode is and where real
+ * traces go. Reads and the demo's own seeded content are untouched — the
+ * dashboard keeps working exactly as before. Rule deploys are not storage
+ * writes (they go to the demo-scoped rule store) and stay allowed; they
+ * are part of what the demo exists to show.
+ *
+ * Implemented as a Proxy over the adapter rather than a subclass or a
+ * hand-written delegate: any method added to IStorageAdapter later
+ * delegates automatically instead of silently bypassing the guard.
+ */
+export const DEMO_INGEST_REFUSED_MESSAGE = 'Demo mode does not accept trace ingest. `--demo` serves a seeded, disposable database (demo.db) — ' +
+    '`--demo-clear` deletes everything in it, so real traces stored here would be lost. ' +
+    'Start the real server to store traces: `iris-mcp --dashboard` for HTTP ingest on POST /api/v1/traces, ' +
+    'or the MCP transport for log_trace.';
+const REFUSED_METHODS = new Set([
+    'insertTrace',
+    'insertSpan',
+    'insertEvalResult',
+]);
+export class DemoIngestRefusedError extends Error {
+    /** Read by the dashboard's error handler: a client fault, not a server one. */
+    status = 403;
+    constructor() {
+        super(DEMO_INGEST_REFUSED_MESSAGE);
+        this.name = 'DemoIngestRefusedError';
+    }
+}
+export function withDemoIngestGuard(storage) {
+    return new Proxy(storage, {
+        get(target, prop, receiver) {
+            if (typeof prop === 'string' && REFUSED_METHODS.has(prop)) {
+                return async () => {
+                    throw new DemoIngestRefusedError();
+                };
+            }
+            const value = Reflect.get(target, prop, receiver);
+            // Class methods live on the prototype and read private fields off
+            // `this`; bind them to the real adapter so `this.db` resolves.
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+}

package/dist/storage/sqlite-adapter.d.ts

@@ -34,6 +34,12 @@ export declare class SqliteAdapter implements IStorageAdapter {
     getEvalStatsRules(tenantId: TenantId, period: EvalStatsPeriod): Promise<EvalStatsRuleBreakdown[]>;
     getEvalStatsFailures(tenantId: TenantId, period: EvalStatsPeriod, limit: number): Promise<EvalStatsFailure[]>;
     deleteTracesOlderThan(tenantId: TenantId, days: number): Promise<number>;
+    deleteEvalResultsOlderThan(tenantId: TenantId, days: number): Promise<number>;
+    purge(tenantId: TenantId): Promise<{
+        traces: number;
+        evalResults: number;
+    }>;
+    checkpoint(): Promise<void>;
     deleteTrace(tenantId: TenantId, traceId: string): Promise<boolean>;
     getDistinctValues(tenantId: TenantId, column: string): Promise<string[]>;
     private rowToTrace;