@atomicmemory/core 1.0.0

package/dist/routes/memories.js

@@ -0,0 +1,725 @@
+/**
+ * Memory API routes for ingest, search, listing, stats, config, and deletion.
+ * Keeps the existing `/v1/memories/ingest` and `/v1/memories/search` contract stable.
+ *
+ * Request validation for every route is delegated to the Zod-based
+ * validators in `src/middleware/validate.ts` using schemas authored in
+ * `src/schemas/memories.ts`. `validateBody` / `validateQuery` /
+ * `validateParams` replace the hand-written `parseIngestBody` /
+ * `parseSearchBody` / `requireBodyString` helpers this file previously
+ * exported. The 400 response envelope `{ error: string }` is
+ * preserved byte-for-byte by `formatZodIssues`.
+ */
+import { Router } from 'express';
+import { config, updateRuntimeConfig } from '../config.js';
+import { readRuntimeConfigRouteSnapshot as projectRuntimeConfigRouteSnapshot, } from '../app/runtime-config-route-snapshot.js';
+import { applyConfigOverride, hashEffectiveConfig, summarizeOverrideKeys, } from '../services/retrieval-config-overlay.js';
+import { formatIngestResponse, formatScope, formatStatsResponse, formatConsolidateResponse, formatConsolidateExecuteResponse, formatDecayResponse, formatCapResponse, formatLessonStatsResponse, formatReconciliationResponse, formatResetSourceResponse, formatMutationSummaryResponse, formatAuditTrailEntry, formatObservability, } from './memory-response-formatters.js';
+import { handleRouteError } from './route-errors.js';
+import { validateBody, validateQuery, validateParams } from '../middleware/validate.js';
+import { CORS_ALLOWED_HEADERS_VALUE } from '../app/cors-headers.js';
+import { validateResponse } from '../middleware/validate-response.js';
+import { MEMORY_RESPONSE_SCHEMAS } from './response-schema-map.js';
+import { IngestBodySchema, SearchBodySchema, ExpandBodySchema, VerifyBodySchema, ConsolidateBodySchema, DecayBodySchema, ReconcileBodySchema, ResetSourceBodySchema, LessonReportBodySchema, UserIdQuerySchema, EventChainsQuerySchema, FirstMentionsExtractBodySchema, UserIdLimitQuerySchema, ListQuerySchema, MemoryByIdQuerySchema, UuidIdParamSchema, FreeIdParamSchema, ConfigBodySchema, } from '../schemas/memories.js';
+import { verifyAnswer } from '../services/answer-verifier.js';
+const ALLOWED_ORIGINS = new Set((process.env.ALLOWED_ORIGINS ?? 'http://localhost:3050,http://localhost:3081')
+    .split(',')
+    .map((o) => o.trim())
+    .filter(Boolean));
+const STARTUP_ONLY_CONFIG_FIELDS = [
+    'embedding_provider',
+    'embedding_model',
+    'voyage_api_key',
+    'voyage_document_model',
+    'voyage_query_model',
+    'llm_provider',
+    'llm_model',
+];
+const defaultRuntimeConfigRouteAdapter = {
+    base() {
+        return config;
+    },
+    current() {
+        return readRuntimeConfigRouteSnapshot();
+    },
+    update(updates) {
+        return updateRuntimeConfig(updates);
+    },
+};
+export function createMemoryRouter(service, configRouteAdapter = defaultRuntimeConfigRouteAdapter) {
+    const router = Router();
+    registerCors(router);
+    // Dev/test-mode response validator: no-op in production, throws loudly
+    // if any 2xx body violates the schema declared in responses.ts.
+    router.use(validateResponse(MEMORY_RESPONSE_SCHEMAS));
+    registerIngestRoute(router, service, configRouteAdapter);
+    registerQuickIngestRoute(router, service, configRouteAdapter);
+    registerSearchRoute(router, service, configRouteAdapter);
+    registerFastSearchRoute(router, service, configRouteAdapter);
+    registerVerifyRoute(router);
+    registerExpandRoute(router, service);
+    registerListRoute(router, service);
+    registerStatsRoute(router, service);
+    registerHealthRoute(router, configRouteAdapter);
+    registerConfigRoute(router, configRouteAdapter);
+    registerEventChainsRoute(router, service);
+    registerFirstMentionsExtractRoute(router, service);
+    registerConsolidateRoute(router, service);
+    registerDecayRoute(router, service);
+    registerCapRoute(router, service);
+    registerAuditSummaryRoute(router, service);
+    registerAuditRecentRoute(router, service);
+    registerAuditTrailRoute(router, service);
+    registerLessonRoutes(router, service);
+    registerReconcileRoute(router, service);
+    registerResetSourceRoute(router, service);
+    registerGetRoute(router, service);
+    registerDeleteRoute(router, service);
+    return router;
+}
+function registerCors(router) {
+    router.use((req, res, next) => {
+        applyCorsHeaders(req, res);
+        if (req.method === 'OPTIONS') {
+            res.sendStatus(204);
+            return;
+        }
+        next();
+    });
+}
+function registerIngestRoute(router, service, configRouteAdapter) {
+    router.post('/ingest', validateBody(IngestBodySchema), async (req, res) => {
+        try {
+            await handleIngestRequest(service, req, res, configRouteAdapter, 'full');
+        }
+        catch (err) {
+            handleRouteError(res, 'POST /v1/memories/ingest', err);
+        }
+    });
+}
+function registerQuickIngestRoute(router, service, configRouteAdapter) {
+    router.post('/ingest/quick', validateBody(IngestBodySchema), async (req, res) => {
+        try {
+            await handleIngestRequest(service, req, res, configRouteAdapter, 'quick');
+        }
+        catch (err) {
+            handleRouteError(res, 'POST /v1/memories/ingest/quick', err);
+        }
+    });
+}
+async function handleIngestRequest(service, req, res, configRouteAdapter, mode) {
+    const { body, effectiveConfig } = readIngestRequest(req, res, configRouteAdapter);
+    // Caller-supplied `metadata` is only honored on the verbatim branch
+    // (mode === 'quick' && skip_extraction === true && no workspace).
+    // Reject loudly elsewhere — silent drops would violate the
+    // "no silent error catching" rule. Direct res.status(400).json(...)
+    // because handleRouteError emits 500-only.
+    if (body.metadata &&
+        !(mode === 'quick' && body.skipExtraction && !body.workspace)) {
+        res.status(400).json({
+            error: 'metadata is only supported on /v1/memories/ingest/quick with skip_extraction=true and no workspace context',
+        });
+        return;
+    }
+    const result = await runIngest(service, body, effectiveConfig, mode);
+    res.json(formatIngestResponse(result));
+}
+async function runIngest(service, body, effectiveConfig, mode) {
+    if (body.workspace) {
+        return service.workspaceIngest(body.userId, body.conversation, body.sourceSite, body.sourceUrl, body.workspace, undefined, effectiveConfig);
+    }
+    if (mode === 'full') {
+        return service.ingest(body.userId, body.conversation, body.sourceSite, body.sourceUrl, undefined, effectiveConfig);
+    }
+    if (body.skipExtraction) {
+        return service.storeVerbatim(body.userId, body.conversation, body.sourceSite, body.sourceUrl, body.metadata, effectiveConfig);
+    }
+    return service.quickIngest(body.userId, body.conversation, body.sourceSite, body.sourceUrl, undefined, effectiveConfig);
+}
+/**
+ * Resolve scope + clamped limit using the *effective* maxSearchResults — i.e.
+ * the post-override value when a `config_override` was carried, or the startup
+ * snapshot otherwise. Clamping against the startup snapshot when an override
+ * is present would silently pin requests to the old cap even though
+ * `X-Atomicmem-Effective-Config-Hash` advertises the new one.
+ */
+function resolveSearchPreamble(body, maxSearchResults) {
+    const scope = toMemoryScope(body.userId, body.workspace, body.agentScope);
+    const requestLimit = body.limit === undefined
+        ? undefined
+        : resolveEffectiveSearchLimit(body.limit, maxSearchResults);
+    return { scope, requestLimit };
+}
+function readIngestRequest(req, res, configRouteAdapter) {
+    const body = req.body;
+    return {
+        body,
+        effectiveConfig: applyRequestConfigOverride(res, configRouteAdapter.base(), body.configOverride),
+    };
+}
+function readSearchRequest(req, res, configRouteAdapter) {
+    const body = req.body;
+    const effectiveConfig = applyRequestConfigOverride(res, configRouteAdapter.base(), body.configOverride);
+    const maxSearchResults = effectiveConfig?.maxSearchResults ?? configRouteAdapter.current().maxSearchResults;
+    const { scope, requestLimit } = resolveSearchPreamble(body, maxSearchResults);
+    return { body, effectiveConfig, scope, requestLimit };
+}
+function registerSearchRoute(router, service, configRouteAdapter) {
+    router.post('/search', validateBody(SearchBodySchema), async (req, res) => {
+        try {
+            const { body, effectiveConfig, scope, requestLimit } = readSearchRequest(req, res, configRouteAdapter);
+            const retrievalOptions = {
+                retrievalMode: body.retrievalMode,
+                tokenBudget: body.tokenBudget,
+                relevanceThreshold: body.relevanceThreshold,
+                ...(body.skipRepair ? { skipRepairLoop: true } : {}),
+            };
+            const result = await service.scopedSearch(scope, body.query, {
+                sourceSite: body.sourceSite,
+                limit: requestLimit,
+                asOf: body.asOf,
+                namespaceScope: body.namespaceScope,
+                retrievalOptions,
+                effectiveConfig,
+            });
+            res.json(formatSearchResponse(result, scope));
+        }
+        catch (err) {
+            handleRouteError(res, 'POST /v1/memories/search', err);
+        }
+    });
+}
+/**
+ * Latency-optimized search endpoint for UC1 (memory injection, <200ms target).
+ * Skips the LLM repair loop which accounts for ~88% of search latency.
+ */
+function registerFastSearchRoute(router, service, configRouteAdapter) {
+    router.post('/search/fast', validateBody(SearchBodySchema), async (req, res) => {
+        try {
+            const { body, effectiveConfig, scope, requestLimit } = readSearchRequest(req, res, configRouteAdapter);
+            const retrievalOptions = {
+                relevanceThreshold: body.relevanceThreshold,
+            };
+            const result = await service.scopedSearch(scope, body.query, {
+                fast: true,
+                sourceSite: body.sourceSite,
+                limit: requestLimit,
+                namespaceScope: body.namespaceScope,
+                retrievalOptions,
+                effectiveConfig,
+            });
+            res.json(formatSearchResponse(result, scope));
+        }
+        catch (err) {
+            handleRouteError(res, 'POST /v1/memories/search/fast', err);
+        }
+    });
+}
+/**
+ * POST /v1/memories/verify (Sprint 3 v1.7 — H5).
+ *
+ * Second-pass verifier: re-grounds a candidate answer against retrieved
+ * context. The AMB harness calls this between its answer-LLM call and
+ * scoring when `ATOMICMEMORY_VERIFIER_ENABLED=1` is set. Returns the
+ * original answer if every specific is grounded, or a rewritten answer
+ * if it dropped unsupported specifics.
+ */
+function registerVerifyRoute(router) {
+    router.post('/verify', validateBody(VerifyBodySchema), async (req, res) => {
+        try {
+            const { question, context, candidateAnswer } = req.body;
+            const result = await verifyAnswer(question, context, candidateAnswer);
+            res.json({ verified_answer: result.verified_answer, changed: result.changed });
+        }
+        catch (err) {
+            handleRouteError(res, 'POST /v1/memories/verify', err);
+        }
+    });
+}
+function registerExpandRoute(router, service) {
+    router.post('/expand', validateBody(ExpandBodySchema), async (req, res) => {
+        try {
+            const { userId, memoryIds, workspace } = req.body;
+            const scope = toMemoryScope(userId, workspace, undefined);
+            const expanded = await service.scopedExpand(scope, memoryIds);
+            res.json({ memories: expanded });
+        }
+        catch (err) {
+            handleRouteError(res, 'POST /v1/memories/expand', err);
+        }
+    });
+}
+function registerListRoute(router, service) {
+    router.get('/list', validateQuery(ListQuerySchema), async (req, res) => {
+        try {
+            const q = req.query;
+            const memories = q.workspaceId
+                ? await service.scopedList({ kind: 'workspace', userId: q.userId, workspaceId: q.workspaceId, agentId: q.agentId }, q.limit, q.offset)
+                : await service.list(q.userId, q.limit, q.offset, q.sourceSite, q.episodeId);
+            res.json({ memories, count: memories.length });
+        }
+        catch (err) {
+            handleRouteError(res, 'GET /v1/memories/list', err);
+        }
+    });
+}
+function registerStatsRoute(router, service) {
+    router.get('/stats', validateQuery(UserIdQuerySchema), async (req, res) => {
+        try {
+            const { userId } = req.query;
+            const stats = await service.getStats(userId);
+            res.json(formatStatsResponse(stats));
+        }
+        catch (err) {
+            handleRouteError(res, 'GET /v1/memories/stats', err);
+        }
+    });
+}
+function registerHealthRoute(router, configRouteAdapter) {
+    router.get('/health', (_req, res) => {
+        res.json({ status: 'ok', config: formatHealthConfig(configRouteAdapter.current()) });
+    });
+}
+function registerConfigRoute(router, configRouteAdapter) {
+    router.put('/config', validateBody(ConfigBodySchema), async (req, res) => {
+        try {
+            if (!configRouteAdapter.current().runtimeConfigMutationEnabled) {
+                res.status(410).json({
+                    error: 'PUT /v1/memories/config is deprecated for production',
+                    detail: 'Set CORE_RUNTIME_CONFIG_MUTATION_ENABLED=true to enable runtime mutation in dev/test environments. Production deploys should use startup env vars.',
+                });
+                return;
+            }
+            const rejected = STARTUP_ONLY_CONFIG_FIELDS.filter((field) => req.body[field] !== undefined);
+            if (rejected.length > 0) {
+                res.status(400).json({
+                    error: 'Provider/model selection is startup-only',
+                    detail: `Fields ${rejected.join(', ')} cannot be mutated at runtime — the embedding/LLM provider caches are fixed at first use. Set the equivalent env vars (EMBEDDING_PROVIDER, EMBEDDING_MODEL, VOYAGE_API_KEY, VOYAGE_DOCUMENT_MODEL, VOYAGE_QUERY_MODEL, LLM_PROVIDER, LLM_MODEL) and restart the process.`,
+                    rejected,
+                });
+                return;
+            }
+            const body = req.body;
+            const applied = configRouteAdapter.update({
+                similarityThreshold: body.similarity_threshold,
+                audnCandidateThreshold: body.audn_candidate_threshold,
+                clarificationConflictThreshold: body.clarification_conflict_threshold,
+                maxSearchResults: body.max_search_results,
+            });
+            res.json({
+                applied: applied.map(toSnakeCase),
+                config: formatHealthConfig(configRouteAdapter.current()),
+                note: 'Threshold updates applied in-memory for local experimentation. Provider/model selection is startup-only — restart the process to change it.',
+            });
+        }
+        catch (err) {
+            handleRouteError(res, 'PUT /v1/memories/config', err);
+        }
+    });
+}
+/**
+ * GET /v1/memories/event-chains?user_id=X&entity_ids=uuid1,uuid2
+ *
+ * Returns per-entity chronological event chains from the Temporal Linkage
+ * List. Entities with no events are dropped from the result. Within an
+ * entity, events are ordered by position_in_chain ASC. Used by EO-shaped
+ * read paths that need content alongside chain position. Returns
+ * `{ chains: [] }` if TLL is disabled in the runtime config.
+ */
+function registerEventChainsRoute(router, service) {
+    router.get('/event-chains', validateQuery(EventChainsQuerySchema), async (req, res) => {
+        try {
+            const q = req.query;
+            const chains = await service.getEventChains(q.userId, q.entityIds);
+            res.json({
+                chains: chains.map(c => ({
+                    entity_id: c.entityId,
+                    events: c.events.map(e => ({
+                        memory_id: e.memoryId,
+                        content: e.content,
+                        observation_date: e.observationDate.toISOString(),
+                        position_in_chain: e.positionInChain,
+                        predecessor_memory_id: e.predecessorMemoryId,
+                    })),
+                })),
+            });
+        }
+        catch (err) {
+            handleRouteError(res, 'GET /v1/memories/event-chains', err);
+        }
+    });
+}
+/**
+ * POST /v1/memories/first-mentions/extract
+ *
+ * Extract first-mention events from a conversation transcript and persist
+ * them. Caller supplies the turn-id-to-memory-id mapping. Returns the
+ * parsed events. Best-effort: if FirstMentionService is not wired or the
+ * underlying LLM call fails, returns `{ events: [] }` without throwing.
+ */
+function registerFirstMentionsExtractRoute(router, service) {
+    router.post('/first-mentions/extract', validateBody(FirstMentionsExtractBodySchema), async (req, res) => {
+        try {
+            const b = req.body;
+            const events = await service.extractFirstMentions(b.userId, b.conversationText, b.sourceSite, b.memoryIdsByTurnId);
+            res.json({
+                events: events.map(e => ({
+                    topic: e.topic,
+                    turn_id: e.turnId,
+                    memory_id: e.memoryId,
+                    anchor_date: e.anchorDate ? e.anchorDate.toISOString() : null,
+                    position_in_conversation: e.positionInConversation,
+                })),
+            });
+        }
+        catch (err) {
+            handleRouteError(res, 'POST /v1/memories/first-mentions/extract', err);
+        }
+    });
+}
+function registerConsolidateRoute(router, service) {
+    router.post('/consolidate', validateBody(ConsolidateBodySchema), async (req, res) => {
+        try {
+            const { userId, execute } = req.body;
+            res.json(execute
+                ? formatConsolidateExecuteResponse(await service.executeConsolidation(userId))
+                : formatConsolidateResponse(await service.consolidate(userId)));
+        }
+        catch (err) {
+            handleRouteError(res, 'POST /v1/memories/consolidate', err);
+        }
+    });
+}
+function registerDecayRoute(router, service) {
+    router.post('/decay', validateBody(DecayBodySchema), async (req, res) => {
+        try {
+            const { userId, dryRun } = req.body;
+            const result = await service.evaluateDecay(userId);
+            const archived = !dryRun && result.candidatesForArchival.length > 0
+                ? await service.archiveDecayed(userId, result.candidatesForArchival.map((c) => c.id))
+                : 0;
+            res.json(formatDecayResponse(result, archived));
+        }
+        catch (err) {
+            handleRouteError(res, 'POST /v1/memories/decay', err);
+        }
+    });
+}
+function registerCapRoute(router, service) {
+    router.get('/cap', validateQuery(UserIdQuerySchema), async (req, res) => {
+        try {
+            const { userId } = req.query;
+            const result = await service.checkCap(userId);
+            res.json(formatCapResponse(result));
+        }
+        catch (err) {
+            handleRouteError(res, 'GET /v1/memories/cap', err);
+        }
+    });
+}
+function registerLessonRoutes(router, service) {
+    router.get('/lessons', validateQuery(UserIdQuerySchema), async (req, res) => {
+        try {
+            const { userId } = req.query;
+            const lessons = await service.getLessons(userId);
+            res.json({ lessons, count: lessons.length });
+        }
+        catch (err) {
+            handleRouteError(res, 'GET /v1/memories/lessons', err);
+        }
+    });
+    router.get('/lessons/stats', validateQuery(UserIdQuerySchema), async (req, res) => {
+        try {
+            const { userId } = req.query;
+            const stats = await service.getLessonStats(userId);
+            res.json(formatLessonStatsResponse(stats));
+        }
+        catch (err) {
+            handleRouteError(res, 'GET /v1/memories/lessons/stats', err);
+        }
+    });
+    router.post('/lessons/report', validateBody(LessonReportBodySchema), async (req, res) => {
+        try {
+            const { userId, pattern, sourceMemoryIds, severity } = req.body;
+            const lessonId = await service.reportLesson(userId, pattern, sourceMemoryIds, severity);
+            res.json({ lesson_id: lessonId });
+        }
+        catch (err) {
+            handleRouteError(res, 'POST /v1/memories/lessons/report', err);
+        }
+    });
+    router.delete('/lessons/:id', validateParams(FreeIdParamSchema), validateQuery(UserIdQuerySchema), async (req, res) => {
+        try {
+            const { id } = req.params;
+            const { userId } = req.query;
+            await service.deactivateLesson(userId, id);
+            res.json({ success: true });
+        }
+        catch (err) {
+            handleRouteError(res, 'DELETE /v1/memories/lessons/:id', err);
+        }
+    });
+}
+function registerReconcileRoute(router, service) {
+    router.post('/reconcile', validateBody(ReconcileBodySchema), async (req, res) => {
+        try {
+            const { userId } = req.body;
+            const result = userId
+                ? await service.reconcileDeferred(userId)
+                : await service.reconcileDeferredAll();
+            res.json(formatReconciliationResponse(result));
+        }
+        catch (err) {
+            handleRouteError(res, 'POST /v1/memories/reconcile', err);
+        }
+    });
+    router.get('/reconcile/status', validateQuery(UserIdQuerySchema), async (req, res) => {
+        try {
+            const { userId } = req.query;
+            const status = await service.getDeferredStatus(userId);
+            res.json(status);
+        }
+        catch (err) {
+            handleRouteError(res, 'GET /v1/memories/reconcile/status', err);
+        }
+    });
+}
+function registerResetSourceRoute(router, service) {
+    router.post('/reset-source', validateBody(ResetSourceBodySchema), async (req, res) => {
+        try {
+            const { userId, sourceSite } = req.body;
+            const result = await service.resetBySource(userId, sourceSite);
+            res.json(formatResetSourceResponse(result));
+        }
+        catch (err) {
+            handleRouteError(res, 'POST /v1/memories/reset-source', err);
+        }
+    });
+}
+function registerGetRoute(router, service) {
+    router.get('/:id', validateParams(UuidIdParamSchema), validateQuery(MemoryByIdQuerySchema), async (req, res) => {
+        try {
+            const { memoryId, q } = readMemoryByIdRequest(req);
+            const memory = q.workspaceId
+                ? await service.scopedGet({ kind: 'workspace', userId: q.userId, workspaceId: q.workspaceId, agentId: q.agentId }, memoryId)
+                : await service.get(memoryId, q.userId);
+            if (!memory) {
+                res.status(404).json({ error: 'Memory not found' });
+                return;
+            }
+            res.json(memory);
+        }
+        catch (err) {
+            handleRouteError(res, 'GET /v1/memories/:id', err);
+        }
+    });
+}
+function registerDeleteRoute(router, service) {
+    router.delete('/:id', validateParams(UuidIdParamSchema), validateQuery(MemoryByIdQuerySchema), async (req, res) => {
+        try {
+            const { memoryId, q } = readMemoryByIdRequest(req);
+            if (q.workspaceId) {
+                const deleted = await service.scopedDelete({ kind: 'workspace', userId: q.userId, workspaceId: q.workspaceId, agentId: q.agentId }, memoryId);
+                if (!deleted) {
+                    res.status(404).json({ error: 'Memory not found' });
+                    return;
+                }
+            }
+            else {
+                await service.delete(memoryId, q.userId);
+            }
+            res.json({ success: true });
+        }
+        catch (err) {
+            handleRouteError(res, 'DELETE /v1/memories/:id', err);
+        }
+    });
+}
+function readMemoryByIdRequest(req) {
+    const { id: memoryId } = req.params;
+    return {
+        memoryId,
+        q: req.query,
+    };
+}
+function registerAuditSummaryRoute(router, service) {
+    router.get('/audit/summary', validateQuery(UserIdQuerySchema), async (req, res) => {
+        try {
+            const { userId } = req.query;
+            const summary = await service.getMutationSummary(userId);
+            res.json(formatMutationSummaryResponse(summary));
+        }
+        catch (err) {
+            handleRouteError(res, 'GET /v1/memories/audit/summary', err);
+        }
+    });
+}
+function registerAuditRecentRoute(router, service) {
+    router.get('/audit/recent', validateQuery(UserIdLimitQuerySchema), async (req, res) => {
+        try {
+            const { userId, limit } = req.query;
+            const mutations = await service.getRecentMutations(userId, limit);
+            res.json({ mutations, count: mutations.length });
+        }
+        catch (err) {
+            handleRouteError(res, 'GET /v1/memories/audit/recent', err);
+        }
+    });
+}
+function registerAuditTrailRoute(router, service) {
+    router.get('/:id/audit', validateParams(UuidIdParamSchema), validateQuery(UserIdQuerySchema), async (req, res) => {
+        try {
+            const { id: memoryId } = req.params;
+            const { userId } = req.query;
+            const trail = await service.getAuditTrail(userId, memoryId);
+            res.json({
+                memory_id: memoryId,
+                trail: trail.map(formatAuditTrailEntry),
+                version_count: trail.length,
+            });
+        }
+        catch (err) {
+            handleRouteError(res, 'GET /v1/memories/:id/audit', err);
+        }
+    });
+}
+function resolveEffectiveSearchLimit(requestedLimit, maxSearchResults) {
+    if (requestedLimit === undefined)
+        return maxSearchResults;
+    return Math.min(requestedLimit, maxSearchResults);
+}
+function toMemoryScope(userId, workspace, agentScope) {
+    if (!workspace)
+        return { kind: 'user', userId };
+    return { kind: 'workspace', userId, workspaceId: workspace.workspaceId, agentId: workspace.agentId, agentScope };
+}
+/**
+ * Overlay a validated body-level config_override onto the startup
+ * singleton and emit the observability response headers. Returns the
+ * EffectiveConfig to hand to MemoryService (or undefined when no
+ * override was present — the zero-cost no-headers path).
+ *
+ * Headers emitted when an override is applied:
+ *   X-Atomicmem-Config-Override-Applied: true
+ *   X-Atomicmem-Effective-Config-Hash:   sha256:<hex>
+ *   X-Atomicmem-Config-Override-Keys:    comma-joined sorted key list
+ *
+ * Additional header, emitted only when one or more override keys do
+ * not correspond to a known RuntimeConfig field on this build:
+ *   X-Atomicmem-Unknown-Override-Keys:   comma-joined sorted key list
+ *
+ * Unknown keys are NOT rejected — the permissive schema is deliberate
+ * so adding a new RuntimeConfig field in a future release doesn't
+ * require a matching schema landing before experiments can set it.
+ * Typos surface via this header + a server-side warning log.
+ */
+function applyRequestConfigOverride(res, baseConfig, override) {
+    if (!override || Object.keys(override).length === 0)
+        return undefined;
+    const effective = applyConfigOverride(baseConfig, override);
+    res.setHeader('X-Atomicmem-Config-Override-Applied', 'true');
+    res.setHeader('X-Atomicmem-Effective-Config-Hash', hashEffectiveConfig(effective));
+    res.setHeader('X-Atomicmem-Config-Override-Keys', summarizeOverrideKeys(override));
+    const knownKeys = new Set(Object.keys(baseConfig));
+    const unknownKeys = Object.keys(override)
+        .filter((k) => !knownKeys.has(k))
+        .sort();
+    if (unknownKeys.length > 0) {
+        res.setHeader('X-Atomicmem-Unknown-Override-Keys', unknownKeys.join(','));
+        console.warn(`[config_override] request carried ${unknownKeys.length} unknown key(s): ${unknownKeys.join(', ')} — carried through on effective config but nothing currently reads them`);
+    }
+    return effective;
+}
+function buildRetrievalObservability(result) {
+    const observability = {
+        ...(result.retrievalSummary ? { retrieval: result.retrievalSummary } : {}),
+        ...(result.packagingSummary ? { packaging: result.packagingSummary } : {}),
+        ...(result.assemblySummary ? { assembly: result.assemblySummary } : {}),
+    };
+    return Object.keys(observability).length > 0 ? observability : undefined;
+}
+function applyCorsHeaders(req, res) {
+    const origin = req.headers.origin;
+    if (origin && ALLOWED_ORIGINS.has(origin))
+        res.header('Access-Control-Allow-Origin', origin);
+    res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+    res.header('Access-Control-Allow-Headers', CORS_ALLOWED_HEADERS_VALUE);
+}
+function readRuntimeConfigRouteSnapshot() {
+    return projectRuntimeConfigRouteSnapshot(config);
+}
+function toSnakeCase(camel) {
+    return camel.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+function formatHealthConfig(runtimeConfig) {
+    return {
+        retrieval_profile: runtimeConfig.retrievalProfile,
+        embedding_provider: runtimeConfig.embeddingProvider,
+        embedding_model: runtimeConfig.embeddingModel,
+        voyage_document_model: runtimeConfig.voyageDocumentModel,
+        voyage_query_model: runtimeConfig.voyageQueryModel,
+        llm_provider: runtimeConfig.llmProvider,
+        llm_model: runtimeConfig.llmModel,
+        clarification_conflict_threshold: runtimeConfig.clarificationConflictThreshold,
+        max_search_results: runtimeConfig.maxSearchResults,
+        hybrid_search_enabled: runtimeConfig.hybridSearchEnabled,
+        iterative_retrieval_enabled: runtimeConfig.iterativeRetrievalEnabled,
+        entity_graph_enabled: runtimeConfig.entityGraphEnabled,
+        cross_encoder_enabled: runtimeConfig.crossEncoderEnabled,
+        agentic_retrieval_enabled: runtimeConfig.agenticRetrievalEnabled,
+        repair_loop_enabled: runtimeConfig.repairLoopEnabled,
+    };
+}
+function formatSearchResponse(result, scope) {
+    const observability = buildRetrievalObservability(result);
+    return {
+        count: result.memories.length,
+        retrieval_mode: result.retrievalMode,
+        scope: formatScope(scope),
+        memories: result.memories.map((memory) => ({
+            id: memory.id,
+            content: memory.content,
+            similarity: memory.similarity,
+            score: memory.score,
+            semantic_similarity: memory.semantic_similarity ?? memory.similarity,
+            ranking_score: memory.ranking_score ?? memory.score,
+            relevance: memory.relevance ?? memory.similarity,
+            importance: memory.importance,
+            source_site: memory.source_site,
+            created_at: memory.created_at,
+            metadata: memory.metadata,
+        })),
+        injection_text: result.injectionText,
+        citations: result.citations,
+        budget_constrained: result.budgetConstrained,
+        ...(result.tierAssignments ? {
+            tier_assignments: result.tierAssignments.map((a) => ({
+                memory_id: a.memoryId,
+                tier: a.tier,
+                estimated_tokens: a.estimatedTokens,
+            })),
+        } : {}),
+        ...(result.expandIds ? { expand_ids: result.expandIds } : {}),
+        ...(result.estimatedContextTokens !== undefined ? {
+            estimated_context_tokens: result.estimatedContextTokens,
+        } : {}),
+        ...(result.lessonCheck ? {
+            lesson_check: {
+                safe: result.lessonCheck.safe,
+                warnings: result.lessonCheck.warnings,
+                highest_severity: result.lessonCheck.highestSeverity,
+                matched_count: result.lessonCheck.matchedLessons.length,
+            },
+        } : {}),
+        ...(result.consensusResult ? {
+            consensus: {
+                original_count: result.consensusResult.originalCount,
+                filtered_count: result.consensusResult.filteredCount,
+                removed_count: result.consensusResult.removedMemoryIds.length,
+                removed_memory_ids: result.consensusResult.removedMemoryIds,
+            },
+        } : {}),
+        ...(observability ? { observability: formatObservability(observability) } : {}),
+        ...(result.specialistAnswer ? { specialist_answer: result.specialistAnswer } : {}),
+    };
+}