hippo-memory 1.15.0 → 1.16.0

package/dist/server.js

@@ -22,6 +22,12 @@ 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 { saveDecision, closeDecision, loadDecisionById, loadDecisions, VALID_DECISION_STATES, } from './decisions.js';
+import { saveIncident, resolveIncident, closeIncident, loadIncidentById, loadIncidents, VALID_INCIDENT_STATES, } from './incidents.js';
+import { saveProcess, closeProcess, loadProcessById, loadProcesses, VALID_PROCESS_STATES, } from './processes.js';
+import { savePolicy, closePolicy, loadPolicyById, loadPolicies, loadPoliciesAsOf, VALID_POLICY_STATES, } from './policies.js';
+import { saveSkill, closeSkill, loadSkillById, loadSkills, exportSkills, VALID_SKILL_STATES, } from './skills.js';
+import { saveProjectBrief, closeProjectBrief, loadProjectBriefById, loadProjectBriefs, assembleBriefFromReceipts, refreshBrief, VALID_BRIEF_STATES, } from './project-briefs.js';
+import { saveCustomerNote, closeCustomerNote, loadCustomerNoteById, loadCustomerNotes, VALID_NOTE_STATES, } from './customer-notes.js';
 import { handleMcpRequest } from './mcp/server.js';
 import { verifySlackSignature } from './connectors/slack/signature.js';
 import { isSlackEventEnvelope, isSlackMessageEvent } from './connectors/slack/types.js';
@@ -80,11 +86,85 @@ const VALID_AUDIT_OPS = new Set([
     'decision_create', // E2 decision first-class object — emitted by saveDecision
     'decision_supersede', // E2 — emitted by saveDecision when --supersedes resolves to an active decision row
     'decision_close', // E2 — emitted by closeDecision
+    'incident_open', // E2 incident first-class object — emitted by saveIncident
+    'incident_resolve', // E2 — emitted by resolveIncident (open -> resolved)
+    'incident_close', // E2 — emitted by closeIncident (open|resolved -> closed)
+    'process_create', // E2 process first-class object — emitted by saveProcess
+    'process_supersede', // E2 — emitted by saveProcess on a supersession
+    'process_close', // E2 — emitted by closeProcess
+    'policy_create', // E2 policy first-class object — emitted by savePolicy
+    'policy_supersede', // E2 — emitted by savePolicy on a supersession
+    'policy_close', // E2 — emitted by closePolicy
+    'skill_create', // E2 skill first-class object — emitted by saveSkill
+    'skill_supersede', // E2 — emitted by saveSkill on a supersession
+    'skill_close', // E2 — emitted by closeSkill
+    'project_brief_create', // E2 project_brief first-class object — emitted by saveProjectBrief
+    'project_brief_supersede', // E2 — emitted by saveProjectBrief on a supersession (incl. refresh)
+    'project_brief_close', // E2 — emitted by closeProjectBrief
+    'customer_note_create', // E2 customer_note first-class object — emitted by saveCustomerNote
+    'customer_note_supersede', // E2 — emitted by saveCustomerNote on a supersession
+    'customer_note_close', // E2 — emitted by closeCustomerNote
 ]);
 // 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
 // small enough that a malicious client can't ask for the world.
 const MAX_AUDIT_LIMIT = 10000;
