ai-memory-layer 2.0.1 → 3.0.0

package/dist/server/http-server.js

@@ -1,8 +1,14 @@
+import { createHash, timingSafeEqual } from 'crypto';
 import { createServer } from 'http';
 import { createMemoryWithAsyncAdapter, } from '../core/quick.js';
 import { normalizeScope } from '../contracts/identity.js';
+import { isMemoryDomainError } from '../contracts/errors.js';
+import { MEMORY_EVENT_TYPES, } from '../contracts/observability.js';
+import { EPISODE_DETAIL_LEVELS, PLAYBOOK_STATUSES, ASSOCIATION_TYPES, ASSOCIATION_TARGET_KINDS } from '../contracts/types.js';
+import { ACTOR_KINDS, CONTEXT_VIEW_POLICIES, MEMORY_VISIBILITY_CLASSES } from '../contracts/coordination.js';
 import { createSQLiteAdapterWithEmbeddings } from '../adapters/sqlite/index.js';
 import { wrapSyncAdapter } from '../adapters/sync-to-async.js';
+import { parseOptionalFiniteInteger, parseOptionalFiniteNumber, parseOptionalTemporalIdValue, } from './parsing.js';
 class HttpRequestError extends Error {
     status;
     constructor(status, message) {
@@ -10,6 +16,40 @@ class HttpRequestError extends Error {
         this.status = status;
     }
 }
+const SESSION_SNAPSHOT_LIMIT = 1000;
+const PER_SCOPE_SESSION_SNAPSHOT_LIMIT = 10;
+const MANAGER_CACHE_LIMIT = 256;
+const SESSION_MANAGER_CACHE_LIMIT = 256;
+const MAX_LIST_LIMIT = 100;
+const DEFAULT_DIFF_MAX_EVENTS = 5000;
+const MAX_DIFF_MAX_EVENTS = 20000;
+function resolveDiffEventCaps(defaultMaxEvents, maxMaxEvents) {
+    const resolvedMax = maxMaxEvents ?? MAX_DIFF_MAX_EVENTS;
+    const resolvedDefault = defaultMaxEvents ?? DEFAULT_DIFF_MAX_EVENTS;
+    if (!Number.isInteger(resolvedMax) || resolvedMax < 1) {
+        throw new Error('memory-layer: maxDiffMaxEvents must be a positive integer');
+    }
+    if (!Number.isInteger(resolvedDefault) || resolvedDefault < 1) {
+        throw new Error('memory-layer: defaultDiffMaxEvents must be a positive integer');
+    }
+    if (resolvedDefault > resolvedMax) {
+        throw new Error('memory-layer: defaultDiffMaxEvents must not exceed maxDiffMaxEvents');
+    }
+    return {
+        defaultDiffMaxEvents: resolvedDefault,
+        maxDiffMaxEvents: resolvedMax,
+    };
+}
+function failHttpValidation(message) {
+    throw new HttpRequestError(400, message);
+}
+function safeSecretEquals(provided, expected) {
+    if (typeof provided !== 'string')
+        return false;
+    const providedBuffer = createHash('sha256').update(provided).digest();
+    const expectedBuffer = createHash('sha256').update(expected).digest();
+    return timingSafeEqual(providedBuffer, expectedBuffer) && provided.length === expected.length;
+}
 function writeJson(res, status, data) {
     const body = JSON.stringify(data);
     res.writeHead(status, {
@@ -21,6 +61,143 @@ function writeJson(res, status, data) {
 function writeError(res, status, message) {
     writeJson(res, status, { error: message });
 }
+function serializeContextResponse(context, options = {}) {
+    return {
+        currentObjective: context.currentObjective,
+        sessionState: context.sessionState,
+        activeTurnCount: context.activeTurns.length,
+        workingMemory: context.workingMemory
+            ? {
+                summary: context.workingMemory.summary,
+                key_entities: context.workingMemory.key_entities,
+                topic_tags: context.workingMemory.topic_tags,
+            }
+            : null,
+        relevantKnowledge: context.relevantKnowledge.map((knowledge) => ({
+            id: knowledge.id,
+            fact: knowledge.fact,
+            fact_type: knowledge.fact_type,
+            confidence: knowledge.confidence,
+        })),
+        activeObjectives: context.activeObjectives.map((objective) => ({
+            id: objective.id,
+            title: objective.title,
+            status: objective.status,
+            visibility_class: objective.visibility_class,
+        })),
+        associatedKnowledge: options.includeAssociatedKnowledge === false
+            ? undefined
+            : context.associatedKnowledge.map((knowledge) => ({
+                id: knowledge.id,
+                fact: knowledge.fact,
+                fact_type: knowledge.fact_type,
+                knowledge_class: knowledge.knowledge_class,
+                trust_score: knowledge.trust_score,
+            })),
+        unresolvedWork: context.unresolvedWork,
+        coordinationState: context.coordinationState
+            ? {
+                ownedClaims: context.coordinationState.ownedClaims.map(serializeWorkClaim),
+                pendingInboundHandoffs: context.coordinationState.pendingInboundHandoffs.map(serializeHandoffRecord),
+                pendingOutboundHandoffs: context.coordinationState.pendingOutboundHandoffs.map(serializeHandoffRecord),
+                sharedWorkItems: context.coordinationState.sharedWorkItems.map((item) => ({
+                    id: item.id,
+                    title: item.title,
+                    status: item.status,
+                    visibility_class: item.visibility_class,
+                })),
+            }
+            : null,
+        tokenEstimate: context.tokenEstimate,
+        ...(options.includeDebug
+            ? {
+                debugTrace: context.debugTrace,
+                knowledgeSelectionReasons: context.knowledgeSelectionReasons,
+            }
+            : {}),
+    };
+}
+function serializeActorRef(actor) {
+    return {
+        actor_kind: actor.actor_kind,
+        actor_id: actor.actor_id,
+        system_id: actor.system_id,
+        display_name: actor.display_name,
+        metadata: actor.metadata,
+    };
+}
+function serializeWorkClaim(claim) {
+    return {
+        id: claim.id,
+        work_item_id: claim.work_item_id,
+        actor: serializeActorRef(claim.actor),
+        session_id: claim.session_id,
+        claim_token: claim.claim_token,
+        status: claim.status,
+        claimed_at: claim.claimed_at,
+        expires_at: claim.expires_at,
+        released_at: claim.released_at,
+        release_reason: claim.release_reason,
+        source_event_id: claim.source_event_id,
+        visibility_class: claim.visibility_class,
+        version: claim.version,
+    };
+}
+function serializeHandoffRecord(handoff) {
+    return {
+        id: handoff.id,
+        work_item_id: handoff.work_item_id,
+        from_actor: serializeActorRef(handoff.from_actor),
+        to_actor: serializeActorRef(handoff.to_actor),
+        session_id: handoff.session_id,
+        summary: handoff.summary,
+        context_bundle_ref: handoff.context_bundle_ref,
+        status: handoff.status,
+        created_at: handoff.created_at,
+        accepted_at: handoff.accepted_at,
+        rejected_at: handoff.rejected_at,
+        canceled_at: handoff.canceled_at,
+        expires_at: handoff.expires_at,
+        decision_reason: handoff.decision_reason,
+        source_event_id: handoff.source_event_id,
+        visibility_class: handoff.visibility_class,
+        version: handoff.version,
+    };
+}
+function serializeTimelineResult(result) {
+    return {
+        events: result.events,
+        nextCursor: result.nextCursor,
+    };
+}
+function serializeTemporalState(state, options = {}) {
+    return {
+        asOf: state.asOf,
+        exact: state.exact,
+        cutoverAt: state.cutoverAt,
+        watermarkEventId: state.watermarkEventId,
+        context: serializeContextResponse(state.context, {
+            includeDebug: options.includeDebug,
+        }),
+        sessionState: state.sessionState,
+        turns: state.turns,
+        workingMemory: state.workingMemory,
+        knowledge: state.knowledge,
+        workItems: state.workItems,
+        workClaims: state.workClaims.map(serializeWorkClaim),
+        handoffs: state.handoffs.map(serializeHandoffRecord),
+        coordinationState: state.coordinationState
+            ? {
+                ownedClaims: state.coordinationState.ownedClaims.map(serializeWorkClaim),
+                pendingInboundHandoffs: state.coordinationState.pendingInboundHandoffs.map(serializeHandoffRecord),
+                pendingOutboundHandoffs: state.coordinationState.pendingOutboundHandoffs.map(serializeHandoffRecord),
+                sharedWorkItems: state.coordinationState.sharedWorkItems,
+            }
+            : null,
+        associations: state.associations,
+        playbooks: state.playbooks,
+    };
+}
 async function readBody(req, limitBytes = 1_048_576) {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -80,6 +257,9 @@ function parseOptionalInteger(value) {
     const parsed = Number(value);
     return Number.isInteger(parsed) ? parsed : undefined;
 }
+function parseOptionalTemporalId(value) {
+    return parseOptionalTemporalIdValue(value, 'cursor', failHttpValidation);
+}
 function normalizePath(path) {
     if (path.length > 1 && path.endsWith('/')) {
         return path.slice(0, -1);
@@ -109,13 +289,51 @@ function requireEnum(value, allowed, name) {
     }
     return value;
 }
+function parseContextViewPolicy(value, name = 'view') {
+    return value ? requireEnum(value, CONTEXT_VIEW_POLICIES, name) : undefined;
+}
+function parseViewerFromQuery(query) {
+    if (query.viewer_actor_id == null && query.viewer_actor_kind == null)
+        return undefined;
+    return parseActorRef({
+        actor_kind: query.viewer_actor_kind,
+        actor_id: query.viewer_actor_id,
+        system_id: query.viewer_system_id,
+        display_name: query.viewer_display_name,
+    }, 'viewer');
+}
+function parseActorRef(value, name = 'actor') {
+    if (value == null)
+        return undefined;
+    if (!isRecord(value)) {
+        throw new HttpRequestError(400, `Invalid field: ${name}`);
+    }
+    return {
+        actor_kind: requireEnum(value.actor_kind, ACTOR_KINDS, `${name}.actor_kind`),
+        actor_id: requireString(value.actor_id, `${name}.actor_id`),
+        system_id: value.system_id == null ? null : requireString(value.system_id, `${name}.system_id`),
+        display_name: value.display_name == null ? null : requireString(value.display_name, `${name}.display_name`),
+        metadata: isRecord(value.metadata) ? value.metadata : null,
+    };
+}
 function parseLimit(value) {
     const parsed = parseOptionalInteger(value);
     if (value != null && parsed == null) {
         throw new HttpRequestError(400, 'Invalid limit parameter');
     }
+    if (parsed != null && parsed > MAX_LIST_LIMIT) {
+        throw new HttpRequestError(400, `Limit parameter exceeds maximum of ${MAX_LIST_LIMIT}`);
+    }
     return parsed;
 }
+function parseOptionalNonNegativeInteger(value, name) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new HttpRequestError(400, `Invalid field: ${name} (must be a non-negative integer)`);
+    }
+    return value;
+}
 function parseScopeLevel(value, name, allowed = ['scope', 'workspace', 'system', 'tenant']) {
     if (value == null || value === '')
         return undefined;
@@ -141,21 +359,11 @@ function resolvePartialScope(source, labels) {
 function parseEventTypes(value) {
     if (!value)
         return undefined;
-    const allowed = [
-        'manager',
-        'search',
-        'compaction',
-        'extraction',
-        'promotion',
-        'knowledge_change',
-        'context_assembly',
-        'semantic_search',
-    ];
     return new Set(value
         .split(',')
         .map((entry) => entry.trim())
         .filter(Boolean)
-        .map((entry) => requireEnum(entry, allowed, 'event_types')));
+        .map((entry) => requireEnum(entry, MEMORY_EVENT_TYPES, 'event_types')));
 }
 function resolveRequestScope(fallbackScope, req, query, body) {
     const bodyScope = body?.scope;
@@ -190,6 +398,18 @@ function resolveRequestScope(fallbackScope, req, query, body) {
     }
     return fallbackScope ?? 'default';
 }
+function materializeScope(scopeInput) {
+    return typeof scopeInput === 'string'
+        ? {
+            tenant_id: 'default',
+            system_id: 'default',
+            scope_id: scopeInput,
+        }
+        : scopeInput;
+}
+function cloneSnapshotValue(value) {
+    return structuredClone(value);
+}
 function matchesEventScope(event, scope, level) {
     const left = normalizeScope(event.scope);
     const right = normalizeScope(scope);
@@ -197,6 +417,9 @@ function matchesEventScope(event, scope, level) {
         return false;
     if (level === 'tenant')
         return true;
+    // Collaboration scope is the explicit shared-memory boundary across systems,
+    // so workspace-level collaboration listeners intentionally fan out across
+    // system_id values when both sides are bound to the same collaboration.
     if (level === 'workspace' && left.collaboration_id && right.collaboration_id) {
         return left.collaboration_id === right.collaboration_id;
     }
@@ -233,7 +456,49 @@ export async function startHttpServer(config = {}) {
     const adminApiKey = config.adminApiKey ?? process.env.MEMORY_ADMIN_API_KEY;
     const enableCors = config.cors ?? true;
     const bodyLimitBytes = config.bodyLimitBytes ?? 1_048_576;
+    const { defaultDiffMaxEvents, maxDiffMaxEvents } = resolveDiffEventCaps(config.defaultDiffMaxEvents, config.maxDiffMaxEvents);
     const managers = new Map();
+    // Managers keyed by (scope, sessionId) for snapshot endpoints that must
+    // honor the URL-path session instead of the scope's bound default session.
+    const sessionManagers = new Map();
+    const sessionSnapshots = new Map();
+    function touchManagerCache(cache, key, manager, limit) {
+        cache.delete(key);
+        cache.set(key, manager);
+        while (cache.size > limit) {
+            const oldestKey = cache.keys().next().value;
+            if (!oldestKey)
+                break;
+            cache.delete(oldestKey);
+        }
+    }
+    function touchSnapshot(key, snapshot) {
+        const cachedSnapshot = cloneSnapshotValue(snapshot);
+        sessionSnapshots.delete(key);
+        sessionSnapshots.set(key, cachedSnapshot);
+        const scopeEntries = [...sessionSnapshots.entries()].filter(([, value]) => value.scopeKey === cachedSnapshot.scopeKey);
+        while (scopeEntries.length > PER_SCOPE_SESSION_SNAPSHOT_LIMIT) {
+            const [oldestKey] = scopeEntries.shift() ?? [];
+            if (!oldestKey)
+                break;
+            sessionSnapshots.delete(oldestKey);
+        }
+        while (sessionSnapshots.size > SESSION_SNAPSHOT_LIMIT) {
+            const oldest = sessionSnapshots.keys().next().value;
+            if (oldest === undefined)
+                break;
+            sessionSnapshots.delete(oldest);
+        }
+    }
+    function readSnapshot(key) {
+        const snapshot = sessionSnapshots.get(key);
+        if (!snapshot)
+            return undefined;
+        // Refresh LRU recency
+        sessionSnapshots.delete(key);
+        sessionSnapshots.set(key, snapshot);
+        return cloneSnapshotValue(snapshot);
+    }
     const databaseUrl = config.databaseUrl ?? process.env.MEMORY_DATABASE_URL;
     const adapterResources = databaseUrl
         ? await (async () => {
@@ -244,7 +509,7 @@ export async function startHttpServer(config = {}) {
             const { createPostgresAdapter, createPostgresEmbeddingAdapter } = await import('../adapters/postgres/index.js');
             const Pool = pgModule.Pool ?? pgModule.default?.Pool;
             const pool = new Pool({ connectionString: databaseUrl });
-            const asyncAdapter = createPostgresAdapter(pool);
+            const asyncAdapter = createPostgresAdapter(pool, { ownsPool: false });
             return {
                 asyncAdapter,
                 embeddingAdapter: createPostgresEmbeddingAdapter(pool),
@@ -264,11 +529,10 @@ export async function startHttpServer(config = {}) {
             };
         })();
     const sseClients = new Set();
-    function createHostedManager(scopeInput) {
-        const baseOptions = {
-            adapter: 'sqlite',
-            path: config.dbPath ?? ':memory:',
+    function buildHostedManagerOptions(scopeInput, sessionId) {
+        return {
             scope: scopeInput,
+            ...(sessionId ? { sessionId } : {}),
             summarizer: config.summarizer ?? 'extractive',
             extractor: config.extractor ?? 'regex',
             preset: config.preset,
@@ -276,6 +540,13 @@ export async function startHttpServer(config = {}) {
             qualityMode: config.qualityMode,
             qualityTier: config.qualityTier,
             crossScopeLevel: config.crossScopeLevel,
+            autoDetectWorkspace: config.autoDetectWorkspace,
+            structuredClient: config.structuredClient,
+        };
+    }
+    function createHostedManager(scopeInput) {
+        const baseOptions = {
+            ...buildHostedManagerOptions(scopeInput),
             onEvent: (event) => {
                 if (sseClients.size === 0)
                     return;
@@ -295,6 +566,7 @@ export async function startHttpServer(config = {}) {
             ...baseOptions,
             asyncAdapter: adapterResources.asyncAdapter,
             embeddingAdapter: adapterResources.embeddingAdapter,
+            closeAdapter: false,
         });
     }
     function getManager(scopeInput) {
@@ -303,10 +575,38 @@ export async function startHttpServer(config = {}) {
             : JSON.stringify(normalizeScope(scopeInput));
         const existing = managers.get(key);
         if (existing) {
+            touchManagerCache(managers, key, existing, MANAGER_CACHE_LIMIT);
             return existing;
         }
         const manager = createHostedManager(scopeInput);
-        managers.set(key, manager);
+        touchManagerCache(managers, key, manager, MANAGER_CACHE_LIMIT);
+        return manager;
+    }
+    function scopeKeyFor(scopeInput) {
+        return typeof scopeInput === 'string'
+            ? `scope:${scopeInput}`
+            : JSON.stringify(normalizeScope(scopeInput));
+    }
+    /**
+     * Get a manager bound to a specific sessionId under the given scope.
+     * Snapshot endpoints use this so POST/GET/REFRESH against different URL
+     * :sessionId values read from the correct session, not the scope's default.
+     */
+    function getSessionManager(scopeInput, sessionId) {
+        const key = `${scopeKeyFor(scopeInput)}|session:${sessionId}`;
+        const existing = sessionManagers.get(key);
+        if (existing) {
+            touchManagerCache(sessionManagers, key, existing, SESSION_MANAGER_CACHE_LIMIT);
+            return existing;
+        }
+        const baseOptions = buildHostedManagerOptions(scopeInput, sessionId);
+        const manager = createMemoryWithAsyncAdapter({
+            ...baseOptions,
+            asyncAdapter: adapterResources.asyncAdapter,
+            embeddingAdapter: adapterResources.embeddingAdapter,
+            closeAdapter: false,
+        });
+        touchManagerCache(sessionManagers, key, manager, SESSION_MANAGER_CACHE_LIMIT);
         return manager;
     }
     const manager = getManager(config.scope ?? 'default');
@@ -325,7 +625,7 @@ export async function startHttpServer(config = {}) {
         // Auth
         if (apiKey) {
             const auth = req.headers.authorization;
-            if (!auth || auth !== `Bearer ${apiKey}`) {
+            if (!safeSecretEquals(auth, `Bearer ${apiKey}`)) {
                 writeError(res, 401, 'Unauthorized');
                 return;
             }
@@ -357,30 +657,132 @@ export async function startHttpServer(config = {}) {
             // GET /v1/context
             if (path === '/v1/context' && req.method === 'GET') {
                 const requestManager = getManager(resolveRequestScope(config.scope, req, query));
-                const context = await requestManager.getContext(query.query || undefined);
-                writeJson(res, 200, {
-                    currentObjective: context.currentObjective,
-                    activeTurnCount: context.activeTurns.length,
-                    workingMemory: context.workingMemory
-                        ? {
-                            summary: context.workingMemory.summary,
-                            key_entities: context.workingMemory.key_entities,
-                            topic_tags: context.workingMemory.topic_tags,
-                        }
-                        : null,
-                    relevantKnowledge: context.relevantKnowledge.map((k) => ({
-                        id: k.id,
-                        fact: k.fact,
-                        fact_type: k.fact_type,
-                        confidence: k.confidence,
-                    })),
-                    activeObjectives: context.activeObjectives.map((o) => ({
-                        title: o.title,
-                        status: o.status,
-                    })),
-                    unresolvedWork: context.unresolvedWork,
-                    tokenEstimate: context.tokenEstimate,
+                const context = await requestManager.getContext(query.query || undefined, {
+                    view: parseContextViewPolicy(query.view),
+                    viewer: parseViewerFromQuery(query),
+                    includeCoordinationState: query.include_coordination === 'true',
+                });
+                writeJson(res, 200, serializeContextResponse(context, {
+                    includeDebug: query.debug === 'true',
+                }));
+                return;
+            }
+            // GET /v1/state
+            if (path === '/v1/state' && req.method === 'GET') {
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                const asOf = parseOptionalFiniteNumber(query.as_of, { name: 'as_of' }, failHttpValidation);
+                if (asOf == null) {
+                    writeError(res, 400, 'Missing or invalid as_of parameter');
+                    return;
+                }
+                const state = await requestManager.getStateAt(asOf, {
+                    relevanceQuery: query.query || undefined,
+                    view: parseContextViewPolicy(query.view),
+                    viewer: parseViewerFromQuery(query),
+                    includeCoordinationState: query.include_coordination === 'true',
+                });
+                writeJson(res, 200, serializeTemporalState(state, {
+                    includeDebug: query.include_debug === 'true',
+                }));
+                return;
+            }
+            // GET /v1/timeline
+            if (path === '/v1/timeline' && req.method === 'GET') {
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                const startAt = parseOptionalFiniteNumber(query.start_at, { name: 'start_at' }, failHttpValidation);
+                const endAt = parseOptionalFiniteNumber(query.end_at, { name: 'end_at' }, failHttpValidation);
+                const cursor = parseOptionalTemporalId(query.cursor);
+                const limit = parseLimit(query.limit);
+                const timeline = await requestManager.getTimeline({
+                    sessionId: query.session_id || undefined,
+                    entityKind: query.entity_kind,
+                    entityId: query.entity_id || undefined,
+                    startAt,
+                    endAt,
+                    limit,
+                    cursor,
+                });
+                writeJson(res, 200, serializeTimelineResult(timeline));
+                return;
+            }
+            // GET /v1/state/diff
+            if (path === '/v1/state/diff' && req.method === 'GET') {
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                const from = parseOptionalFiniteNumber(query.from, { name: 'from' }, failHttpValidation);
+                const to = parseOptionalFiniteNumber(query.to, { name: 'to' }, failHttpValidation);
+                const maxEvents = parseOptionalFiniteInteger(query.max_events, { name: 'max_events', min: 1, max: maxDiffMaxEvents }, failHttpValidation);
+                if (from == null || to == null) {
+                    writeError(res, 400, 'Missing or invalid from/to parameters');
+                    return;
+                }
+                const diff = await requestManager.diffState(from, to, {
+                    sessionId: query.session_id || undefined,
+                    entityKind: query.entity_kind,
+                    entityId: query.entity_id || undefined,
+                    maxEvents: maxEvents ?? defaultDiffMaxEvents,
+                });
+                writeJson(res, 200, diff);
+                return;
+            }
+            // GET /v1/events/log
+            if (path === '/v1/events/log' && req.method === 'GET') {
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                const startAt = parseOptionalFiniteNumber(query.start_at, { name: 'start_at' }, failHttpValidation);
+                const endAt = parseOptionalFiniteNumber(query.end_at, { name: 'end_at' }, failHttpValidation);
+                const cursor = parseOptionalTemporalId(query.cursor);
+                const limit = parseLimit(query.limit);
+                const events = await requestManager.listMemoryEvents({
+                    sessionId: query.session_id || undefined,
+                    entityKind: query.entity_kind,
+                    entityId: query.entity_id || undefined,
+                    startAt,
+                    endAt,
+                    limit,
+                    cursor,
                 });
+                writeJson(res, 200, serializeTimelineResult(events));
+                return;
+            }
+            // GET /v1/changes/stream
+            if (path === '/v1/changes/stream' && req.method === 'GET') {
+                res.writeHead(200, {
+                    'Content-Type': 'text/event-stream',
+                    'Cache-Control': 'no-cache',
+                    Connection: 'keep-alive',
+                });
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                let closed = false;
+                const abortController = new AbortController();
+                req.on('close', () => {
+                    closed = true;
+                    abortController.abort();
+                });
+                const cursor = parseOptionalTemporalId(query.cursor);
+                const initialCursor = await requestManager.resolveChangeStreamCursor(cursor);
+                const iterator = requestManager.streamChanges({
+                    cursor,
+                    sessionId: query.session_id || undefined,
+                    entityKind: query.entity_kind,
+                    entityId: query.entity_id || undefined,
+                    pollIntervalMs: 250,
+                    signal: abortController.signal,
+                });
+                void (async () => {
+                    res.write(`data: ${JSON.stringify({ type: 'connected', cursor: initialCursor })}\n\n`);
+                    try {
+                        for await (const event of iterator) {
+                            if (closed)
+                                break;
+                            res.write(`data: ${JSON.stringify(event)}\n\n`);
+                        }
+                    }
+                    catch (error) {
+                        if (!closed) {
+                            res.write(`data: ${JSON.stringify({ type: 'error', error: String(error) })}\n\n`);
+                            res.end();
+                        }
+                    }
+                })();
                 return;
             }
             // GET /v1/search
@@ -435,7 +837,7 @@ export async function startHttpServer(config = {}) {
             // GET /v1/inspect/knowledge
             if (path === '/v1/inspect/knowledge' && req.method === 'GET') {
                 const requestManager = getManager(resolveRequestScope(config.scope, req, query));
-                const limit = parseOptionalInteger(query.limit);
+                const limit = parseLimit(query.limit);
                 const cursor = parseOptionalInteger(query.cursor);
                 if ((query.limit && limit == null) || (query.cursor && cursor == null)) {
                     writeError(res, 400, 'Invalid pagination parameters');
@@ -463,7 +865,7 @@ export async function startHttpServer(config = {}) {
             if (path === '/v1/inspect/audits' && req.method === 'GET') {
                 const requestManager = getManager(resolveRequestScope(config.scope, req, query));
                 const knowledgeId = parseOptionalInteger(query.knowledge_id);
-                const limit = parseOptionalInteger(query.limit);
+                const limit = parseLimit(query.limit);
                 if ((query.knowledge_id && knowledgeId == null) || (query.limit && limit == null)) {
                     writeError(res, 400, 'Invalid audit inspection parameters');
                     return;
@@ -478,14 +880,17 @@ export async function startHttpServer(config = {}) {
             // GET /v1/inspect/monitor
             if (path === '/v1/inspect/monitor' && req.method === 'GET') {
                 const requestManager = getManager(resolveRequestScope(config.scope, req, query));
-                const monitor = await requestManager.getContextMonitor();
-                writeJson(res, 200, { monitor });
+                const [monitor, diagnostics] = await Promise.all([
+                    requestManager.getContextMonitor(),
+                    requestManager.getRuntimeDiagnostics(),
+                ]);
+                writeJson(res, 200, { monitor, diagnostics });
                 return;
             }
             // GET /v1/inspect/compactions
             if (path === '/v1/inspect/compactions' && req.method === 'GET') {
                 const requestManager = getManager(resolveRequestScope(config.scope, req, query));
-                const limit = parseOptionalInteger(query.limit);
+                const limit = parseLimit(query.limit);
                 if (query.limit && limit == null) {
                     writeError(res, 400, 'Invalid compaction inspection parameters');
                     return;
@@ -494,6 +899,40 @@ export async function startHttpServer(config = {}) {
                 writeJson(res, 200, { logs });
                 return;
             }
+            // GET /v1/inspect/context
+            if (path === '/v1/inspect/context' && req.method === 'GET') {
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                const asOf = parseOptionalFiniteNumber(query.as_of, { name: 'as_of' }, failHttpValidation);
+                const context = asOf != null
+                    ? await requestManager.getContextAt(asOf, query.query || undefined)
+                    : await requestManager.getContext(query.query || undefined);
+                writeJson(res, 200, serializeContextResponse(context, { includeDebug: true }));
+                return;
+            }
+            // GET /v1/inspect/session-state
+            if (path === '/v1/inspect/session-state' && req.method === 'GET') {
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                const asOf = parseOptionalFiniteNumber(query.as_of, { name: 'as_of' }, failHttpValidation);
+                const context = asOf != null
+                    ? await requestManager.getContextAt(asOf, query.query || undefined)
+                    : await requestManager.getContext(query.query || undefined);
+                writeJson(res, 200, { sessionState: context.sessionState });
+                return;
+            }
+            // GET /v1/inspect/retrieval
+            if (path === '/v1/inspect/retrieval' && req.method === 'GET') {
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                const asOf = parseOptionalFiniteNumber(query.as_of, { name: 'as_of' }, failHttpValidation);
+                const context = asOf != null
+                    ? await requestManager.getContextAt(asOf, query.query || undefined)
+                    : await requestManager.getContext(query.query || undefined);
+                writeJson(res, 200, {
+                    sessionState: context.sessionState,
+                    knowledgeSelectionReasons: context.knowledgeSelectionReasons,
+                    debugTrace: context.debugTrace,
+                });
+                return;
+            }
             // GET /v1/inspect/reverification
             if (path === '/v1/inspect/reverification' && req.method === 'GET') {
                 const requestManager = getManager(resolveRequestScope(config.scope, req, query));
@@ -520,13 +959,134 @@ export async function startHttpServer(config = {}) {
             if (path === '/v1/work' && req.method === 'POST') {
                 const body = await readBody(req, bodyLimitBytes);
                 const requestManager = getManager(resolveRequestScope(config.scope, req, query, body));
-                const item = await requestManager.trackWorkItem(requireString(body.title, 'title'), requireEnum(body.kind ?? 'objective', ['objective', 'unresolved_work', 'constraint'], 'kind'), requireEnum(body.status ?? 'open', ['open', 'in_progress', 'blocked', 'done'], 'status'), optionalString(body.detail, 'detail'));
+                const item = await requestManager.trackWorkItem(requireString(body.title, 'title'), requireEnum(body.kind ?? 'objective', ['objective', 'unresolved_work', 'constraint'], 'kind'), requireEnum(body.status ?? 'open', ['open', 'in_progress', 'blocked', 'done'], 'status'), optionalString(body.detail, 'detail'), {
+                    visibilityClass: body.visibility_class == null
+                        ? undefined
+                        : requireEnum(body.visibility_class, MEMORY_VISIBILITY_CLASSES, 'visibility_class'),
+                });
                 writeJson(res, 201, { workItemId: item.id });
                 return;
             }
+            const workItemMatch = path.match(/^\/v1\/work-items\/(\d+)$/);
+            if (workItemMatch && req.method === 'POST') {
+                const body = await readBody(req, bodyLimitBytes);
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query, body));
+                const item = await requestManager.updateWorkItem(Number(workItemMatch[1]), {
+                    title: body.title != null ? requireString(body.title, 'title') : undefined,
+                    detail: body.detail != null ? optionalString(body.detail, 'detail') ?? null : undefined,
+                    status: body.status != null
+                        ? requireEnum(body.status, ['open', 'in_progress', 'blocked', 'done'], 'status')
+                        : undefined,
+                    visibility_class: body.visibility_class != null
+                        ? requireEnum(body.visibility_class, MEMORY_VISIBILITY_CLASSES, 'visibility_class')
+                        : undefined,
+                }, {
+                    expectedVersion: parseOptionalFiniteInteger(body.expectedVersion, { name: 'expectedVersion', min: 0 }, failHttpValidation),
+                });
+                writeJson(res, 200, { workItem: item });
+                return;
+            }
+            const claimMatch = path.match(/^\/v1\/work-items\/(\d+)\/claim$/);
+            if (claimMatch && req.method === 'POST') {
+                const body = await readBody(req, bodyLimitBytes);
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query, body));
+                const actor = parseActorRef(body.actor, 'actor');
+                if (!actor) {
+                    writeError(res, 400, 'Missing required field: actor');
+                    return;
+                }
+                const claim = await requestManager.claimWorkItem({
+                    workItemId: Number(claimMatch[1]),
+                    actor,
+                    leaseSeconds: parseOptionalFiniteInteger(body.leaseSeconds, { name: 'leaseSeconds', min: 1 }, failHttpValidation),
+                });
+                writeJson(res, 200, { claim: serializeWorkClaim(claim) });
+                return;
+            }
+            const renewMatch = path.match(/^\/v1\/work-claims\/(\d+)\/renew$/);
+            if (renewMatch && req.method === 'POST') {
+                const body = await readBody(req, bodyLimitBytes);
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query, body));
+                const actor = parseActorRef(body.actor, 'actor');
+                if (!actor) {
+                    writeError(res, 400, 'Missing required field: actor');
+                    return;
+                }
+                const claim = await requestManager.renewWorkClaim(Number(renewMatch[1]), actor, parseOptionalFiniteInteger(body.leaseSeconds, { name: 'leaseSeconds', min: 1 }, failHttpValidation));
+                writeJson(res, 200, { claim: claim ? serializeWorkClaim(claim) : null });
+                return;
+            }
+            const releaseMatch = path.match(/^\/v1\/work-claims\/(\d+)\/release$/);
+            if (releaseMatch && req.method === 'POST') {
+                const body = await readBody(req, bodyLimitBytes);
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query, body));
+                const actor = parseActorRef(body.actor, 'actor');
+                if (!actor) {
+                    writeError(res, 400, 'Missing required field: actor');
+                    return;
+                }
+                const claim = await requestManager.releaseWorkClaim(Number(releaseMatch[1]), actor, optionalString(body.reason, 'reason'));
+                writeJson(res, 200, { claim: claim ? serializeWorkClaim(claim) : null });
+                return;
+            }
+            if (path === '/v1/work-claims' && req.method === 'GET') {
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                const claims = await requestManager.listWorkClaims();
+                writeJson(res, 200, { claims: claims.map(serializeWorkClaim) });
+                return;
+            }
+            const handoffCreateMatch = path.match(/^\/v1\/work-items\/(\d+)\/handoffs$/);
+            if (handoffCreateMatch && req.method === 'POST') {
+                const body = await readBody(req, bodyLimitBytes);
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query, body));
+                const fromActor = parseActorRef(body.from_actor, 'from_actor');
+                const toActor = parseActorRef(body.to_actor, 'to_actor');
+                if (!fromActor || !toActor) {
+                    writeError(res, 400, 'Missing required field: from_actor/to_actor');
+                    return;
+                }
+                const handoff = await requestManager.handoffWorkItem({
+                    workItemId: Number(handoffCreateMatch[1]),
+                    fromActor,
+                    toActor,
+                    summary: requireString(body.summary, 'summary'),
+                    contextBundleRef: optionalString(body.context_bundle_ref, 'context_bundle_ref') ?? null,
+                    expiresAt: parseOptionalFiniteInteger(body.expires_at, { name: 'expires_at', min: 0 }, failHttpValidation) ?? null,
+                });
+                writeJson(res, 201, { handoff: serializeHandoffRecord(handoff) });
+                return;
+            }
+            const handoffActionMatch = path.match(/^\/v1\/handoffs\/(\d+)\/(accept|reject|cancel)$/);
+            if (handoffActionMatch && req.method === 'POST') {
+                const body = await readBody(req, bodyLimitBytes);
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query, body));
+                const actor = parseActorRef(body.actor, 'actor');
+                if (!actor) {
+                    writeError(res, 400, 'Missing required field: actor');
+                    return;
+                }
+                const id = Number(handoffActionMatch[1]);
+                const action = handoffActionMatch[2];
+                const reason = optionalString(body.reason, 'reason');
+                const handoff = action === 'accept'
+                    ? await requestManager.acceptHandoff(id, actor, reason)
+                    : action === 'reject'
+                        ? await requestManager.rejectHandoff(id, actor, reason)
+                        : await requestManager.cancelHandoff(id, actor, reason);
+                writeJson(res, 200, { handoff: handoff ? serializeHandoffRecord(handoff) : null });
+                return;
+            }
+            if (path === '/v1/handoffs' && req.method === 'GET') {
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                const handoffs = await requestManager.listPendingHandoffs({
+                    direction: query.direction ?? 'all',
+                });
+                writeJson(res, 200, { handoffs: handoffs.map(serializeHandoffRecord) });
+                return;
+            }
             // POST /v1/compact
             if (path === '/v1/compact' && req.method === 'POST') {
-                if (adminApiKey && req.headers['x-admin-key'] !== adminApiKey) {
+                if (adminApiKey && !safeSecretEquals(req.headers['x-admin-key'], adminApiKey)) {
                     writeError(res, 403, 'Admin key required');
                     return;
                 }
@@ -542,13 +1102,18 @@ export async function startHttpServer(config = {}) {
             // GET /v1/health
             if (path === '/v1/health' && req.method === 'GET') {
                 const requestManager = getManager(resolveRequestScope(config.scope, req, query));
-                const context = await requestManager.getContext();
+                const [context, diagnostics] = await Promise.all([
+                    requestManager.getContext(),
+                    requestManager.getRuntimeDiagnostics(),
+                ]);
                 writeJson(res, 200, {
                     activeTurnCount: context.activeTurns.length,
                     tokenEstimate: context.tokenEstimate,
                     knowledgeCount: context.relevantKnowledge.length,
                     objectiveCount: context.activeObjectives.length,
                     unresolvedWorkCount: context.unresolvedWork.length,
+                    sessionStateUpdatedAt: context.sessionState.updatedAt,
+                    circuitBreakers: diagnostics.circuitBreakers,
                 });
                 return;
             }
@@ -558,7 +1123,7 @@ export async function startHttpServer(config = {}) {
             }
             // POST /v1/maintenance
             if (path === '/v1/maintenance' && req.method === 'POST') {
-                if (adminApiKey && req.headers['x-admin-key'] !== adminApiKey) {
+                if (adminApiKey && !safeSecretEquals(req.headers['x-admin-key'], adminApiKey)) {
                     writeError(res, 403, 'Admin key required');
                     return;
                 }
@@ -569,12 +1134,13 @@ export async function startHttpServer(config = {}) {
                     expiredWorkingMemory: report.expiredWorkingMemoryIds.length,
                     retiredKnowledge: report.retiredKnowledgeIds.length,
                     deletedWorkItems: report.deletedWorkItemIds.length,
+                    deletedAssociationIds: report.deletedAssociationIds,
                 });
                 return;
             }
             const reverificationMatch = path.match(/^\/v1\/reverification\/(\d+)$/);
             if (reverificationMatch && req.method === 'POST') {
-                if (adminApiKey && req.headers['x-admin-key'] !== adminApiKey) {
+                if (adminApiKey && !safeSecretEquals(req.headers['x-admin-key'], adminApiKey)) {
                     writeError(res, 403, 'Admin key required');
                     return;
                 }
@@ -585,7 +1151,7 @@ export async function startHttpServer(config = {}) {
             }
             // POST /v1/reverification/run
             if (path === '/v1/reverification/run' && req.method === 'POST') {
-                if (adminApiKey && req.headers['x-admin-key'] !== adminApiKey) {
+                if (adminApiKey && !safeSecretEquals(req.headers['x-admin-key'], adminApiKey)) {
                     writeError(res, 403, 'Admin key required');
                     return;
                 }
@@ -637,7 +1203,7 @@ export async function startHttpServer(config = {}) {
                 const scope = resolveRequestScope(config.scope, req, query);
                 sseClients.add({
                     response: res,
-                    scope: typeof scope === 'string' ? undefined : scope,
+                    scope: materializeScope(scope),
                     scopeLevel: parseScopeLevel(query.scope_level, 'scope_level') ?? 'scope',
                     eventTypes: parseEventTypes(query.event_types),
                 });
@@ -650,6 +1216,352 @@ export async function startHttpServer(config = {}) {
                 });
                 return;
             }
+            // GET /v1/episodes
+            if (path === '/v1/episodes' && req.method === 'GET') {
+                if (!query.q) {
+                    writeError(res, 400, 'Missing required query parameter: q');
+                    return;
+                }
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                const detailLevel = query.detail
+                    ? requireEnum(query.detail, EPISODE_DETAIL_LEVELS, 'detail')
+                    : undefined;
+                const episodeStartAt = parseOptionalFiniteNumber(query.start_at, { name: 'start_at' }, failHttpValidation);
+                const episodeEndAt = parseOptionalFiniteNumber(query.end_at, { name: 'end_at' }, failHttpValidation);
+                const episodes = await requestManager.searchEpisodes({
+                    query: query.q,
+                    detailLevel,
+                    limit: parseLimit(query.limit),
+                    timeRange: episodeStartAt != null || episodeEndAt != null
+                        ? {
+                            start_at: episodeStartAt,
+                            end_at: episodeEndAt,
+                        }
+                        : undefined,
+                });
+                writeJson(res, 200, { episodes });
+                return;
+            }
+            // POST /v1/episodes/summarize
+            if (path === '/v1/episodes/summarize' && req.method === 'POST') {
+                const body = await readBody(req, bodyLimitBytes);
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query, body));
+                const sessionId = requireString(body.session_id, 'session_id');
+                const detailLevel = body.detailLevel
+                    ? requireEnum(body.detailLevel, EPISODE_DETAIL_LEVELS, 'detailLevel')
+                    : undefined;
+                const summary = await requestManager.summarizeEpisode(sessionId, { detailLevel });
+                writeJson(res, 200, { episode: summary });
+                return;
+            }
+            // POST /v1/reflect
+            if (path === '/v1/reflect' && req.method === 'POST') {
+                const body = await readBody(req, bodyLimitBytes);
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query, body));
+                const reflectQuery = requireString(body.query, 'query');
+                const detailLevel = body.detailLevel
+                    ? requireEnum(body.detailLevel, EPISODE_DETAIL_LEVELS, 'detailLevel')
+                    : undefined;
+                const includeDeclarative = body.includeDeclarative != null ? Boolean(body.includeDeclarative) : undefined;
+                const includeEpisodic = body.includeEpisodic != null ? Boolean(body.includeEpisodic) : undefined;
+                const reflectLimit = parseOptionalNonNegativeInteger(body.limit, 'limit');
+                const timeRange = isRecord(body.timeRange)
+                    ? {
+                        start_at: parseOptionalFiniteNumber(body.timeRange.start_at, { name: 'timeRange.start_at' }, failHttpValidation),
+                        end_at: parseOptionalFiniteNumber(body.timeRange.end_at, { name: 'timeRange.end_at' }, failHttpValidation),
+                    }
+                    : undefined;
+                const result = await requestManager.reflect({
+                    query: reflectQuery,
+                    detailLevel,
+                    includeDeclarative,
+                    includeEpisodic,
+                    limit: reflectLimit,
+                    timeRange,
+                });
+                writeJson(res, 200, result);
+                return;
+            }
+            // GET /v1/memory
+            if (path === '/v1/memory' && req.method === 'GET') {
+                if (!query.q) {
+                    writeError(res, 400, 'Missing required query parameter: q');
+                    return;
+                }
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                const types = query.types
+                    ? query.types.split(',').map((t) => t.trim()).filter(Boolean)
+                    : undefined;
+                const cogMinTrust = parseOptionalFiniteNumber(query.minimumTrustScore, { name: 'minimumTrustScore', min: 0, max: 1 }, failHttpValidation);
+                const cogActiveOnly = query.activeOnly != null
+                    ? query.activeOnly === 'true'
+                    : undefined;
+                const result = await requestManager.searchCognitive({
+                    query: query.q,
+                    types,
+                    limit: parseLimit(query.limit),
+                    minimumTrustScore: cogMinTrust,
+                    activeOnly: cogActiveOnly,
+                });
+                writeJson(res, 200, result);
+                return;
+            }
+            // GET /v1/profile
+            if (path === '/v1/profile' && req.method === 'GET') {
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                const validViews = ['user', 'operator', 'workspace'];
+                const view = query.view
+                    ? requireEnum(query.view, validViews, 'view')
+                    : undefined;
+                const validSections = ['identity', 'preferences', 'communication', 'constraints', 'workflows'];
+                const sections = query.sections
+                    ? query.sections.split(',').map((s) => requireEnum(s.trim(), validSections, 'sections'))
+                    : undefined;
+                const minTrust = parseOptionalFiniteNumber(query.min_trust, { name: 'min_trust', min: 0, max: 1 }, failHttpValidation);
+                const includeProvisional = query.includeProvisional === 'true' ? true : undefined;
+                const includeDisputed = query.includeDisputed === 'true' ? true : undefined;
+                const profile = await requestManager.getProfile({
+                    view,
+                    sections,
+                    minimumTrustScore: minTrust,
+                    includeProvisional,
+                    includeDisputed,
+                });
+                writeJson(res, 200, { profile });
+                return;
+            }
+            // POST /v1/playbooks
+            if (path === '/v1/playbooks' && req.method === 'POST') {
+                const body = await readBody(req, bodyLimitBytes);
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query, body));
+                const playbook = await requestManager.createPlaybook({
+                    title: requireString(body.title, 'title'),
+                    description: requireString(body.description, 'description'),
+                    instructions: requireString(body.instructions, 'instructions'),
+                    references: Array.isArray(body.references) ? body.references.map(String) : undefined,
+                    templates: Array.isArray(body.templates) ? body.templates.map(String) : undefined,
+                    scripts: Array.isArray(body.scripts) ? body.scripts.map(String) : undefined,
+                    assets: Array.isArray(body.assets) ? body.assets.map(String) : undefined,
+                    tags: Array.isArray(body.tags) ? body.tags.map(String) : undefined,
+                    status: body.status ? requireEnum(body.status, PLAYBOOK_STATUSES, 'status') : undefined,
+                });
+                writeJson(res, 201, { playbook });
+                return;
+            }
+            // GET /v1/playbooks
+            if (path === '/v1/playbooks' && req.method === 'GET') {
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                if (query.q) {
+                    const results = await requestManager.searchPlaybooks(query.q, query.limit ? { limit: parseLimit(query.limit) } : undefined);
+                    writeJson(res, 200, {
+                        playbooks: results.map((r) => ({ ...r.item, rank: r.rank })),
+                    });
+                }
+                else {
+                    const playbooks = await requestManager.listPlaybooks();
+                    writeJson(res, 200, { playbooks });
+                }
+                return;
+            }
+            // POST /v1/playbooks/from-task
+            if (path === '/v1/playbooks/from-task' && req.method === 'POST') {
+                const body = await readBody(req, bodyLimitBytes);
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query, body));
+                const playbook = await requestManager.createPlaybookFromTask({
+                    title: requireString(body.title, 'title'),
+                    description: requireString(body.description, 'description'),
+                    sessionId: requireString(body.sessionId, 'sessionId'),
+                    tags: Array.isArray(body.tags) ? body.tags.map(String) : undefined,
+                    sourceWorkingMemoryId: parseOptionalFiniteInteger(body.sourceWorkingMemoryId, { name: 'sourceWorkingMemoryId', min: 1 }, failHttpValidation),
+                });
+                writeJson(res, 201, { playbook });
+                return;
+            }
+            // GET /v1/playbooks/:id
+            const playbookGetMatch = path.match(/^\/v1\/playbooks\/(\d+)$/);
+            if (playbookGetMatch && req.method === 'GET') {
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                const playbook = await requestManager.getPlaybook(Number(playbookGetMatch[1]));
+                if (!playbook) {
+                    writeError(res, 404, 'Playbook not found');
+                    return;
+                }
+                writeJson(res, 200, { playbook });
+                return;
+            }
+            // PUT /v1/playbooks/:id
+            if (playbookGetMatch && req.method === 'PUT') {
+                const body = await readBody(req, bodyLimitBytes);
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query, body));
+                const patch = {};
+                if (body.title != null)
+                    patch.title = requireString(body.title, 'title');
+                if (body.description != null)
+                    patch.description = requireString(body.description, 'description');
+                if (body.instructions != null)
+                    patch.instructions = requireString(body.instructions, 'instructions');
+                if (Array.isArray(body.references))
+                    patch.references = body.references.map(String);
+                if (Array.isArray(body.templates))
+                    patch.templates = body.templates.map(String);
+                if (Array.isArray(body.scripts))
+                    patch.scripts = body.scripts.map(String);
+                if (Array.isArray(body.assets))
+                    patch.assets = body.assets.map(String);
+                if (Array.isArray(body.tags))
+                    patch.tags = body.tags.map(String);
+                if (body.status != null)
+                    patch.status = requireEnum(body.status, PLAYBOOK_STATUSES, 'status');
+                const updated = await requestManager.updatePlaybook(Number(playbookGetMatch[1]), patch);
+                if (!updated) {
+                    writeError(res, 404, 'Playbook not found');
+                    return;
+                }
+                writeJson(res, 200, { playbook: updated });
+                return;
+            }
+            // POST /v1/playbooks/:id/revise
+            const playbookReviseMatch = path.match(/^\/v1\/playbooks\/(\d+)\/revise$/);
+            if (playbookReviseMatch && req.method === 'POST') {
+                const body = await readBody(req, bodyLimitBytes);
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query, body));
+                const result = await requestManager.revisePlaybook(Number(playbookReviseMatch[1]), requireString(body.instructions, 'instructions'), requireString(body.revisionReason, 'revisionReason'), optionalString(body.sourceSessionId, 'sourceSessionId'));
+                writeJson(res, 200, result);
+                return;
+            }
+            // POST /v1/playbooks/:id/use
+            const playbookUseMatch = path.match(/^\/v1\/playbooks\/(\d+)\/use$/);
+            if (playbookUseMatch && req.method === 'POST') {
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                const playbookId = Number(playbookUseMatch[1]);
+                await requestManager.recordPlaybookUse(playbookId);
+                const playbook = await requestManager.getPlaybook(playbookId);
+                writeJson(res, 200, { recorded: true, playbook });
+                return;
+            }
+            // POST /v1/associations
+            if (path === '/v1/associations' && req.method === 'POST') {
+                const body = await readBody(req, bodyLimitBytes);
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query, body));
+                const sourceId = Number.isInteger(body.source_id) && body.source_id > 0
+                    ? body.source_id
+                    : (() => { throw new HttpRequestError(400, 'Missing or invalid field: source_id (must be positive integer)'); })();
+                const targetId = Number.isInteger(body.target_id) && body.target_id > 0
+                    ? body.target_id
+                    : (() => { throw new HttpRequestError(400, 'Missing or invalid field: target_id (must be positive integer)'); })();
+                let confidence;
+                if (body.confidence !== undefined && body.confidence !== null) {
+                    if (typeof body.confidence !== 'number' || Number.isNaN(body.confidence) || body.confidence < 0 || body.confidence > 1) {
+                        throw new HttpRequestError(400, 'Invalid field: confidence (must be a number in [0, 1])');
+                    }
+                    confidence = body.confidence;
+                }
+                const association = await requestManager.addAssociation({
+                    source_kind: requireEnum(body.source_kind, ASSOCIATION_TARGET_KINDS, 'source_kind'),
+                    source_id: sourceId,
+                    target_kind: requireEnum(body.target_kind, ASSOCIATION_TARGET_KINDS, 'target_kind'),
+                    target_id: targetId,
+                    association_type: requireEnum(body.association_type, ASSOCIATION_TYPES, 'association_type'),
+                    confidence,
+                    auto_generated: typeof body.auto_generated === 'boolean' ? body.auto_generated : undefined,
+                });
+                writeJson(res, 201, { association });
+                return;
+            }
+            // GET /v1/associations/:kind/:id
+            const assocGetMatch = path.match(/^\/v1\/associations\/([a-z_]+)\/(\d+)$/);
+            if (assocGetMatch && req.method === 'GET') {
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                const kind = requireEnum(assocGetMatch[1], ASSOCIATION_TARGET_KINDS, 'kind');
+                const targetId = Number(assocGetMatch[2]);
+                const result = await requestManager.getAssociations(kind, targetId);
+                writeJson(res, 200, result);
+                return;
+            }
+            // POST /v1/associations/traverse
+            if (path === '/v1/associations/traverse' && req.method === 'POST') {
+                const body = await readBody(req, bodyLimitBytes);
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query, body));
+                const kind = requireEnum(body.kind, ASSOCIATION_TARGET_KINDS, 'kind');
+                const id = Number.isInteger(body.id) && body.id > 0
+                    ? body.id
+                    : (() => { throw new HttpRequestError(400, 'Missing or invalid field: id (must be positive integer)'); })();
+                const maxDepth = parseOptionalNonNegativeInteger(body.maxDepth, 'maxDepth');
+                const maxNodes = parseOptionalNonNegativeInteger(body.maxNodes, 'maxNodes');
+                const graph = await requestManager.traverseAssociations(kind, id, { maxDepth, maxNodes });
+                writeJson(res, 200, graph);
+                return;
+            }
+            // DELETE /v1/associations/:id
+            const assocDeleteMatch = path.match(/^\/v1\/associations\/(\d+)$/);
+            if (assocDeleteMatch && req.method === 'DELETE') {
+                const requestManager = getManager(resolveRequestScope(config.scope, req, query));
+                await requestManager.removeAssociation(Number(assocDeleteMatch[1]));
+                writeJson(res, 200, { deleted: true });
+                return;
+            }
+            // POST /v1/sessions/:sessionId/snapshot — capture a frozen snapshot
+            const snapshotCaptureMatch = path.match(/^\/v1\/sessions\/([^/]+)\/snapshot$/);
+            if (snapshotCaptureMatch && req.method === 'POST') {
+                const body = await readBody(req, bodyLimitBytes);
+                const sessionId = decodeURIComponent(snapshotCaptureMatch[1]);
+                const scopeInput = resolveRequestScope(config.scope, req, query, body);
+                // Use session-aware manager so getContext/getSessionBootstrap read
+                // the session named in the URL, not the scope's bound default.
+                const requestManager = getSessionManager(scopeInput, sessionId);
+                const scopeKey = scopeKeyFor(scopeInput);
+                const relevanceQuery = typeof body.relevanceQuery === 'string' ? body.relevanceQuery : undefined;
+                const snapshotData = await requestManager.captureSnapshot(relevanceQuery);
+                const snapshot = {
+                    scopeKey,
+                    snapshotId: `snap-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`,
+                    bootstrap: snapshotData.bootstrap,
+                    context: snapshotData.context,
+                    frozenAt: snapshotData.frozenAt,
+                    watermarkEventId: snapshotData.watermarkEventId,
+                };
+                touchSnapshot(`${scopeKey}:${sessionId}`, snapshot);
+                const { scopeKey: _scopeKey, ...publicSnapshot } = snapshot;
+                writeJson(res, 201, { snapshot: { ...publicSnapshot, sessionId } });
+                return;
+            }
+            // GET /v1/sessions/:sessionId/snapshot — fetch cached snapshot
+            if (snapshotCaptureMatch && req.method === 'GET') {
+                const sessionId = decodeURIComponent(snapshotCaptureMatch[1]);
+                const scopeInput = resolveRequestScope(config.scope, req, query);
+                const scopeKey = scopeKeyFor(scopeInput);
+                const snapshot = readSnapshot(`${scopeKey}:${sessionId}`);
+                if (!snapshot) {
+                    writeError(res, 404, 'Snapshot not found');
+                    return;
+                }
+                const { scopeKey: _scopeKey, ...publicSnapshot } = snapshot;
+                writeJson(res, 200, { snapshot: { ...publicSnapshot, sessionId } });
+                return;
+            }
+            // POST /v1/sessions/:sessionId/refresh — re-capture and replace
+            const snapshotRefreshMatch = path.match(/^\/v1\/sessions\/([^/]+)\/refresh$/);
+            if (snapshotRefreshMatch && req.method === 'POST') {
+                const body = await readBody(req, bodyLimitBytes);
+                const sessionId = decodeURIComponent(snapshotRefreshMatch[1]);
+                const scopeInput = resolveRequestScope(config.scope, req, query, body);
+                const requestManager = getSessionManager(scopeInput, sessionId);
+                const scopeKey = scopeKeyFor(scopeInput);
+                const relevanceQuery = typeof body.relevanceQuery === 'string' ? body.relevanceQuery : undefined;
+                const snapshotData = await requestManager.captureSnapshot(relevanceQuery);
+                const snapshot = {
+                    scopeKey,
+                    snapshotId: `snap-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`,
+                    bootstrap: snapshotData.bootstrap,
+                    context: snapshotData.context,
+                    frozenAt: snapshotData.frozenAt,
+                    watermarkEventId: snapshotData.watermarkEventId,
+                };
+                touchSnapshot(`${scopeKey}:${sessionId}`, snapshot);
+                const { scopeKey: _scopeKey, ...publicSnapshot } = snapshot;
+                writeJson(res, 200, { snapshot: { ...publicSnapshot, sessionId } });
+                return;
+            }
             writeError(res, 404, `Not found: ${req.method} ${path}`);
         }
         catch (error) {
@@ -657,7 +1569,12 @@ export async function startHttpServer(config = {}) {
                 writeError(res, error.status, error.message);
                 return;
             }
-            writeError(res, 500, error instanceof Error ? error.message : String(error));
+            if (isMemoryDomainError(error)) {
+                writeError(res, error.status, error.message);
+                return;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            writeError(res, 500, message);
         }
     });
     return new Promise((resolve) => {
@@ -670,11 +1587,12 @@ export async function startHttpServer(config = {}) {
                         client.response.end();
                     }
                     sseClients.clear();
-                    server.close();
-                    for (const cachedManager of managers.values()) {
-                        await cachedManager.close();
-                    }
+                    await new Promise((resolveClose) => {
+                        server.close(() => resolveClose());
+                    });
                     managers.clear();
+                    sessionManagers.clear();
+                    sessionSnapshots.clear();
                     await adapterResources.close();
                 },
             });