hippo-memory 1.56.0 → 1.58.0

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.d.ts

@@ -267,4 +267,23 @@ export declare function createSuccessor(old: MemoryEntry, content: string, opts:
  * Rare shared tags signal stronger schema fit than common ones.
  */
 export declare function computeSchemaFit(content: string, tags: string[], existingEntries: MemoryEntry[]): number;
+/**
+ * Update retrieval metadata on entries that were returned by a search.
+ * Returns the mutated copies (caller must persist to disk).
+ *
+ * EVAL-ONLY ablation (see ablation.ts): with HIPPO_ABLATE_RECALL_BOOST set,
+ * this returns the entries UNMUTATED - neutralizing all three strengthening
+ * sub-effects (clock reset, retrieval_count, half-life increment) at the
+ * single shared write site. The entries (not an empty array) must be
+ * returned because callers derive `last_retrieval_ids` from the return
+ * value, and a later `hippo outcome --good/--bad` targets those ids - an
+ * empty return would silently co-ablate the outcome channel in the
+ * strengthen-off arm. PERSISTENCE is gated separately at
+ * each persisting caller (CLI recall, api context, MCP recall/context,
+ * consolidation replay): writeEntry on identical rows still refreshes
+ * updated_at, rewrites mirrors, and marks DAG parents dirty,
+ * so those write loops skip under the flag.
+ * The default `now` honors HIPPO_FAKE_NOW (simulated-time protocols).
+ */
+export declare function markRetrieved(entries: MemoryEntry[], now?: Date): MemoryEntry[];
 //# sourceMappingURL=memory.d.ts.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;
@@ -471,4 +472,42 @@ function inferValence(tags) {
         return 'positive';
     return 'neutral';
 }
+/**
+ * Update retrieval metadata on entries that were returned by a search.
+ * Returns the mutated copies (caller must persist to disk).
+ *
+ * EVAL-ONLY ablation (see ablation.ts): with HIPPO_ABLATE_RECALL_BOOST set,
+ * this returns the entries UNMUTATED - neutralizing all three strengthening
+ * sub-effects (clock reset, retrieval_count, half-life increment) at the
+ * single shared write site. The entries (not an empty array) must be
+ * returned because callers derive `last_retrieval_ids` from the return
+ * value, and a later `hippo outcome --good/--bad` targets those ids - an
+ * empty return would silently co-ablate the outcome channel in the
+ * strengthen-off arm. PERSISTENCE is gated separately at
+ * each persisting caller (CLI recall, api context, MCP recall/context,
+ * consolidation replay): writeEntry on identical rows still refreshes
+ * updated_at, rewrites mirrors, and marks DAG parents dirty,
+ * so those write loops skip under the flag.
+ * The default `now` honors HIPPO_FAKE_NOW (simulated-time protocols).
+ */
+// Confidence is deliberately absent below: it is an epistemic tier, not a
+// recency signal, and a stored 'stale' is always a deliberate mark.
+export function markRetrieved(entries, now = evalNow()) {
+    if (isRecallBoostAblated())
+        return entries;
+    return entries.map((e) => {
+        if (e.superseded_by)
+            return e;
+        const wrong = netWrong(e) > 0;
+        const updated = {
+            ...e,
+            retrieval_count: e.retrieval_count + 1,
+            last_retrieved: wrong ? e.last_retrieved : now.toISOString(),
+            // +2 days half-life per retrieval (PLAN.md); a wrong memory keeps both, since last_retrieved is the decay anchor
+            half_life_days: wrong ? e.half_life_days : e.half_life_days + 2,
+        };
+        updated.strength = calculateStrength(updated, now);
+        return updated;
+    });
+}
 //# sourceMappingURL=memory.js.map

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,8 +36,10 @@
  * 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, assertTenantId } from './store.js';
+import { writeEntry } from './store.js';
+import { assertTenantId } from './tenant.js';
 import { markGraphDirty, removeGraphEntitiesForObject } from './graph.js';
 import { createMemory, Layer } from './memory.js';
 import { appendAuditEvent } from './audit.js';
@@ -61,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();
 }
@@ -75,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 };
 }
@@ -122,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
@@ -162,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;
             }
@@ -183,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,
@@ -247,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
@@ -257,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,
@@ -314,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,8 +24,10 @@
  * (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, assertTenantId } from './store.js';
+import { writeEntry } from './store.js';
+import { assertTenantId } from './tenant.js';
 import { createMemory, Layer } from './memory.js';
 import { appendAuditEvent } from './audit.js';
 import { loadConfig } from './config.js';
@@ -71,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],
@@ -142,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);
@@ -170,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.
@@ -183,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,
@@ -238,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(`
@@ -295,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,8 +30,10 @@
  * '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, assertTenantId } from './store.js';
+import { writeEntry } from './store.js';
+import { assertTenantId } from './tenant.js';
 import { createMemory, Layer } from './memory.js';
 import { appendAuditEvent } from './audit.js';
 import { objectHalfLifeDays } from './half-life-migration.js';
@@ -57,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);
     }
@@ -142,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;
@@ -176,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;
             }
@@ -197,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,
@@ -261,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,
@@ -317,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).