+// HTTP-boundary validation for a process `steps` body (untrusted). Returns the
+// step strings (saveProcess re-validates + trims, this is the fail-fast 400
+// gate). Caps mirror src/processes.ts MAX_PROCESS_STEPS / MAX_PROCESS_STEP_LEN.
+function validateProcessStepsBody(raw) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new HttpError(400, 'steps must be an array of strings');
+    }
+    if (raw.length > 200) {
+        throw new HttpError(400, 'steps exceeds 200-step cap');
+    }
+    for (const item of raw) {
+        if (typeof item !== 'string') {
+            throw new HttpError(400, 'each step must be a string');
+        }
+        if (item.trim().length === 0) {
+            throw new HttpError(400, 'a step is empty');
+        }
+        if (item.length > 2000) {
+            throw new HttpError(400, 'a step exceeds the 2000-character cap');
+        }
+    }
+    return raw;
+}
+// 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 (typeof raw !== 'string') {
+        throw new HttpError(400, `${label} must be a string`);
+    }
+    if (raw.length > 64) {
+        throw new HttpError(400, `${label} exceeds 64-character cap`);
+    }
+    return raw;
+}
+// Parse a `?limit=` query param for the E2 list routes. Defaults to 100; requires
+// a positive INTEGER <= 1000. Number.isInteger rejects fractional values like
+// "1.5" that Number.isFinite would pass but SQLite `LIMIT ?` rejects with a
+// datatype mismatch (a 500). Shared across the decision/incident/process/policy
+// list routes so the guard cannot drift (codex review 2026-05-30 P2: fractional
+// limit reached SQLite on the policy route; the same latent hole existed in the
+// sibling routes this was copied from).
+function parseListLimit(limitRaw) {
+    if (limitRaw === null)
+        return 100;
+    const limit = Number(limitRaw);
+    if (!Number.isInteger(limit) || limit <= 0 || limit > 1000) {
+        throw new HttpError(400, 'limit must be a positive integer <= 1000');
+    }
+    return limit;
+}
 const VALID_KINDS = new Set([
     'raw',
     'distilled',
@@ -1029,14 +1109,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     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 limit = parseListLimit(query.get('limit'));
         const ctx = buildContextWithAuth(req, opts.hippoRoot);
         let predictions;
         if (status === 'all') {
@@ -1199,14 +1272,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     }
     if (method === 'GET' && path === '/v1/decisions') {
         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 limit = parseListLimit(query.get('limit'));
         const ctx = buildContextWithAuth(req, opts.hippoRoot);
         let decisions;
         if (status === 'all') {
@@ -1298,6 +1364,952 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         sendJson(res, 200, { decision });
         return;
     }
+    // ── 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.
+    if (method === 'POST' && path === '/v1/incidents') {
+        const body = await parseJsonBody(req);
+        const text = body['text'];
+        if (typeof text !== 'string' || 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 (typeof contextRaw !== 'string') {
+                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');
+            }
+            for (const item of linkedRaw) {
+                if (typeof item !== 'string' || item.length === 0 || item.length > 4096) {
+                    throw new HttpError(400, 'each linkedMemoryIds entry must be a non-empty string <= 4096 chars');
+                }
+            }
+            linkedMemoryIds = linkedRaw;
+        }
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        try {
+            const incident = saveIncident(opts.hippoRoot, ctx.tenantId, {
+                incidentText: text,
+                context,
+                linkedMemoryIds,
+            }, ctx.actor.subject);
+            sendJson(res, 201, { incident });
+        }
+        catch (e) {
+            const msg = e.message;
+            if (msg.includes('not found')) {
+                throw new HttpError(409, msg);
+            }
+            throw e;
+        }
+        return;
+    }
+    if (method === 'GET' && path === '/v1/incidents') {
+        const status = query.get('status') ?? 'all';
+        const limit = parseListLimit(query.get('limit'));
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        let incidents;
+        if (status === 'all') {
+            incidents = loadIncidents(opts.hippoRoot, ctx.tenantId, { limit });
+        }
+        else {
+            if (!VALID_INCIDENT_STATES.has(status)) {
+                throw new HttpError(400, `status must be one of: open | resolved | closed | all (got "${status}")`);
+            }
+            incidents = loadIncidents(opts.hippoRoot, ctx.tenantId, {
+                status: status,
+                limit,
+            });
+        }
+        sendJson(res, 200, { incidents });
+        return;
+    }
+    const incidentResolveMatch = path.match(/^\/v1\/incidents\/(\d+)\/resolve$/);
+    if (method === 'POST' && incidentResolveMatch) {
+        const id = parseInt(incidentResolveMatch[1], 10);
+        const body = await parseJsonBody(req);
+        const resolutionText = body['resolutionText'];
+        if (typeof resolutionText !== 'string' || 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 ctx = buildContextWithAuth(req, opts.hippoRoot);
+        try {
+            const incident = resolveIncident(opts.hippoRoot, ctx.tenantId, id, resolutionText, ctx.actor.subject);
+            sendJson(res, 200, { incident });
+        }
+        catch (e) {
+            const msg = e.message;
+            if (msg.includes('not found')) {
+                throw new HttpError(404, msg);
+            }
+            if (msg.includes('not open')) {
+                throw new HttpError(409, msg);
+            }
+            throw e;
+        }
+        return;
+    }
+    const incidentCloseMatch = path.match(/^\/v1\/incidents\/(\d+)\/close$/);
+    if (method === 'POST' && incidentCloseMatch) {
+        const id = parseInt(incidentCloseMatch[1], 10);
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        try {
+            const incident = closeIncident(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+            sendJson(res, 200, { incident });
+        }
+        catch (e) {
+            const msg = e.message;
+            if (msg.includes('not found')) {
+                throw new HttpError(404, msg);
+            }
+            if (msg.includes('already closed')) {
+                throw new HttpError(409, msg);
+            }
+            throw e;
+        }
+        return;
+    }
+    const incidentByIdMatch = path.match(/^\/v1\/incidents\/(\d+)$/);
+    if (method === 'GET' && incidentByIdMatch) {
+        const id = parseInt(incidentByIdMatch[1], 10);
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const incident = loadIncidentById(opts.hippoRoot, ctx.tenantId, id);
+        if (!incident) {
+            throw new HttpError(404, `incident ${id} not found`);
+        }
+        sendJson(res, 200, { incident });
+        return;
+    }
+    // ── processes (E2 first-class object) ──
+    //
+    // 5 routes: POST /v1/processes (new; body processName + steps[] + description),
+    // GET /v1/processes (list, status filter), GET /v1/processes/:id (show),
+    // POST /v1/processes/:id/supersede (active -> superseded by a new version; body
+    // steps[] + changeSummary + description; reuses the predecessor's name),
+    // POST /v1/processes/:id/close (active -> closed). Bearer-authed + tenant-scoped
+    // via buildContextWithAuth. status validated against VALID_PROCESS_STATES. DoS
+    // caps: processName/description/changeSummary 4096, steps 200x2000
+    // (validateProcessStepsBody). Mirrors /v1/decisions; the delta lifecycle is the
+    // decision supersede path.
+    if (method === 'POST' && path === '/v1/processes') {
+        const body = await parseJsonBody(req);
+        const processName = body['processName'];
+        if (typeof processName !== 'string' || processName.trim().length === 0) {
+            throw new HttpError(400, 'processName is required (non-empty string)');
+        }
+        if (processName.length > 4096) {
+            throw new HttpError(400, 'processName exceeds 4096-character cap');
+        }
+        const steps = validateProcessStepsBody(body['steps']);
+        const descriptionRaw = body['description'];
+        let description;
+        if (descriptionRaw !== undefined && descriptionRaw !== null) {
+            if (typeof descriptionRaw !== 'string') {
+                throw new HttpError(400, 'description must be a string');
+            }
+            if (descriptionRaw.length > 4096) {
+                throw new HttpError(400, 'description exceeds 4096-character cap');
+            }
+            description = descriptionRaw;
+        }
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const process = saveProcess(opts.hippoRoot, ctx.tenantId, {
+            processName,
+            steps,
+            description,
+        }, ctx.actor.subject);
+        sendJson(res, 201, { process });
+        return;
+    }
+    if (method === 'GET' && path === '/v1/processes') {
+        const status = query.get('status') ?? 'all';
+        const limit = parseListLimit(query.get('limit'));
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        let processes;
+        if (status === 'all') {
+            processes = loadProcesses(opts.hippoRoot, ctx.tenantId, { limit });
+        }
+        else {
+            if (!VALID_PROCESS_STATES.has(status)) {
+                throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
+            }
+            processes = loadProcesses(opts.hippoRoot, ctx.tenantId, {
+                status: status,
+                limit,
+            });
+        }
+        sendJson(res, 200, { processes });
+        return;
+    }
+    const processSupersedeMatch = path.match(/^\/v1\/processes\/(\d+)\/supersede$/);
+    if (method === 'POST' && processSupersedeMatch) {
+        const id = parseInt(processSupersedeMatch[1], 10);
+        const body = await parseJsonBody(req);
+        const steps = validateProcessStepsBody(body['steps']);
+        if (steps.length === 0) {
+            throw new HttpError(400, 'steps is required (at least one step) for a supersession');
+        }
+        const changeRaw = body['changeSummary'];
+        let changeSummary;
+        if (changeRaw !== undefined && changeRaw !== null) {
+            if (typeof changeRaw !== 'string') {
+                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 descRaw = body['description'];
+        let description;
+        if (descRaw !== undefined && descRaw !== null) {
+            if (typeof descRaw !== 'string') {
+                throw new HttpError(400, 'description must be a string');
+            }
+            if (descRaw.length > 4096) {
+                throw new HttpError(400, 'description exceeds 4096-character cap');
+            }
+            description = descRaw;
+        }
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        // A supersession is a new version of the SAME process: reuse the
+        // predecessor's name. 404 if the target does not exist; saveProcess's
+        // in-SAVEPOINT preflight is the authoritative active-state check (409).
+        const existing = loadProcessById(opts.hippoRoot, ctx.tenantId, id);
+        if (!existing) {
+            throw new HttpError(404, `process ${id} not found`);
+        }
+        try {
+            const process = saveProcess(opts.hippoRoot, ctx.tenantId, {
+                processName: existing.processName,
+                steps,
+                description,
+                changeSummary,
+                supersedesProcessId: id,
+            }, ctx.actor.subject);
+            sendJson(res, 200, { process });
+        }
+        catch (e) {
+            const msg = e.message;
+            if (msg.includes('not found')) {
+                throw new HttpError(404, msg);
+            }
+            if (msg.includes('not active') || msg.includes('could not be superseded')) {
+                throw new HttpError(409, msg);
+            }
+            throw e;
+        }
+        return;
+    }
+    const processCloseMatch = path.match(/^\/v1\/processes\/(\d+)\/close$/);
+    if (method === 'POST' && processCloseMatch) {
+        const id = parseInt(processCloseMatch[1], 10);
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        try {
+            const process = closeProcess(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+            sendJson(res, 200, { process });
+        }
+        catch (e) {
+            const msg = e.message;
+            if (msg.includes('not found')) {
+                throw new HttpError(404, msg);
+            }
+            if (msg.includes('not active')) {
+                throw new HttpError(409, msg);
+            }
+            throw e;
+        }
+        return;
+    }
+    const processByIdMatch = path.match(/^\/v1\/processes\/(\d+)$/);
+    if (method === 'GET' && processByIdMatch) {
+        const id = parseInt(processByIdMatch[1], 10);
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const process = loadProcessById(opts.hippoRoot, ctx.tenantId, id);
+        if (!process) {
+            throw new HttpError(404, `process ${id} not found`);
+        }
+        sendJson(res, 200, { process });
+        return;
+    }
+    // ── 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.
+    if (method === 'POST' && path === '/v1/policies') {
+        const body = await parseJsonBody(req);
+        const policyName = body['policyName'];
+        if (typeof policyName !== 'string' || 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 (typeof policyText !== 'string' || 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 ctx = buildContextWithAuth(req, opts.hippoRoot);
+        try {
+            const policy = savePolicy(opts.hippoRoot, ctx.tenantId, {
+                policyName,
+                policyText,
+                validFrom,
+                validTo,
+            }, ctx.actor.subject);
+            sendJson(res, 201, { policy });
+        }
+        catch (e) {
+            // savePolicy throws on invalid/inverted dates (validation) -> 400.
+            throw new HttpError(400, e.message);
+        }
+        return;
+    }
+    if (method === 'GET' && path === '/v1/policies') {
+        const status = query.get('status') ?? 'all';
+        const limit = parseListLimit(query.get('limit'));
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        let policies;
+        if (status === 'all') {
+            policies = loadPolicies(opts.hippoRoot, ctx.tenantId, { limit });
+        }
+        else {
+            if (!VALID_POLICY_STATES.has(status)) {
+                throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
+            }
+            policies = loadPolicies(opts.hippoRoot, ctx.tenantId, {
+                status: status,
+                limit,
+            });
+        }
+        sendJson(res, 200, { policies });
+        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).
+    if (method === 'GET' && path === '/v1/policies/asof') {
+        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 = buildContextWithAuth(req, opts.hippoRoot);
+        try {
+            const policies = loadPoliciesAsOf(opts.hippoRoot, ctx.tenantId, date, { name });
+            sendJson(res, 200, { policies });
+        }
+        catch (e) {
+            throw new HttpError(400, e.message);
+        }
+        return;
+    }
+    const policySupersedeMatch = path.match(/^\/v1\/policies\/(\d+)\/supersede$/);
+    if (method === 'POST' && policySupersedeMatch) {
+        const id = parseInt(policySupersedeMatch[1], 10);
+        const body = await parseJsonBody(req);
+        const policyText = body['policyText'];
+        if (typeof policyText !== 'string' || 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 (typeof changeRaw !== 'string') {
+                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 ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const existing = loadPolicyById(opts.hippoRoot, ctx.tenantId, id);
+        if (!existing) {
+            throw new HttpError(404, `policy ${id} not found`);
+        }
+        try {
+            const policy = savePolicy(opts.hippoRoot, ctx.tenantId, {
+                policyName: existing.policyName,
+                policyText,
+                validFrom,
+                validTo,
+                changeSummary,
+                supersedesPolicyId: id,
+            }, ctx.actor.subject);
+            sendJson(res, 200, { policy });
+        }
+        catch (e) {
+            const msg = e.message;
+            if (msg.includes('not found')) {
+                throw new HttpError(404, msg);
+            }
+            if (msg.includes('not active') || msg.includes('could not be superseded')) {
+                throw new HttpError(409, msg);
+            }
+            // invalid/inverted date or missing field -> validation.
+            throw new HttpError(400, msg);
+        }
+        return;
+    }
+    const policyCloseMatch = path.match(/^\/v1\/policies\/(\d+)\/close$/);
+    if (method === 'POST' && policyCloseMatch) {
+        const id = parseInt(policyCloseMatch[1], 10);
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        try {
+            const policy = closePolicy(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+            sendJson(res, 200, { policy });
+        }
+        catch (e) {
+            const msg = e.message;
+            if (msg.includes('not found')) {
+                throw new HttpError(404, msg);
+            }
+            if (msg.includes('not active')) {
+                throw new HttpError(409, msg);
+            }
+            throw e;
+        }
+        return;
+    }
+    const policyByIdMatch = path.match(/^\/v1\/policies\/(\d+)$/);
+    if (method === 'GET' && policyByIdMatch) {
+        const id = parseInt(policyByIdMatch[1], 10);
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const policy = loadPolicyById(opts.hippoRoot, ctx.tenantId, id);
+        if (!policy) {
+            throw new HttpError(404, `policy ${id} not found`);
+        }
+        sendJson(res, 200, { policy });
+        return;
+    }
+    // ── skills (E2 first-class object, executable/exportable) ──
+    //
+    // 6 routes: POST /v1/skills (new; body skillName + instructions + trigger?),
+    // GET /v1/skills (list, status filter; shared parseListLimit), GET
+    // /v1/skills/export (renders ACTIVE skills as an AGENTS.md/CLAUDE.md markdown
+    // block -> {markdown}; literal 'export' is non-numeric so the /:id (\d+) route
+    // cannot capture it, but it is ordered first regardless), GET /v1/skills/:id,
+    // POST /v1/skills/:id/supersede, POST /v1/skills/:id/close. DoS caps:
+    // skillName 256, instructions 8192, trigger 1024, changeSummary 4096. The store
+    // validates + throws; the boundary maps validation -> 400, not-found -> 404,
+    // not-active -> 409. Mirrors /v1/processes; "executable" = exportable
+    // instruction (no code exec).
+    if (method === 'POST' && path === '/v1/skills') {
+        const body = await parseJsonBody(req);
+        const skillName = body['skillName'];
+        if (typeof skillName !== 'string' || skillName.trim().length === 0) {
+            throw new HttpError(400, 'skillName is required (non-empty string)');
+        }
+        if (skillName.length > 256) {
+            throw new HttpError(400, 'skillName exceeds 256-character cap');
+        }
+        const instructions = body['instructions'];
+        if (typeof instructions !== 'string' || instructions.trim().length === 0) {
+            throw new HttpError(400, 'instructions are required (non-empty string)');
+        }
+        if (instructions.length > 8192) {
+            throw new HttpError(400, 'instructions exceed 8192-character cap');
+        }
+        const triggerRaw = body['trigger'];
+        let trigger;
+        if (triggerRaw !== undefined && triggerRaw !== null) {
+            if (typeof triggerRaw !== 'string') {
+                throw new HttpError(400, 'trigger must be a string');
+            }
+            if (triggerRaw.length > 1024) {
+                throw new HttpError(400, 'trigger exceeds 1024-character cap');
+            }
+            trigger = triggerRaw;
+        }
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        try {
+            const skill = saveSkill(opts.hippoRoot, ctx.tenantId, {
+                skillName,
+                instructions,
+                trigger,
+            }, ctx.actor.subject);
+            sendJson(res, 201, { skill });
+        }
+        catch (e) {
+            // saveSkill throws on validation (single-line name etc.) -> 400.
+            throw new HttpError(400, e.message);
+        }
+        return;
+    }
+    if (method === 'GET' && path === '/v1/skills') {
+        const status = query.get('status') ?? 'all';
+        const limit = parseListLimit(query.get('limit'));
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        let skills;
+        if (status === 'all') {
+            skills = loadSkills(opts.hippoRoot, ctx.tenantId, { limit });
+        }
+        else {
+            if (!VALID_SKILL_STATES.has(status)) {
+                throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
+            }
+            skills = loadSkills(opts.hippoRoot, ctx.tenantId, {
+                status: status,
+                limit,
+            });
+        }
+        sendJson(res, 200, { skills });
+        return;
+    }
+    // The export renderer: must precede the /:id GET (literal 'export' is
+    // non-numeric so the /(\d+)/ route would not match it, but order it first).
+    if (method === 'GET' && path === '/v1/skills/export') {
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const markdown = exportSkills(opts.hippoRoot, ctx.tenantId);
+        sendJson(res, 200, { markdown });
+        return;
+    }
+    const skillSupersedeMatch = path.match(/^\/v1\/skills\/(\d+)\/supersede$/);
+    if (method === 'POST' && skillSupersedeMatch) {
+        const id = parseInt(skillSupersedeMatch[1], 10);
+        const body = await parseJsonBody(req);
+        const instructions = body['instructions'];
+        if (typeof instructions !== 'string' || instructions.trim().length === 0) {
+            throw new HttpError(400, 'instructions are required (non-empty string)');
+        }
+        if (instructions.length > 8192) {
+            throw new HttpError(400, 'instructions exceed 8192-character cap');
+        }
+        const triggerRaw = body['trigger'];
+        let trigger;
+        if (triggerRaw !== undefined && triggerRaw !== null) {
+            if (typeof triggerRaw !== 'string') {
+                throw new HttpError(400, 'trigger must be a string');
+            }
+            if (triggerRaw.length > 1024) {
+                throw new HttpError(400, 'trigger exceeds 1024-character cap');
+            }
+            trigger = triggerRaw;
+        }
+        const changeRaw = body['changeSummary'];
+        let changeSummary;
+        if (changeRaw !== undefined && changeRaw !== null) {
+            if (typeof changeRaw !== 'string') {
+                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 ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const existing = loadSkillById(opts.hippoRoot, ctx.tenantId, id);
+        if (!existing) {
+            throw new HttpError(404, `skill ${id} not found`);
+        }
+        try {
+            const skill = saveSkill(opts.hippoRoot, ctx.tenantId, {
+                skillName: existing.skillName,
+                instructions,
+                trigger,
+                changeSummary,
+                supersedesSkillId: id,
+            }, ctx.actor.subject);
+            sendJson(res, 200, { skill });
+        }
+        catch (e) {
+            const msg = e.message;
+            if (msg.includes('not found')) {
+                throw new HttpError(404, msg);
+            }
+            if (msg.includes('not active') || msg.includes('could not be superseded')) {
+                throw new HttpError(409, msg);
+            }
+            throw new HttpError(400, msg);
+        }
+        return;
+    }
+    const skillCloseMatch = path.match(/^\/v1\/skills\/(\d+)\/close$/);
+    if (method === 'POST' && skillCloseMatch) {
+        const id = parseInt(skillCloseMatch[1], 10);
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        try {
+            const skill = closeSkill(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+            sendJson(res, 200, { skill });
+        }
+        catch (e) {
+            const msg = e.message;
+            if (msg.includes('not found')) {
+                throw new HttpError(404, msg);
+            }
+            if (msg.includes('not active')) {
+                throw new HttpError(409, msg);
+            }
+            throw e;
+        }
+        return;
+    }
+    const skillByIdMatch = path.match(/^\/v1\/skills\/(\d+)$/);
+    if (method === 'GET' && skillByIdMatch) {
+        const id = parseInt(skillByIdMatch[1], 10);
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const skill = loadSkillById(opts.hippoRoot, ctx.tenantId, id);
+        if (!skill) {
+            throw new HttpError(404, `skill ${id} not found`);
+        }
+        sendJson(res, 200, { skill });
+        return;
+    }
+    // ── E2 project_brief routes ──
+    //
+    // 6 routes: POST /v1/project-briefs (new; body repo + summary), GET
+    // /v1/project-briefs (list; status + repo filter; shared parseListLimit), POST
+    // /v1/project-briefs/refresh (body {repo, dryRun?} -> auto-assemble the brief
+    // from the repo's receipts; dryRun returns {markdown} without writing; ordered
+    // before /:id), GET /v1/project-briefs/:id, POST /v1/project-briefs/:id/supersede,
+    // POST /v1/project-briefs/:id/close. DoS caps: repo 256, summary 8192,
+    // changeSummary 4096. The store validates + throws; the boundary maps validation
+    // -> 400, not-found -> 404, not-active -> 409. Mirrors /v1/skills.
+    if (method === 'POST' && path === '/v1/project-briefs') {
+        const body = await parseJsonBody(req);
+        const repo = body['repo'];
+        if (typeof repo !== 'string' || repo.trim().length === 0) {
+            throw new HttpError(400, 'repo is required (non-empty string)');
+        }
+        if (repo.length > 256) {
+            throw new HttpError(400, 'repo exceeds 256-character cap');
+        }
+        const summary = body['summary'];
+        if (typeof summary !== 'string' || summary.trim().length === 0) {
+            throw new HttpError(400, 'summary is required (non-empty string)');
+        }
+        if (summary.length > 8192) {
+            throw new HttpError(400, 'summary exceeds 8192-character cap');
+        }
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        try {
+            const brief = saveProjectBrief(opts.hippoRoot, ctx.tenantId, {
+                repo,
+                summary,
+            }, ctx.actor.subject);
+            sendJson(res, 201, { brief });
+        }
+        catch (e) {
+            // saveProjectBrief throws on validation (single-line repo etc.) -> 400.
+            throw new HttpError(400, e.message);
+        }
+        return;
+    }
+    if (method === 'GET' && path === '/v1/project-briefs') {
+        const status = query.get('status') ?? 'all';
+        const repoFilter = query.get('repo');
+        const limit = parseListLimit(query.get('limit'));
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const listOpts = { limit };
+        if (repoFilter !== null && repoFilter.trim().length > 0) {
+            listOpts.repo = repoFilter.trim();
+        }
+        if (status !== 'all') {
+            if (!VALID_BRIEF_STATES.has(status)) {
+                throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
+            }
+            listOpts.status = status;
+        }
+        const briefs = loadProjectBriefs(opts.hippoRoot, ctx.tenantId, listOpts);
+        sendJson(res, 200, { briefs });
+        return;
+    }
+    // The refresh op: must precede the /:id routes (literal 'refresh' is non-numeric
+    // so the /(\d+)/ routes would not match it, but order it first).
+    if (method === 'POST' && path === '/v1/project-briefs/refresh') {
+        const body = await parseJsonBody(req);
+        const repo = body['repo'];
+        if (typeof repo !== 'string' || repo.trim().length === 0) {
+            throw new HttpError(400, 'repo is required (non-empty string)');
+        }
+        if (repo.length > 256) {
+            throw new HttpError(400, 'repo exceeds 256-character cap');
+        }
+        const dryRun = body['dryRun'] === true;
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        try {
+            if (dryRun) {
+                const { markdown, receiptCount } = assembleBriefFromReceipts(opts.hippoRoot, ctx.tenantId, repo);
+                sendJson(res, 200, { markdown, receiptCount });
+                return;
+            }
+            const brief = refreshBrief(opts.hippoRoot, ctx.tenantId, repo, ctx.actor.subject);
+            sendJson(res, 200, { brief });
+        }
+        catch (e) {
+            // A refresh race (the active brief is closed/superseded between
+            // loadActiveBriefForRepo and the supersede CAS) is a state conflict, not a
+            // validation error — map it to 409 like the explicit supersede route
+            // (codex-review 2026-05-30, P3).
+            const msg = e.message;
+            if (msg.includes('not found')) {
+                throw new HttpError(404, msg);
+            }
+            if (msg.includes('not active') || msg.includes('could not be superseded')) {
+                throw new HttpError(409, msg);
+            }
+            throw new HttpError(400, msg);
+        }
+        return;
+    }
+    const briefSupersedeMatch = path.match(/^\/v1\/project-briefs\/(\d+)\/supersede$/);
+    if (method === 'POST' && briefSupersedeMatch) {
+        const id = parseInt(briefSupersedeMatch[1], 10);
+        const body = await parseJsonBody(req);
+        const summary = body['summary'];
+        if (typeof summary !== 'string' || summary.trim().length === 0) {
+            throw new HttpError(400, 'summary is required (non-empty string)');
+        }
+        if (summary.length > 8192) {
+            throw new HttpError(400, 'summary exceeds 8192-character cap');
+        }
+        const changeRaw = body['changeSummary'];
+        let changeSummary;
+        if (changeRaw !== undefined && changeRaw !== null) {
+            if (typeof changeRaw !== 'string') {
+                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 ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const existing = loadProjectBriefById(opts.hippoRoot, ctx.tenantId, id);
+        if (!existing) {
+            throw new HttpError(404, `project brief ${id} not found`);
+        }
+        try {
+            const brief = saveProjectBrief(opts.hippoRoot, ctx.tenantId, {
+                repo: existing.repo,
+                summary,
+                changeSummary,
+                supersedesBriefId: id,
+            }, ctx.actor.subject);
+            sendJson(res, 200, { brief });
+        }
+        catch (e) {
+            const msg = e.message;
+            if (msg.includes('not found')) {
+                throw new HttpError(404, msg);
+            }
+            if (msg.includes('not active') || msg.includes('could not be superseded')) {
+                throw new HttpError(409, msg);
+            }
+            throw new HttpError(400, msg);
+        }
+        return;
+    }
+    const briefCloseMatch = path.match(/^\/v1\/project-briefs\/(\d+)\/close$/);
+    if (method === 'POST' && briefCloseMatch) {
+        const id = parseInt(briefCloseMatch[1], 10);
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        try {
+            const brief = closeProjectBrief(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+            sendJson(res, 200, { brief });
+        }
+        catch (e) {
+            const msg = e.message;
+            if (msg.includes('not found')) {
+                throw new HttpError(404, msg);
+            }
+            if (msg.includes('not active')) {
+                throw new HttpError(409, msg);
+            }
+            throw e;
+        }
+        return;
+    }
+    const briefByIdMatch = path.match(/^\/v1\/project-briefs\/(\d+)$/);
+    if (method === 'GET' && briefByIdMatch) {
+        const id = parseInt(briefByIdMatch[1], 10);
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const brief = loadProjectBriefById(opts.hippoRoot, ctx.tenantId, id);
+        if (!brief) {
+            throw new HttpError(404, `project brief ${id} not found`);
+        }
+        sendJson(res, 200, { brief });
+        return;
+    }
+    // ── E2 customer_note routes ──
+    //
+    // 5 routes (no assembler/refresh): POST /v1/customer-notes (new; body customer +
+    // note), GET /v1/customer-notes (list; status + customer filter; shared
+    // parseListLimit), GET /v1/customer-notes/:id, POST /v1/customer-notes/:id/supersede,
+    // POST /v1/customer-notes/:id/close. DoS caps: customer 256, note 8192,
+    // changeSummary 4096. The store validates + throws; the boundary maps validation ->
+    // 400, not-found -> 404, not-active -> 409. Mirrors /v1/project-briefs.
+    if (method === 'POST' && path === '/v1/customer-notes') {
+        const body = await parseJsonBody(req);
+        const customer = body['customer'];
+        if (typeof customer !== 'string' || customer.trim().length === 0) {
+            throw new HttpError(400, 'customer is required (non-empty string)');
+        }
+        if (customer.length > 256) {
+            throw new HttpError(400, 'customer exceeds 256-character cap');
+        }
+        const note = body['note'];
+        if (typeof note !== 'string' || note.trim().length === 0) {
+            throw new HttpError(400, 'note is required (non-empty string)');
+        }
+        if (note.length > 8192) {
+            throw new HttpError(400, 'note exceeds 8192-character cap');
+        }
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        try {
+            const customerNote = saveCustomerNote(opts.hippoRoot, ctx.tenantId, {
+                customer,
+                note,
+            }, ctx.actor.subject);
+            sendJson(res, 201, { note: customerNote });
+        }
+        catch (e) {
+            // saveCustomerNote throws on validation (single-line customer etc.) -> 400.
+            throw new HttpError(400, e.message);
+        }
+        return;
+    }
+    if (method === 'GET' && path === '/v1/customer-notes') {
+        const status = query.get('status') ?? 'all';
+        const customerFilter = query.get('customer');
+        const limit = parseListLimit(query.get('limit'));
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const listOpts = { limit };
+        if (customerFilter !== null && customerFilter.trim().length > 0) {
+            listOpts.customer = customerFilter.trim();
+        }
+        if (status !== 'all') {
+            if (!VALID_NOTE_STATES.has(status)) {
+                throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
+            }
+            listOpts.status = status;
+        }
+        const notes = loadCustomerNotes(opts.hippoRoot, ctx.tenantId, listOpts);
+        sendJson(res, 200, { notes });
+        return;
+    }
+    const noteSupersedeMatch = path.match(/^\/v1\/customer-notes\/(\d+)\/supersede$/);
+    if (method === 'POST' && noteSupersedeMatch) {
+        const id = parseInt(noteSupersedeMatch[1], 10);
+        const body = await parseJsonBody(req);
+        const note = body['note'];
+        if (typeof note !== 'string' || note.trim().length === 0) {
+            throw new HttpError(400, 'note is required (non-empty string)');
+        }
+        if (note.length > 8192) {
+            throw new HttpError(400, 'note exceeds 8192-character cap');
+        }
+        const changeRaw = body['changeSummary'];
+        let changeSummary;
+        if (changeRaw !== undefined && changeRaw !== null) {
+            if (typeof changeRaw !== 'string') {
+                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 ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const existing = loadCustomerNoteById(opts.hippoRoot, ctx.tenantId, id);
+        if (!existing) {
+            throw new HttpError(404, `customer note ${id} not found`);
+        }
+        try {
+            const customerNote = saveCustomerNote(opts.hippoRoot, ctx.tenantId, {
+                customer: existing.customer,
+                note,
+                changeSummary,
+                supersedesNoteId: id,
+            }, ctx.actor.subject);
+            sendJson(res, 200, { note: customerNote });
+        }
+        catch (e) {
+            const msg = e.message;
+            if (msg.includes('not found')) {
+                throw new HttpError(404, msg);
+            }
+            if (msg.includes('not active') || msg.includes('could not be superseded')) {
+                throw new HttpError(409, msg);
+            }
+            throw new HttpError(400, msg);
+        }
+        return;
+    }
+    const noteCloseMatch = path.match(/^\/v1\/customer-notes\/(\d+)\/close$/);
+    if (method === 'POST' && noteCloseMatch) {
+        const id = parseInt(noteCloseMatch[1], 10);
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        try {
+            const customerNote = closeCustomerNote(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+            sendJson(res, 200, { note: customerNote });
+        }
+        catch (e) {
+            const msg = e.message;
+            if (msg.includes('not found')) {
+                throw new HttpError(404, msg);
+            }
+            if (msg.includes('not active')) {
+                throw new HttpError(409, msg);
+            }
+            throw e;
+        }
+        return;
+    }
+    const noteByIdMatch = path.match(/^\/v1\/customer-notes\/(\d+)$/);
+    if (method === 'GET' && noteByIdMatch) {
+        const id = parseInt(noteByIdMatch[1], 10);
+        const ctx = buildContextWithAuth(req, opts.hippoRoot);
+        const customerNote = loadCustomerNoteById(opts.hippoRoot, ctx.tenantId, id);
+        if (!customerNote) {
+            throw new HttpError(404, `customer note ${id} not found`);
+        }
+        sendJson(res, 200, { note: customerNote });
+        return;
+    }
     // ── POST /v1/connectors/slack/events ──
     //
     // Slack Events API webhook. Auth is signature-based (HMAC over the raw