hippo-memory 1.12.12 → 1.13.0

package/dist/predictions.js

@@ -0,0 +1,386 @@
+/**
+ * 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.ts:1196). The
+ * afterWrite hook (store.ts:1199-1201) 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 { openHippoDb, closeHippoDb } from './db.js';
+import { writeEntry, assertTenantId } from './store.js';
+import { createMemory, Layer } from './memory.js';
+import { appendAuditEvent } from './audit.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,
+        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 Error('savePrediction: classTag is required');
+    if (!opts.claimText)
+        throw new Error('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',
+        kind: 'distilled',
+        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) => {
+            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);
+            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');
+            }
+            savedRow = 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,
+                },
+            });
+        },
+    });
+    if (!savedRow) {
+        // Cannot reach here without the afterWrite throwing first; defensive.
+        throw new Error('savePrediction: afterWrite did not populate the row');
+    }
+    return rowToPrediction(savedRow);
+}
+/**
+ * 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 Error(`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 {
+            // 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) {
+                // Distinguish "not found" from "already closed" so callers (CLI, HTTP)
+                // can surface the right error to the user.
+                const existing = db.prepare(`
+          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 Error(`closePrediction: prediction ${id} is already closed (state='${existing.closure_state}'); ` +
+                    `cannot re-close. Open predictions only.`);
+            }
+            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 Error(`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,
+                },
+            });
+            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);
+    }
+}
+export function loadPredictionById(hippoRoot, tenantId, id) {
+    assertTenantId('loadPredictionById', tenantId);
+    const db = openHippoDb(hippoRoot);
+    try {
+        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 db = openHippoDb(hippoRoot);
+    try {
+        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}`);
+            }
+            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 = ?
+        ORDER BY created_at DESC, id DESC
+        LIMIT ?
+      `).all(tenantId, classTag, opts.closureState, limit);
+        }
+        else {
+            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 = ?
+        ORDER BY created_at DESC, id DESC
+        LIMIT ?
+      `).all(tenantId, classTag, 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') {
+    assertTenantId('computePredictionBaserate', tenantId);
+    if (!classTag)
+        throw new Error('computePredictionBaserate: classTag is required');
+    const db = openHippoDb(hippoRoot);
+    try {
+        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.
+            appendAuditEvent(db, {
+                tenantId,
+                actor,
+                op: 'predict_baserate',
+                targetId: classTag,
+                metadata: { class_tag: classTag, n_closed: 0 },
+            });
+            return {
+                classTag,
+                nClosed: 0,
+                nRatioEligible: 0,
+                meanEstimate: null,
+                meanActual: null,
+                meanRatio: null,
+                p50Ratio: null,
+                mae: null,
+                summary: '',
+            };
+        }
+        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)}).`;
+        appendAuditEvent(db, {
+            tenantId,
+            actor,
+            op: 'predict_baserate',
+            targetId: classTag,
+            metadata: { class_tag: classTag, n_closed: nClosed },
+        });
+        return {
+            classTag,
+            nClosed,
+            nRatioEligible,
+            meanEstimate,
+            meanActual,
+            meanRatio,
+            p50Ratio,
+            mae,
+            summary,
+        };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+export function loadOpenPredictions(hippoRoot, tenantId, opts = {}) {
+    assertTenantId('loadOpenPredictions', tenantId);
+    const limit = opts.limit ?? 100;
+    const db = openHippoDb(hippoRoot);
+    try {
+        let rows;
+        if (opts.classTag) {
+            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'
+        ORDER BY created_at DESC, id DESC
+        LIMIT ?
+      `).all(tenantId, opts.classTag, limit);
+        }
+        else {
+            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'
+        ORDER BY created_at DESC, id DESC
+        LIMIT ?
+      `).all(tenantId, limit);
+        }
+        return rows.map(rowToPrediction);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=predictions.js.map

package/dist/predictions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"predictions.js","sourceRoot":"","sources":["../src/predictions.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AA8GA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA0HD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAMrE;AAw1CD;;;;;;;;;;GAUG;AACH,wBAAsB,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAyIlE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AA2HA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA0HD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAMrE;AAqgDD;;;;;;;;;;GAUG;AACH,wBAAsB,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAyIlE"}

package/dist/server.js

@@ -7,6 +7,7 @@ import { PACKAGE_VERSION } from './version.js';
 import { validateApiKey } from './auth.js';
 import { createRateLimiter } from './rate-limit.js';
 import { remember, recall, RecallContractError, drillDown, assemble, forget, promote, supersede, archiveRaw, authCreate, authList, authRevoke, auditList, outcome, outcomeForLastRecall, getContext, sleep, adminActor, } from './api.js';
+import { savePrediction, closePrediction, loadPredictionById, loadPredictionsByClass, loadOpenPredictions, computePredictionBaserate, VALID_CLOSURE_STATES, } from './predictions.js';
 import { handleMcpRequest } from './mcp/server.js';
 import { verifySlackSignature } from './connectors/slack/signature.js';
 import { isSlackEventEnvelope, isSlackMessageEvent } from './connectors/slack/types.js';
@@ -52,6 +53,9 @@ const VALID_AUDIT_OPS = new Set([
     'summary_marked_dirty', // v0.30 / E1 — lockstep with AuditOp union + cli.ts VALID_AUDIT_OPS (v1.11.5 CRIT A institutional rule)
     'summary_marked_clean', // v0.30 / E3 — buildDag post-link clean op; lockstep
     'summary_rebuilt', // v0.30 / E3 — sleep-cycle rebuild op; lockstep
+    'predict_create', // v0.31 / E2 prediction first-class object — emitted by savePrediction
+    'predict_close', // v0.31 / E2 — emitted by closePrediction
+    'predict_baserate', // v0.31 / J3 — emitted by computePredictionBaserate
 ]);
 // Cap on GET /v1/audit?limit=. Matches docs/api.md (when written) and is large
 // enough to dump a small deployment's full audit log without paginating, but
@@ -880,6 +884,177 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         sendJson(res, 200, result);
         return;
     }
+    // ── E2 prediction first-class object (v0.31) ──
+    // docs/plans/2026-05-26-e2-prediction-object.md
+    //
+    // 4 routes: POST /v1/predictions (create), GET /v1/predictions (list),
+    // GET /v1/predictions/:id (show), POST /v1/predictions/:id/close (close).
+    // All Bearer-authed + tenant-scoped via buildContextWithAuth. closure_state
+    // validated against VALID_CLOSURE_STATES (3 states). DoS caps on claim
+    // (4096 chars) + closureNote (2048 chars) per v1.11.4 pattern.
+    if (method === 'POST' && path === '/v1/predictions') {
+        const body = await parseJsonBody(req);
+        const claim = body['claim'];
+        if (typeof claim !== 'string' || claim.length === 0) {
+            throw new HttpError(400, 'claim is required (non-empty string)');
+        }
+        if (claim.length > 4096) {
+            throw new HttpError(400, 'claim exceeds 4096-character cap');
+        }
+        const classTag = body['classTag'];
+        if (typeof classTag !== 'string' || classTag.length === 0) {
+            throw new HttpError(400, 'classTag is required (non-empty string)');
+        }
+        const estimate = body['estimate'];
+        let estimateValue;
+        if (estimate !== undefined && estimate !== null) {
+            if (typeof estimate !== 'number' || !Number.isFinite(estimate)) {
+                throw new HttpError(400, 'estimate must be a finite number');
+            }
+            estimateValue = estimate;
+        }
+        const unit = body['unit'];
+        let estimateUnit;
+        if (unit !== undefined && unit !== null) {
+            if (typeof unit !== 'string') {
+                throw new HttpError(400, 'unit must be a string');
+            }
+            estimateUnit = unit;
+        }
+        const targetDate = body['targetDate'];
+        let targetDateValue;
+        if (targetDate !== undefined && targetDate !== null) {
+            if (typeof targetDate !== 'string') {
+                throw new HttpError(400, 'targetDate must be an ISO date string');
+            }
+            targetDateValue = targetDate;
+        }
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const prediction = savePrediction(opts.hippoRoot, ctx.tenantId, {
+            classTag,
+            claimText: claim,
+            estimateValue,
+            estimateUnit,
+            targetDate: targetDateValue,
+        }, ctx.actor.subject);
+        sendJson(res, 201, { prediction });
+        return;
+    }
+    if (method === 'GET' && path === '/v1/predictions') {
+        const classTag = query.get('class') ?? undefined;
+        const status = query.get('status') ?? 'all';
+        const limitRaw = query.get('limit');
+        let limit = 100;
+        if (limitRaw !== null) {
+            limit = Number(limitRaw);
+            if (!Number.isFinite(limit) || limit <= 0 || limit > 1000) {
+                throw new HttpError(400, 'limit must be a positive integer <= 1000');
+            }
+        }
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        let predictions;
+        if (status === 'all') {
+            if (classTag) {
+                predictions = loadPredictionsByClass(opts.hippoRoot, ctx.tenantId, classTag, { limit });
+            }
+            else {
+                predictions = loadOpenPredictions(opts.hippoRoot, ctx.tenantId, { limit });
+            }
+        }
+        else if (status === 'open') {
+            predictions = loadOpenPredictions(opts.hippoRoot, ctx.tenantId, {
+                classTag: classTag || undefined,
+                limit,
+            });
+        }
+        else {
+            if (!VALID_CLOSURE_STATES.has(status)) {
+                throw new HttpError(400, `status must be one of: open | closed | closed-unknown | all (got "${status}")`);
+            }
+            if (!classTag) {
+                throw new HttpError(400, 'status filter (non-open) requires class param');
+            }
+            predictions = loadPredictionsByClass(opts.hippoRoot, ctx.tenantId, classTag, {
+                closureState: status,
+                limit,
+            });
+        }
+        sendJson(res, 200, { predictions });
+        return;
+    }
+    // J3 reference-class / planning-fallacy detector (v0.31).
+    // Order matters: this must match BEFORE /v1/predictions/:id since 'stats'
+    // is not a number — the :id regex requires \d+ so they don't conflict,
+    // but routing this first avoids the dispatch order risk.
+    if (method === 'GET' && path === '/v1/predictions/stats') {
+        const classTag = query.get('class');
+        if (!classTag || classTag.length === 0) {
+            throw new HttpError(400, 'class param is required');
+        }
+        if (classTag.length > 256) {
+            throw new HttpError(400, 'class exceeds 256-character cap');
+        }
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const baserate = computePredictionBaserate(opts.hippoRoot, ctx.tenantId, classTag, ctx.actor.subject);
+        sendJson(res, 200, { baserate });
+        return;
+    }
+    const predictionByIdMatch = path.match(/^\/v1\/predictions\/(\d+)$/);
+    if (method === 'GET' && predictionByIdMatch) {
+        const id = parseInt(predictionByIdMatch[1], 10);
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const prediction = loadPredictionById(opts.hippoRoot, ctx.tenantId, id);
+        if (!prediction) {
+            throw new HttpError(404, `prediction ${id} not found`);
+        }
+        sendJson(res, 200, { prediction });
+        return;
+    }
+    const predictionCloseMatch = path.match(/^\/v1\/predictions\/(\d+)\/close$/);
+    if (method === 'POST' && predictionCloseMatch) {
+        const id = parseInt(predictionCloseMatch[1], 10);
+        const body = await parseJsonBody(req);
+        const state = body['state'];
+        if (typeof state !== 'string' || !VALID_CLOSURE_STATES.has(state) || state === 'open') {
+            throw new HttpError(400, 'state is required and must be one of: closed | closed-unknown');
+        }
+        const actual = body['actual'];
+        let actualValue;
+        if (actual !== undefined && actual !== null) {
+            if (typeof actual !== 'number' || !Number.isFinite(actual)) {
+                throw new HttpError(400, 'actual must be a finite number');
+            }
+            actualValue = actual;
+        }
+        const note = body['note'];
+        let closureNote;
+        if (note !== undefined && note !== null) {
+            if (typeof note !== 'string') {
+                throw new HttpError(400, 'note must be a string');
+            }
+            if (note.length > 2048) {
+                throw new HttpError(400, 'note exceeds 2048-character cap');
+            }
+            closureNote = note;
+        }
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        try {
+            const prediction = closePrediction(opts.hippoRoot, ctx.tenantId, id, {
+                closureState: state,
+                actualValue,
+                closureNote,
+            }, ctx.actor.subject);
+            sendJson(res, 200, { prediction });
+        }
+        catch (e) {
+            const msg = e.message;
+            if (msg.includes('not found')) {
+                throw new HttpError(404, msg);
+            }
+            throw e;
+        }
+        return;
+    }
     // ── POST /v1/connectors/slack/events ──
     //
     // Slack Events API webhook. Auth is signature-based (HMAC over the raw