hippo-memory 1.60.0 → 1.62.0

package/dist/predictions/store.js

@@ -0,0 +1,434 @@
+/**
+ * E2 prediction first-class object (v0.31 / docs/plans/2026-05-26-e2-prediction-object.md).
+ *
+ * Canonical store for ex-ante claims that can be closed against ex-post
+ * outcomes. The `predictions` table holds every field (including
+ * `claim_text`); a memory row mirrors the claim for recall/inspect surfaces
+ * but is NOT the source of truth — ON DELETE SET NULL on memory_id means
+ * memory deletion gracefully orphans the prediction without losing data.
+ *
+ * Tenant scoping: every helper requires tenantId. The schema's BEFORE INSERT
+ * + BEFORE UPDATE triggers (`trg_predictions_tenant_match_*`) enforce that
+ * `predictions.tenant_id` matches the referenced memory's tenant_id when
+ * `memory_id IS NOT NULL`. Cross-tenant references are unrepresentable at
+ * the schema level.
+ *
+ * Dual-write atomicity: `savePrediction` writes the memory + predictions
+ * row inside `writeEntry`'s SAVEPOINT 'write_entry' (store/entry-writes.ts). The
+ * afterWrite hook (store/entry-writes.ts) runs inside the same SAVEPOINT, so
+ * a failure in either step rolls back both. Pattern matches supersede
+ * (api.ts:1486) and the Slack/GitHub connectors.
+ *
+ * J3 (reference-class / planning-fallacy detector) reads from
+ * `loadPredictionsByClass` to compute per-class base rates from
+ * (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/entry-writes.js';
+import { assertTenantId } from '../tenant.js';
+import { createMemory, Layer } from '../memory.js';
+import { appendAuditEvent } from '../audit.js';
+import { loadConfig } from '../config.js';
+import { keysetAfter } from '../keyset.js';
+export const VALID_CLOSURE_STATES = new Set([
+    'open',
+    'closed',
+    'closed-unknown',
+]);
+function rowToPrediction(row) {
+    return {
+        id: row.id,
+        memoryId: row.memory_id,
+        tenantId: row.tenant_id,
+        classTag: row.class_tag,
+        claimText: row.claim_text,
+        estimateValue: row.estimate_value,
+        estimateUnit: row.estimate_unit,
+        targetDate: row.target_date,
+        actualValue: row.actual_value,
+        // SAFETY: closure_state is DB-constrained to VALID_CLOSURE_STATES; this
+        // module is the only writer and always inserts one of those literals.
+        closureState: row.closure_state,
+        closedAt: row.closed_at,
+        closureNote: row.closure_note,
+        createdAt: row.created_at,
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Create a new prediction. Writes a memory mirror + a predictions table
+ * row atomically inside `writeEntry`'s SAVEPOINT 'write_entry'. On any
+ * failure (audit write, predictions INSERT, trigger ABORT), the SAVEPOINT
+ * rolls back — neither the memory row nor the predictions row lands.
+ *
+ * The memory is tagged `['prediction', classTag]` with `source='prediction'`
+ * and `kind='distilled'`. It surfaces in `hippo recall` so the agent can
+ * see open predictions naturally; the predictions table is the canonical
+ * structured store used by J3.
+ */
+export function savePrediction(hippoRoot, tenantId, opts, actor = 'cli') {
+    assertTenantId('savePrediction', tenantId);
+    if (!opts.classTag)
+        throw new BadRequestError('savePrediction: classTag is required');
+    if (!opts.claimText)
+        throw new BadRequestError('savePrediction: claimText is required');
+    const now = new Date().toISOString();
+    const mem = createMemory(opts.claimText, {
+        tags: ['prediction', opts.classTag],
+        layer: Layer.Semantic,
+        confidence: 'observed',
+        source: 'prediction',
+        // SAFETY: 'distilled' is a valid MemoryKind literal (see memory.ts).
+        kind: 'distilled',
+        baseHalfLifeDays: loadConfig(hippoRoot).defaultHalfLifeDays,
+        tenantId,
+    });
+    // Captured for the return value; populated inside afterWrite hook so the
+    // INSERT and the memory write share a SAVEPOINT.
+    let savedRow;
+    writeEntry(hippoRoot, mem, {
+        actor,
+        afterWrite: (db, memoryId) => {
+            savedRow = insertPredictionRow(db, memoryId, tenantId, opts, now, actor);
+        },
+    });
+    if (!savedRow) {
+        // Cannot reach here without the afterWrite throwing first; defensive.
+        throw new Error('savePrediction: afterWrite did not populate the row');
+    }
+    return rowToPrediction(savedRow);
+}
+/** Inserts, reloads and audits the predictions row inside writeEntry's SAVEPOINT. */
+function insertPredictionRow(db, memoryId, tenantId, opts, now, actor) {
+    const result = db.prepare(`
+        INSERT INTO predictions(
+          memory_id, tenant_id, class_tag, claim_text,
+          estimate_value, estimate_unit, target_date,
+          actual_value, closure_state, closed_at, closure_note, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'open', NULL, NULL, ?)
+      `).run(memoryId, tenantId, opts.classTag, opts.claimText, opts.estimateValue ?? null, opts.estimateUnit ?? null, opts.targetDate ?? null, null, // actual_value — null until close
+    now);
+    const predictionId = Number(result.lastInsertRowid ?? 0);
+    // SAFETY: row's shape matches the columns named in the SELECT above.
+    const row = db.prepare(`
+        SELECT id, memory_id, tenant_id, class_tag, claim_text,
+               estimate_value, estimate_unit, target_date,
+               actual_value, closure_state, closed_at, closure_note, created_at
+        FROM predictions WHERE id = ?
+      `).get(predictionId);
+    if (!row) {
+        throw new Error('Failed to reload saved prediction row');
+    }
+    // GDPR-light audit metadata: prediction_id + class_tag + flags only.
+    // No claim_text in metadata; the predictions table holds it canonically.
+    appendAuditEvent(db, {
+        tenantId,
+        actor,
+        op: 'predict_create',
+        targetId: String(predictionId),
+        metadata: {
+            prediction_id: predictionId,
+            class_tag: opts.classTag,
+            has_estimate: opts.estimateValue !== undefined && opts.estimateValue !== null,
+            target_date: opts.targetDate ?? null,
+        },
+    });
+    return row;
+}
+/**
+ * Close an existing open prediction. Updates the predictions row only;
+ * the memory mirror is NOT mutated in v1 (predictions table is canonical).
+ * J3 computes accuracy (clean vs regressed) from (estimateValue,
+ * actualValue) at query time.
+ */
+export function closePrediction(hippoRoot, tenantId, id, opts, actor = 'cli') {
+    assertTenantId('closePrediction', tenantId);
+    if (!VALID_CLOSURE_STATES.has(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);
+    try {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const row = closeOpenPredictionRow(db, tenantId, id, opts, now, actor);
+            db.exec('COMMIT');
+            return rowToPrediction(row);
+        }
+        catch (e) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch {
+                // Ignore rollback failures — the throw below is what matters.
+            }
+            throw e;
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Closes the row, reloads it and audits the close; the caller owns the transaction. */
+function closeOpenPredictionRow(db, tenantId, id, opts, now, actor) {
+    // Codex review finding 2026-05-26: WHERE clause requires
+    // closure_state='open' so duplicate close requests / retries against
+    // an already-closed prediction return a clear error instead of
+    // silently overwriting actual_value + emitting a duplicate
+    // predict_close audit row. Zero changed rows → caller decides
+    // whether it's a "not found" or "already closed" case based on the
+    // load-then-close pattern.
+    const updateResult = db.prepare(`
+        UPDATE predictions
+        SET actual_value = ?, closure_state = ?, closed_at = ?, closure_note = ?
+        WHERE id = ? AND tenant_id = ? AND closure_state = 'open'
+      `).run(opts.actualValue ?? null, opts.closureState, now, opts.closureNote ?? null, id, tenantId);
+    if (updateResult.changes === 0)
+        throwCloseMiss(db, tenantId, id);
+    // SAFETY: row's shape matches the columns named in the SELECT above.
+    const row = db.prepare(`
+        SELECT id, memory_id, tenant_id, class_tag, claim_text,
+               estimate_value, estimate_unit, target_date,
+               actual_value, closure_state, closed_at, closure_note, created_at
+        FROM predictions WHERE id = ? AND tenant_id = ?
+      `).get(id, tenantId);
+    if (!row) {
+        throw new NotFoundError(`closePrediction: prediction ${id} not found after UPDATE`);
+    }
+    appendAuditEvent(db, {
+        tenantId,
+        actor,
+        op: 'predict_close',
+        targetId: String(id),
+        metadata: {
+            prediction_id: id,
+            closure_state: opts.closureState,
+            has_actual: opts.actualValue !== undefined && opts.actualValue !== null,
+        },
+    });
+    return row;
+}
+function throwCloseMiss(db, tenantId, id) {
+    // Distinguish "not found" from "already closed" so callers (CLI, HTTP)
+    // can surface the right error to the user.
+    // SAFETY: row shape matches the single `closure_state` column named
+    // in the SELECT above.
+    const existing = db.prepare(`
+          SELECT closure_state FROM predictions WHERE id = ? AND tenant_id = ?
+        `).get(id, tenantId);
+    if (!existing) {
+        throw new NotFoundError(`closePrediction: prediction ${id} not found for tenant ${tenantId}`);
+    }
+    throw new BadRequestError(`closePrediction: prediction ${id} is already closed (state='${existing.closure_state}'); ` +
+        `cannot re-close. Open predictions only.`);
+}
+export function loadPredictionById(hippoRoot, tenantId, id) {
+    assertTenantId('loadPredictionById', tenantId);
+    const db = openHippoDb(hippoRoot);
+    try {
+        // SAFETY: row's shape matches the columns named in the SELECT above.
+        const row = db.prepare(`
+      SELECT id, memory_id, tenant_id, class_tag, claim_text,
+             estimate_value, estimate_unit, target_date,
+             actual_value, closure_state, closed_at, closure_note, created_at
+      FROM predictions WHERE id = ? AND tenant_id = ?
+    `).get(id, tenantId);
+        return row ? rowToPrediction(row) : null;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+export function loadPredictionsByClass(hippoRoot, tenantId, classTag, opts = {}) {
+    assertTenantId('loadPredictionsByClass', tenantId);
+    const limit = opts.limit ?? 100;
+    const after = keysetAfter('created_at', 'id', opts.after);
+    const db = openHippoDb(hippoRoot);
+    try {
+        let rows;
+        if (opts.closureState) {
+            if (!VALID_CLOSURE_STATES.has(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(`
+        SELECT id, memory_id, tenant_id, class_tag, claim_text,
+               estimate_value, estimate_unit, target_date,
+               actual_value, closure_state, closed_at, closure_note, created_at
+        FROM predictions
+        WHERE tenant_id = ? AND class_tag = ? AND closure_state = ?${after.sql}
+        ORDER BY created_at DESC, id DESC
+        LIMIT ?
+      `).all(tenantId, classTag, opts.closureState, ...after.params, limit);
+        }
+        else {
+            // SAFETY: rows' shape matches the columns named in the SELECT above.
+            rows = db.prepare(`
+        SELECT id, memory_id, tenant_id, class_tag, claim_text,
+               estimate_value, estimate_unit, target_date,
+               actual_value, closure_state, closed_at, closure_note, created_at
+        FROM predictions
+        WHERE tenant_id = ? AND class_tag = ?${after.sql}
+        ORDER BY created_at DESC, id DESC
+        LIMIT ?
+      `).all(tenantId, classTag, ...after.params, limit);
+        }
+        return rows.map(rowToPrediction);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Compute base-rate stats for closed predictions in a class. Used by J3
+ * reference-class / planning-fallacy detector. Direct application of
+ * Lovallo-Kahneman (2003) inside-vs-outside view.
+ *
+ * Filter: closure_state='closed' AND estimate_value IS NOT NULL AND
+ * actual_value IS NOT NULL. Excludes closed-unknown (no actual to
+ * compare against) and open (not yet resolved).
+ *
+ * Audit-emit is BUILT IN here (single source of truth, no caller-site
+ * drift risk). Plan-eng-critic round 1 HIGH recommendation: emit inside
+ * helper, not at 3 call sites.
+ */
+export function computePredictionBaserate(hippoRoot, tenantId, classTag, actor = 'cli', 
+/** v0.32 / J3.2 — when false, skip the predict_baserate audit emit. The
+ *  J3.2 orchestrator (computePlanningFallacyOutput, below) calls this with
+ *  emitAudit=false and emits its own `recall_autodebias_hint` audit row
+ *  instead, so the predict_baserate channel stays scoped to deliberate
+ *  CLI / HTTP / MCP predict-baserate calls and does NOT pollute on every
+ *  recall containing a forward-claim phrase. Default true preserves the
+ *  v1.13.0 J3 audit semantics for the 3 direct callers (cmdPredict
+ *  baserate, /v1/predictions/stats route, hippo_predict_baserate MCP
+ *  handler) — none of them pass this argument. */
+emitAudit = true) {
+    assertTenantId('computePredictionBaserate', tenantId);
+    if (!classTag)
+        throw new BadRequestError('computePredictionBaserate: classTag is required');
+    const db = openHippoDb(hippoRoot);
+    try {
+        // SAFETY: rows' shape matches the two columns named in the SELECT above.
+        const rows = db.prepare(`
+      SELECT estimate_value, actual_value
+      FROM predictions
+      WHERE tenant_id = ?
+        AND class_tag = ?
+        AND closure_state = 'closed'
+        AND estimate_value IS NOT NULL
+        AND actual_value IS NOT NULL
+    `).all(tenantId, classTag);
+        const nClosed = rows.length;
+        if (nClosed === 0) {
+            // Audit zero-result reads too — agents probing empty classes is
+            // a signal worth recording. Skipped when emitAudit=false (J3.2
+            // orchestrator path; its own recall_autodebias_hint audit fires
+            // only when nClosed > 0 anyway, so no signal is lost).
+            if (emitAudit)
+                auditBaserateRead(db, tenantId, actor, classTag, 0);
+            return {
+                classTag,
+                nClosed: 0,
+                nRatioEligible: 0,
+                meanEstimate: null,
+                meanActual: null,
+                meanRatio: null,
+                p50Ratio: null,
+                mae: null,
+                summary: '',
+            };
+        }
+        const baserate = baserateFromRows(classTag, rows);
+        if (emitAudit)
+            auditBaserateRead(db, tenantId, actor, classTag, nClosed);
+        return baserate;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+function auditBaserateRead(db, tenantId, actor, classTag, nClosed) {
+    appendAuditEvent(db, {
+        tenantId,
+        actor,
+        op: 'predict_baserate',
+        targetId: classTag,
+        metadata: { class_tag: classTag, n_closed: nClosed },
+    });
+}
+/** Stats over a non-empty set of closed rows. */
+function baserateFromRows(classTag, rows) {
+    const nClosed = rows.length;
+    const ratioEligible = rows.filter((r) => r.estimate_value > 0);
+    const nRatioEligible = ratioEligible.length;
+    const meanEstimate = rows.reduce((s, r) => s + r.estimate_value, 0) / nClosed;
+    const meanActual = rows.reduce((s, r) => s + r.actual_value, 0) / nClosed;
+    const mae = rows.reduce((s, r) => s + Math.abs(r.actual_value - r.estimate_value), 0) / nClosed;
+    let meanRatio = null;
+    let p50Ratio = null;
+    if (nRatioEligible > 0) {
+        const ratios = ratioEligible.map((r) => r.actual_value / r.estimate_value);
+        meanRatio = ratios.reduce((s, x) => s + x, 0) / nRatioEligible;
+        const sorted = ratios.slice().sort((a, b) => a - b);
+        p50Ratio = nRatioEligible % 2 === 1
+            ? sorted[(nRatioEligible - 1) / 2]
+            : (sorted[nRatioEligible / 2 - 1] + sorted[nRatioEligible / 2]) / 2;
+    }
+    const ratioPart = meanRatio !== null
+        ? `averaged ${meanRatio.toFixed(2)}x actual`
+        : 'no ratio-eligible rows (all estimates were 0)';
+    const summary = `Last ${nClosed} estimate${nClosed === 1 ? '' : 's'} in class ${classTag} ${ratioPart} (MAE ${mae.toFixed(2)}).`;
+    return {
+        classTag,
+        nClosed,
+        nRatioEligible,
+        meanEstimate,
+        meanActual,
+        meanRatio,
+        p50Ratio,
+        mae,
+        summary,
+    };
+}
+export function loadOpenPredictions(hippoRoot, tenantId, opts = {}) {
+    assertTenantId('loadOpenPredictions', tenantId);
+    const limit = opts.limit ?? 100;
+    const after = keysetAfter('created_at', 'id', opts.after);
+    const db = openHippoDb(hippoRoot);
+    try {
+        let rows;
+        if (opts.classTag) {
+            // SAFETY: rows' shape matches the columns named in the SELECT above.
+            rows = db.prepare(`
+        SELECT id, memory_id, tenant_id, class_tag, claim_text,
+               estimate_value, estimate_unit, target_date,
+               actual_value, closure_state, closed_at, closure_note, created_at
+        FROM predictions
+        WHERE tenant_id = ? AND class_tag = ? AND closure_state = 'open'${after.sql}
+        ORDER BY created_at DESC, id DESC
+        LIMIT ?
+      `).all(tenantId, opts.classTag, ...after.params, limit);
+        }
+        else {
+            // SAFETY: rows' shape matches the columns named in the SELECT above.
+            rows = db.prepare(`
+        SELECT id, memory_id, tenant_id, class_tag, claim_text,
+               estimate_value, estimate_unit, target_date,
+               actual_value, closure_state, closed_at, closure_note, created_at
+        FROM predictions
+        WHERE tenant_id = ? AND closure_state = 'open'${after.sql}
+        ORDER BY created_at DESC, id DESC
+        LIMIT ?
+      `).all(tenantId, ...after.params, limit);
+        }
+        return rows.map(rowToPrediction);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/processes.d.ts

@@ -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 { type KeysetPosition } from './keyset.js';
 export type ProcessStatus = 'active' | 'superseded' | 'closed';
 export declare const VALID_PROCESS_STATES: ReadonlySet<ProcessStatus>;
 /** Arbitrary JSON-shaped value; the domain type for untrusted input at the
@@ -75,6 +76,8 @@ export interface SaveProcessOpts {
 export interface ListProcessesOpts {
     status?: ProcessStatus;
     limit?: number;
+    /** Resume after this row: the position the previous page ended on. */
+    after?: KeysetPosition;
 }
 /**
  * Validate + normalise the steps body. Returns the trimmed step strings

package/dist/processes.js

@@ -32,11 +32,12 @@
  */
 import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry } from './store.js';
+import { writeEntry } from './store/entry-writes.js';
 import { assertTenantId } from './tenant.js';
 import { createMemory, Layer } from './memory.js';
 import { appendAuditEvent } from './audit.js';
 import { objectHalfLifeDays } from './half-life-migration.js';
+import { keysetAfter } from './keyset.js';
 export const VALID_PROCESS_STATES = new Set([
     'active',
     'superseded',
@@ -129,9 +130,82 @@ function buildProcessContent(processName, steps, description) {
         content += `\n\nDescription: ${description}`;
     return content;
 }
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
+// Preflight the supersede target BEFORE inserting the new row. The new
+// row's autoincrement id could otherwise collide with a non-existent
+// supersedesProcessId (e.g. superseding id 1 on an empty store), making
+// the row supersede itself. Validating first means the new row is never a
+// candidate for its own supersede UPDATE. Mirrors saveDecision (codex P1
+// 2026-05-28). The same SELECT reads the predecessor version so the
+// successor's version is server-derived, never client-supplied.
+function preflightProcessSupersede(db, tenantId, supersedesId) {
+    // SAFETY: SELECT status, version FROM processes; row shape matches
+    // the two selected columns 1:1.
+    const pred = db.prepare(`SELECT status, version FROM processes WHERE id = ? AND tenant_id = ?`).get(supersedesId, tenantId);
+    if (!pred) {
+        throw new NotFoundError(`saveProcess: process ${supersedesId} to supersede not found for tenant ${tenantId}`);
+    }
+    if (pred.status !== 'active') {
+        throw new ConflictError(`saveProcess: process ${supersedesId} is not active (status='${pred.status}'); only active processes can be superseded.`);
+    }
+    return pred.version + 1;
+}
+function insertProcessRow(db, memoryId, w, version) {
+    const result = db.prepare(`
+    INSERT INTO processes(
+      memory_id, tenant_id, process_name, description, steps, version,
+      status, superseded_by, superseded_at, change_summary, closed_at, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, 'active', NULL, NULL, ?, NULL, ?)
+  `).run(memoryId, w.tenantId, w.processName, w.description ?? null, JSON.stringify(w.steps), version, w.changeSummary, w.now);
+    return Number(result.lastInsertRowid ?? 0);
+}
+function supersedeProcessRow(db, w, supersedesId, processId, version) {
+    const sup = db.prepare(`
+    UPDATE processes
+    SET status = 'superseded', superseded_by = ?, superseded_at = ?
+    WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
+  `).run(processId, w.now, supersedesId, w.tenantId, processId);
+    if (sup.changes === 0) {
+        throw new ConflictError(`saveProcess: process ${supersedesId} could not be superseded (no longer active or self-reference).`);
+    }
+    appendAuditEvent(db, {
+        tenantId: w.tenantId,
+        actor: w.actor,
+        op: 'process_supersede',
+        targetId: String(supersedesId),
+        metadata: {
+            process_id: supersedesId,
+            superseded_by: processId,
+            new_version: version,
+        },
+    });
+}
+/** The afterWrite body: preflight, INSERT, supersede, reload, create audit, all in one SAVEPOINT. */
+function writeProcessRow(db, memoryId, w) {
+    const version = w.supersedesId !== undefined ? preflightProcessSupersede(db, w.tenantId, w.supersedesId) : 1;
+    const processId = insertProcessRow(db, memoryId, w, version);
+    if (w.supersedesId !== undefined)
+        supersedeProcessRow(db, w, w.supersedesId, processId, version);
+    // 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 = ?`)
+        .get(processId);
+    if (!row)
+        throw new Error('saveProcess: failed to reload saved process row');
+    // GDPR-light metadata: ids + counts only, no process_name / step text.
+    appendAuditEvent(db, {
+        tenantId: w.tenantId,
+        actor: w.actor,
+        op: 'process_create',
+        targetId: String(processId),
+        metadata: {
+            process_id: processId,
+            version,
+            step_count: w.steps.length,
+            has_description: w.description !== undefined && w.description !== null && w.description !== '',
+        },
+    });
+    return row;
+}
 /**
  * Create a process (or a new version that supersedes an existing one). Writes
  * the memory mirror + the processes row atomically inside writeEntry's SAVEPOINT
@@ -162,78 +236,21 @@ export function saveProcess(hippoRoot, tenantId, opts, actor = 'cli') {
         baseHalfLifeDays: objectHalfLifeDays(hippoRoot),
         tenantId,
     });
+    const w = {
+        tenantId,
+        actor,
+        processName: opts.processName,
+        description: opts.description,
+        steps,
+        changeSummary,
+        supersedesId: opts.supersedesProcessId,
+        now,
+    };
     let savedRow;
     writeEntry(hippoRoot, mem, {
         actor,
         afterWrite: (db, memoryId) => {
-            // Preflight the supersede target BEFORE inserting the new row. The new
-            // row's autoincrement id could otherwise collide with a non-existent
-            // supersedesProcessId (e.g. superseding id 1 on an empty store), making
-            // the row supersede itself. Validating first means the new row is never a
-            // candidate for its own supersede UPDATE. Mirrors saveDecision (codex P1
-            // 2026-05-28). The same SELECT reads the predecessor version so the
-            // successor's version is server-derived, never client-supplied.
-            let version = 1;
-            if (opts.supersedesProcessId !== undefined) {
-                // SAFETY: SELECT status, version FROM processes; row shape matches
-                // 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 NotFoundError(`saveProcess: process ${opts.supersedesProcessId} to supersede not found for tenant ${tenantId}`);
-                }
-                if (pred.status !== 'active') {
-                    throw new ConflictError(`saveProcess: process ${opts.supersedesProcessId} is not active (status='${pred.status}'); only active processes can be superseded.`);
-                }
-                version = pred.version + 1;
-            }
-            const result = db.prepare(`
-        INSERT INTO processes(
-          memory_id, tenant_id, process_name, description, steps, version,
-          status, superseded_by, superseded_at, change_summary, closed_at, created_at
-        ) VALUES (?, ?, ?, ?, ?, ?, 'active', NULL, NULL, ?, NULL, ?)
-      `).run(memoryId, tenantId, opts.processName, opts.description ?? null, JSON.stringify(steps), version, changeSummary, now);
-            const processId = Number(result.lastInsertRowid ?? 0);
-            if (opts.supersedesProcessId !== undefined) {
-                const sup = db.prepare(`
-          UPDATE processes
-          SET status = 'superseded', superseded_by = ?, superseded_at = ?
-          WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
-        `).run(processId, now, opts.supersedesProcessId, tenantId, processId);
-                if (sup.changes === 0) {
-                    throw new ConflictError(`saveProcess: process ${opts.supersedesProcessId} could not be superseded (no longer active or self-reference).`);
-                }
-                appendAuditEvent(db, {
-                    tenantId,
-                    actor,
-                    op: 'process_supersede',
-                    targetId: String(opts.supersedesProcessId),
-                    metadata: {
-                        process_id: opts.supersedesProcessId,
-                        superseded_by: processId,
-                        new_version: version,
-                    },
-                });
-            }
-            // 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 = ?`)
-                .get(processId);
-            if (!row)
-                throw new Error('saveProcess: failed to reload saved process row');
-            savedRow = row;
-            // GDPR-light metadata: ids + counts only, no process_name / step text.
-            appendAuditEvent(db, {
-                tenantId,
-                actor,
-                op: 'process_create',
-                targetId: String(processId),
-                metadata: {
-                    process_id: processId,
-                    version,
-                    step_count: steps.length,
-                    has_description: opts.description !== undefined && opts.description !== null && opts.description !== '',
-                },
-            });
+            savedRow = writeProcessRow(db, memoryId, w);
         },
     });
     if (!savedRow) {
@@ -315,6 +332,7 @@ export function loadProcessById(hippoRoot, tenantId, id) {
 export function loadProcesses(hippoRoot, tenantId, opts = {}) {
     assertTenantId('loadProcesses', tenantId);
     const limit = opts.limit ?? 100;
+    const after = keysetAfter('created_at', 'id', opts.after);
     const db = openHippoDb(hippoRoot);
     try {
         let rows;
@@ -326,20 +344,20 @@ export function loadProcesses(hippoRoot, tenantId, opts = {}) {
             // 1:1 (see PROCESS_COLS above).
             rows = db.prepare(`
         SELECT ${PROCESS_COLS} FROM processes
-        WHERE tenant_id = ? AND status = ?
+        WHERE tenant_id = ? AND status = ?${after.sql}
         ORDER BY created_at DESC, id DESC
         LIMIT ?
-      `).all(tenantId, opts.status, limit);
+      `).all(tenantId, opts.status, ...after.params, limit);
         }
         else {
             // SAFETY: SELECT ${PROCESS_COLS} enumerates every ProcessRow field
             // 1:1 (see PROCESS_COLS above).
             rows = db.prepare(`
         SELECT ${PROCESS_COLS} FROM processes
-        WHERE tenant_id = ?
+        WHERE tenant_id = ?${after.sql}
         ORDER BY created_at DESC, id DESC
         LIMIT ?
-      `).all(tenantId, limit);
+      `).all(tenantId, ...after.params, limit);
         }
         return rows.map(rowToProcess);
     }