hippo-memory 1.69.0 → 1.71.0

package/dist/server/routes/decisions.js

@@ -1,56 +1,36 @@
 // /v1/decisions routes.
-import { closeDecision, loadDecisionById, loadDecisions, saveDecision, VALID_DECISION_STATES } from '../../decisions.js';
-import { HttpError, sendJson } from '../../http-util.js';
-import { NotFoundError } from '../../api-errors.js';
+import { DECISION } from '../../objects/decisions.js';
+import { HttpError, sendJson } from '../../util/http-util.js';
+import { NotFoundError } from '../../core/api-errors.js';
+import { isJsonNumber } from '../../util/json.js';
 import { buildContextWithAuth } from '../auth.js';
-import { byCreatedAt, pageOf, parseCursor } from '../cursor.js';
-import { isJsonNumber, isSetMember, parseJsonBody, parseListLimit } from '../validation.js';
-import { isJsonString } from '../../json.js';
-// ── decisions (first-class object) ──
-//
-// 5 routes: POST /v1/decisions (create, optional supersedesDecisionId),
-// GET /v1/decisions (list, status filter), GET /v1/decisions/:id (show),
-// POST /v1/decisions/:id/supersede (create a successor + supersede :id),
-// POST /v1/decisions/:id/close (retire). Bearer-authed + tenant-scoped via
-// buildContextWithAuth. status validated against VALID_DECISION_STATES.
-// DoS caps: text 4096, context 4096. The HTTP surface is
-// new (no legacy --supersedes <memory-id> constraint), so it supersedes by
-// table id and never weakens a memory mirror.
-export async function handleCreateDecision({ 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 supRaw = body['supersedesDecisionId'];
-    let supersedesDecisionId;
-    if (supRaw !== undefined && supRaw !== null) {
-        if (!isJsonNumber(supRaw) || !Number.isInteger(supRaw) || supRaw <= 0) {
-            throw new HttpError(400, 'supersedesDecisionId must be a positive integer');
-        }
-        supersedesDecisionId = supRaw;
+import { MAX_SHORT_FIELD_LEN, parseJsonBody } from '../validation.js';
+import { saveFor } from '../../api/objects.js';
+import { closeRoute, getRoute, listRoute, optionalString, requiredString } from './object-routes.js';
+const decisionRoutes = { noun: 'decision', field: 'decision', listField: 'decisions', object: DECISION };
+const TEXT = { max: MAX_SHORT_FIELD_LEN, untrimmed: true };
+function supersededId(body) {
+    const raw = body['supersedesDecisionId'];
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isJsonNumber(raw) || !Number.isInteger(raw) || raw <= 0) {
+        throw new HttpError(400, 'supersedesDecisionId must be a positive integer');
     }
+    return raw;
+}
+// Routes: /v1/decisions (create, list, show, supersede, close), Bearer-authed and tenant-scoped; status is validated against VALID_DECISION_STATES.
+// The HTTP surface has no legacy --supersedes <memory-id> constraint, so it supersedes by table id and never weakens a memory mirror.
+export async function handleCreateDecision(rr) {
+    const { req, res } = rr;
+    const ctx = await buildContextWithAuth(req, rr.opts);
+    const body = await parseJsonBody(req, ctx);
+    const write = {
+        decisionText: requiredString(body, 'text', TEXT),
+        context: optionalString(body, 'context', MAX_SHORT_FIELD_LEN),
+        supersedesDecisionId: supersededId(body),
+    };
     try {
-        const decision = saveDecision(opts.hippoRoot, ctx.tenantId, {
-            decisionText: text,
-            context,
-            supersedesDecisionId,
-        }, ctx.actor.subject);
+        const decision = await saveFor(ctx, DECISION, write);
         sendJson(res, 201, { decision });
     }
     catch (e) {
@@ -59,76 +39,26 @@ export async function handleCreateDecision({ req, res, opts }) {
             throw new HttpError(409, e.message);
         throw e;
     }
-    return;
 }
-export async function handleListDecisions({ 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 decisions;
-    if (status === 'all') {
-        decisions = loadDecisions(opts.hippoRoot, ctx.tenantId, { limit: limit + 1, after });
-    }
-    else {
-        if (!isSetMember(VALID_DECISION_STATES, status)) {
-            throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
-        }
-        decisions = loadDecisions(opts.hippoRoot, ctx.tenantId, {
-            status,
-            limit: limit + 1,
-            after,
-        });
-    }
-    const page = pageOf(decisions, limit, byCreatedAt);
-    sendJson(res, 200, { decisions: page.items, next_cursor: page.nextCursor });
-    return;
+export function handleListDecisions(rr) {
+    return listRoute(decisionRoutes, rr);
 }
-export async function handleSupersedeDecision({ req, res, opts }, decisionSupersedeMatch) {
-    const oldId = parseInt(decisionSupersedeMatch[1], 10);
-    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 decision = saveDecision(opts.hippoRoot, ctx.tenantId, {
-        decisionText: text,
-        context,
+// Not on supersedeRoute: this one answers 201 and leaves the missing-row 404 to the store, where the other five answer 200 after their own lookup.
+export async function handleSupersedeDecision(rr, match) {
+    const oldId = parseInt(match[1], 10);
+    const ctx = await buildContextWithAuth(rr.req, rr.opts);
+    const body = await parseJsonBody(rr.req, ctx);
+    const decision = await saveFor(ctx, DECISION, {
+        decisionText: requiredString(body, 'text', TEXT),
+        context: optionalString(body, 'context', MAX_SHORT_FIELD_LEN),
         supersedesDecisionId: oldId,
-    }, ctx.actor.subject);
-    sendJson(res, 201, { decision });
-    return;
+    });
+    sendJson(rr.res, 201, { decision });
 }
-export async function handleCloseDecision({ req, res, opts }, decisionCloseMatch) {
-    const id = parseInt(decisionCloseMatch[1], 10);
-    const ctx = await buildContextWithAuth(req, opts);
-    const decision = closeDecision(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
-    sendJson(res, 200, { decision });
-    return;
+export function handleCloseDecision(rr, match) {
+    return closeRoute(decisionRoutes, rr, match);
 }
-export async function handleGetDecision({ req, res, opts }, decisionByIdMatch) {
-    const id = parseInt(decisionByIdMatch[1], 10);
-    const ctx = await buildContextWithAuth(req, opts);
-    const decision = loadDecisionById(opts.hippoRoot, ctx.tenantId, id);
-    if (!decision) {
-        throw new HttpError(404, `decision ${id} not found`);
-    }
-    sendJson(res, 200, { decision });
-    return;
+export function handleGetDecision(rr, match) {
+    return getRoute(decisionRoutes, rr, match);
 }
 //# sourceMappingURL=decisions.js.map

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

@@ -1,7 +1,7 @@
 import type { RouteRequest } from '../types.js';
-export declare function handleCreateIncident({ req, res, opts }: RouteRequest): Promise<void>;
-export declare function handleListIncidents({ req, res, opts, query }: RouteRequest): Promise<void>;
-export declare function handleResolveIncident({ req, res, opts }: RouteRequest, incidentResolveMatch: RegExpMatchArray): Promise<void>;
-export declare function handleCloseIncident({ req, res, opts }: RouteRequest, incidentCloseMatch: RegExpMatchArray): Promise<void>;
-export declare function handleGetIncident({ req, res, opts }: RouteRequest, incidentByIdMatch: RegExpMatchArray): Promise<void>;
+export declare function handleCreateIncident(rr: RouteRequest): Promise<void>;
+export declare function handleListIncidents(rr: RouteRequest): Promise<void>;
+export declare function handleResolveIncident(rr: RouteRequest, match: RegExpMatchArray): Promise<void>;
+export declare function handleCloseIncident(rr: RouteRequest, match: RegExpMatchArray): Promise<void>;
+export declare function handleGetIncident(rr: RouteRequest, match: RegExpMatchArray): Promise<void>;
 //# sourceMappingURL=incidents.d.ts.map

package/dist/server/routes/incidents.js

@@ -1,65 +1,43 @@
 // /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 { INCIDENT, openIncident, resolveOpenIncident } from '../../objects/incidents.js';
+import { HttpError, sendJson } from '../../util/http-util.js';
+import { NotFoundError } from '../../core/api-errors.js';
 import { buildContextWithAuth } from '../auth.js';
-import { byCreatedAt, pageOf, parseCursor } from '../cursor.js';
-import { isSetMember, parseJsonBody, parseListLimit } from '../validation.js';
-import { isJsonString } from '../../json.js';
+import { MAX_SHORT_FIELD_LEN, parseJsonBody } from '../validation.js';
+import { isJsonString } from '../../util/json.js';
+import { objectsOf } from '../../api/objects.js';
+import { closeRoute, getRoute, listRoute, optionalString, requiredString } from './object-routes.js';
 const MAX_LINKED_MEMORY_IDS = 256;
-// ── incidents (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. 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 incidentRoutes = { noun: 'incident', field: 'incident', listField: 'incidents', object: INCIDENT };
+function linkedMemoryIds(body) {
+    const raw = body['linkedMemoryIds'];
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!Array.isArray(raw)) {
+        throw new HttpError(400, 'linkedMemoryIds must be an array of memory ids');
     }
-    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;
+    if (raw.length > MAX_LINKED_MEMORY_IDS) {
+        throw new HttpError(400, `linkedMemoryIds exceeds ${MAX_LINKED_MEMORY_IDS}-item cap`);
     }
-    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 > MAX_LINKED_MEMORY_IDS) {
-            throw new HttpError(400, `linkedMemoryIds exceeds ${MAX_LINKED_MEMORY_IDS}-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;
+    const isValidMemoryId = (item) => isJsonString(item) && item.length > 0 && item.length <= MAX_SHORT_FIELD_LEN;
+    if (!raw.every(isValidMemoryId)) {
+        throw new HttpError(400, `each linkedMemoryIds entry must be a non-empty string <= ${MAX_SHORT_FIELD_LEN} chars`);
     }
+    return raw;
+}
+// Routes: /v1/incidents (open, list, show, resolve, close), mirroring /v1/decisions; status is validated against VALID_INCIDENT_STATES.
+// Lifecycle is open->resolved->closed (no supersede), so linkedMemoryIds replaces supersedesDecisionId on create.
+export async function handleCreateIncident(rr) {
+    const { req, res, opts } = rr;
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const write = {
+        incidentText: requiredString(body, 'text', { max: MAX_SHORT_FIELD_LEN, untrimmed: true }),
+        context: optionalString(body, 'context', MAX_SHORT_FIELD_LEN),
+        linkedMemoryIds: linkedMemoryIds(body),
+    };
     try {
-        const incident = saveIncident(opts.hippoRoot, ctx.tenantId, {
-            incidentText: text,
-            context,
-            linkedMemoryIds,
-        }, ctx.actor.subject);
+        const incident = await openIncident(objectsOf(ctx), opts.hippoRoot, ctx.tenantId, write, ctx.actor.subject);
         sendJson(res, 201, { incident });
     }
     catch (e) {
@@ -68,61 +46,22 @@ export async function handleCreateIncident({ req, res, opts }) {
             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 function handleListIncidents(rr) {
+    return listRoute(incidentRoutes, rr);
 }
-export async function handleResolveIncident({ req, res, opts }, incidentResolveMatch) {
-    const id = parseInt(incidentResolveMatch[1], 10);
+export async function handleResolveIncident(rr, match) {
+    const { req, res, opts } = rr;
+    const id = parseInt(match[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);
+    const resolutionText = requiredString(await parseJsonBody(req, ctx), 'resolutionText', { max: MAX_SHORT_FIELD_LEN });
+    const incident = await resolveOpenIncident(objectsOf(ctx), 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 function handleCloseIncident(rr, match) {
+    return closeRoute(incidentRoutes, rr, match);
 }
-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;
+export function handleGetIncident(rr, match) {
+    return getRoute(incidentRoutes, rr, match);
 }
 //# sourceMappingURL=incidents.js.map

package/dist/server/routes/memories.js

@@ -1,12 +1,13 @@
 // 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 { canReadScope } from '../../recall-scope.js';
+import { graphRows } from '../../api/graph.js';
+import { archiveRaw, forget, outcome, outcomeForLastRecall, promote, remember, supersede } from '../../api/index.js';
+import { graphModelOf } from '../../graph/view.js';
+import { MAX_ENTITY_NAME_LEN } from '../../store/graph-rows.js';
+import { HttpError, sendJson } from '../../util/http-util.js';
 import { assertCrossTenantAdmin, buildContextWithAuth, isLoopback } from '../auth.js';
-import { getCallerProject, getString, getStringArray, isJsonBoolean, isSetMember, parseJsonBody, parseListLimit, validateIdSegment } from '../validation.js';
-import { isJsonString } from '../../json.js';
+import { sleepInChild } from '../sleep-offload.js';
+import { getCallerProject, getString, getStringArray, isSetMember, parseJsonBody, parseListLimit, validateIdSegment } from '../validation.js';
+import { isJsonString, isJsonBoolean } from '../../util/json.js';
 const VALID_KINDS = new Set([
     'raw',
     'distilled',
@@ -52,12 +53,8 @@ export async function handleGetGraph({ req, res, opts, query }) {
     }
     const limit = parseListLimit(query.get('limit'));
     const ctx = await buildContextWithAuth(req, opts);
-    const model = buildGraphModel(ctx.hippoRoot, ctx.tenantId, {
-        entity: entityRaw ?? undefined,
-        limit,
-        canRead: (s) => s === null || canReadScope(ctx.actor, s),
-    });
-    sendJson(res, 200, model);
+    const rows = await graphRows(ctx, { entity: entityRaw ?? undefined, limit });
+    sendJson(res, 200, graphModelOf(rows));
     return;
 }
 // /v1/memories/:id/* and DELETE /v1/memories/:id
@@ -99,12 +96,8 @@ export async function handleForgetMemory({ req, res, opts }, idMatch) {
     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).
+// POST /v1/outcome: applies a positive/negative outcome to memory ids; without ids it falls back to the last-recall path (api.outcomeForLastRecall)
+// and returns {applied, ids}, so callers can tell "no recent recall" from "all ids skipped". Each applied id writes one audit_log row (op='outcome').
 export async function handleApplyOutcome({ req, res, opts }) {
     const ctx = await buildContextWithAuth(req, opts);
     const body = await parseJsonBody(req, ctx);
@@ -122,10 +115,8 @@ export async function handleApplyOutcome({ req, res, opts }) {
         if (!idsRaw.every(isNonEmptyId)) {
             throw new HttpError(400, 'ids must be an array of non-empty strings');
         }
-        // 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.
+        // DoS cap on ids.length (each id costs ~3 DB ops): N=1000 keeps per-request work sub-second on SQLite.
+        // Checked BEFORE buildContextWithAuth so attack traffic does not pay the api-key lookup.
         if (idsRaw.length > 1000) {
             throw new HttpError(400, 'ids exceeds 1000-id cap');
         }
@@ -144,29 +135,16 @@ export async function handleApplyOutcome({ req, res, opts }) {
     }
     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.
+// POST /v1/sleep: host-wide consolidation (consolidate, dedup, audit, share, ambient); api.sleep spans the WHOLE hippoRoot, cross-tenant by design, so the
+// loopback-only guard is the trust boundary; non-loopback serving must also zero cross-tenant counters. Body {dry_run?, no_share?}; returns SleepResult JSON.
 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.
+    // Defensive per-request loopback guard using isLoopback(), so future mapped/IPv6/NAT64 forms flow through without drift;
+    // serve()'s boot-time host check is the primary trust boundary.
     if (!isLoopback(req.socket.remoteAddress)) {
         throw new HttpError(403, '/v1/sleep is loopback-only (host-wide consolidation; see CHANGELOG v1.11.4)');
     }
-    // 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.
+    // Admin-role gate, forward-defensive: loopback fallback is admin by default and Bearer callers carry an explicit role from the api_keys row;
+    // when non-loopback serving lands, this gate is the real 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');
@@ -180,7 +158,7 @@ export async function handleSleep({ req, res, opts }) {
         throw new HttpError(400, 'no_share must be a boolean');
     }
     // sleepCtx already built above for the admin-role gate; reuse.
-    const result = await sleep(sleepCtx, {
+    const result = await sleepInChild(sleepCtx, {
         dryRun: dryRunRaw === true,
         noShare: noShareRaw === true,
     });

package/dist/server/routes/object-routes.d.ts

@@ -0,0 +1,35 @@
+import { type JsonValue } from '../../util/json.js';
+import type { ObjectDescriptor, SavableDescriptor } from '../../objects/descriptor.js';
+import type { ObjectByKind, ObjectKind, SavableKind } from '../../store/object-types.js';
+import type { RouteRequest } from '../types.js';
+export interface ObjectRouteConfig<K extends ObjectKind> {
+    /** Names the object in the 404 text, e.g. "customer note". */
+    readonly noun: string;
+    /** Reply field that carries one object, e.g. "note". */
+    readonly field: string;
+    /** Reply field that carries a page, e.g. "notes". */
+    readonly listField: string;
+    /** The bad-status reply lists `object.states` in the set's own order. */
+    readonly object: ObjectDescriptor<K>;
+    /** List query parameter matched against the kind's filter column, e.g. "customer". */
+    readonly filterParam?: string;
+}
+export interface VersionedRouteConfig<K extends SavableKind, W> extends ObjectRouteConfig<K> {
+    readonly object: SavableDescriptor<K, W>;
+    /** Checks the body, then returns the successor's write; split in two so a bad body answers 400 before a missing row answers 404. */
+    readonly revise: (body: Record<string, JsonValue>) => (existing: ObjectByKind[K], id: number) => W;
+}
+export interface RequiredStringRule {
+    readonly max: number;
+    /** The field name is a plural noun, so the replies read "are required" and "exceed". */
+    readonly plural?: boolean;
+    /** The blank check does not trim, so a value of only spaces passes it. */
+    readonly untrimmed?: boolean;
+}
+export declare function requiredString(body: Record<string, JsonValue>, key: string, rule: RequiredStringRule): string;
+export declare function optionalString(body: Record<string, JsonValue>, key: string, max: number): string | undefined;
+export declare function listRoute<K extends ObjectKind>(cfg: ObjectRouteConfig<K>, rr: RouteRequest): Promise<void>;
+export declare function getRoute<K extends ObjectKind>(cfg: ObjectRouteConfig<K>, rr: RouteRequest, match: RegExpMatchArray): Promise<void>;
+export declare function closeRoute<K extends ObjectKind>(cfg: ObjectRouteConfig<K>, rr: RouteRequest, match: RegExpMatchArray): Promise<void>;
+export declare function supersedeRoute<K extends SavableKind, W>(cfg: VersionedRouteConfig<K, W>, rr: RouteRequest, match: RegExpMatchArray): Promise<void>;
+//# sourceMappingURL=object-routes.d.ts.map

package/dist/server/routes/object-routes.js

@@ -0,0 +1,72 @@
+// List, get, close and supersede handlers shared by the typed-object routes; each route file passes one config.
+import { HttpError, sendJson } from '../../util/http-util.js';
+import { isJsonString } from '../../util/json.js';
+import { objectsOf, saveFor } from '../../api/objects.js';
+import { closeObject, listObjects, objectById } from '../../objects/lifecycle.js';
+import { buildContextWithAuth } from '../auth.js';
+import { byCreatedAt, pageOf, parseCursor } from '../cursor.js';
+import { isSetMember, parseJsonBody, parseListLimit } from '../validation.js';
+export function requiredString(body, key, rule) {
+    const value = body[key];
+    if (!isJsonString(value) || (rule.untrimmed ? value : value.trim()).length === 0) {
+        throw new HttpError(400, `${key} ${rule.plural ? 'are' : 'is'} required (non-empty string)`);
+    }
+    if (value.length > rule.max) {
+        throw new HttpError(400, `${key} ${rule.plural ? 'exceed' : 'exceeds'} ${rule.max}-character cap`);
+    }
+    return value;
+}
+export function optionalString(body, key, max) {
+    const value = body[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (!isJsonString(value))
+        throw new HttpError(400, `${key} must be a string`);
+    if (value.length > max)
+        throw new HttpError(400, `${key} exceeds ${max}-character cap`);
+    return value;
+}
+async function found(cfg, objects, tenantId, id) {
+    const row = await objectById(objects, cfg.object, tenantId, id);
+    if (!row)
+        throw new HttpError(404, `${cfg.noun} ${id} not found`);
+    return row;
+}
+// Limit and cursor are checked before auth and status after it, so a keyless caller gets 400 for the first two and 401 for a bad status.
+export async function listRoute(cfg, rr) {
+    const { req, res, opts, query } = rr;
+    const status = query.get('status') ?? 'all';
+    const filter = cfg.filterParam === undefined ? null : query.get(cfg.filterParam);
+    const limit = parseListLimit(query.get('limit'));
+    const after = parseCursor(query.get('cursor'), 'string', 'integer');
+    const ctx = await buildContextWithAuth(req, opts);
+    const listOpts = { limit: limit + 1, after, filter: filter?.trim() || undefined };
+    if (status !== 'all') {
+        const states = cfg.object.states;
+        if (!isSetMember(states, status)) {
+            throw new HttpError(400, `status must be one of: ${[...states].join(' | ')} | all (got "${status}")`);
+        }
+        listOpts.status = status;
+    }
+    const page = pageOf(await listObjects(objectsOf(ctx), cfg.object, ctx.tenantId, listOpts), limit, byCreatedAt);
+    sendJson(res, 200, { [cfg.listField]: page.items, next_cursor: page.nextCursor });
+}
+export async function getRoute(cfg, rr, match) {
+    const id = parseInt(match[1], 10);
+    const ctx = await buildContextWithAuth(rr.req, rr.opts);
+    sendJson(rr.res, 200, { [cfg.field]: await found(cfg, objectsOf(ctx), ctx.tenantId, id) });
+}
+export async function closeRoute(cfg, rr, match) {
+    const id = parseInt(match[1], 10);
+    const ctx = await buildContextWithAuth(rr.req, rr.opts);
+    sendJson(rr.res, 200, { [cfg.field]: await closeObject(objectsOf(ctx), cfg.object, ctx.tenantId, id, ctx.actor.subject) });
+}
+export async function supersedeRoute(cfg, rr, match) {
+    const id = parseInt(match[1], 10);
+    const ctx = await buildContextWithAuth(rr.req, rr.opts);
+    const successor = cfg.revise(await parseJsonBody(rr.req, ctx));
+    const existing = await found(cfg, objectsOf(ctx), ctx.tenantId, id);
+    const saved = await saveFor(ctx, cfg.object, successor(existing, id));
+    sendJson(rr.res, 200, { [cfg.field]: saved });
+}
+//# sourceMappingURL=object-routes.js.map

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

@@ -1,8 +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>;
+export declare function handleCreatePolicy(rr: RouteRequest): Promise<void>;
+export declare function handleListPolicies(rr: RouteRequest): Promise<void>;
+export declare function handlePoliciesAsOf(rr: RouteRequest): Promise<void>;
+export declare function handleSupersedePolicy(rr: RouteRequest, match: RegExpMatchArray): Promise<void>;
+export declare function handleClosePolicy(rr: RouteRequest, match: RegExpMatchArray): Promise<void>;
+export declare function handleGetPolicy(rr: RouteRequest, match: RegExpMatchArray): Promise<void>;
 //# sourceMappingURL=policies.d.ts.map