@iris-eval/mcp-server 0.5.1 → 0.6.0

package/dist/storage/sqlite-adapter.js

@@ -45,6 +45,16 @@ export class SqliteAdapter {
         this.db.pragma('journal_mode = WAL');
         this.db.pragma('busy_timeout = 5000');
         this.db.pragma('foreign_keys = ON');
+        /*
+         * secure_delete overwrites freed content with zeros instead of leaving
+         * it in place until the page is reused. Without it, a DELETE — the
+         * retention sweep, delete_trace, --purge — removed the row from every
+         * query while the text stayed byte-for-byte readable in the file with
+         * `strings iris.db`. Deletes are rare here (startup sweep, explicit
+         * deletes), so the write cost is negligible; the privacy cost of the
+         * alternative is the whole point of #372.
+         */
+        this.db.pragma('secure_delete = ON');
         runMigrations(this.db);
         /*
          * iris.db holds agent inputs and outputs verbatim, and a tool that
@@ -352,11 +362,18 @@ export class SqliteAdapter {
          * skips rules that passed, so scanning every safety eval in the window
          * is both correct and sufficient.
          */
+        /*
+         * eval_type IN ('safety', 'all'): an eval_type="all" run carries the
+         * whole safety bundle inside its rule_results, and a PII leak caught
+         * there is exactly as real as one caught by a safety-only run. The
+         * per-rule loop below keys on rule NAMES, so the wider filter cannot
+         * over-count.
+         */
         const safetyRows = this.db.prepare(`
       SELECT rule_results
       FROM eval_results
       WHERE tenant_id = ? AND created_at >= ?
-        AND eval_type = 'safety'
+        AND eval_type IN ('safety', 'all')
     `).all(tenantId, since);
         const violations = { pii: 0, injection: 0, hallucination: 0 };
         for (const row of safetyRows) {
@@ -492,6 +509,55 @@ export class SqliteAdapter {
             .run(tenantId, cutoff);
         return result.changes;
     }
+    async deleteEvalResultsOlderThan(tenantId, days) {
+        assertTenant(tenantId);
+        const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+        /*
+         * created_at, not the linked trace's timestamp: an unlinked eval has
+         * no trace, and a linked one whose trace was already swept has a NULL
+         * trace_id — either way the eval's own age is the only age it has.
+         * Rows are ISO-8601 here (write path + migration 005), so the string
+         * comparison against an ISO cutoff is exact.
+         */
+        const result = this.db
+            .prepare('DELETE FROM eval_results WHERE tenant_id = ? AND created_at < ?')
+            .run(tenantId, cutoff);
+        return result.changes;
+    }
+    async purge(tenantId) {
+        assertTenant(tenantId);
+        const deleteAll = this.db.transaction(() => {
+            const evalResults = this.db.prepare('DELETE FROM eval_results WHERE tenant_id = ?').run(tenantId).changes;
+            // spans cascade (FK ON DELETE CASCADE).
+            const traces = this.db.prepare('DELETE FROM traces WHERE tenant_id = ?').run(tenantId).changes;
+            return { traces, evalResults };
+        });
+        const counts = deleteAll();
+        /*
+         * VACUUM rebuilds the file from the live rows only — the freed pages
+         * (already zeroed by secure_delete) are dropped rather than kept as
+         * free-list slack — and the TRUNCATE checkpoint then folds the WAL into
+         * the main file and cuts it to zero bytes, so neither iris.db nor
+         * iris.db-wal keeps a copy of what was just deleted. Skipped for
+         * :memory: (nothing on disk to clean).
+         */
+        if (this.dbPath !== ':memory:') {
+            this.db.exec('VACUUM');
+        }
+        await this.checkpoint();
+        return counts;
+    }
+    async checkpoint() {
+        if (this.dbPath === ':memory:')
+            return;
+        try {
+            this.db.pragma('wal_checkpoint(TRUNCATE)');
+        }
+        catch {
+            // Best effort: a checkpoint can be refused while another connection
+            // holds a read transaction. The next one will pick the pages up.
+        }
+    }
     async deleteTrace(tenantId, traceId) {
         assertTenant(tenantId);
         // Tenant-scoped: a trace id owned by a different tenant is
@@ -551,6 +617,11 @@ export class SqliteAdapter {
             id: row.id,
             trace_id: row.trace_id,
             eval_type: row.eval_type,
+            /*
+             * `categories` is not a column: an eval_type="all" row carries a
+             * `category` on every rule_results entry instead, so a reader can
+             * regroup the per-bundle breakdown from what IS stored.
+             */
             output_text: row.output_text,
             expected_text: row.expected_text,
             score: row.score,

package/dist/tools/delete-rule.js

@@ -1,43 +1,56 @@
 /*
- * delete_rule MCP tool — remove a deployed custom rule.
+ * delete_rule MCP tool — remove a deployed custom rule, or disable /
+ * re-enable one without removing it.
  *
  * Destructive counterpart to deploy_rule. Removes the rule from
  * ~/.iris/custom-rules.json AND unregisters it from the live eval
  * engine, so it stops firing on the very next evaluate_output call —
  * no restart needed. Appends a `rule.delete` entry to the audit log.
  *
+ * With `enabled` present the call is a TOGGLE instead: the rule stays in
+ * the store with its history and provenance, is unregistered from (or
+ * re-registered with) the live engine, and a `rule.toggle` audit row is
+ * written. The descriptions used to point at "the dashboard's toggle
+ * affordance" for this — which did not exist on any surface; the store
+ * had setEnabled() and nothing called it. This is the MCP path to it.
+ *
  * Past eval_results that referenced this rule stay intact — the
  * history is preserved even after the rule is removed. The audit
  * log row is the permanent record that the rule ever existed.
  */
 import { z } from 'zod';
+import { createCustomRule } from '../eval/rules/custom.js';
 import { LOCAL_TENANT } from '../types/tenant.js';
 import { strictInput } from './strict-input.js';
 const inputSchema = {
     rule_id: z
         .string()
         .regex(/^rule-[a-z0-9]+$/)
-        .describe('Rule id to delete (format: rule-<hex>); obtained from list_rules or deploy_rule response'),
+        .describe('Rule id to delete or toggle (format: rule-<hex>); obtained from list_rules or deploy_rule response'),
+    enabled: z
+        .boolean()
+        .optional()
+        .describe('When present the rule is NOT deleted: false DISABLES it (kept in the store, stops firing immediately, history and provenance preserved); true RE-ENABLES a disabled rule. Omit to delete'),
 };
 export function registerDeleteRuleTool(server, customRuleStore, evalEngine) {
     server.registerTool('delete_rule', {
-        title: 'Delete Custom Rule',
+        title: 'Delete or Disable Custom Rule',
         description: [
-            'Remove a deployed custom evaluation rule. The rule stops firing on future evaluate_output calls; past eval_results that referenced it are preserved.',
+            'Remove a deployed custom evaluation rule — or, with `enabled`, disable / re-enable it without removing it. Either way the change takes effect on the next evaluate_output call; past eval_results that referenced the rule are preserved.',
             '',
-            'Sibling tools — deploy_rule adds custom rules, list_rules enumerates them, evaluate_output runs them. delete_trace handles trace deletion (separate concern); log_trace / get_traces handle trace I/O. delete_rule is the DESTRUCTIVE remove path for the custom-rule store; it does NOT touch traces, eval_results, or built-in (non-custom) rules.',
+            'Sibling tools — deploy_rule adds custom rules, list_rules enumerates them (including disabled ones, with `enabled: false`), evaluate_output runs them. delete_trace handles trace deletion (separate concern); log_trace / get_traces handle trace I/O. delete_rule is the DESTRUCTIVE remove path for the custom-rule store and the only MCP path that toggles a rule; it does NOT touch traces, eval_results, or built-in (non-custom) rules.',
             '',
-            'Behavior. DESTRUCTIVE — rewrites ~/.iris/custom-rules.json without the deleted row and appends a `rule.delete` entry to the audit log (~/.iris/audit.log). Not idempotent: deleting an already-deleted rule returns `deleted: false` rather than re-emitting the audit row. The rule stops firing immediately on the live process. Historical eval_results that reference this rule_id stay in the database — drift analytics + audit trail remain valid. Tenant-scoped in Cloud tier; OSS operates on LOCAL_TENANT. Rate-limited to 20 req/min on HTTP MCP.',
+            'Behavior. Without `enabled`: DESTRUCTIVE — rewrites ~/.iris/custom-rules.json without the deleted row and appends a `rule.delete` entry to the audit log (~/.iris/audit.log). Not idempotent: deleting an already-deleted rule returns `deleted: false` rather than re-emitting the audit row. The rule stops firing immediately on the live process. With `enabled`: NOT destructive — the rule row stays, its `enabled` flag and `updatedAt` change, a `rule.toggle` audit entry is appended (none if the flag was already in that state), and the live engine unregisters (false) or re-registers (true) the rule so the change is immediate; a disabled rule is not loaded at the next boot either. Historical eval_results that reference this rule_id stay in the database — drift analytics + audit trail remain valid. Tenant-scoped in Cloud tier; OSS operates on LOCAL_TENANT. Rate-limited to 20 req/min on HTTP MCP.',
             '',
-            'Output shape. Returns JSON: `{ "deleted": boolean, "rule_id": string }`. `deleted=true` if a row was removed; `deleted=false` if no rule with that id existed.',
+            'Output shape. Delete: `{ "deleted": boolean, "rule_id": string }` — `deleted=true` if a row was removed; `deleted=false` if no rule with that id existed. Toggle (enabled given): `{ "deleted": false, "toggled": boolean, "rule_id": string, "enabled"?: boolean, "rule"?: { ...the rule } }` — `toggled=true` with the rule\'s current state when the id exists (also when it was already in the requested state), `toggled=false` and no `rule` when it does not.',
             '',
-            "Use when a custom rule is obsolete (behavior changed, false positives unacceptable, replaced by a better rule). Typical flow: list_rules → identify the stale one → delete_rule(id). Combine with deploy_rule to replace: delete_rule(oldId) + deploy_rule(newDefinition). To temporarily disable a rule WITHOUT deletion, use the dashboard's toggle affordance instead — delete is permanent in intent (rule is gone; re-adding requires a new id).",
+            "Use when a custom rule is obsolete (behavior changed, false positives unacceptable, replaced by a better rule). Typical flow: list_rules → identify the stale one → delete_rule(id). Combine with deploy_rule to replace: delete_rule(oldId) + deploy_rule(newDefinition), or deploy_rule with the same name and replace:true. To temporarily PAUSE a rule — false positives to investigate, a rollout to stage — pass `enabled: false` instead of deleting; it keeps the id, the provenance and the history, and `enabled: true` brings it back with the same id.",
             '',
-            "Don't use to pause a rule (toggle in the dashboard preserves history better). Don't use on built-in (non-custom) rules — the rule_id format checks for `rule-<hex>` custom ids; built-ins aren't in the store. Don't use to delete a trace or eval result (use delete_trace for traces; eval_results deletion is not exposed in v0.4 — they fall under data retention).",
+            "Don't use on built-in (non-custom) rules — the rule_id format checks for `rule-<hex>` custom ids; built-ins aren't in the store. Don't use to delete a trace or eval result (use delete_trace for traces; eval_results deletion is not exposed per row — they fall under data retention and `--purge`).",
             '',
-            'Parameters. rule_id is the only parameter; must match `rule-<lowercase-hex>` format (Zod regex). Format mismatch fails Zod with 400 BEFORE the store is touched. Cross-tenant rule_ids return `deleted: false` silently — they\'re invisible to the caller\'s tenant rather than producing a not-found error (prevents enumeration attacks). The rule_id you pass is exactly what list_rules returned in `id` or what deploy_rule returned in `rule.id`.',
+            'Parameters. rule_id must match `rule-<lowercase-hex>` format (Zod regex). Format mismatch fails Zod with 400 BEFORE the store is touched. Cross-tenant rule_ids return `deleted: false` / `toggled: false` silently — they\'re invisible to the caller\'s tenant rather than producing a not-found error (prevents enumeration attacks). The rule_id you pass is exactly what list_rules returned in `id` or what deploy_rule returned in `rule.id`. enabled is optional: omit to delete, false to disable, true to re-enable.',
             '',
-            "Error modes. Throws 400 on malformed rule_id (wrong prefix). Returns `{deleted: false}` if rule_id doesn't match any deployed rule (not an error — idempotent-ish). Returns 429 on HTTP rate limit. File-write failures propagate as 500.",
+            "Error modes. Throws 400 on malformed rule_id (wrong prefix) or an unknown argument. Returns `{deleted: false}` (or `{toggled: false}`) if rule_id doesn't match any deployed rule (not an error — idempotent-ish). Returns 429 on HTTP rate limit. File-write failures propagate as 500.",
         ].join('\n'),
         inputSchema: strictInput(inputSchema),
         annotations: {
@@ -48,6 +61,31 @@ export function registerDeleteRuleTool(server, customRuleStore, evalEngine) {
         },
     }, async (args) => {
         // OSS: MCP tools operate under LOCAL_TENANT. See list-rules.ts for context.
+        if (args.enabled !== undefined) {
+            const rule = customRuleStore.setEnabled(LOCAL_TENANT, args.rule_id, args.enabled, 'mcp');
+            if (!rule) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ deleted: false, toggled: false, rule_id: args.rule_id }) }],
+                };
+            }
+            // Mirror the store in the live engine, so the toggle is immediate
+            // (registerRule is idempotent by id — re-enabling an already-live
+            // rule does not stack a second copy).
+            if (rule.enabled) {
+                evalEngine.registerRule(rule.evalType, createCustomRule(rule.definition, rule.severity), rule.id);
+            }
+            else {
+                evalEngine.unregisterRule(rule.id);
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ deleted: false, toggled: true, rule_id: args.rule_id, enabled: rule.enabled, rule }),
+                    },
+                ],
+            };
+        }
         const deleted = customRuleStore.delete(LOCAL_TENANT, args.rule_id, 'mcp');
         if (deleted) {
             // Hot-remove from the live engine so the rule stops firing on the

package/dist/tools/deploy-rule.d.ts

@@ -1,4 +1,37 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CustomRuleStore } from '../custom-rule-store.js';
 import type { EvalEngine } from '../eval/engine.js';
