hippo-memory 1.32.0 → 1.33.0

package/dist/src/server.js

@@ -118,6 +118,41 @@ const VALID_AUDIT_OPS = new Set([
 // 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;
+function isJsonString(value) {
+    return typeof value === 'string';
+}
+function isJsonNumber(value) {
+    return typeof value === 'number';
+}
+function isJsonBoolean(value) {
+    return typeof value === 'boolean';
+}
+function isJsonObjectRecord(value) {
+    return value !== undefined && value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+// node:http header values are `string | string[] | undefined` (never a bare
+// unknown), so this gets its own predicate rather than reusing isJsonString.
+function isHeaderString(value) {
+    return typeof value === 'string';
+}
+// server.address() returns AddressInfo once a TCP socket is bound; null before
+// listening, a string only for pipe/unix-socket listeners (never used here).
+function isAddressInfo(a) {
+    return a !== null && typeof a !== 'string';
+}
+// Runtime membership check for a `ReadonlySet<T>` of string-literal union
+// members, used at every `body` field validated against a VALID_* set below.
+// Set<T>.has(value: T) itself gives no narrowing (its parameter type is T,
+// not a type predicate) so callers previously needed a separate `as T` cast
+// at both the check and the later usage; this helper is the one place that
+// assertion lives, so downstream call sites narrow via the `value is T`
+// return instead of re-asserting.
+function isSetMember(set, value) {
+    // SAFETY: `value as T` is discarded unless `set.has` (the real runtime
+    // check) confirms membership; the `value is T` return type is what
+    // performs the actual narrowing for callers.
+    return set.has(value);
+}
 // 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.
@@ -131,7 +166,7 @@ function validateProcessStepsBody(raw) {
         throw new HttpError(400, 'steps exceeds 200-step cap');
     }
     for (const item of raw) {
-        if (typeof item !== 'string') {
+        if (!isJsonString(item)) {
             throw new HttpError(400, 'each step must be a string');
         }
         if (item.trim().length === 0) {
@@ -141,6 +176,7 @@ function validateProcessStepsBody(raw) {
             throw new HttpError(400, 'a step exceeds the 2000-character cap');
         }
     }
+    // SAFETY: every item in raw was confirmed to be a string in the loop above.
     return raw;
 }
 // HTTP-boundary check for an optional policy date field (validFrom/validTo).
@@ -150,7 +186,7 @@ function validateProcessStepsBody(raw) {
 function optionalDateField(raw, label) {
     if (raw === undefined || raw === null)
         return undefined;
-    if (typeof raw !== 'string') {
+    if (!isJsonString(raw)) {
         throw new HttpError(400, `${label} must be a string`);
     }
     if (raw.length > 64) {
@@ -216,6 +252,8 @@ async function readBody(req) {
     const chunks = [];
     let total = 0;
     for await (const chunk of req) {
+        // SAFETY: IncomingMessage never runs setEncoding() here, so every
+        // streamed chunk is a Buffer, not a decoded string.
         const buf = chunk;
         total += buf.length;
         if (total > MAX_BODY_BYTES) {
@@ -231,7 +269,7 @@ async function parseJsonBody(req) {
         return {};
     try {
         const parsed = JSON.parse(raw);
-        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        if (!isJsonObjectRecord(parsed)) {
             throw new HttpError(400, 'request body must be a JSON object');
         }
         return parsed;
@@ -320,8 +358,9 @@ function readAuthHeader(req) {
     if (raw === undefined)
         return { kind: 'absent' };
     const value = Array.isArray(raw) ? raw[0] : raw;
-    if (typeof value !== 'string' || value.length === 0)
+    if (!isHeaderString(value) || value.length === 0) {
         return { kind: 'malformed' };
+    }
     const space = value.indexOf(' ');
     if (space < 0)
         return { kind: 'malformed' };
@@ -432,13 +471,13 @@ function requireAuth(req, hippoRoot) {
 }
 function getString(obj, key) {
     const v = obj[key];
-    return typeof v === 'string' ? v : undefined;
+    return isJsonString(v) ? v : undefined;
 }
 function getStringArray(obj, key) {
     const v = obj[key];
     if (!Array.isArray(v))
         return undefined;
-    if (!v.every((x) => typeof x === 'string'))
+    if (!v.every(isJsonString))
         return undefined;
     return v;
 }
@@ -518,7 +557,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             throw new HttpError(400, 'content is required');
         }
         const kindRaw = getString(body, 'kind');
-        if (kindRaw !== undefined && !VALID_KINDS.has(kindRaw)) {
+        if (kindRaw !== undefined && !isSetMember(VALID_KINDS, kindRaw)) {
             throw new HttpError(400, `invalid kind: ${kindRaw}`);
         }
         const ctx = buildContextWithAuth(req, opts.hippoRoot);
@@ -667,19 +706,28 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
                 }
             }
         }
+        const recallExtra = {};
+        if (freshTailCount !== undefined)
+            recallExtra.freshTailCount = freshTailCount;
+        if (freshTailSessionId !== undefined)
+            recallExtra.freshTailSessionId = freshTailSessionId;
+        if (summarizeOverflow !== undefined)
+            recallExtra.summarizeOverflow = summarizeOverflow;
+        if (scorerWindow !== undefined)
+            recallExtra.scorerWindow = scorerWindow;
+        if (sessionId !== undefined)
+            recallExtra.sessionId = sessionId;
+        if (httpRecallHistory !== undefined)
+            recallExtra.recallHistory = httpRecallHistory;
+        if (explain)
+            recallExtra.explain = explain;
         const result = recall(ctx, {
             query: q,
             limit,
-            mode: (mode ?? undefined),
+            mode: mode ?? undefined,
             scope: scope ?? undefined,
             includeContinuity,
-            ...(freshTailCount !== undefined ? { freshTailCount } : {}),
-            ...(freshTailSessionId !== undefined ? { freshTailSessionId } : {}),
-            ...(summarizeOverflow !== undefined ? { summarizeOverflow } : {}),
-            ...(scorerWindow !== undefined ? { scorerWindow } : {}),
-            ...(sessionId !== undefined ? { sessionId } : {}),
-            ...(httpRecallHistory !== undefined ? { recallHistory: httpRecallHistory } : {}),
-            ...(explain ? { explain } : {}),
+            ...recallExtra,
         });
         // v0.33 / J1 — append AFTER recall completes (snapshot was taken before
         // recall() ran). anchoredOn carries the memoryId of any hint that fired
@@ -729,12 +777,16 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const scopeQ = query.get('scope');
         const scope = scopeQ !== null && scopeQ.length > 0 ? scopeQ : undefined;
         const ctx = buildContextWithAuth(req, opts.hippoRoot);
-        const result = assemble(ctx, assembleMatch.id, {
-            ...(budget !== undefined ? { budget } : {}),
-            ...(freshTailCount !== undefined ? { freshTailCount } : {}),
-            ...(summarizeOlder !== undefined ? { summarizeOlder } : {}),
-            ...(scope !== undefined ? { scope } : {}),
-        });
+        const assembleExtra = {};
+        if (budget !== undefined)
+            assembleExtra.budget = budget;
+        if (freshTailCount !== undefined)
+            assembleExtra.freshTailCount = freshTailCount;
+        if (summarizeOlder !== undefined)
+            assembleExtra.summarizeOlder = summarizeOlder;
+        if (scope !== undefined)
+            assembleExtra.scope = scope;
+        const result = assemble(ctx, assembleMatch.id, assembleExtra);
         sendJson(res, 200, result);
         return;
     }
@@ -769,11 +821,14 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             depth = parsed;
         }
         const ctx = buildContextWithAuth(req, opts.hippoRoot);
-        const result = drillDown(ctx, drillMatch.id, {
-            ...(limit !== undefined ? { limit } : {}),
-            ...(budget !== undefined ? { budget } : {}),
-            ...(depth !== undefined ? { depth } : {}),
-        });
+        const drillExtra = {};
+        if (limit !== undefined)
+            drillExtra.limit = limit;
+        if (budget !== undefined)
+            drillExtra.budget = budget;
+        if (depth !== undefined)
+            drillExtra.depth = depth;
+        const result = drillDown(ctx, drillMatch.id, drillExtra);
         if ('failure' in result) {
             // v1.6.4: leaf id maps to 422 (caller-actionable). Other cases stay
             // as 404 to avoid leaking cross-tenant existence or scope grants.
@@ -837,7 +892,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     if (method === 'POST' && path === '/v1/outcome') {
         const body = await parseJsonBody(req);
         const good = body['good'];
-        if (typeof good !== 'boolean') {
+        if (!isJsonBoolean(good)) {
             throw new HttpError(400, 'good is required (boolean)');
         }
         const idsRaw = body['ids'];
@@ -846,10 +901,9 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             if (!Array.isArray(idsRaw)) {
                 throw new HttpError(400, 'ids must be an array of non-empty strings');
             }
-            for (const id of idsRaw) {
-                if (typeof id !== 'string' || id.length === 0) {
-                    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
@@ -965,11 +1019,11 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         }
         const body = await parseJsonBody(req);
         const dryRunRaw = body['dry_run'];
-        if (dryRunRaw !== undefined && typeof dryRunRaw !== 'boolean') {
+        if (dryRunRaw !== undefined && !isJsonBoolean(dryRunRaw)) {
             throw new HttpError(400, 'dry_run must be a boolean');
         }
         const noShareRaw = body['no_share'];
-        if (noShareRaw !== undefined && typeof noShareRaw !== 'boolean') {
+        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.
@@ -986,7 +1040,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     if (method === 'POST' && path === '/v1/auth/keys') {
         const body = await parseJsonBody(req);
         const labelRaw = body['label'];
-        if (labelRaw !== undefined && typeof labelRaw !== 'string') {
+        if (labelRaw !== undefined && !isJsonString(labelRaw)) {
             throw new HttpError(400, 'label must be a string');
         }
         // v1.12.3: optional body.role mirrors the --role CLI flag. Validated
@@ -1054,7 +1108,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const opRaw = query.get('op');
         let op;
         if (opRaw !== null) {
-            if (!VALID_AUDIT_OPS.has(opRaw)) {
+            if (!isSetMember(VALID_AUDIT_OPS, opRaw)) {
                 throw new HttpError(400, `invalid op: ${opRaw}`);
             }
             op = opRaw;
@@ -1103,20 +1157,20 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     if (method === 'POST' && path === '/v1/predictions') {
         const body = await parseJsonBody(req);
         const claim = body['claim'];
-        if (typeof claim !== 'string' || claim.length === 0) {
+        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 (typeof classTag !== 'string' || classTag.length === 0) {
+        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 (typeof estimate !== 'number' || !Number.isFinite(estimate)) {
+            if (!isJsonNumber(estimate) || !Number.isFinite(estimate)) {
                 throw new HttpError(400, 'estimate must be a finite number');
             }
             estimateValue = estimate;
@@ -1124,7 +1178,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const unit = body['unit'];
         let estimateUnit;
         if (unit !== undefined && unit !== null) {
-            if (typeof unit !== 'string') {
+            if (!isJsonString(unit)) {
                 throw new HttpError(400, 'unit must be a string');
             }
             estimateUnit = unit;
@@ -1132,7 +1186,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const targetDate = body['targetDate'];
         let targetDateValue;
         if (targetDate !== undefined && targetDate !== null) {
-            if (typeof targetDate !== 'string') {
+            if (!isJsonString(targetDate)) {
                 throw new HttpError(400, 'targetDate must be an ISO date string');
             }
             targetDateValue = targetDate;
@@ -1169,7 +1223,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             });
         }
         else {
-            if (!VALID_CLOSURE_STATES.has(status)) {
+            if (!isSetMember(VALID_CLOSURE_STATES, status)) {
                 throw new HttpError(400, `status must be one of: open | closed | closed-unknown | all (got "${status}")`);
             }
             if (!classTag) {
@@ -1216,13 +1270,13 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const id = parseInt(predictionCloseMatch[1], 10);
         const body = await parseJsonBody(req);
         const state = body['state'];
-        if (typeof state !== 'string' || !VALID_CLOSURE_STATES.has(state) || state === 'open') {
+        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 (typeof actual !== 'number' || !Number.isFinite(actual)) {
+            if (!isJsonNumber(actual) || !Number.isFinite(actual)) {
                 throw new HttpError(400, 'actual must be a finite number');
             }
             actualValue = actual;
@@ -1230,7 +1284,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const note = body['note'];
         let closureNote;
         if (note !== undefined && note !== null) {
-            if (typeof note !== 'string') {
+            if (!isJsonString(note)) {
                 throw new HttpError(400, 'note must be a string');
             }
             if (note.length > 2048) {
@@ -1248,7 +1302,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { prediction });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -1269,7 +1323,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     if (method === 'POST' && path === '/v1/decisions') {
         const body = await parseJsonBody(req);
         const text = body['text'];
-        if (typeof text !== 'string' || text.length === 0) {
+        if (!isJsonString(text) || text.length === 0) {
             throw new HttpError(400, 'text is required (non-empty string)');
         }
         if (text.length > 4096) {
@@ -1278,7 +1332,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const contextRaw = body['context'];
         let context;
         if (contextRaw !== undefined && contextRaw !== null) {
-            if (typeof contextRaw !== 'string') {
+            if (!isJsonString(contextRaw)) {
                 throw new HttpError(400, 'context must be a string');
             }
             if (contextRaw.length > 4096) {
@@ -1289,7 +1343,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const supRaw = body['supersedesDecisionId'];
         let supersedesDecisionId;
         if (supRaw !== undefined && supRaw !== null) {
-            if (typeof supRaw !== 'number' || !Number.isInteger(supRaw) || supRaw <= 0) {
+            if (!isJsonNumber(supRaw) || !Number.isInteger(supRaw) || supRaw <= 0) {
                 throw new HttpError(400, 'supersedesDecisionId must be a positive integer');
             }
             supersedesDecisionId = supRaw;
@@ -1304,7 +1358,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 201, { decision });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found') || msg.includes('not active')) {
                 throw new HttpError(409, msg);
             }
@@ -1321,11 +1375,11 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             decisions = loadDecisions(opts.hippoRoot, ctx.tenantId, { limit });
         }
         else {
-            if (!VALID_DECISION_STATES.has(status)) {
+            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: status,
+                status,
                 limit,
             });
         }
@@ -1337,7 +1391,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const oldId = parseInt(decisionSupersedeMatch[1], 10);
         const body = await parseJsonBody(req);
         const text = body['text'];
-        if (typeof text !== 'string' || text.length === 0) {
+        if (!isJsonString(text) || text.length === 0) {
             throw new HttpError(400, 'text is required (non-empty string)');
         }
         if (text.length > 4096) {
@@ -1346,7 +1400,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const contextRaw = body['context'];
         let context;
         if (contextRaw !== undefined && contextRaw !== null) {
-            if (typeof contextRaw !== 'string') {
+            if (!isJsonString(contextRaw)) {
                 throw new HttpError(400, 'context must be a string');
             }
             if (contextRaw.length > 4096) {
@@ -1364,7 +1418,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 201, { decision });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -1384,7 +1438,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { decision });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -1420,7 +1474,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     if (method === 'POST' && path === '/v1/incidents') {
         const body = await parseJsonBody(req);
         const text = body['text'];
-        if (typeof text !== 'string' || text.length === 0) {
+        if (!isJsonString(text) || text.length === 0) {
             throw new HttpError(400, 'text is required (non-empty string)');
         }
         if (text.length > 4096) {
@@ -1429,7 +1483,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const contextRaw = body['context'];
         let context;
         if (contextRaw !== undefined && contextRaw !== null) {
-            if (typeof contextRaw !== 'string') {
+            if (!isJsonString(contextRaw)) {
                 throw new HttpError(400, 'context must be a string');
             }
             if (contextRaw.length > 4096) {
@@ -1446,10 +1500,9 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             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');
-                }
+            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;
         }
@@ -1463,7 +1516,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 201, { incident });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(409, msg);
             }
@@ -1480,11 +1533,11 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             incidents = loadIncidents(opts.hippoRoot, ctx.tenantId, { limit });
         }
         else {
-            if (!VALID_INCIDENT_STATES.has(status)) {
+            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: status,
+                status,
                 limit,
             });
         }
@@ -1496,7 +1549,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const id = parseInt(incidentResolveMatch[1], 10);
         const body = await parseJsonBody(req);
         const resolutionText = body['resolutionText'];
-        if (typeof resolutionText !== 'string' || resolutionText.trim().length === 0) {
+        if (!isJsonString(resolutionText) || resolutionText.trim().length === 0) {
             throw new HttpError(400, 'resolutionText is required (non-empty string)');
         }
         if (resolutionText.length > 4096) {
@@ -1508,7 +1561,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { incident });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -1528,7 +1581,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { incident });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -1564,7 +1617,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     if (method === 'POST' && path === '/v1/processes') {
         const body = await parseJsonBody(req);
         const processName = body['processName'];
-        if (typeof processName !== 'string' || processName.trim().length === 0) {
+        if (!isJsonString(processName) || processName.trim().length === 0) {
             throw new HttpError(400, 'processName is required (non-empty string)');
         }
         if (processName.length > 4096) {
@@ -1574,7 +1627,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const descriptionRaw = body['description'];
         let description;
         if (descriptionRaw !== undefined && descriptionRaw !== null) {
-            if (typeof descriptionRaw !== 'string') {
+            if (!isJsonString(descriptionRaw)) {
                 throw new HttpError(400, 'description must be a string');
             }
             if (descriptionRaw.length > 4096) {
@@ -1600,11 +1653,11 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             processes = loadProcesses(opts.hippoRoot, ctx.tenantId, { limit });
         }
         else {
-            if (!VALID_PROCESS_STATES.has(status)) {
+            if (!isSetMember(VALID_PROCESS_STATES, status)) {
                 throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
             }
             processes = loadProcesses(opts.hippoRoot, ctx.tenantId, {
-                status: status,
+                status,
                 limit,
             });
         }
@@ -1622,7 +1675,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const changeRaw = body['changeSummary'];
         let changeSummary;
         if (changeRaw !== undefined && changeRaw !== null) {
-            if (typeof changeRaw !== 'string') {
+            if (!isJsonString(changeRaw)) {
                 throw new HttpError(400, 'changeSummary must be a string');
             }
             if (changeRaw.length > 4096) {
@@ -1633,7 +1686,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const descRaw = body['description'];
         let description;
         if (descRaw !== undefined && descRaw !== null) {
-            if (typeof descRaw !== 'string') {
+            if (!isJsonString(descRaw)) {
                 throw new HttpError(400, 'description must be a string');
             }
             if (descRaw.length > 4096) {
@@ -1660,7 +1713,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { process });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -1680,7 +1733,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { process });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -1714,14 +1767,14 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     if (method === 'POST' && path === '/v1/policies') {
         const body = await parseJsonBody(req);
         const policyName = body['policyName'];
-        if (typeof policyName !== 'string' || policyName.trim().length === 0) {
+        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 (typeof policyText !== 'string' || policyText.trim().length === 0) {
+        if (!isJsonString(policyText) || policyText.trim().length === 0) {
             throw new HttpError(400, 'policyText is required (non-empty string)');
         }
         if (policyText.length > 4096) {
@@ -1741,7 +1794,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         }
         catch (e) {
             // savePolicy throws on invalid/inverted dates (validation) -> 400.
-            throw new HttpError(400, e.message);
+            throw new HttpError(400, e instanceof Error ? e.message : String(e));
         }
         return;
     }
@@ -1754,11 +1807,11 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             policies = loadPolicies(opts.hippoRoot, ctx.tenantId, { limit });
         }
         else {
-            if (!VALID_POLICY_STATES.has(status)) {
+            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: status,
+                status,
                 limit,
             });
         }
@@ -1779,7 +1832,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { policies });
         }
         catch (e) {
-            throw new HttpError(400, e.message);
+            throw new HttpError(400, e instanceof Error ? e.message : String(e));
         }
         return;
     }
@@ -1788,7 +1841,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const id = parseInt(policySupersedeMatch[1], 10);
         const body = await parseJsonBody(req);
         const policyText = body['policyText'];
-        if (typeof policyText !== 'string' || policyText.trim().length === 0) {
+        if (!isJsonString(policyText) || policyText.trim().length === 0) {
             throw new HttpError(400, 'policyText is required (non-empty string)');
         }
         if (policyText.length > 4096) {
@@ -1799,7 +1852,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const changeRaw = body['changeSummary'];
         let changeSummary;
         if (changeRaw !== undefined && changeRaw !== null) {
-            if (typeof changeRaw !== 'string') {
+            if (!isJsonString(changeRaw)) {
                 throw new HttpError(400, 'changeSummary must be a string');
             }
             if (changeRaw.length > 4096) {
@@ -1824,7 +1877,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { policy });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -1845,7 +1898,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { policy });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -1882,14 +1935,14 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     if (method === 'POST' && path === '/v1/skills') {
         const body = await parseJsonBody(req);
         const skillName = body['skillName'];
-        if (typeof skillName !== 'string' || skillName.trim().length === 0) {
+        if (!isJsonString(skillName) || 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) {
+        if (!isJsonString(instructions) || instructions.trim().length === 0) {
             throw new HttpError(400, 'instructions are required (non-empty string)');
         }
         if (instructions.length > 8192) {
@@ -1898,7 +1951,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const triggerRaw = body['trigger'];
         let trigger;
         if (triggerRaw !== undefined && triggerRaw !== null) {
-            if (typeof triggerRaw !== 'string') {
+            if (!isJsonString(triggerRaw)) {
                 throw new HttpError(400, 'trigger must be a string');
             }
             if (triggerRaw.length > 1024) {
@@ -1917,7 +1970,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         }
         catch (e) {
             // saveSkill throws on validation (single-line name etc.) -> 400.
-            throw new HttpError(400, e.message);
+            throw new HttpError(400, e instanceof Error ? e.message : String(e));
         }
         return;
     }
@@ -1930,11 +1983,11 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             skills = loadSkills(opts.hippoRoot, ctx.tenantId, { limit });
         }
         else {
-            if (!VALID_SKILL_STATES.has(status)) {
+            if (!isSetMember(VALID_SKILL_STATES, status)) {
                 throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
             }
             skills = loadSkills(opts.hippoRoot, ctx.tenantId, {
-                status: status,
+                status,
                 limit,
             });
         }
@@ -1954,7 +2007,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const id = parseInt(skillSupersedeMatch[1], 10);
         const body = await parseJsonBody(req);
         const instructions = body['instructions'];
-        if (typeof instructions !== 'string' || instructions.trim().length === 0) {
+        if (!isJsonString(instructions) || instructions.trim().length === 0) {
             throw new HttpError(400, 'instructions are required (non-empty string)');
         }
         if (instructions.length > 8192) {
@@ -1963,7 +2016,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const triggerRaw = body['trigger'];
         let trigger;
         if (triggerRaw !== undefined && triggerRaw !== null) {
-            if (typeof triggerRaw !== 'string') {
+            if (!isJsonString(triggerRaw)) {
                 throw new HttpError(400, 'trigger must be a string');
             }
             if (triggerRaw.length > 1024) {
@@ -1974,7 +2027,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const changeRaw = body['changeSummary'];
         let changeSummary;
         if (changeRaw !== undefined && changeRaw !== null) {
-            if (typeof changeRaw !== 'string') {
+            if (!isJsonString(changeRaw)) {
                 throw new HttpError(400, 'changeSummary must be a string');
             }
             if (changeRaw.length > 4096) {
@@ -1998,7 +2051,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { skill });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -2018,7 +2071,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { skill });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -2053,14 +2106,14 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     if (method === 'POST' && path === '/v1/project-briefs') {
         const body = await parseJsonBody(req);
         const repo = body['repo'];
-        if (typeof repo !== 'string' || repo.trim().length === 0) {
+        if (!isJsonString(repo) || 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) {
+        if (!isJsonString(summary) || summary.trim().length === 0) {
             throw new HttpError(400, 'summary is required (non-empty string)');
         }
         if (summary.length > 8192) {
@@ -2076,7 +2129,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         }
         catch (e) {
             // saveProjectBrief throws on validation (single-line repo etc.) -> 400.
-            throw new HttpError(400, e.message);
+            throw new HttpError(400, e instanceof Error ? e.message : String(e));
         }
         return;
     }
@@ -2090,7 +2143,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             listOpts.repo = repoFilter.trim();
         }
         if (status !== 'all') {
-            if (!VALID_BRIEF_STATES.has(status)) {
+            if (!isSetMember(VALID_BRIEF_STATES, status)) {
                 throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
             }
             listOpts.status = status;
@@ -2104,7 +2157,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     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) {
+        if (!isJsonString(repo) || repo.trim().length === 0) {
             throw new HttpError(400, 'repo is required (non-empty string)');
         }
         if (repo.length > 256) {
@@ -2126,7 +2179,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             // 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;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -2142,7 +2195,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const id = parseInt(briefSupersedeMatch[1], 10);
         const body = await parseJsonBody(req);
         const summary = body['summary'];
-        if (typeof summary !== 'string' || summary.trim().length === 0) {
+        if (!isJsonString(summary) || summary.trim().length === 0) {
             throw new HttpError(400, 'summary is required (non-empty string)');
         }
         if (summary.length > 8192) {
@@ -2151,7 +2204,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const changeRaw = body['changeSummary'];
         let changeSummary;
         if (changeRaw !== undefined && changeRaw !== null) {
-            if (typeof changeRaw !== 'string') {
+            if (!isJsonString(changeRaw)) {
                 throw new HttpError(400, 'changeSummary must be a string');
             }
             if (changeRaw.length > 4096) {
@@ -2174,7 +2227,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { brief });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -2194,7 +2247,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { brief });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -2227,14 +2280,14 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     if (method === 'POST' && path === '/v1/customer-notes') {
         const body = await parseJsonBody(req);
         const customer = body['customer'];
-        if (typeof customer !== 'string' || customer.trim().length === 0) {
+        if (!isJsonString(customer) || 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) {
+        if (!isJsonString(note) || note.trim().length === 0) {
             throw new HttpError(400, 'note is required (non-empty string)');
         }
         if (note.length > 8192) {
@@ -2250,7 +2303,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         }
         catch (e) {
             // saveCustomerNote throws on validation (single-line customer etc.) -> 400.
-            throw new HttpError(400, e.message);
+            throw new HttpError(400, e instanceof Error ? e.message : String(e));
         }
         return;
     }
@@ -2264,7 +2317,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             listOpts.customer = customerFilter.trim();
         }
         if (status !== 'all') {
-            if (!VALID_NOTE_STATES.has(status)) {
+            if (!isSetMember(VALID_NOTE_STATES, status)) {
                 throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
             }
             listOpts.status = status;
@@ -2278,7 +2331,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const id = parseInt(noteSupersedeMatch[1], 10);
         const body = await parseJsonBody(req);
         const note = body['note'];
-        if (typeof note !== 'string' || note.trim().length === 0) {
+        if (!isJsonString(note) || note.trim().length === 0) {
             throw new HttpError(400, 'note is required (non-empty string)');
         }
         if (note.length > 8192) {
@@ -2287,7 +2340,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const changeRaw = body['changeSummary'];
         let changeSummary;
         if (changeRaw !== undefined && changeRaw !== null) {
-            if (typeof changeRaw !== 'string') {
+            if (!isJsonString(changeRaw)) {
                 throw new HttpError(400, 'changeSummary must be a string');
             }
             if (changeRaw.length > 4096) {
@@ -2310,7 +2363,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { note: customerNote });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -2330,7 +2383,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { note: customerNote });
         }
         catch (e) {
-            const msg = e.message;
+            const msg = e instanceof Error ? e.message : String(e);
             if (msg.includes('not found')) {
                 throw new HttpError(404, msg);
             }
@@ -2386,8 +2439,8 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const previousSecret = process.env.SLACK_SIGNING_SECRET_PREVIOUS;
         const sig = req.headers['x-slack-signature'];
         const tsHdr = req.headers['x-slack-request-timestamp'];
-        const sigStr = typeof sig === 'string' ? sig : null;
-        const tsStr = typeof tsHdr === 'string' ? tsHdr : null;
+        const sigStr = isHeaderString(sig) ? sig : null;
+        const tsStr = isHeaderString(tsHdr) ? tsHdr : null;
         if (sigStr === null ||
             tsStr === null ||
             !verifySlackSignature({
@@ -2438,20 +2491,21 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { ok: true, status: 'dlq' });
             return;
         }
-        if (body &&
-            typeof body === 'object' &&
-            body.type === 'url_verification') {
-            sendJson(res, 200, {
-                challenge: String(body.challenge ?? ''),
-            });
-            return;
+        if (isJsonObjectRecord(body)) {
+            const bodyRecord = body;
+            if (bodyRecord.type === 'url_verification') {
+                sendJson(res, 200, {
+                    challenge: String(bodyRecord.challenge ?? ''),
+                });
+                return;
+            }
         }
         // Resolve tenant. v0.39 fail-closed: when slack_workspaces is non-empty
         // and the team_id is unknown, resolveTenantForTeam returns null and we
         // park the envelope in slack_dlq with bucket='unroutable'. Mandatory ACK
         // 200 so Slack stops retrying; do NOT call ingest.
         let resolvedTenant = null;
-        if (isSlackEventEnvelope(body)) {
+        if (body !== undefined && isSlackEventEnvelope(body)) {
             const db = openHippoDb(opts.hippoRoot);
             try {
                 resolvedTenant = resolveTenantForTeam(db, body.team_id);
@@ -2488,7 +2542,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             tenantId: resolvedTenant,
             actor: adminActor('connector:slack'),
         };
-        if (!isSlackEventEnvelope(body)) {
+        if (body === undefined || !isSlackEventEnvelope(body)) {
             const db = openHippoDb(ctx.hippoRoot);
             try {
                 writeToDlq(db, {
@@ -2542,7 +2596,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
                 tenantId: ctx.tenantId,
                 teamId: body.team_id,
                 rawPayload: rawBody,
-                error: `unhandled event type: ${inner?.type ?? 'unknown'}`,
+                error: `unhandled event type: ${inner.type ?? 'unknown'}`,
                 bucket: 'parse_error',
                 signature: sigStr,
                 slackTimestamp: tsStr,
@@ -2583,9 +2637,9 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const sigHdr = req.headers['x-hub-signature-256'];
         const eventHdr = req.headers['x-github-event'];
         const deliveryHdr = req.headers['x-github-delivery'];
-        const sigStr = typeof sigHdr === 'string' ? sigHdr : null;
-        const eventName = typeof eventHdr === 'string' ? eventHdr : null;
-        const deliveryId = typeof deliveryHdr === 'string' ? deliveryHdr : null;
+        const sigStr = isHeaderString(sigHdr) ? sigHdr : null;
+        const eventName = isHeaderString(eventHdr) ? eventHdr : null;
+        const deliveryId = isHeaderString(deliveryHdr) ? deliveryHdr : null;
         if (sigStr === null ||
             !verifyGitHubSignature({
                 rawBody,
@@ -2686,7 +2740,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             sendJson(res, 200, { ok: true, status: 'dlq' });
             return;
         }
-        if (!isGitHubWebhookEnvelope(body)) {
+        if (body === undefined || !isGitHubWebhookEnvelope(body)) {
             const db = openHippoDb(opts.hippoRoot);
             try {
                 writeToGitHubDlq(db, {
@@ -2892,12 +2946,16 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         catch {
             throw new HttpError(400, 'invalid JSON-RPC body');
         }
-        if (!mcpReq || typeof mcpReq !== 'object' || typeof mcpReq.method !== 'string') {
+        if (!isJsonObjectRecord(mcpReq) || !isJsonString(mcpReq.method)) {
             throw new HttpError(400, 'JSON-RPC body must include a method string');
         }
+        // SAFETY: validated above as a plain JSON object carrying a string method;
+        // the remaining McpRequest wire fields (jsonrpc, id, params) are checked or
+        // safely defaulted inside handleMcpRequest's JSON-RPC dispatch.
+        const rpcReq = mcpReq;
         let mcpRes;
         try {
-            mcpRes = await handleMcpRequest(mcpReq, {
+            mcpRes = await handleMcpRequest(rpcReq, {
                 hippoRoot: ctx.hippoRoot,
                 tenantId: ctx.tenantId,
                 // v1.12.0: McpContext.actor stays string; extract subject at the boundary.
@@ -2982,7 +3040,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         }, heartbeatMs);
         // Don't keep the event loop alive just for this timer — the server's
         // listener already does that, and tests want the process to exit cleanly.
-        if (typeof ping.unref === 'function')
+        if (ping.unref instanceof Function)
             ping.unref();
         req.on('close', () => clearInterval(ping));
         return;
@@ -3098,10 +3156,11 @@ export async function serve(opts) {
         server.listen(requestedPort, host);
     });
     const address = server.address();
-    if (!address || typeof address === 'string') {
+    if (!isAddressInfo(address)) {
         throw new Error('server.address() returned unexpected shape');
     }
-    const actualPort = address.port;
+    const addressInfo = address;
+    const actualPort = addressInfo.port;
     const url = `http://${host}:${actualPort}`;
     writePidfile(opts.hippoRoot, { port: actualPort, url, startedAt });
     let stopping = false;