hippo-memory 1.57.0 → 1.58.0

package/dist/mcp/server.js

@@ -39,6 +39,7 @@ export function __resetSessionRecallHistoryMcp() {
 import { openHippoDb, closeHippoDb } from '../db.js';
 import { recordTokenUse } from '../token-ledger.js';
 import { PACKAGE_VERSION } from '../version.js';
+import { validateToolArgs } from './tool-args.js';
 // ── Find hippo root ──
 /** Same bounded walk as the CLI (ends at home, so HIPPO_HOME wins over ~/.hippo); cwd/opts are the test seam. */
 export function findHippoRoot(cwd = process.cwd(), opts) {
@@ -205,6 +206,10 @@ function planningSection(r) {
     return '';
 }
 // ── Tool definitions ──
+// HTTP sets no budget cap; 25x the 4000 recall default leaves room for large-context clients while bounding one call's work.
+const MAX_BUDGET_TOKENS = 100_000;
+// Same ceiling as the HTTP list routes' parseListLimit.
+const MAX_LIST_LIMIT = 1000;
 const TOOLS = [
     {
         name: 'hippo_recall',
@@ -213,7 +218,12 @@ const TOOLS = [
             type: 'object',
             properties: {
                 query: { type: 'string', description: 'What to search for in memory (natural language)' },
-                budget: { type: 'number', description: 'Max tokens to return (default: config.defaultBudget, 4000)' },
+                budget: {
+                    type: 'number',
+                    minimum: 0,
+                    maximum: MAX_BUDGET_TOKENS,
+                    description: `Max tokens to return (default: config.defaultBudget, 4000; max ${MAX_BUDGET_TOKENS})`,
+                },
                 include_continuity: {
                     type: 'boolean',
                     description: 'Append continuity context (active snapshot + handoff + last 5 session events) below the memory results. Useful at session boot.',
@@ -259,7 +269,9 @@ const TOOLS = [
                 },
                 budget: {
                     type: 'number',
-                    description: 'Token budget for the assembled context (default 4000). Eviction kicks in over budget.',
+                    minimum: 0,
+                    maximum: MAX_BUDGET_TOKENS,
+                    description: `Token budget for the assembled context (default 4000; max ${MAX_BUDGET_TOKENS}). Eviction kicks in over budget.`,
                 },
                 fresh_tail_count: {
                     type: 'number',
@@ -289,11 +301,15 @@ const TOOLS = [
                 },
                 limit: {
                     type: 'number',
-                    description: 'Max children to return (default 50).',
+                    minimum: 0,
+                    maximum: MAX_LIST_LIMIT,
+                    description: `Max children to return (default 50; max ${MAX_LIST_LIMIT}).`,
                 },
                 budget: {
                     type: 'number',
-                    description: 'Max total token cost (~ chars/4) of returned children. Truncates chronologically.',
+                    minimum: 0,
+                    maximum: MAX_BUDGET_TOKENS,
+                    description: `Max total token cost (~ chars/4) of returned children (max ${MAX_BUDGET_TOKENS}). Truncates chronologically.`,
                 },
                 depth: {
                     type: 'integer',
@@ -342,7 +358,12 @@ const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
-                budget: { type: 'number', minimum: 0, description: 'Max tokens (default: config.defaultContextBudget, 3000)' },
+                budget: {
+                    type: 'number',
+                    minimum: 0,
+                    maximum: MAX_BUDGET_TOKENS,
+                    description: `Max tokens (default: config.defaultContextBudget, 3000; max ${MAX_BUDGET_TOKENS})`,
+                },
                 scope: {
                     type: 'string',
                     description: 'Restrict memories, snapshot, handoff and trail to this scope exactly. When omitted, default-deny applies to ANY <source>:private:* (slack, github, ...) and unknown-legacy rows.',
@@ -426,6 +447,9 @@ const TOOLS = [
         },
     },
 ];
+const TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
+// api.retrieve rejects these itself, so MCP and HTTP callers get the same typed error code for the same bad value.
+const ARGS_CHECKED_BY_API = new Map([['hippo_recall', new Set(['scorer_window'])]]);
 // ── Track last recalled IDs for outcome feedback ──
 //
 // Keyed per-client so two HTTP-MCP clients hitting the same tenant cannot
@@ -522,12 +546,7 @@ async function executeTool(name, args, ctx) {
             const summarizeOverflow = isJsonBoolean(args.summarize_overflow)
                 ? args.summarize_overflow
                 : undefined;
-            // v1.7.2 T4 — scorer_window: Number-coerce so non-numeric input
-            // (string 'abc', boolean, etc.) reaches api.retrieve() and produces
-            // the same typed RecallContractError(code='invalid_scorer_window')
-            // as HTTP. Codex CRITICAL[2]: do NOT use `typeof === 'number'` — that
-            // would silently default-200 on string `"5"` while HTTP 400s on the
-            // same value. Both transports must agree.
+            // Number-coerce, never typeof-check: "abc" must reach api.retrieve and fail as invalid_scorer_window, the same code HTTP returns.
             const scorerWindow = args.scorer_window === undefined
                 ? undefined
                 : Number(args.scorer_window);
@@ -760,17 +779,8 @@ async function executeTool(name, args, ctx) {
                 return 'No summary_id provided.';
             const limit = Number(args.limit);
             const budget = Number(args.budget);
-            // v0.30 / E5: depth walks N levels (default 1, hard cap 10).
-            // independent-review MED #5 fold: reject out-of-range explicitly
-            // (no silent clamp) so MCP callers see the constraint at their layer.
-            let depth;
-            if (args.depth !== undefined) {
-                const depthRaw = Number(args.depth);
-                if (!Number.isInteger(depthRaw) || depthRaw < 1 || depthRaw > 10) {
-                    return `depth must be an integer between 1 and 10 (got ${args.depth})`;
-                }
-                depth = depthRaw;
-            }
+            // The inputSchema rejects a depth outside 1..10 before this runs, so no silent clamp hides the cap.
+            const depth = args.depth === undefined ? undefined : Number(args.depth);
             const apiCtx = {
                 hippoRoot,
                 tenantId,
@@ -862,7 +872,8 @@ async function executeTool(name, args, ctx) {
             }
             const halfLife = entry?.half_life_days ?? config.defaultHalfLifeDays;
             const tagStr = entry?.tags.join(', ') || tags.join(', ') || 'none';
-            return `Remembered [${result.id}] (half-life: ${halfLife}d, tags: ${tagStr})`;
+            const warnings = (result.warnings ?? []).map((w) => `\nWarning: ${w}`).join('');
+            return `Remembered [${result.id}] (half-life: ${halfLife}d, tags: ${tagStr})${warnings}`;
         }
         case 'hippo_outcome': {
             const good = Boolean(args.good);
@@ -1043,7 +1054,8 @@ async function executeTool(name, args, ctx) {
             return peers.map((p) => `${p.project}: ${p.count} memories (latest: ${p.latest.slice(0, 10)})`).join('\n');
         }
         default:
-            return `Unknown tool: ${name}`;
+            // handleMcpRequest rejects names missing from TOOLS, so reaching here means TOOLS and this switch drifted apart.
+            throw new Error(`hippo-mcp: tool ${name} is declared but has no handler`);
     }
 }
 // ── Request handling ──
@@ -1074,8 +1086,24 @@ export async function handleMcpRequest(req, ctx) {
         case 'tools/call': {
             const nameValue = params?.name;
             const toolName = isJsonString(nameValue) ? nameValue : '';
+            const tool = TOOLS_BY_NAME.get(toolName);
+            if (!tool) {
+                return { jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown tool: ${toolName.slice(0, 128)}` } };
+            }
             const argumentsValue = params?.arguments;
+            if (argumentsValue !== undefined && argumentsValue !== null && !isJsonObjectRecord(argumentsValue)) {
+                return { jsonrpc: '2.0', id, error: { code: -32602, message: `${toolName}: arguments must be an object` } };
+            }
             const toolArgs = isJsonObjectRecord(argumentsValue) ? argumentsValue : {};
+            // The MCP spec reports input validation as a tool result with isError, so the model can read it and retry.
+            const problems = validateToolArgs(tool.inputSchema, toolArgs, ARGS_CHECKED_BY_API.get(toolName));
+            if (problems.length > 0) {
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: { content: [{ type: 'text', text: `Invalid arguments for ${toolName}: ${problems.join('; ')}` }], isError: true },
+                };
+            }
             const output = await executeTool(toolName, toolArgs, ctx);
             recordMcpTokens(toolName, output, ctx);
             return {

package/dist/mcp/tool-args.d.ts

@@ -0,0 +1,21 @@
+export type ToolArgValue = string | number | boolean | null | ToolArgValue[] | {
+    [key: string]: ToolArgValue;
+};
+/** One property of a tool's inputSchema. Keywords outside this subset are not supported. */
+export interface ToolPropertySchema {
+    readonly type: 'string' | 'number' | 'integer' | 'boolean';
+    readonly description?: string;
+    readonly enum?: readonly (string | number | boolean)[];
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly maxLength?: number;
+}
+/** A tool's inputSchema: an object with named properties and an optional required list. */
+export interface ToolInputSchema {
+    readonly type: 'object';
+    readonly properties: Readonly<Record<string, ToolPropertySchema>>;
+    readonly required?: readonly string[];
+}
+/** One message per violation; undeclared properties pass, and `checkedDownstream` names keep the API layer's own error contract. */
+export declare function validateToolArgs(schema: ToolInputSchema, args: Readonly<Record<string, ToolArgValue>>, checkedDownstream?: ReadonlySet<string>): string[];
+//# sourceMappingURL=tool-args.d.ts.map

package/dist/mcp/tool-args.js

@@ -0,0 +1,80 @@
+// Hand-written for the JSON Schema subset the hippo tool definitions use, so the MCP server needs no validator dependency.
+function isArgString(v) {
+    return typeof v === 'string';
+}
+function isArgBoolean(v) {
+    return typeof v === 'boolean';
+}
+function isArgNumber(v) {
+    return typeof v === 'number' && Number.isFinite(v);
+}
+const NUMERIC_STRING = /^-?\d+(\.\d+)?$/;
+// LLM clients often send numbers as strings, and the handlers Number-coerce, so "4000" counts as 4000 while "12abc" does not.
+function asNumber(v) {
+    if (isArgNumber(v))
+        return v;
+    if (isArgString(v) && NUMERIC_STRING.test(v.trim()))
+        return Number(v.trim());
+    return null;
+}
+function describeValue(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    if (isArgString(v))
+        return JSON.stringify(v.length > 40 ? `${v.slice(0, 40)}...` : v);
+    if (isArgNumber(v) || isArgBoolean(v))
+        return String(v);
+    return 'object';
+}
+function checkProperty(name, schema, raw) {
+    const got = ` (got ${describeValue(raw)})`;
+    const isNumeric = schema.type === 'number' || schema.type === 'integer';
+    const value = isNumeric ? asNumber(raw) : raw;
+    switch (schema.type) {
+        case 'string':
+            if (!isArgString(value))
+                return `${name} must be a string${got}`;
+            if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+                return `${name} must be at most ${schema.maxLength} characters (got ${value.length})`;
+            }
+            break;
+        case 'boolean':
+            if (!isArgBoolean(value))
+                return `${name} must be a boolean${got}`;
+            break;
+        case 'number':
+        case 'integer':
+            if (value === null || !isArgNumber(value))
+                return `${name} must be a number${got}`;
+            if (schema.type === 'integer' && !Number.isInteger(value))
+                return `${name} must be an integer${got}`;
+            if (schema.minimum !== undefined && value < schema.minimum)
+                return `${name} must be >= ${schema.minimum}${got}`;
+            if (schema.maximum !== undefined && value > schema.maximum)
+                return `${name} must be <= ${schema.maximum}${got}`;
+            break;
+    }
+    if (schema.enum !== undefined && !schema.enum.some((allowed) => allowed === value)) {
+        return `${name} must be one of ${schema.enum.map((e) => JSON.stringify(e)).join(', ')}${got}`;
+    }
+    return null;
+}
+/** One message per violation; undeclared properties pass, and `checkedDownstream` names keep the API layer's own error contract. */
+export function validateToolArgs(schema, args, checkedDownstream = new Set()) {
+    const problems = [];
+    for (const name of schema.required ?? []) {
+        if (!Object.hasOwn(args, name))
+            problems.push(`${name} is required`);
+    }
+    for (const [name, propSchema] of Object.entries(schema.properties)) {
+        if (!Object.hasOwn(args, name) || checkedDownstream.has(name))
+            continue;
+        const problem = checkProperty(name, propSchema, args[name]);
+        if (problem !== null)
+            problems.push(problem);
+    }
+    return problems;
+}
+//# sourceMappingURL=tool-args.js.map

package/dist/memory.js

@@ -2,6 +2,7 @@
  * Core data model for Hippo memory entries.
  * Based on the strength formula from PLAN.md.
  */
+import { BadRequestError } from './api-errors.js';
 import { randomUUID } from 'crypto';
 import { isDecayAblated, isOutcomeSlowAblated, isRecallBoostAblated, evalNow, } from './ablation.js';
 import { AGENT_MEMORY_TOOLS, toolSourcePrefix } from './agent-memories/tools.js';
@@ -332,11 +333,11 @@ export function canAutoDelete(entry) {
 export function createMemory(content, options = {}) {
     const trimmed = content.trim();
     if (trimmed.length < 3) {
-        throw new Error(`Memory content too short (${trimmed.length} chars, minimum 3): "${trimmed}"`);
+        throw new BadRequestError(`Memory content too short (${trimmed.length} chars, minimum 3): "${trimmed}"`);
     }
     const validOutcomes = ['success', 'failure', 'partial', null];
     if (options.trace_outcome !== undefined && !validOutcomes.includes(options.trace_outcome)) {
-        throw new Error(`Invalid trace_outcome: ${options.trace_outcome}. Must be 'success', 'failure', 'partial', or null.`);
+        throw new BadRequestError(`Invalid trace_outcome: ${options.trace_outcome}. Must be 'success', 'failure', 'partial', or null.`);
     }
     const now = evalNow().toISOString(); // honors HIPPO_FAKE_NOW (eval-only)
     const layer = options.layer ?? Layer.Episodic;

package/dist/overlap-index.d.ts

@@ -0,0 +1,7 @@
+/** Smallest number of shared tokens any qualifying pair can have, given either side's token count. */
+export type MinShared = (size: number) => number;
+/** Shared >= threshold * union >= threshold * size; one token of slack covers float rounding in the caller's Jaccard check. */
+export declare function jaccardMinShared(threshold: number, atLeast?: number): MinShared;
+/** Maps i to each j > i, ascending, that may share `minShared` tokens with set i; a superset the caller checks exactly, never a pair sharing no token. */
+export declare function overlapPartners(sets: readonly ReadonlySet<string>[], minShared: MinShared): (i: number) => number[];
+//# sourceMappingURL=overlap-index.d.ts.map

package/dist/overlap-index.js

@@ -0,0 +1,38 @@
+// All-pairs overlap join through an inverted index over rare-first token prefixes (prefix filtering, Chaudhuri et al. 2006).
+/** Shared >= threshold * union >= threshold * size; one token of slack covers float rounding in the caller's Jaccard check. */
+export function jaccardMinShared(threshold, atLeast = 1) {
+    return (size) => Math.max(atLeast, Math.ceil(threshold * size) - 1);
+}
+/** Maps i to each j > i, ascending, that may share `minShared` tokens with set i; a superset the caller checks exactly, never a pair sharing no token. */
+export function overlapPartners(sets, minShared) {
+    const docFreq = new Map();
+    for (const set of sets)
+        for (const t of set)
+            docFreq.set(t, (docFreq.get(t) ?? 0) + 1);
+    const rareFirst = (a, b) => ((docFreq.get(a) ?? 0) - (docFreq.get(b) ?? 0)) || (a < b ? -1 : a > b ? 1 : 0);
+    // Under one total order the first token two sets share lies in both sets' first size - minShared + 1 tokens.
+    const prefixes = sets.map((set) => {
+        const keep = set.size - Math.max(1, minShared(set.size)) + 1;
+        return keep > 0 ? [...set].sort(rareFirst).slice(0, keep) : [];
+    });
+    const postings = new Map();
+    prefixes.forEach((prefix, i) => {
+        for (const t of prefix) {
+            const list = postings.get(t);
+            if (list)
+                list.push(i);
+            else
+                postings.set(t, [i]);
+        }
+    });
+    return (i) => {
+        const found = new Set();
+        for (const t of prefixes[i]) {
+            const list = postings.get(t) ?? [];
+            for (let k = list.length - 1; k >= 0 && list[k] > i; k--)
+                found.add(list[k]);
+        }
+        return [...found].sort((a, b) => a - b);
+    };
+}
+//# sourceMappingURL=overlap-index.js.map

package/dist/pilot-arm.d.ts

@@ -0,0 +1,9 @@
+import { type DatabaseSyncLike } from './db.js';
+export type PilotArm = 'hippo' | 'holdout';
+/** Deterministic split: the same session and rate always land in the same arm. */
+export declare function hashArm(sessionId: string, rateBp: number): PilotArm;
+/** The session's first stored arm, or null; never writes. No tenant filter: a session has one arm. */
+export declare function readPilotArm(db: DatabaseSyncLike, sessionId: string): PilotArm | null;
+/** The stored arm, else the hash arm written once; on any error the hash arm comes back unrecorded. */
+export declare function ensurePilotArm(db: DatabaseSyncLike, tenantId: string, sessionId: string, rateBp: number, now?: string): PilotArm;
+//# sourceMappingURL=pilot-arm.d.ts.map

package/dist/pilot-arm.js

@@ -0,0 +1,47 @@
+// Pilot arm: one token_ledger row per session names its arm, `hippo` or `holdout`, so a pilot can compare them.
+// `items` holds the holdout rate in basis points; readers outside this repo depend on these rows, so their shape is fixed.
+import { createHash } from 'node:crypto';
+import { execWithBusyRetry, HOOK_DB_WAIT_MS } from './db.js';
+import { recordTokenUse } from './token-ledger.js';
+/** Deterministic split: the same session and rate always land in the same arm. */
+export function hashArm(sessionId, rateBp) {
+    const bucket = parseInt(createHash('sha256').update(sessionId).digest('hex').slice(0, 8), 16) % 10000;
+    return bucket < rateBp ? 'holdout' : 'hippo';
+}
+/** The session's first stored arm, or null; never writes. No tenant filter: a session has one arm. */
+export function readPilotArm(db, sessionId) {
+    // SAFETY: the SELECT names exactly this one column.
+    const row = db.prepare(`SELECT block_hash FROM token_ledger WHERE session_id = ? AND surface = 'pilot' AND event = 'arm' ORDER BY id LIMIT 1`).get(sessionId);
+    return row?.block_hash === 'holdout' || row?.block_hash === 'hippo' ? row.block_hash : null;
+}
+/** The stored arm, else the hash arm written once; on any error the hash arm comes back unrecorded. */
+// The hook's lock-wait bound holds only on a handle opened with `busyWaitMs: HOOK_DB_WAIT_MS`, as hook commands are.
+export function ensurePilotArm(db, tenantId, sessionId, rateBp, now) {
+    const hashed = hashArm(sessionId, rateBp);
+    let began = false;
+    try {
+        // A stored row is the common case after the first prompt, so it must not take the write lock.
+        const existing = readPilotArm(db, sessionId);
+        if (existing !== null)
+            return existing;
+        execWithBusyRetry(db, 'BEGIN IMMEDIATE', HOOK_DB_WAIT_MS);
+        began = true;
+        const stored = readPilotArm(db, sessionId);
+        if (stored === null) {
+            recordTokenUse(db, { tenantId, sessionId, surface: 'pilot', event: 'arm', items: rateBp, tokens: 0, hash: hashed, now });
+        }
+        db.exec('COMMIT');
+        return stored ?? hashed;
+    }
+    catch {
+        // A prompt hook must not fail on pilot bookkeeping; concurrent callers still agree on the hash arm.
+        if (began) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* keep the hash arm */ }
+        }
+        return hashed;
+    }
+}
+//# sourceMappingURL=pilot-arm.js.map

package/dist/policies.js

@@ -36,6 +36,7 @@
  * Dual-write atomicity: `savePolicy` writes the memory + policies row (and, on
  * supersede, the predecessor's UPDATE) inside writeEntry's SAVEPOINT.
  */
+import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { writeEntry } from './store.js';
 import { assertTenantId } from './tenant.js';
@@ -62,7 +63,7 @@ export const VALID_POLICY_STATES = new Set([
 export function normalizePolicyDate(input, label = 'date') {
     const d = new Date(input);
     if (Number.isNaN(d.getTime())) {
-        throw new Error(`policy: invalid ${label} "${input}" (expected an ISO-8601 date or datetime)`);
+        throw new BadRequestError(`policy: invalid ${label} "${input}" (expected an ISO-8601 date or datetime)`);
     }
     return d.toISOString();
 }
@@ -76,7 +77,7 @@ export function validatePolicyDates(validFromRaw, validToRaw, nowIso) {
         ? normalizePolicyDate(validToRaw, 'valid_to')
         : null;
     if (validTo !== null && validTo <= validFrom) {
-        throw new Error(`policy: valid_to (${validTo}) must be strictly after valid_from (${validFrom})`);
+        throw new BadRequestError(`policy: valid_to (${validTo}) must be strictly after valid_from (${validFrom})`);
     }
     return { validFrom, validTo };
 }
@@ -123,10 +124,10 @@ function buildPolicyContent(policyName, policyText, validFrom, validTo) {
 export function savePolicy(hippoRoot, tenantId, opts, actor = 'cli') {
     assertTenantId('savePolicy', tenantId);
     if (!opts.policyName || opts.policyName.trim().length === 0) {
-        throw new Error('savePolicy: policyName is required');
+        throw new BadRequestError('savePolicy: policyName is required');
     }
     if (!opts.policyText || opts.policyText.trim().length === 0) {
-        throw new Error('savePolicy: policyText is required');
+        throw new BadRequestError('savePolicy: policyText is required');
     }
     const now = new Date().toISOString();
     // valid_from defaults to the precise creation instant (the honest effective
@@ -163,10 +164,10 @@ export function savePolicy(hippoRoot, tenantId, opts, actor = 'cli') {
                 // shape for the matching row, or undefined when no policy/tenant pair matches.
                 const pred = db.prepare(`SELECT status, version FROM policies WHERE id = ? AND tenant_id = ?`).get(opts.supersedesPolicyId, tenantId);
                 if (!pred) {
-                    throw new Error(`savePolicy: policy ${opts.supersedesPolicyId} to supersede not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`savePolicy: policy ${opts.supersedesPolicyId} to supersede not found for tenant ${tenantId}`);
                 }
                 if (pred.status !== 'active') {
-                    throw new Error(`savePolicy: policy ${opts.supersedesPolicyId} is not active (status='${pred.status}'); only active policies can be superseded.`);
+                    throw new ConflictError(`savePolicy: policy ${opts.supersedesPolicyId} is not active (status='${pred.status}'); only active policies can be superseded.`);
                 }
                 version = pred.version + 1;
             }
@@ -184,7 +185,7 @@ export function savePolicy(hippoRoot, tenantId, opts, actor = 'cli') {
           WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
         `).run(policyId, now, opts.supersedesPolicyId, tenantId, policyId);
                 if (sup.changes === 0) {
-                    throw new Error(`savePolicy: policy ${opts.supersedesPolicyId} could not be superseded (no longer active or self-reference).`);
+                    throw new ConflictError(`savePolicy: policy ${opts.supersedesPolicyId} could not be superseded (no longer active or self-reference).`);
                 }
                 appendAuditEvent(db, {
                     tenantId,
@@ -248,9 +249,9 @@ export function closePolicy(hippoRoot, tenantId, id, actor = 'cli') {
                 // shape, or undefined when the id/tenant pair doesn't exist.
                 const existing = db.prepare(`SELECT status FROM policies WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
                 if (!existing) {
-                    throw new Error(`closePolicy: policy ${id} not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`closePolicy: policy ${id} not found for tenant ${tenantId}`);
                 }
-                throw new Error(`closePolicy: policy ${id} is not active (status='${existing.status}'); only active policies can be closed.`);
+                throw new ConflictError(`closePolicy: policy ${id} is not active (status='${existing.status}'); only active policies can be closed.`);
             }
             // SAFETY: SELECT ${POLICY_COLS} projects exactly the PolicyRow columns;
             // .get() returns that row for the just-updated id, or undefined only in an
@@ -258,7 +259,7 @@ export function closePolicy(hippoRoot, tenantId, id, actor = 'cli') {
             const row = db.prepare(`SELECT ${POLICY_COLS} FROM policies WHERE id = ? AND tenant_id = ?`)
                 .get(id, tenantId);
             if (!row)
-                throw new Error(`closePolicy: policy ${id} not found after UPDATE`);
+                throw new NotFoundError(`closePolicy: policy ${id} not found after UPDATE`);
             appendAuditEvent(db, {
                 tenantId,
                 actor,
@@ -315,7 +316,7 @@ export function loadPolicies(hippoRoot, tenantId, opts = {}) {
         let rows;
         if (opts.status) {
             if (!VALID_POLICY_STATES.has(opts.status)) {
-                throw new Error(`loadPolicies: status must be one of ${Array.from(VALID_POLICY_STATES).join('|')}; got ${opts.status}`);
+                throw new BadRequestError(`loadPolicies: status must be one of ${Array.from(VALID_POLICY_STATES).join('|')}; got ${opts.status}`);
             }
             // SAFETY: SELECT ${POLICY_COLS} projects exactly the PolicyRow columns;
             // .all() returns rows in that shape regardless of the status filter applied.

package/dist/predictions.js

@@ -24,6 +24,7 @@
  * (estimate_value, actual_value) at query time. J3 is a follow-up episode;
  * this module ships the data layer.
  */
+import { BadRequestError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { writeEntry } from './store.js';
 import { assertTenantId } from './tenant.js';
@@ -72,9 +73,9 @@ function rowToPrediction(row) {
 export function savePrediction(hippoRoot, tenantId, opts, actor = 'cli') {
     assertTenantId('savePrediction', tenantId);
     if (!opts.classTag)
-        throw new Error('savePrediction: classTag is required');
+        throw new BadRequestError('savePrediction: classTag is required');
     if (!opts.claimText)
-        throw new Error('savePrediction: claimText is required');
+        throw new BadRequestError('savePrediction: claimText is required');
     const now = new Date().toISOString();
     const mem = createMemory(opts.claimText, {
         tags: ['prediction', opts.classTag],
@@ -143,7 +144,7 @@ export function savePrediction(hippoRoot, tenantId, opts, actor = 'cli') {
 export function closePrediction(hippoRoot, tenantId, id, opts, actor = 'cli') {
     assertTenantId('closePrediction', tenantId);
     if (!VALID_CLOSURE_STATES.has(opts.closureState)) {
-        throw new Error(`closePrediction: closureState must be one of ${Array.from(VALID_CLOSURE_STATES).join('|')}; got ${opts.closureState}`);
+        throw new BadRequestError(`closePrediction: closureState must be one of ${Array.from(VALID_CLOSURE_STATES).join('|')}; got ${opts.closureState}`);
     }
     const now = new Date().toISOString();
     const db = openHippoDb(hippoRoot);
@@ -171,9 +172,9 @@ export function closePrediction(hippoRoot, tenantId, id, opts, actor = 'cli') {
           SELECT closure_state FROM predictions WHERE id = ? AND tenant_id = ?
         `).get(id, tenantId);
                 if (!existing) {
-                    throw new Error(`closePrediction: prediction ${id} not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`closePrediction: prediction ${id} not found for tenant ${tenantId}`);
                 }
-                throw new Error(`closePrediction: prediction ${id} is already closed (state='${existing.closure_state}'); ` +
+                throw new BadRequestError(`closePrediction: prediction ${id} is already closed (state='${existing.closure_state}'); ` +
                     `cannot re-close. Open predictions only.`);
             }
             // SAFETY: row's shape matches the columns named in the SELECT above.
@@ -184,7 +185,7 @@ export function closePrediction(hippoRoot, tenantId, id, opts, actor = 'cli') {
         FROM predictions WHERE id = ? AND tenant_id = ?
       `).get(id, tenantId);
             if (!row) {
-                throw new Error(`closePrediction: prediction ${id} not found after UPDATE`);
+                throw new NotFoundError(`closePrediction: prediction ${id} not found after UPDATE`);
             }
             appendAuditEvent(db, {
                 tenantId,
@@ -239,7 +240,7 @@ export function loadPredictionsByClass(hippoRoot, tenantId, classTag, opts = {})
         let rows;
         if (opts.closureState) {
             if (!VALID_CLOSURE_STATES.has(opts.closureState)) {
-                throw new Error(`loadPredictionsByClass: closureState must be one of ${Array.from(VALID_CLOSURE_STATES).join('|')}; got ${opts.closureState}`);
+                throw new BadRequestError(`loadPredictionsByClass: closureState must be one of ${Array.from(VALID_CLOSURE_STATES).join('|')}; got ${opts.closureState}`);
             }
             // SAFETY: rows' shape matches the columns named in the SELECT above.
             rows = db.prepare(`
@@ -296,7 +297,7 @@ export function computePredictionBaserate(hippoRoot, tenantId, classTag, actor =
 emitAudit = true) {
     assertTenantId('computePredictionBaserate', tenantId);
     if (!classTag)
-        throw new Error('computePredictionBaserate: classTag is required');
+        throw new BadRequestError('computePredictionBaserate: classTag is required');
     const db = openHippoDb(hippoRoot);
     try {
         // SAFETY: rows' shape matches the two columns named in the SELECT above.

package/dist/processes.js

@@ -30,6 +30,7 @@
  * 'write_entry' via the afterWrite hook, so a failure in any step rolls all of
  * them back. Pattern matches saveDecision (decisions.ts).
  */
+import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { writeEntry } from './store.js';
 import { assertTenantId } from './tenant.js';
@@ -58,23 +59,23 @@ export const MAX_PROCESS_STEP_LEN = 2000;
  */
 export function validateProcessSteps(steps) {
     if (!Array.isArray(steps)) {
-        throw new Error('saveProcess: steps must be an array of strings');
+        throw new BadRequestError('saveProcess: steps must be an array of strings');
     }
     if (steps.length > MAX_PROCESS_STEPS) {
-        throw new Error(`saveProcess: steps exceeds the ${MAX_PROCESS_STEPS}-step cap (got ${steps.length})`);
+        throw new BadRequestError(`saveProcess: steps exceeds the ${MAX_PROCESS_STEPS}-step cap (got ${steps.length})`);
     }
     const out = [];
     for (let i = 0; i < steps.length; i++) {
         const raw = steps[i];
         if (!isString(raw)) {
-            throw new Error(`saveProcess: step ${i + 1} is not a string`);
+            throw new BadRequestError(`saveProcess: step ${i + 1} is not a string`);
         }
         const trimmed = raw.trim();
         if (trimmed.length === 0) {
-            throw new Error(`saveProcess: step ${i + 1} is empty`);
+            throw new BadRequestError(`saveProcess: step ${i + 1} is empty`);
         }
         if (trimmed.length > MAX_PROCESS_STEP_LEN) {
-            throw new Error(`saveProcess: step ${i + 1} exceeds the ${MAX_PROCESS_STEP_LEN}-char cap`);
+            throw new BadRequestError(`saveProcess: step ${i + 1} exceeds the ${MAX_PROCESS_STEP_LEN}-char cap`);
         }
         out.push(trimmed);
     }
@@ -143,7 +144,7 @@ function buildProcessContent(processName, steps, description) {
 export function saveProcess(hippoRoot, tenantId, opts, actor = 'cli') {
     assertTenantId('saveProcess', tenantId);
     if (!opts.processName || opts.processName.trim().length === 0) {
-        throw new Error('saveProcess: processName is required');
+        throw new BadRequestError('saveProcess: processName is required');
     }
     const steps = validateProcessSteps(opts.steps);
     const isSupersede = opts.supersedesProcessId !== undefined;
@@ -177,10 +178,10 @@ export function saveProcess(hippoRoot, tenantId, opts, actor = 'cli') {
                 // the two selected columns 1:1.
                 const pred = db.prepare(`SELECT status, version FROM processes WHERE id = ? AND tenant_id = ?`).get(opts.supersedesProcessId, tenantId);
                 if (!pred) {
-                    throw new Error(`saveProcess: process ${opts.supersedesProcessId} to supersede not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`saveProcess: process ${opts.supersedesProcessId} to supersede not found for tenant ${tenantId}`);
                 }
                 if (pred.status !== 'active') {
-                    throw new Error(`saveProcess: process ${opts.supersedesProcessId} is not active (status='${pred.status}'); only active processes can be superseded.`);
+                    throw new ConflictError(`saveProcess: process ${opts.supersedesProcessId} is not active (status='${pred.status}'); only active processes can be superseded.`);
                 }
                 version = pred.version + 1;
             }
@@ -198,7 +199,7 @@ export function saveProcess(hippoRoot, tenantId, opts, actor = 'cli') {
           WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
         `).run(processId, now, opts.supersedesProcessId, tenantId, processId);
                 if (sup.changes === 0) {
-                    throw new Error(`saveProcess: process ${opts.supersedesProcessId} could not be superseded (no longer active or self-reference).`);
+                    throw new ConflictError(`saveProcess: process ${opts.supersedesProcessId} could not be superseded (no longer active or self-reference).`);
                 }
                 appendAuditEvent(db, {
                     tenantId,
@@ -262,16 +263,16 @@ export function closeProcess(hippoRoot, tenantId, id, actor = 'cli') {
                 // single selected column.
                 const existing = db.prepare(`SELECT status FROM processes WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
                 if (!existing) {
-                    throw new Error(`closeProcess: process ${id} not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`closeProcess: process ${id} not found for tenant ${tenantId}`);
                 }
-                throw new Error(`closeProcess: process ${id} is not active (status='${existing.status}'); only active processes can be closed.`);
+                throw new ConflictError(`closeProcess: process ${id} is not active (status='${existing.status}'); only active processes can be closed.`);
             }
             // SAFETY: SELECT ${PROCESS_COLS} enumerates every ProcessRow field
             // 1:1 (see PROCESS_COLS above).
             const row = db.prepare(`SELECT ${PROCESS_COLS} FROM processes WHERE id = ? AND tenant_id = ?`)
                 .get(id, tenantId);
             if (!row)
-                throw new Error(`closeProcess: process ${id} not found after UPDATE`);
+                throw new NotFoundError(`closeProcess: process ${id} not found after UPDATE`);
             appendAuditEvent(db, {
                 tenantId,
                 actor,
@@ -318,7 +319,7 @@ export function loadProcesses(hippoRoot, tenantId, opts = {}) {
         let rows;
         if (opts.status) {
             if (!VALID_PROCESS_STATES.has(opts.status)) {
-                throw new Error(`loadProcesses: status must be one of ${Array.from(VALID_PROCESS_STATES).join('|')}; got ${opts.status}`);
+                throw new BadRequestError(`loadProcesses: status must be one of ${Array.from(VALID_PROCESS_STATES).join('|')}; got ${opts.status}`);
             }
             // SAFETY: SELECT ${PROCESS_COLS} enumerates every ProcessRow field
             // 1:1 (see PROCESS_COLS above).