+import type { DeployedCustomRule } from '../types/custom-rule.js';
+import { type TenantId } from '../types/tenant.js';
+/**
+ * A rule with this name is already deployed and the caller did not ask to
+ * replace it. Carries the existing rule(s) so an HTTP surface can answer
+ * 409 with them beside the same message the MCP tool throws.
+ */
+export declare class DuplicateRuleNameError extends Error {
+    readonly existing: DeployedCustomRule[];
+    constructor(name: string, existing: DeployedCustomRule[]);
+}
+/** One rule retired by a `replace: true` deploy. */
+export interface ReplacedRule {
+    id: string;
+    evalType: string;
+    severity: string;
+}
+/**
+ * Same-name redeploy (#373). Two rules with one name both fire, and their
+ * rule_results used to be indistinguishable — the same ruleName showing
+ * PASS and FAIL in one response. Refuse by default; with replace:true,
+ * retire the earlier rule(s) first so the name means one thing again. The
+ * store keeps the audit trail either way.
+ *
+ * One function for both deploy surfaces — the `deploy_rule` tool and the
+ * dashboard's `POST /api/v1/rules/custom` — so the semantics and the
+ * wording cannot drift between them. Returns the rules it retired (empty
+ * when the name was free); throws DuplicateRuleNameError when the name is
+ * taken and `replace` is false. Nothing is deployed by this function.
+ */
+export declare function retireSameNamedRules(store: CustomRuleStore, engine: EvalEngine, tenantId: TenantId, name: string, replace: boolean, user: string): ReplacedRule[];
+/** The `warning` both deploy surfaces attach when a replace retired rules. */
+export declare function replacedRulesWarning(name: string, replaced: ReplacedRule[]): string;
 export declare function registerDeployRuleTool(server: McpServer, customRuleStore: CustomRuleStore, evalEngine: EvalEngine): void;

