hippo-memory 1.60.0 → 1.61.0

package/dist/server/routes/incidents.js

@@ -0,0 +1,126 @@
+// /v1/incidents routes.
+import { closeIncident, loadIncidentById, loadIncidents, resolveIncident, saveIncident, VALID_INCIDENT_STATES } from '../../incidents.js';
+import { HttpError, sendJson } from '../../http-util.js';
+import { NotFoundError } from '../../api-errors.js';
+import { buildContextWithAuth } from '../auth.js';
+import { byCreatedAt, pageOf, parseCursor } from '../cursor.js';
+import { isJsonString, isSetMember, parseJsonBody, parseListLimit } from '../validation.js';
+// ── incidents (E2 first-class object) ──
+//
+// 5 routes: POST /v1/incidents (open; body text + context + linkedMemoryIds[]),
+// GET /v1/incidents (list, status filter), GET /v1/incidents/:id (show),
+// POST /v1/incidents/:id/resolve (open -> resolved; body resolutionText),
+// POST /v1/incidents/:id/close (open|resolved -> closed). Bearer-authed +
+// tenant-scoped via buildContextWithAuth. status validated against
+// VALID_INCIDENT_STATES. DoS caps: text 4096, context 4096, resolutionText
+// 4096 (v1.11.4 pattern). Mirrors /v1/decisions; lifecycle is
+// open->resolved->closed (no supersede), so linkedMemoryIds replaces
+// supersedesDecisionId on create.
+export async function handleCreateIncident({ req, res, opts }) {
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const text = body['text'];
+    if (!isJsonString(text) || text.length === 0) {
+        throw new HttpError(400, 'text is required (non-empty string)');
+    }
+    if (text.length > 4096) {
+        throw new HttpError(400, 'text exceeds 4096-character cap');
+    }
+    const contextRaw = body['context'];
+    let context;
+    if (contextRaw !== undefined && contextRaw !== null) {
+        if (!isJsonString(contextRaw)) {
+            throw new HttpError(400, 'context must be a string');
+        }
+        if (contextRaw.length > 4096) {
+            throw new HttpError(400, 'context exceeds 4096-character cap');
+        }
+        context = contextRaw;
+    }
+    const linkedRaw = body['linkedMemoryIds'];
+    let linkedMemoryIds;
+    if (linkedRaw !== undefined && linkedRaw !== null) {
+        if (!Array.isArray(linkedRaw)) {
+            throw new HttpError(400, 'linkedMemoryIds must be an array of memory ids');
+        }
+        if (linkedRaw.length > 256) {
+            throw new HttpError(400, 'linkedMemoryIds exceeds 256-item cap');
+        }
+        const isValidMemoryId = (item) => isJsonString(item) && item.length > 0 && item.length <= 4096;
+        if (!linkedRaw.every(isValidMemoryId)) {
+            throw new HttpError(400, 'each linkedMemoryIds entry must be a non-empty string <= 4096 chars');
+        }
+        linkedMemoryIds = linkedRaw;
+    }
+    try {
+        const incident = saveIncident(opts.hippoRoot, ctx.tenantId, {
+            incidentText: text,
+            context,
+            linkedMemoryIds,
+        }, ctx.actor.subject);
+        sendJson(res, 201, { incident });
+    }
+    catch (e) {
+        // A missing referenced row is a conflict with the create, not a missing target.
+        if (e instanceof NotFoundError)
+            throw new HttpError(409, e.message);
+        throw e;
+    }
+    return;
+}
+export async function handleListIncidents({ req, res, opts, query }) {
+    const status = query.get('status') ?? 'all';
+    const limit = parseListLimit(query.get('limit'));
+    const after = parseCursor(query.get('cursor'), 'string', 'integer');
+    const ctx = await buildContextWithAuth(req, opts);
+    let incidents;
+    if (status === 'all') {
+        incidents = loadIncidents(opts.hippoRoot, ctx.tenantId, { limit: limit + 1, after });
+    }
+    else {
+        if (!isSetMember(VALID_INCIDENT_STATES, status)) {
+            throw new HttpError(400, `status must be one of: open | resolved | closed | all (got "${status}")`);
+        }
+        incidents = loadIncidents(opts.hippoRoot, ctx.tenantId, {
+            status,
+            limit: limit + 1,
+            after,
+        });
+    }
+    const page = pageOf(incidents, limit, byCreatedAt);
+    sendJson(res, 200, { incidents: page.items, next_cursor: page.nextCursor });
+    return;
+}
+export async function handleResolveIncident({ req, res, opts }, incidentResolveMatch) {
+    const id = parseInt(incidentResolveMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const resolutionText = body['resolutionText'];
+    if (!isJsonString(resolutionText) || resolutionText.trim().length === 0) {
+        throw new HttpError(400, 'resolutionText is required (non-empty string)');
+    }
+    if (resolutionText.length > 4096) {
+        throw new HttpError(400, 'resolutionText exceeds 4096-character cap');
+    }
+    const incident = resolveIncident(opts.hippoRoot, ctx.tenantId, id, resolutionText, ctx.actor.subject);
+    sendJson(res, 200, { incident });
+    return;
+}
+export async function handleCloseIncident({ req, res, opts }, incidentCloseMatch) {
+    const id = parseInt(incidentCloseMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const incident = closeIncident(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+    sendJson(res, 200, { incident });
+    return;
+}
+export async function handleGetIncident({ req, res, opts }, incidentByIdMatch) {
+    const id = parseInt(incidentByIdMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const incident = loadIncidentById(opts.hippoRoot, ctx.tenantId, id);
+    if (!incident) {
+        throw new HttpError(404, `incident ${id} not found`);
+    }
+    sendJson(res, 200, { incident });
+    return;
+}
+//# sourceMappingURL=incidents.js.map

package/dist/server/routes/memories.d.ts

@@ -0,0 +1,10 @@
+import type { RouteRequest } from '../types.js';
+export declare function handleCreateMemory({ req, res, opts }: RouteRequest): Promise<void>;
+export declare function handleGetGraph({ req, res, opts, query }: RouteRequest): Promise<void>;
+export declare function handleArchiveMemory({ req, res, opts }: RouteRequest, archiveMatch: Record<string, string>): Promise<void>;
+export declare function handleSupersedeMemory({ req, res, opts }: RouteRequest, supersedeMatch: Record<string, string>): Promise<void>;
+export declare function handlePromoteMemory({ req, res, opts }: RouteRequest, promoteMatch: Record<string, string>): Promise<void>;
+export declare function handleForgetMemory({ req, res, opts }: RouteRequest, idMatch: Record<string, string>): Promise<void>;
+export declare function handleApplyOutcome({ req, res, opts }: RouteRequest): Promise<void>;
+export declare function handleSleep({ req, res, opts }: RouteRequest): Promise<void>;
+//# sourceMappingURL=memories.d.ts.map

package/dist/server/routes/memories.js

@@ -0,0 +1,179 @@
+// Memory write routes: create, graph, archive, supersede, promote, forget, outcome, sleep.
+import { archiveRaw, forget, outcome, outcomeForLastRecall, promote, remember, sleep, supersede } from '../../api.js';
+import { buildGraphModel } from '../../graph-view.js';
+import { MAX_ENTITY_NAME_LEN } from '../../graph/types.js';
+import { HttpError, sendJson } from '../../http-util.js';
+import { assertCrossTenantAdmin, buildContextWithAuth, isLoopback } from '../auth.js';
+import { getString, getStringArray, isJsonBoolean, isJsonString, isSetMember, parseJsonBody, parseListLimit, validateIdSegment } from '../validation.js';
+const VALID_KINDS = new Set([
+    'raw',
+    'distilled',
+    'superseded',
+    'archived',
+]);
+// POST /v1/memories
+export async function handleCreateMemory({ req, res, opts }) {
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const content = getString(body, 'content');
+    if (!content) {
+        throw new HttpError(400, 'content is required');
+    }
+    const kindRaw = getString(body, 'kind');
+    if (kindRaw !== undefined && !isSetMember(VALID_KINDS, kindRaw)) {
+        throw new HttpError(400, `invalid kind: ${kindRaw}`);
+    }
+    const result = remember(ctx, {
+        content,
+        kind: kindRaw,
+        scope: getString(body, 'scope'),
+        owner: getString(body, 'owner'),
+        artifactRef: getString(body, 'artifactRef'),
+        tags: getStringArray(body, 'tags'),
+    });
+    sendJson(res, 200, result);
+    return;
+}
+// GET /v1/graph?entity=NAME&limit=N — read-only entity/relation graph (tenant-scoped)
+export async function handleGetGraph({ req, res, opts, query }) {
+    const entityRaw = query.get('entity');
+    // Cap at the graph entity-name cap (512), not the id-shaped 256, so a valid
+    // long decision/policy name remains focusable over HTTP (codex P2).
+    if (entityRaw !== null && entityRaw.length > MAX_ENTITY_NAME_LEN) {
+        throw new HttpError(400, `entity exceeds the ${MAX_ENTITY_NAME_LEN}-character cap`);
+    }
+    const limit = parseListLimit(query.get('limit'));
+    const ctx = await buildContextWithAuth(req, opts);
+    const model = buildGraphModel(ctx.hippoRoot, ctx.tenantId, {
+        entity: entityRaw ?? undefined,
+        limit,
+    });
+    sendJson(res, 200, model);
+    return;
+}
+// /v1/memories/:id/* and DELETE /v1/memories/:id
+export async function handleArchiveMemory({ req, res, opts }, archiveMatch) {
+    validateIdSegment(archiveMatch.id, 'memory id');
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const reason = getString(body, 'reason');
+    if (!reason) {
+        throw new HttpError(400, 'reason is required');
+    }
+    const result = archiveRaw(ctx, archiveMatch.id, reason);
+    sendJson(res, 200, result);
+    return;
+}
+export async function handleSupersedeMemory({ req, res, opts }, supersedeMatch) {
+    validateIdSegment(supersedeMatch.id, 'memory id');
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const content = getString(body, 'content');
+    if (!content) {
+        throw new HttpError(400, 'content is required');
+    }
+    const result = supersede(ctx, supersedeMatch.id, content);
+    sendJson(res, 200, result);
+    return;
+}
+export async function handlePromoteMemory({ req, res, opts }, promoteMatch) {
+    validateIdSegment(promoteMatch.id, 'memory id');
+    const ctx = await buildContextWithAuth(req, opts);
+    const result = promote(ctx, promoteMatch.id);
+    sendJson(res, 200, result);
+    return;
+}
+export async function handleForgetMemory({ req, res, opts }, idMatch) {
+    validateIdSegment(idMatch.id, 'memory id');
+    const ctx = await buildContextWithAuth(req, opts);
+    const result = forget(ctx, idMatch.id);
+    sendJson(res, 200, result);
+    return;
+}
+// POST /v1/outcome — apply a positive/negative outcome to memory ids.
+// Body: {ids?: string[], good: boolean}. If ids omitted, falls back to
+// the last-recall path (api.outcomeForLastRecall); returned shape is
+// {applied, ids} in that case so callers can disambiguate "no recent
+// recall" from "all ids skipped". Each applied id writes one audit_log
+// row (op='outcome', actor from Bearer).
+export async function handleApplyOutcome({ req, res, opts }) {
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const good = body['good'];
+    if (!isJsonBoolean(good)) {
+        throw new HttpError(400, 'good is required (boolean)');
+    }
+    const idsRaw = body['ids'];
+    let ids;
+    if (idsRaw !== undefined) {
+        if (!Array.isArray(idsRaw)) {
+            throw new HttpError(400, 'ids must be an array of non-empty strings');
+        }
+        const isNonEmptyId = (item) => isJsonString(item) && item.length > 0;
+        if (!idsRaw.every(isNonEmptyId)) {
+            throw new HttpError(400, 'ids must be an array of non-empty strings');
+        }
+        // v1.11.5: DoS cap on ids.length. Each id triggers ~3 DB ops (readEntry +
+        // writeEntry + appendAuditEvent). N=1000 keeps per-request work bounded
+        // to sub-second wall time on SQLite hot path. Cap BEFORE buildContextWithAuth
+        // so attack traffic doesn't pay the api-key lookup cost.
+        if (idsRaw.length > 1000) {
+            throw new HttpError(400, 'ids exceeds 1000-id cap');
+        }
+        ids = idsRaw;
+    }
+    if (ids !== undefined) {
+        const { applied } = outcome(ctx, ids, good);
+        sendJson(res, 200, { applied });
+    }
+    else {
+        const result = outcomeForLastRecall(ctx, good);
+        sendJson(res, 200, result);
+    }
+    return;
+}
+// POST /v1/sleep — host-wide consolidation pipeline (consolidate + dedup +
+// audit + share + ambient). serve() refuses non-loopback hosts at boot, AND
+// this per-request loopback assertion makes the host-wide semantic fail-
+// closed regardless of any future serve() boot-config change. Body:
+// {dry_run?, no_share?}. Returns SleepResult JSON.
+//
+// Tenant scope (Episode A follow-up tracked in TODOS.md): api.sleep operates
+// on the WHOLE hippoRoot (cross-tenant by design, matching CLI cmdSleep).
+// The loopback-only guard is the trust boundary today. Future non-loopback
+// serving must also zero the cross-tenant counters for other tenants
+// (D1 in docs/decisions/2026-05-24-blocked-items.md).
+export async function handleSleep({ req, res, opts }) {
+    // Defensive per-request loopback guard. Uses the canonical isLoopback()
+    // helper above so any future extension (additional mapped/IPv6 forms,
+    // NAT64 prefixes) flows through without drift. serve()'s boot-time host
+    // check is the primary trust boundary; this is belt-and-suspenders.
+    if (!isLoopback(req.socket.remoteAddress)) {
+        throw new HttpError(403, '/v1/sleep is loopback-only (host-wide consolidation; see CHANGELOG v1.11.4)');
+    }
+    // v1.12.0 A5 v2 sub-1: admin-role gate. Forward-defensive — exists today
+    // under loopback-only enforcement (loopback fallback is admin by default;
+    // any Bearer-authed caller now carries an explicit role from the api_keys
+    // row). When non-loopback serving lands, this gate is the actual auth
+    // boundary on host-wide sleep.
+    const sleepCtx = await buildContextWithAuth(req, opts);
+    // Sleep consolidates every tenant under hippoRoot, so it is a cross-tenant action.
+    assertCrossTenantAdmin(sleepCtx, '/v1/sleep');
+    const body = await parseJsonBody(req, sleepCtx);
+    const dryRunRaw = body['dry_run'];
+    if (dryRunRaw !== undefined && !isJsonBoolean(dryRunRaw)) {
+        throw new HttpError(400, 'dry_run must be a boolean');
+    }
+    const noShareRaw = body['no_share'];
+    if (noShareRaw !== undefined && !isJsonBoolean(noShareRaw)) {
+        throw new HttpError(400, 'no_share must be a boolean');
+    }
+    // v1.12.0: sleepCtx already built above for the admin-role gate; reuse.
+    const result = await sleep(sleepCtx, {
+        dryRun: dryRunRaw === true,
+        noShare: noShareRaw === true,
+    });
+    sendJson(res, 200, result);
+    return;
+}
+//# sourceMappingURL=memories.js.map

package/dist/server/routes/policies.d.ts

@@ -0,0 +1,8 @@
+import type { RouteRequest } from '../types.js';
+export declare function handleCreatePolicy({ req, res, opts }: RouteRequest): Promise<void>;
+export declare function handleListPolicies({ req, res, opts, query }: RouteRequest): Promise<void>;
+export declare function handlePoliciesAsOf({ req, res, opts, query }: RouteRequest): Promise<void>;
+export declare function handleSupersedePolicy({ req, res, opts }: RouteRequest, policySupersedeMatch: RegExpMatchArray): Promise<void>;
+export declare function handleClosePolicy({ req, res, opts }: RouteRequest, policyCloseMatch: RegExpMatchArray): Promise<void>;
+export declare function handleGetPolicy({ req, res, opts }: RouteRequest, policyByIdMatch: RegExpMatchArray): Promise<void>;
+//# sourceMappingURL=policies.d.ts.map

package/dist/server/routes/policies.js

@@ -0,0 +1,151 @@
+// /v1/policies routes.
+import { closePolicy, loadPolicies, loadPoliciesAsOf, loadPolicyById, savePolicy, VALID_POLICY_STATES } from '../../policies.js';
+import { HttpError, sendJson } from '../../http-util.js';
+import { buildContextWithAuth } from '../auth.js';
+import { byCreatedAt, pageOf, parseCursor } from '../cursor.js';
+import { isJsonString, isSetMember, parseJsonBody, parseListLimit } from '../validation.js';
+// HTTP-boundary check for an optional policy date field (validFrom/validTo).
+// Type + length only; savePolicy/loadPoliciesAsOf normalize + format-validate the
+// value (an unparseable date throws there -> mapped to 400). 64-char cap bounds a
+// junk string before it reaches the Date parser.
+function optionalDateField(raw, label) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isJsonString(raw)) {
+        throw new HttpError(400, `${label} must be a string`);
+    }
+    if (raw.length > 64) {
+        throw new HttpError(400, `${label} exceeds 64-character cap`);
+    }
+    return raw;
+}
+// ── policies (E2 first-class object, bi-temporal-first) ──
+//
+// 6 routes: POST /v1/policies (new; processName-style body policyName +
+// policyText + validFrom? + validTo?), GET /v1/policies (list, status filter),
+// GET /v1/policies/asof (date + optional name; the bi-temporal as-of query;
+// placed BEFORE the /:id GET so the literal 'asof' is matched first), GET
+// /v1/policies/:id, POST /v1/policies/:id/supersede, POST /v1/policies/:id/close.
+// Date inputs are normalized + range-validated in the store; an invalid/inverted
+// date throws -> 400. DoS caps: policyName/policyText/changeSummary 4096.
+export async function handleCreatePolicy({ req, res, opts }) {
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const policyName = body['policyName'];
+    if (!isJsonString(policyName) || policyName.trim().length === 0) {
+        throw new HttpError(400, 'policyName is required (non-empty string)');
+    }
+    if (policyName.length > 4096) {
+        throw new HttpError(400, 'policyName exceeds 4096-character cap');
+    }
+    const policyText = body['policyText'];
+    if (!isJsonString(policyText) || policyText.trim().length === 0) {
+        throw new HttpError(400, 'policyText is required (non-empty string)');
+    }
+    if (policyText.length > 4096) {
+        throw new HttpError(400, 'policyText exceeds 4096-character cap');
+    }
+    const validFrom = optionalDateField(body['validFrom'], 'validFrom');
+    const validTo = optionalDateField(body['validTo'], 'validTo');
+    const policy = savePolicy(opts.hippoRoot, ctx.tenantId, {
+        policyName,
+        policyText,
+        validFrom,
+        validTo,
+    }, ctx.actor.subject);
+    sendJson(res, 201, { policy });
+    return;
+}
+export async function handleListPolicies({ req, res, opts, query }) {
+    const status = query.get('status') ?? 'all';
+    const limit = parseListLimit(query.get('limit'));
+    const after = parseCursor(query.get('cursor'), 'string', 'integer');
+    const ctx = await buildContextWithAuth(req, opts);
+    let policies;
+    if (status === 'all') {
+        policies = loadPolicies(opts.hippoRoot, ctx.tenantId, { limit: limit + 1, after });
+    }
+    else {
+        if (!isSetMember(VALID_POLICY_STATES, status)) {
+            throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
+        }
+        policies = loadPolicies(opts.hippoRoot, ctx.tenantId, {
+            status,
+            limit: limit + 1,
+            after,
+        });
+    }
+    const page = pageOf(policies, limit, byCreatedAt);
+    sendJson(res, 200, { policies: page.items, next_cursor: page.nextCursor });
+    return;
+}
+// The as-of query: must precede the /:id GET (literal 'asof' is non-numeric so
+// the /(\d+)/ route would not match it, but order it first for clarity).
+export async function handlePoliciesAsOf({ req, res, opts, query }) {
+    const date = query.get('date');
+    if (date === null || date.length === 0) {
+        throw new HttpError(400, 'date is required (ISO-8601 valid-time)');
+    }
+    const name = query.get('name') ?? undefined;
+    const ctx = await buildContextWithAuth(req, opts);
+    const policies = loadPoliciesAsOf(opts.hippoRoot, ctx.tenantId, date, { name });
+    sendJson(res, 200, { policies });
+    return;
+}
+export async function handleSupersedePolicy({ req, res, opts }, policySupersedeMatch) {
+    const id = parseInt(policySupersedeMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const policyText = body['policyText'];
+    if (!isJsonString(policyText) || policyText.trim().length === 0) {
+        throw new HttpError(400, 'policyText is required (non-empty string)');
+    }
+    if (policyText.length > 4096) {
+        throw new HttpError(400, 'policyText exceeds 4096-character cap');
+    }
+    const validFrom = optionalDateField(body['validFrom'], 'validFrom');
+    const validTo = optionalDateField(body['validTo'], 'validTo');
+    const changeRaw = body['changeSummary'];
+    let changeSummary;
+    if (changeRaw !== undefined && changeRaw !== null) {
+        if (!isJsonString(changeRaw)) {
+            throw new HttpError(400, 'changeSummary must be a string');
+        }
+        if (changeRaw.length > 4096) {
+            throw new HttpError(400, 'changeSummary exceeds 4096-character cap');
+        }
+        changeSummary = changeRaw;
+    }
+    const existing = loadPolicyById(opts.hippoRoot, ctx.tenantId, id);
+    if (!existing) {
+        throw new HttpError(404, `policy ${id} not found`);
+    }
+    const policy = savePolicy(opts.hippoRoot, ctx.tenantId, {
+        policyName: existing.policyName,
+        policyText,
+        validFrom,
+        validTo,
+        changeSummary,
+        supersedesPolicyId: id,
+    }, ctx.actor.subject);
+    sendJson(res, 200, { policy });
+    return;
+}
+export async function handleClosePolicy({ req, res, opts }, policyCloseMatch) {
+    const id = parseInt(policyCloseMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const policy = closePolicy(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+    sendJson(res, 200, { policy });
+    return;
+}
+export async function handleGetPolicy({ req, res, opts }, policyByIdMatch) {
+    const id = parseInt(policyByIdMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const policy = loadPolicyById(opts.hippoRoot, ctx.tenantId, id);
+    if (!policy) {
+        throw new HttpError(404, `policy ${id} not found`);
+    }
+    sendJson(res, 200, { policy });
+    return;
+}
+//# sourceMappingURL=policies.js.map

package/dist/server/routes/predictions.d.ts

@@ -0,0 +1,7 @@
+import type { RouteRequest } from '../types.js';
+export declare function handleCreatePrediction({ req, res, opts }: RouteRequest): Promise<void>;
+export declare function handleListPredictions({ req, res, opts, query }: RouteRequest): Promise<void>;
+export declare function handlePredictionStats({ req, res, opts, query }: RouteRequest): Promise<void>;
+export declare function handleGetPrediction({ req, res, opts }: RouteRequest, predictionByIdMatch: RegExpMatchArray): Promise<void>;
+export declare function handleClosePrediction({ req, res, opts }: RouteRequest, predictionCloseMatch: RegExpMatchArray): Promise<void>;
+//# sourceMappingURL=predictions.d.ts.map

package/dist/server/routes/predictions.js

@@ -0,0 +1,164 @@
+// /v1/predictions routes.
+import { closePrediction, computePredictionBaserate, loadOpenPredictions, loadPredictionById, loadPredictionsByClass, savePrediction, VALID_CLOSURE_STATES } from '../../predictions/store.js';
+import { HttpError, sendJson } from '../../http-util.js';
+import { buildContextWithAuth } from '../auth.js';
+import { byCreatedAt, pageOf, parseCursor } from '../cursor.js';
+import { isJsonNumber, isJsonString, isSetMember, parseJsonBody, parseListLimit } from '../validation.js';
+// ── 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.
+export async function handleCreatePrediction({ req, res, opts }) {
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const claim = body['claim'];
+    if (!isJsonString(claim) || 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 (!isJsonString(classTag) || 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 (!isJsonNumber(estimate) || !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 (!isJsonString(unit)) {
+            throw new HttpError(400, 'unit must be a string');
+        }
+        estimateUnit = unit;
+    }
+    const targetDate = body['targetDate'];
+    let targetDateValue;
+    if (targetDate !== undefined && targetDate !== null) {
+        if (!isJsonString(targetDate)) {
+            throw new HttpError(400, 'targetDate must be an ISO date string');
+        }
+        targetDateValue = targetDate;
+    }
+    const prediction = savePrediction(opts.hippoRoot, ctx.tenantId, {
+        classTag,
+        claimText: claim,
+        estimateValue,
+        estimateUnit,
+        targetDate: targetDateValue,
+    }, ctx.actor.subject);
+    sendJson(res, 201, { prediction });
+    return;
+}
+export async function handleListPredictions({ req, res, opts, query }) {
+    const classTag = query.get('class') ?? undefined;
+    const status = query.get('status') ?? 'all';
+    const limit = parseListLimit(query.get('limit'));
+    const after = parseCursor(query.get('cursor'), 'string', 'integer');
+    const ctx = await buildContextWithAuth(req, opts);
+    let predictions;
+    if (status === 'all') {
+        if (classTag) {
+            predictions = loadPredictionsByClass(opts.hippoRoot, ctx.tenantId, classTag, { limit: limit + 1, after });
+        }
+        else {
+            predictions = loadOpenPredictions(opts.hippoRoot, ctx.tenantId, { limit: limit + 1, after });
+        }
+    }
+    else if (status === 'open') {
+        predictions = loadOpenPredictions(opts.hippoRoot, ctx.tenantId, {
+            classTag: classTag || undefined,
+            limit: limit + 1,
+            after,
+        });
+    }
+    else {
+        if (!isSetMember(VALID_CLOSURE_STATES, 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: limit + 1,
+            after,
+        });
+    }
+    const page = pageOf(predictions, limit, byCreatedAt);
+    sendJson(res, 200, { predictions: page.items, next_cursor: page.nextCursor });
+    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.
+export async function handlePredictionStats({ req, res, opts, query }) {
+    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 = await buildContextWithAuth(req, opts);
+    const baserate = computePredictionBaserate(opts.hippoRoot, ctx.tenantId, classTag, ctx.actor.subject);
+    sendJson(res, 200, { baserate });
+    return;
+}
+export async function handleGetPrediction({ req, res, opts }, predictionByIdMatch) {
+    const id = parseInt(predictionByIdMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const prediction = loadPredictionById(opts.hippoRoot, ctx.tenantId, id);
+    if (!prediction) {
+        throw new HttpError(404, `prediction ${id} not found`);
+    }
+    sendJson(res, 200, { prediction });
+    return;
+}
+export async function handleClosePrediction({ req, res, opts }, predictionCloseMatch) {
+    const id = parseInt(predictionCloseMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const state = body['state'];
+    if (!isJsonString(state) || !isSetMember(VALID_CLOSURE_STATES, 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 (!isJsonNumber(actual) || !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 (!isJsonString(note)) {
+            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 prediction = closePrediction(opts.hippoRoot, ctx.tenantId, id, {
+        closureState: state,
+        actualValue,
+        closureNote,
+    }, ctx.actor.subject);
+    sendJson(res, 200, { prediction });
+    return;
+}
+//# sourceMappingURL=predictions.js.map

package/dist/server/routes/processes.d.ts

@@ -0,0 +1,7 @@
+import type { RouteRequest } from '../types.js';
+export declare function handleCreateProcess({ req, res, opts }: RouteRequest): Promise<void>;
+export declare function handleListProcesses({ req, res, opts, query }: RouteRequest): Promise<void>;
+export declare function handleSupersedeProcess({ req, res, opts }: RouteRequest, processSupersedeMatch: RegExpMatchArray): Promise<void>;
+export declare function handleCloseProcess({ req, res, opts }: RouteRequest, processCloseMatch: RegExpMatchArray): Promise<void>;
+export declare function handleGetProcess({ req, res, opts }: RouteRequest, processByIdMatch: RegExpMatchArray): Promise<void>;
+//# sourceMappingURL=processes.d.ts.map