package/dist/tools/deploy-rule.js

@@ -7,16 +7,82 @@
  *
  * Writes to ~/.iris/custom-rules.json (single source of truth) and
  * appends to the audit log. Persisted rules auto-load on server boot
- * and fire on every future evaluate_output call of the matching
- * eval_type.
+ * and fire on every future evaluate_output call whose eval_type equals
+ * the rule's evalType (or eval_type="all").
  */
 import { z } from 'zod';
 import { createCustomRule } from '../eval/rules/custom.js';
 import { LOCAL_TENANT } from '../types/tenant.js';
-import { strictInput } from './strict-input.js';
-const CustomRuleDefinitionSchema = z.object({
-    name: z.string(),
-    type: z.enum([
+import { strictInput, strictNested } from './strict-input.js';
+const EvalTypeSchema = z.enum(['completeness', 'relevance', 'safety', 'cost', 'custom']);
+/**
+ * A rule with this name is already deployed and the caller did not ask to
+ * replace it. Carries the existing rule(s) so an HTTP surface can answer
+ * 409 with them beside the same message the MCP tool throws.
+ */
+export class DuplicateRuleNameError extends Error {
+    existing;
+    constructor(name, existing) {
+        const listed = existing
+            .map((r) => `${r.id} (eval_type ${r.evalType}, severity ${r.severity}, ${r.enabled ? 'enabled' : 'disabled'})`)
+            .join('; ');
+        super(`A rule named "${name}" is already deployed: ${listed}. Deploying a second rule with the same name ` +
+            'would make both fire with indistinguishable rule_results. Pass replace: true to delete the existing rule ' +
+            'and deploy this one in its place, call delete_rule first, or choose a different name. Nothing was deployed.');
+        this.name = 'DuplicateRuleNameError';
+        this.existing = existing;
+    }
+}
+/**
+ * Same-name redeploy (#373). Two rules with one name both fire, and their
+ * rule_results used to be indistinguishable — the same ruleName showing
+ * PASS and FAIL in one response. Refuse by default; with replace:true,
+ * retire the earlier rule(s) first so the name means one thing again. The
+ * store keeps the audit trail either way.
+ *
+ * One function for both deploy surfaces — the `deploy_rule` tool and the
+ * dashboard's `POST /api/v1/rules/custom` — so the semantics and the
+ * wording cannot drift between them. Returns the rules it retired (empty
+ * when the name was free); throws DuplicateRuleNameError when the name is
+ * taken and `replace` is false. Nothing is deployed by this function.
+ */
+export function retireSameNamedRules(store, engine, tenantId, name, replace, user) {
+    const sameName = store.list(tenantId).filter((r) => r.name === name);
+    if (sameName.length === 0)
+        return [];
+    if (!replace)
+        throw new DuplicateRuleNameError(name, sameName);
+    const replaced = [];
+    for (const old of sameName) {
+        if (store.delete(tenantId, old.id, user)) {
+            engine.unregisterRule(old.id);
+            replaced.push({ id: old.id, evalType: old.evalType, severity: old.severity });
+        }
+    }
+    return replaced;
+}
+/** The `warning` both deploy surfaces attach when a replace retired rules. */
+export function replacedRulesWarning(name, replaced) {
+    return (`Replaced ${replaced.length} previously deployed rule(s) named "${name}" ` +
+        `(${replaced.map((r) => r.id).join(', ')}); they no longer fire. Their audit rows are preserved.`);
+}
+/*
+ * Strict one level down, like evaluate_output's custom_rules entries
+ * (#376): a misspelled `wieght` used to be dropped silently. `config`
+ * stays free-form (its keys depend on `type` and are validated by the
+ * store at deploy time). `name` is optional: the server always overwrites
+ * it with the top-level rule name (#377), so requiring a value that is
+ * then discarded only invited a mismatch.
+ */
+const CustomRuleDefinitionSchema = strictNested({
+    name: z
+        .string()
+        .min(1)
+        .max(80)
+        .optional()
+        .describe('Optional and IGNORED if given — the server overwrites it with the top-level `name` so the rule reports under one name everywhere'),
+    type: z
+        .enum([
         'regex_match',
         'regex_no_match',
         'min_length',
@@ -25,55 +91,81 @@ const CustomRuleDefinitionSchema = z.object({
         'excludes_keywords',
         'json_schema',
         'cost_threshold',
-    ]),
-    config: z.record(z.string(), z.unknown()),
-    weight: z.number().optional(),
-});
+    ])
+        .describe('Check type — decides which config keys are required'),
+    config: z
+        .record(z.string(), z.unknown())
+        .describe('Check configuration; required keys depend on type (regex_match: pattern; min_length: min_length; max_length: max_length; contains_keywords/excludes_keywords: keywords; cost_threshold: max_cost; json_schema: none)'),
+    weight: z.number().positive().optional().describe('Weight in the weighted score (default 1; must be > 0)'),
+}, 'definition');
 const inputSchema = {
     // 80 mirrors the persisted store's cap (custom-rule-store.ts). The tool
     // used to allow 120, so a 100-char name passed the tool schema and then
     // surfaced the store's ZodError as a raw 500 (#332). One limit, enforced
     // at the boundary, fails cleanly as a 400.
-    name: z.string().min(1).max(80).describe('Human-readable rule name (1-80 chars; used in eval results)'),
+    name: z.string().min(1).max(80).describe('Human-readable rule name (1-80 chars; used in eval results). Must be unique among deployed rules unless replace=true'),
     description: z
         .string()
         .max(500)
         .optional()
         .describe('What this rule checks for and why it matters'),
-    evalType: z
-        .enum(['completeness', 'relevance', 'safety', 'cost', 'custom'])
-        .describe('Eval category this rule belongs to; determines when it fires'),
+    eval_type: EvalTypeSchema.optional().describe('Eval category this rule belongs to; the rule fires on evaluate_output calls whose eval_type equals it (and on eval_type="all"). Canonical snake_case spelling — pass exactly one of eval_type / evalType'),
+    evalType: EvalTypeSchema.optional().describe('camelCase alias of eval_type, accepted for compatibility — prefer eval_type (snake_case is canonical across the tools)'),
     severity: z
         .enum(['low', 'medium', 'high', 'critical'])
         .default('medium')
         .describe('What a FAILURE of this rule means. low/medium: informational — contributes to the weighted score only (plus dashboard sort + audit alerts). high/critical: hard-fail — a failing evaluation of this rule forces the overall passed=false regardless of the weighted score'),
-    definition: CustomRuleDefinitionSchema.describe('Check definition (regex, length, keyword, cost, or schema)'),
+    definition: CustomRuleDefinitionSchema.describe('Check definition (regex, length, keyword, cost, or schema). Accepts exactly type, config, weight and an optional name — an unknown key is rejected'),
+    source_moment_id: z
+        .string()
+        .optional()
+        .describe('Optional Decision Moment ID the rule was derived from (preserves workflow-inversion provenance). Canonical snake_case — pass exactly one of source_moment_id / sourceMomentId'),
     sourceMomentId: z
         .string()
         .optional()
-        .describe('Optional Decision Moment ID the rule was derived from (preserves workflow-inversion provenance)'),
+        .describe('camelCase alias of source_moment_id, accepted for compatibility — prefer source_moment_id'),
+    replace: z
+        .boolean()
+        .default(false)
+        .describe('When a rule with this name is already deployed: false (default) rejects the call; true deletes the existing same-named rule(s) and deploys this one in their place (fresh id; audit rows preserved)'),
 };
+/*
+ * Exactly one spelling of each aliased argument. Both spellings present
+ * (even with equal values) is refused rather than reconciled — a caller
+ * sending both has a bug somewhere, and silently picking one hides it.
+ */
+const inputSchemaWithAliases = strictInput(inputSchema).superRefine((args, ctx) => {
+    if (args.eval_type === undefined && args.evalType === undefined) {
+        ctx.addIssue({ code: 'custom', path: ['eval_type'], message: 'eval_type is required (evalType is the accepted camelCase alias)' });
+    }
+    else if (args.eval_type !== undefined && args.evalType !== undefined) {
+        ctx.addIssue({ code: 'custom', path: ['evalType'], message: 'pass either eval_type or evalType, not both' });
+    }
+    if (args.source_moment_id !== undefined && args.sourceMomentId !== undefined) {
+        ctx.addIssue({ code: 'custom', path: ['sourceMomentId'], message: 'pass either source_moment_id or sourceMomentId, not both' });
+    }
+});
 export function registerDeployRuleTool(server, customRuleStore, evalEngine) {
     server.registerTool('deploy_rule', {
         title: 'Deploy Custom Rule',
         description: [
             'Deploy a new custom evaluation rule that will fire on every future evaluate_output call of its eval category.',
             '',
-            'Sibling tools — list_rules enumerates deployed rules, delete_rule removes them, evaluate_output runs them. log_trace / get_traces / delete_trace handle the trace lifecycle separately; evaluate_with_llm_judge / verify_citations run semantic scoring (not heuristic-rule-driven). deploy_rule is the WRITE path that grows the custom-rule library.',
+            'Sibling tools — list_rules enumerates deployed rules, delete_rule removes them (or disables/re-enables them with its `enabled` argument), evaluate_output runs them. log_trace / get_traces / delete_trace handle the trace lifecycle separately; evaluate_with_llm_judge / verify_citations run semantic scoring (not heuristic-rule-driven). deploy_rule is the WRITE path that grows the custom-rule library.',
             '',
-            'Behavior. Writes a row to ~/.iris/custom-rules.json (atomic write via temp file + rename) and appends a `rule.deploy` entry to the audit log (~/.iris/audit.log). The rule activates immediately for the running process and persists across restarts. Each call mints a fresh rule_id; not idempotent (deploying twice creates two rules). Tenant-scoped in Cloud tier; OSS rules are owned by LOCAL_TENANT. Rate-limited to 20 req/min on HTTP MCP.',
+            'Behavior. Writes a row to ~/.iris/custom-rules.json (atomic write via temp file + rename) and appends a `rule.deploy` entry to the audit log (~/.iris/audit.log). The rule activates immediately for the running process and persists across restarts. Each call mints a fresh rule_id. Rule names are unique among deployed rules: deploying a name that is already deployed is REJECTED unless `replace: true`, in which case the existing same-named rule(s) are deleted (audit `rule.delete` rows written, unregistered from the live engine) and the new rule takes their place under a new id — the response lists what was replaced. Tenant-scoped in Cloud tier; OSS rules are owned by LOCAL_TENANT. Rate-limited to 20 req/min on HTTP MCP.',
             '',
-            'Output shape. Returns JSON: `{ "rule": { "id": "rule-XXXX", "name", "description", "evalType", "severity", "definition", "enabled": true, "createdAt", "updatedAt", "version": 1, "sourceMomentId?" } }`. The returned rule is the canonical persisted form; save the `id` if you plan to update or delete later.',
+            'Output shape. Returns JSON: `{ "rule": { "id": "rule-XXXX", "name", "description", "evalType", "severity", "definition", "enabled": true, "createdAt", "updatedAt", "version": 1, "sourceMomentId?" }, "replaced?": [{ "id", "evalType", "severity" }], "warning?": string }`. The returned rule is the canonical persisted form; save the `id` if you plan to disable or delete later. `replaced` and `warning` appear only when `replace: true` removed an earlier rule of the same name.',
             '',
-            "Use when an agent observes a recurring failure pattern and decides to enforce it as a standing rule. The `sourceMomentId` field preserves provenance — downstream audit can trace the rule back to the moment that inspired it. Combine with evaluate_output + get_traces: 1) evaluate_output surfaces failures; 2) get_traces filters to the failure set; 3) analyze the pattern; 4) deploy_rule bakes it into the default eval path.",
+            "Use when an agent observes a recurring failure pattern and decides to enforce it as a standing rule. The `source_moment_id` field preserves provenance — downstream audit can trace the rule back to the moment that inspired it. Combine with evaluate_output + get_traces: 1) evaluate_output surfaces failures; 2) get_traces filters to the failure set; 3) analyze the pattern; 4) deploy_rule bakes it into the default eval path.",
             '',
-            "Don't use to VALIDATE a rule before committing — deploy writes immediately. Use the dashboard's preview endpoint (POST /api/v1/rules/custom/preview) for dry-run validation against sample output. Don't use to EDIT an existing rule — this call only creates; edits require a dedicated flow (coming in v0.5). To update a rule today: delete_rule then deploy_rule with the new definition.",
+            "Don't use to VALIDATE a rule before committing — deploy writes immediately. Use the dashboard's preview endpoint (POST /api/v1/rules/custom/preview) to replay a definition against recent stored traces first. To UPDATE a rule: call deploy_rule with the same name and `replace: true` (the old rule is deleted, the new one gets a fresh id), or delete_rule then deploy_rule. To pause a rule without losing it: delete_rule with `enabled: false`.",
             '',
-            'Parameters. name is 1-80 chars (Zod-enforced min/max — the same cap the persisted store applies); appears in eval_result rule_results so make it human-readable. description is optional, max 500 chars (used in dashboard tooltips). evalType determines WHEN the rule fires (must match the eval_type your evaluate_output calls use; e.g., a "completeness" rule fires on every evaluate_output where eval_type="completeness" OR eval_type="custom"). severity decides what a FAILURE of the rule does: low/medium failures only lower the weighted score (and drive dashboard sort + audit alerts); high/critical failures HARD-FAIL the evaluation — the overall `passed` is forced to false regardless of the weighted score, and the rule is listed in the response\'s `critical_failures`. Severity never changes the numeric score itself (that uses the rule\'s weight). definition.type and definition.config must match (e.g., regex_match needs config.pattern; cost_threshold needs config.max_cost; min_length needs config.min_length; max_length needs config.max_length; contains_keywords/excludes_keywords need config.keywords). Invalid configs are now REJECTED at deploy time with the offending field named, instead of deploying and then failing every evaluation. sourceMomentId is optional but recommended (preserves workflow-inversion provenance from Make-This-A-Rule composer). Defaults: severity="medium".',
+            'Parameters. Argument names are snake_case (eval_type, source_moment_id) — the camelCase spellings evalType / sourceMomentId are accepted as aliases for compatibility, but pass only one spelling of each. name is 1-80 chars (Zod-enforced min/max — the same cap the persisted store applies); appears in eval_result rule_results (alongside the rule id as `ruleId`) so make it human-readable. description is optional, max 500 chars (used in dashboard tooltips). eval_type determines WHEN the rule fires: a deployed rule runs ONLY on evaluate_output calls whose eval_type equals the rule\'s eval_type, plus eval_type="all" (which runs every bundle) — a "completeness" rule does NOT fire on eval_type="safety" or on eval_type="custom"; eval_type="custom" runs rules deployed under "custom" (and the call\'s inline custom_rules) and nothing else. severity decides what a FAILURE of the rule does: low/medium failures only lower the weighted score (and drive dashboard sort + audit alerts); high/critical failures HARD-FAIL the evaluation — the overall `passed` is forced to false regardless of the weighted score, and the rule is listed in the response\'s `critical_failures`. Severity never changes the numeric score itself (that uses the rule\'s weight). definition.type and definition.config must match (e.g., regex_match needs config.pattern; cost_threshold needs config.max_cost; min_length needs config.min_length; max_length needs config.max_length; contains_keywords/excludes_keywords need config.keywords). definition.name is optional and, if given, overwritten by the top-level name. Invalid configs are REJECTED at deploy time with the offending field named, instead of deploying and then failing every evaluation. source_moment_id is optional but recommended (preserves workflow-inversion provenance from Make-This-A-Rule composer). replace defaults to false. Defaults: severity="medium", replace=false.',
             '',
-            "Error modes. Throws 400 on invalid definition (Zod rejects — e.g., regex that fails safe-regex2 ReDoS check, or length > 1000 chars). Throws 400 on empty `name` or `name` over 80 chars. Any evalType/definition.type combination is valid (a regex_match rule can enforce a safety policy; a max_length rule can express completeness) — there is no category/type mismatch error. Returns 429 when HTTP rate limit exceeded. File-write failures (disk full, read-only fs) propagate as 500; the audit log is best-effort and does not block deploy.",
+            "Error modes. Throws 400 on invalid definition (Zod rejects — e.g., regex that fails safe-regex2 ReDoS check, or length > 1000 chars), on an unknown key inside `definition` (the valid keys are listed; config keys are free-form), on empty `name` or `name` over 80 chars, on a non-positive weight, and when both spellings of an aliased argument are passed. Throws when a rule with the same name is already deployed and `replace` is not true — the message names the existing rule id so you can delete it, replace it, or pick another name. Any eval_type/definition.type combination is valid (a regex_match rule can enforce a safety policy; a max_length rule can express completeness) — there is no category/type mismatch error. Returns 429 when HTTP rate limit exceeded. File-write failures (disk full, read-only fs) propagate as 500; the audit log is best-effort and does not block deploy.",
         ].join('\n'),
-        inputSchema: strictInput(inputSchema),
+        inputSchema: inputSchemaWithAliases,
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -81,6 +173,8 @@ export function registerDeployRuleTool(server, customRuleStore, evalEngine) {
             openWorldHint: false,
         },
     }, async (args) => {
+        const evalType = (args.eval_type ?? args.evalType);
+        const sourceMomentId = args.source_moment_id ?? args.sourceMomentId;
         // Server overrides the inner definition's `name` so it always matches
         // the user-facing rule name — same normalization the dashboard's
         // deploy route applies. Also keeps the tool's 80-char cap authoritative
@@ -90,14 +184,18 @@ export function registerDeployRuleTool(server, customRuleStore, evalEngine) {
             ...args.definition,
             name: args.name,
         };
+        // Same-name redeploy (#373) — shared with the dashboard's deploy
+        // route; see retireSameNamedRules above. Throws (nothing deployed)
+        // when the name is taken and replace is false.
+        const replaced = retireSameNamedRules(customRuleStore, evalEngine, LOCAL_TENANT, args.name, args.replace, 'mcp');
         // OSS: MCP tools operate under LOCAL_TENANT. See list-rules.ts for context.
         const rule = customRuleStore.deploy(LOCAL_TENANT, {
             name: args.name,
             description: args.description,
-            evalType: args.evalType,
+            evalType,
             severity: args.severity,
             definition,
-            sourceMomentId: args.sourceMomentId,
+            sourceMomentId,
             user: 'mcp',
         });
         // Register with the live engine so the rule fires on the very next
@@ -111,7 +209,12 @@ export function registerDeployRuleTool(server, customRuleStore, evalEngine) {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify({ rule }),
+                    text: JSON.stringify({
+                        rule,
+                        ...(replaced.length > 0
+                            ? { replaced, warning: replacedRulesWarning(args.name, replaced) }
+                            : {}),
+                    }),
                 },
             ],
         };