limen-ai 1.0.0

package/dist/working-memory/stores/wmp_stores.js

@@ -0,0 +1,754 @@
+/**
+ * WMP (Working Memory Protocol) stores — SQLite-backed implementation.
+ * Pattern P-010: All business logic lives here. Harness is thin wiring only.
+ *
+ * Phase: v3.3.0 — Working Memory Protocol
+ * Invariants: WMP-I1 through WMP-I8 (I-41 through I-48)
+ * System calls: SC-14 (write), SC-15 (read), SC-16 (discard)
+ * Boundary snapshots: §6.2-§6.7 (4 triggers + suspension)
+ */
+import { randomUUID } from 'node:crypto';
+import { WMP_KEY_MAX_LENGTH, WMP_KEY_RESERVED_PREFIX, WMP_KEY_FORBIDDEN_PATTERN, WMP_EVENTS, WMP_NULL_EVENT_SINK, } from '../interfaces/wmp_types.js';
+// ============================================================================
+// NotImplementedError — kept for backward compatibility
+// ============================================================================
+export class NotImplementedError extends Error {
+    code = 'NOT_IMPLEMENTED';
+    constructor(method) {
+        super(`${method} is not yet implemented`);
+        this.name = 'NotImplementedError';
+    }
+}
+// ============================================================================
+// File-local helpers
+// ============================================================================
+function ok(value) {
+    return { ok: true, value };
+}
+function err(code, message, spec) {
+    return { ok: false, error: { code, message, spec } };
+}
+function errWithExtras(code, message, spec, extras) {
+    const error = { code, message, spec, ...extras };
+    return { ok: false, error: error };
+}
+function newId() {
+    return randomUUID();
+}
+// Monotonic timestamp: guarantees strictly increasing values even within same millisecond.
+// Required for P2 eviction ordering (DC-WMP-801) — updatedAt must differ on rapid writes.
+// Hard Stop #7: uses injectable TimeProvider as the clock source.
+let _lastTimestamp = '';
+function monotonicNowISO(time) {
+    let ts = time.nowISO();
+    if (ts <= _lastTimestamp) {
+        const d = new Date(_lastTimestamp);
+        d.setTime(d.getTime() + 1);
+        ts = d.toISOString();
+    }
+    _lastTimestamp = ts;
+    return ts;
+}
+function utf8ByteLength(str) {
+    return Buffer.byteLength(str, 'utf8');
+}
+function validateKey(key) {
+    if (!key || key.length === 0)
+        return { valid: false, reason: 'Key must not be empty' };
+    if (key.length > WMP_KEY_MAX_LENGTH)
+        return { valid: false, reason: `Key exceeds ${WMP_KEY_MAX_LENGTH} characters` };
+    if (WMP_KEY_FORBIDDEN_PATTERN.test(key))
+        return { valid: false, reason: 'Key contains forbidden characters (whitespace or path separators)' };
+    if (key.startsWith(WMP_KEY_RESERVED_PREFIX))
+        return { valid: false, reason: `Key must not begin with reserved prefix '${WMP_KEY_RESERVED_PREFIX}'` };
+    return { valid: true };
+}
+const TERMINAL_STATES = new Set(['COMPLETED', 'FAILED', 'CANCELLED']);
+const EXECUTABLE_STATES = new Set(['RUNNING']);
+function lookupTask(conn, taskId) {
+    return conn.get('SELECT id, state, assigned_agent FROM core_tasks WHERE id = ?', [taskId]);
+}
+// Module-level connection reference for WmpInternalReader (no conn param in interface).
+// Set by every SC handler call. WmpInternalReader uses this to read entries.
+let _connRef = null;
+// ============================================================================
+// Entry Store Implementation
+// ============================================================================
+export function createEntryStore(time) {
+    const clock = time ?? { nowISO: () => new Date().toISOString(), nowMs: () => Date.now() };
+    return Object.freeze({
+        upsert(conn, taskId, key, value, sizeBytes) {
+            const now = monotonicNowISO(clock);
+            const existing = conn.get('SELECT key, value, size_bytes, mutation_position, created_at, updated_at FROM working_memory_entries WHERE task_id = ? AND key = ?', [taskId, key]);
+            // Get next mutation position
+            conn.run('INSERT INTO wmp_mutation_counters (task_id, counter) VALUES (?, 1) ON CONFLICT(task_id) DO UPDATE SET counter = counter + 1', [taskId]);
+            const counterRow = conn.get('SELECT counter FROM wmp_mutation_counters WHERE task_id = ?', [taskId]);
+            const mutationPosition = counterRow.counter;
+            if (existing) {
+                conn.run('UPDATE working_memory_entries SET value = ?, size_bytes = ?, mutation_position = ?, updated_at = ? WHERE task_id = ? AND key = ?', [value, sizeBytes, mutationPosition, now, taskId, key]);
+                return ok({
+                    key,
+                    value,
+                    sizeBytes,
+                    createdAt: existing.created_at,
+                    updatedAt: now,
+                    mutationPosition,
+                });
+            }
+            conn.run('INSERT INTO working_memory_entries (task_id, key, value, size_bytes, mutation_position, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)', [taskId, key, value, sizeBytes, mutationPosition, now, now]);
+            return ok({
+                key,
+                value,
+                sizeBytes,
+                createdAt: now,
+                updatedAt: now,
+                mutationPosition,
+            });
+        },
+        get(conn, taskId, key) {
+            const row = conn.get('SELECT key, value, size_bytes, mutation_position, created_at, updated_at FROM working_memory_entries WHERE task_id = ? AND key = ?', [taskId, key]);
+            if (!row) {
+                return err('WORKING_MEMORY_NOT_FOUND', `Key '${key}' not found in task ${taskId}`, '§5.3');
+            }
+            return ok({
+                key: row.key,
+                value: row.value,
+                sizeBytes: row.size_bytes,
+                createdAt: row.created_at,
+                updatedAt: row.updated_at,
+                mutationPosition: row.mutation_position,
+            });
+        },
+        listAll(conn, taskId) {
+            const rows = conn.query('SELECT key, value, size_bytes, mutation_position, created_at, updated_at FROM working_memory_entries WHERE task_id = ? ORDER BY mutation_position ASC', [taskId]);
+            return ok(rows.map(r => ({
+                key: r.key,
+                value: r.value,
+                sizeBytes: r.size_bytes,
+                createdAt: r.created_at,
+                updatedAt: r.updated_at,
+                mutationPosition: r.mutation_position,
+            })));
+        },
+        discard(conn, taskId, key) {
+            const existing = conn.get('SELECT size_bytes FROM working_memory_entries WHERE task_id = ? AND key = ?', [taskId, key]);
+            if (!existing) {
+                return err('WORKING_MEMORY_NOT_FOUND', `Key '${key}' not found in task ${taskId}`, '§5.4');
+            }
+            conn.run('DELETE FROM working_memory_entries WHERE task_id = ? AND key = ?', [taskId, key]);
+            return ok({ freedBytes: existing.size_bytes });
+        },
+        discardAll(conn, taskId) {
+            const usage = conn.get('SELECT COUNT(*) as cnt, COALESCE(SUM(size_bytes), 0) as total FROM working_memory_entries WHERE task_id = ?', [taskId]);
+            conn.run('DELETE FROM working_memory_entries WHERE task_id = ?', [taskId]);
+            return ok({
+                discardedCount: usage?.cnt ?? 0,
+                freedBytes: usage?.total ?? 0,
+            });
+        },
+        getUsage(conn, taskId) {
+            const row = conn.get('SELECT COUNT(*) as cnt, COALESCE(SUM(size_bytes), 0) as total FROM working_memory_entries WHERE task_id = ?', [taskId]);
+            return ok({
+                entryCount: row?.cnt ?? 0,
+                totalBytes: row?.total ?? 0,
+            });
+        },
+        isInitialized(conn, taskId) {
+            const row = conn.get('SELECT counter FROM wmp_mutation_counters WHERE task_id = ?', [taskId]);
+            return ok(row !== undefined);
+        },
+        getNamespaceState(conn, taskId) {
+            const counterRow = conn.get('SELECT counter FROM wmp_mutation_counters WHERE task_id = ?', [taskId]);
+            if (!counterRow)
+                return ok('never_initialized');
+            const entryCount = conn.get('SELECT COUNT(*) as cnt FROM working_memory_entries WHERE task_id = ?', [taskId]);
+            if ((entryCount?.cnt ?? 0) > 0)
+                return ok('initialized_with_entries');
+            return ok('initialized_empty');
+        },
+    });
+}
+// ============================================================================
+// Boundary Store Implementation
+// ============================================================================
+export function createBoundaryStore(time) {
+    const clock = time ?? { nowISO: () => new Date().toISOString(), nowMs: () => Date.now() };
+    return Object.freeze({
+        createBoundaryEvent(conn, event) {
+            const eventId = newId();
+            const timestamp = event.timestamp || monotonicNowISO(clock);
+            conn.run('INSERT INTO wmp_boundary_events (event_id, task_id, mission_id, trigger, snapshot_content_id, linked_emission_id, timestamp) VALUES (?, ?, ?, ?, ?, ?, ?)', [eventId, event.taskId, event.missionId, event.trigger, event.snapshotContentId, event.linkedEmissionId ?? null, timestamp]);
+            return ok({
+                eventId,
+                taskId: event.taskId,
+                missionId: event.missionId,
+                trigger: event.trigger,
+                snapshotContentId: event.snapshotContentId,
+                linkedEmissionId: event.linkedEmissionId,
+                timestamp,
+            });
+        },
+        createSnapshotContent(conn, content) {
+            const contentId = newId();
+            const entriesJson = content.entries ? JSON.stringify(content.entries) : null;
+            conn.run('INSERT INTO wmp_snapshot_contents (content_id, task_id, namespace_state, entries_json, total_entries, total_size_bytes, highest_mutation_position) VALUES (?, ?, ?, ?, ?, ?, ?)', [contentId, content.taskId ?? '', content.namespaceState, entriesJson, content.totalEntries, content.totalSizeBytes, content.highestMutationPosition ?? null]);
+            return ok({
+                contentId,
+                namespaceState: content.namespaceState,
+                entries: content.entries,
+                totalEntries: content.totalEntries,
+                totalSizeBytes: content.totalSizeBytes,
+                highestMutationPosition: content.highestMutationPosition,
+            });
+        },
+        findMatchingContent(conn, taskId, namespaceState, highestMutationPosition) {
+            let row;
+            if (highestMutationPosition === null) {
+                row = conn.get('SELECT content_id, namespace_state, entries_json, total_entries, total_size_bytes, highest_mutation_position FROM wmp_snapshot_contents WHERE task_id = ? AND namespace_state = ? AND highest_mutation_position IS NULL', [taskId, namespaceState]);
+            }
+            else {
+                row = conn.get('SELECT content_id, namespace_state, entries_json, total_entries, total_size_bytes, highest_mutation_position FROM wmp_snapshot_contents WHERE task_id = ? AND namespace_state = ? AND highest_mutation_position = ?', [taskId, namespaceState, highestMutationPosition]);
+            }
+            if (!row)
+                return ok(null);
+            return ok({
+                contentId: row.content_id,
+                namespaceState: row.namespace_state,
+                entries: row.entries_json ? JSON.parse(row.entries_json) : null,
+                totalEntries: row.total_entries,
+                totalSizeBytes: row.total_size_bytes,
+                highestMutationPosition: row.highest_mutation_position,
+            });
+        },
+        getBoundaryEvent(conn, eventId) {
+            const row = conn.get('SELECT event_id, task_id, mission_id, trigger, snapshot_content_id, linked_emission_id, timestamp FROM wmp_boundary_events WHERE event_id = ?', [eventId]);
+            if (!row)
+                return err('NOT_FOUND', `Boundary event ${eventId} not found`, '§6.2');
+            return ok({
+                eventId: row.event_id,
+                taskId: row.task_id,
+                missionId: row.mission_id,
+                trigger: row.trigger,
+                snapshotContentId: row.snapshot_content_id,
+                linkedEmissionId: row.linked_emission_id,
+                timestamp: row.timestamp,
+            });
+        },
+        getSnapshotContent(conn, contentId) {
+            const row = conn.get('SELECT content_id, namespace_state, entries_json, total_entries, total_size_bytes, highest_mutation_position FROM wmp_snapshot_contents WHERE content_id = ?', [contentId]);
+            if (!row)
+                return err('NOT_FOUND', `Snapshot content ${contentId} not found`, '§6.2');
+            return ok({
+                contentId: row.content_id,
+                namespaceState: row.namespace_state,
+                entries: row.entries_json ? JSON.parse(row.entries_json) : null,
+                totalEntries: row.total_entries,
+                totalSizeBytes: row.total_size_bytes,
+                highestMutationPosition: row.highest_mutation_position,
+            });
+        },
+        listBoundaryEvents(conn, taskId) {
+            const rows = conn.query('SELECT event_id, task_id, mission_id, trigger, snapshot_content_id, linked_emission_id, timestamp FROM wmp_boundary_events WHERE task_id = ? ORDER BY timestamp ASC', [taskId]);
+            return ok(rows.map(r => ({
+                eventId: r.event_id,
+                taskId: r.task_id,
+                missionId: r.mission_id,
+                trigger: r.trigger,
+                snapshotContentId: r.snapshot_content_id,
+                linkedEmissionId: r.linked_emission_id,
+                timestamp: r.timestamp,
+            })));
+        },
+    });
+}
+// ============================================================================
+// Mutation Counter Implementation
+// ============================================================================
+export function createMutationCounter() {
+    return Object.freeze({
+        next(conn, taskId) {
+            conn.run('INSERT INTO wmp_mutation_counters (task_id, counter) VALUES (?, 1) ON CONFLICT(task_id) DO UPDATE SET counter = counter + 1', [taskId]);
+            const row = conn.get('SELECT counter FROM wmp_mutation_counters WHERE task_id = ?', [taskId]);
+            return ok(row.counter);
+        },
+        current(conn, taskId) {
+            const row = conn.get('SELECT counter FROM wmp_mutation_counters WHERE task_id = ?', [taskId]);
+            return ok(row?.counter ?? null);
+        },
+    });
+}
+// ============================================================================
+// Boundary Capture Coordinator Implementation
+// ============================================================================
+export function createBoundaryCaptureCoordinator(entryStore, boundaryStore, mutationCounter, eventSink = WMP_NULL_EVENT_SINK, time) {
+    const clock = time ?? { nowISO: () => new Date().toISOString(), nowMs: () => Date.now() };
+    function captureSnapshot(conn, taskId) {
+        const nsResult = entryStore.getNamespaceState(conn, taskId);
+        if (!nsResult.ok)
+            return nsResult;
+        const namespaceState = nsResult.value;
+        const counterResult = mutationCounter.current(conn, taskId);
+        if (!counterResult.ok)
+            return counterResult;
+        const highestMutationPosition = counterResult.value;
+        // Attempt deduplication
+        const existingResult = boundaryStore.findMatchingContent(conn, taskId, namespaceState, highestMutationPosition);
+        if (existingResult.ok && existingResult.value) {
+            return ok(existingResult.value);
+        }
+        let entries = null;
+        let totalEntries = 0;
+        let totalSizeBytes = 0;
+        if (namespaceState === 'never_initialized') {
+            entries = null;
+        }
+        else if (namespaceState === 'initialized_empty') {
+            entries = [];
+        }
+        else {
+            const listResult = entryStore.listAll(conn, taskId);
+            if (!listResult.ok)
+                return listResult;
+            entries = listResult.value.map(e => ({
+                key: e.key,
+                value: e.value,
+                sizeBytes: e.sizeBytes,
+                createdAt: e.createdAt,
+                updatedAt: e.updatedAt,
+                mutationPosition: e.mutationPosition,
+            }));
+            totalEntries = entries.length;
+            totalSizeBytes = entries.reduce((sum, e) => sum + e.sizeBytes, 0);
+        }
+        // Store taskId in snapshot content for dedup queries
+        const contentInput = {
+            taskId,
+            namespaceState,
+            entries,
+            totalEntries,
+            totalSizeBytes,
+            highestMutationPosition,
+        };
+        return boundaryStore.createSnapshotContent(conn, contentInput);
+    }
+    function createEvent(conn, taskId, missionId, trigger, linkedEmissionId) {
+        const snapshotResult = captureSnapshot(conn, taskId);
+        if (!snapshotResult.ok) {
+            // Emit boundary capture failure event (FM-WMP-02)
+            try {
+                eventSink.emit(WMP_EVENTS.BOUNDARY_CAPTURE_FAILED, taskId, {
+                    trigger,
+                    missionId,
+                    reason: snapshotResult.error.message,
+                    code: snapshotResult.error.code,
+                });
+            }
+            catch { /* event emission failure is non-fatal per I-48 */ }
+            return snapshotResult;
+        }
+        const snapshot = snapshotResult.value;
+        const eventResult = boundaryStore.createBoundaryEvent(conn, {
+            taskId,
+            missionId,
+            trigger,
+            snapshotContentId: snapshot.contentId,
+            linkedEmissionId,
+            timestamp: monotonicNowISO(clock),
+        });
+        if (eventResult.ok) {
+            // Emit boundary captured event (§6.2)
+            try {
+                eventSink.emit(WMP_EVENTS.BOUNDARY_CAPTURED, taskId, {
+                    trigger,
+                    missionId,
+                    eventId: eventResult.value.eventId,
+                    snapshotContentId: snapshot.contentId,
+                    entryCount: snapshot.totalEntries,
+                });
+            }
+            catch { /* event emission failure is non-fatal per I-48 */ }
+        }
+        else {
+            // Emit boundary capture failure event (FM-WMP-02)
+            try {
+                eventSink.emit(WMP_EVENTS.BOUNDARY_CAPTURE_FAILED, taskId, {
+                    trigger,
+                    missionId,
+                    reason: eventResult.error.message,
+                    code: eventResult.error.code,
+                });
+            }
+            catch { /* event emission failure is non-fatal per I-48 */ }
+        }
+        return eventResult;
+    }
+    return Object.freeze({
+        captureAtCheckpoint(conn, taskId, missionId) {
+            return createEvent(conn, taskId, missionId, 'checkpoint', null);
+        },
+        captureAtTerminal(conn, taskId, missionId, terminalState) {
+            return conn.transaction(() => {
+                // 1. Capture snapshot (pre-discard state) — WMP-I7 atomicity
+                const eventResult = createEvent(conn, taskId, missionId, 'task_terminal', null);
+                if (!eventResult.ok)
+                    return eventResult;
+                // 2. Physical reclamation — delete all entries (AL-WMP-07, DC-WMP-209)
+                const discardResult = entryStore.discardAll(conn, taskId);
+                // 3. Emit terminal discard event (§6.4 Trigger 2)
+                try {
+                    const discarded = discardResult.ok ? discardResult.value : { discardedCount: 0, freedBytes: 0 };
+                    eventSink.emit(WMP_EVENTS.TERMINAL_DISCARD, taskId, {
+                        missionId,
+                        terminalState,
+                        discardedCount: discarded.discardedCount,
+                        freedBytes: discarded.freedBytes,
+                    });
+                }
+                catch { /* event emission failure is non-fatal per I-48 */ }
+                // 4. Terminal state transition — update core_tasks
+                // F-WMP-BB-01: Use actual terminal state, never hard-code 'COMPLETED'
+                const now = monotonicNowISO(clock);
+                conn.run('UPDATE core_tasks SET state = ?, completed_at = ?, updated_at = ? WHERE id = ?', [terminalState, now, now, taskId]);
+                return eventResult;
+            });
+        },
+        captureAtMissionTransition(conn, taskId, missionId) {
+            return createEvent(conn, taskId, missionId, 'mission_transition', null);
+        },
+        capturePreEmission(conn, taskId, missionId, emissionId) {
+            return createEvent(conn, taskId, missionId, 'pre_irreversible_emission', emissionId);
+        },
+        captureAtSuspension(conn, taskId, missionId) {
+            return createEvent(conn, taskId, missionId, 'suspension', null);
+        },
+    });
+}
+// ============================================================================
+// SC-14 Write Handler Implementation
+// ============================================================================
+export function createWriteHandler(entryStore, _mutationCounter, capacityPolicy, eventSink = WMP_NULL_EVENT_SINK) {
+    return Object.freeze({
+        execute(conn, callerTaskId, callerAgentId, input) {
+            _connRef = conn;
+            // 1. Scope check: callerTaskId must match input.taskId
+            if (callerTaskId !== input.taskId) {
+                return err('TASK_SCOPE_VIOLATION', 'Caller task does not match target task', 'WMP-I1');
+            }
+            // 2. Task existence and state check
+            const task = lookupTask(conn, input.taskId);
+            if (!task)
+                return err('TASK_NOT_FOUND', `Task ${input.taskId} not found`, '§5.2');
+            if (TERMINAL_STATES.has(task.state)) {
+                return err('TASK_TERMINATED', `Task ${input.taskId} has reached terminal state`, '§5.2');
+            }
+            if (!EXECUTABLE_STATES.has(task.state)) {
+                return err('TASK_NOT_EXECUTABLE', `Task ${input.taskId} is not in an executable state`, '§5.2');
+            }
+            // 2b. WMP-internal suspension check (DC-WMP-212)
+            const suspendedRow = conn.get('SELECT suspended FROM wmp_mutation_counters WHERE task_id = ?', [input.taskId]);
+            if (suspendedRow && suspendedRow.suspended === 1) {
+                return err('TASK_NOT_EXECUTABLE', `Task ${input.taskId} is suspended`, 'DC-WMP-212');
+            }
+            // 3. Agent authorization check
+            if (callerAgentId !== task.assigned_agent) {
+                return err('UNAUTHORIZED', `Agent ${callerAgentId} is not authorized for task ${input.taskId}`, 'I-13');
+            }
+            // 4. Key validation (I-46)
+            const keyValidation = validateKey(input.key);
+            if (!keyValidation.valid) {
+                return err('WORKING_MEMORY_KEY_INVALID', keyValidation.reason, '§5.2');
+            }
+            // 4b. Value validation (DC-WMP-111, F-WMP-BB-04)
+            if (input.value.includes('\0')) {
+                return err('WORKING_MEMORY_VALUE_INVALID', 'Value contains null bytes', '§5.2');
+            }
+            // 5. Compute byte size
+            const sizeBytes = utf8ByteLength(input.value);
+            // 6. Per-entry byte limit check
+            if (sizeBytes > capacityPolicy.maxBytesPerEntry) {
+                return err('WORKING_MEMORY_CAPACITY_EXCEEDED', `Value size ${sizeBytes} exceeds per-entry limit ${capacityPolicy.maxBytesPerEntry}`, '§8.1');
+            }
+            // 7. Capacity check (entry count and total bytes)
+            const usageResult = entryStore.getUsage(conn, input.taskId);
+            if (!usageResult.ok)
+                return usageResult;
+            const usage = usageResult.value;
+            // Check if this is a replacement (existing key)
+            const existingEntry = conn.get('SELECT size_bytes FROM working_memory_entries WHERE task_id = ? AND key = ?', [input.taskId, input.key]);
+            const isReplacement = !!existingEntry;
+            const effectiveEntryCount = isReplacement ? usage.entryCount : usage.entryCount + 1;
+            const effectiveTotalBytes = isReplacement
+                ? usage.totalBytes - existingEntry.size_bytes + sizeBytes
+                : usage.totalBytes + sizeBytes;
+            if (effectiveEntryCount > capacityPolicy.maxEntries) {
+                return errWithExtras('WORKING_MEMORY_CAPACITY_EXCEEDED', `Entry count ${effectiveEntryCount} would exceed limit ${capacityPolicy.maxEntries}`, '§8.1', { currentEntryCount: usage.entryCount, maxEntryCount: capacityPolicy.maxEntries });
+            }
+            if (effectiveTotalBytes > capacityPolicy.maxTotalBytes) {
+                return errWithExtras('WORKING_MEMORY_CAPACITY_EXCEEDED', `Total bytes ${effectiveTotalBytes} would exceed limit ${capacityPolicy.maxTotalBytes}`, '§8.1', { currentEntryCount: usage.entryCount, maxEntryCount: capacityPolicy.maxEntries, currentSizeBytes: usage.totalBytes, maxSizeBytes: capacityPolicy.maxTotalBytes, requestedSizeBytes: sizeBytes });
+            }
+            // 8. Upsert the entry (includes mutation counter increment)
+            const upsertResult = entryStore.upsert(conn, input.taskId, input.key, input.value, sizeBytes);
+            if (!upsertResult.ok)
+                return upsertResult;
+            const entry = upsertResult.value;
+            // 9. Emit event (DC-WMP-X15, Binding 14 — transaction-coupled)
+            // Per I-48: trace failures do not roll back the write
+            try {
+                eventSink.emit(WMP_EVENTS.ENTRY_WRITTEN, input.taskId, {
+                    key: entry.key,
+                    sizeBytes: entry.sizeBytes,
+                    created: !isReplacement,
+                    mutationPosition: entry.mutationPosition,
+                });
+            }
+            catch { /* trace emission failure is non-fatal per I-48 */ }
+            // 10. Capacity warning (FM-WMP-03 monitoring) — after successful write
+            // Emit when usage exceeds 80% of either entry count or total byte limit
+            const CAPACITY_WARNING_THRESHOLD = 0.8;
+            if (effectiveEntryCount > capacityPolicy.maxEntries * CAPACITY_WARNING_THRESHOLD ||
+                effectiveTotalBytes > capacityPolicy.maxTotalBytes * CAPACITY_WARNING_THRESHOLD) {
+                try {
+                    eventSink.emit(WMP_EVENTS.CAPACITY_WARNING, input.taskId, {
+                        currentEntryCount: effectiveEntryCount,
+                        maxEntries: capacityPolicy.maxEntries,
+                        currentTotalBytes: effectiveTotalBytes,
+                        maxTotalBytes: capacityPolicy.maxTotalBytes,
+                        entryPct: effectiveEntryCount / capacityPolicy.maxEntries,
+                        bytesPct: effectiveTotalBytes / capacityPolicy.maxTotalBytes,
+                    });
+                }
+                catch { /* event emission failure is non-fatal per I-48 */ }
+            }
+            return ok({
+                key: entry.key,
+                sizeBytes: entry.sizeBytes,
+                created: !isReplacement,
+                mutationPosition: entry.mutationPosition,
+                createdAt: entry.createdAt,
+                updatedAt: entry.updatedAt,
+            });
+        },
+    });
+}
+// ============================================================================
+// SC-15 Read Handler Implementation
+// ============================================================================
+export function createReadHandler(entryStore) {
+    return Object.freeze({
+        execute(conn, callerTaskId, callerAgentId, input) {
+            _connRef = conn;
+            // 1. Scope check
+            if (callerTaskId !== input.taskId) {
+                return err('TASK_SCOPE_VIOLATION', 'Caller task does not match target task', 'WMP-I1');
+            }
+            // 2. Task existence and state check
+            const task = lookupTask(conn, input.taskId);
+            if (!task)
+                return err('TASK_NOT_FOUND', `Task ${input.taskId} not found`, '§5.3');
+            if (TERMINAL_STATES.has(task.state)) {
+                return err('TASK_TERMINATED', `Task ${input.taskId} has reached terminal state`, '§5.3');
+            }
+            // SC-15 intentionally omits TASK_NOT_EXECUTABLE — reads are always safe (AMB-WMP-05)
+            // 3. Agent authorization check
+            if (callerAgentId !== task.assigned_agent) {
+                return err('UNAUTHORIZED', `Agent ${callerAgentId} is not authorized for task ${input.taskId}`, 'I-13');
+            }
+            // 4. Read entry or list all
+            if (input.key !== null) {
+                // Specific key read
+                const entryResult = entryStore.get(conn, input.taskId, input.key);
+                if (!entryResult.ok)
+                    return entryResult;
+                const e = entryResult.value;
+                return ok({
+                    key: e.key,
+                    value: e.value,
+                    sizeBytes: e.sizeBytes,
+                    createdAt: e.createdAt,
+                    updatedAt: e.updatedAt,
+                });
+            }
+            // List all entries
+            const listResult = entryStore.listAll(conn, input.taskId);
+            if (!listResult.ok)
+                return listResult;
+            const entries = listResult.value;
+            const totalSizeBytes = entries.reduce((sum, e) => sum + e.sizeBytes, 0);
+            return ok({
+                entries: entries.map(e => ({
+                    key: e.key,
+                    value: e.value,
+                    sizeBytes: e.sizeBytes,
+                    createdAt: e.createdAt,
+                    updatedAt: e.updatedAt,
+                })),
+                totalEntries: entries.length,
+                totalSizeBytes,
+            });
+        },
+    });
+}
+// ============================================================================
+// SC-16 Discard Handler Implementation
+// ============================================================================
+export function createDiscardHandler(entryStore, mutationCounter, eventSink = WMP_NULL_EVENT_SINK) {
+    return Object.freeze({
+        execute(conn, callerTaskId, callerAgentId, input) {
+            _connRef = conn;
+            // 1. Scope check
+            if (callerTaskId !== input.taskId) {
+                return err('TASK_SCOPE_VIOLATION', 'Caller task does not match target task', 'WMP-I1');
+            }
+            // 2. Task existence and state check
+            const task = lookupTask(conn, input.taskId);
+            if (!task)
+                return err('TASK_NOT_FOUND', `Task ${input.taskId} not found`, '§5.4');
+            if (TERMINAL_STATES.has(task.state)) {
+                return err('TASK_TERMINATED', `Task ${input.taskId} has reached terminal state`, '§5.4');
+            }
+            if (!EXECUTABLE_STATES.has(task.state)) {
+                return err('TASK_NOT_EXECUTABLE', `Task ${input.taskId} is not in an executable state`, '§5.4');
+            }
+            // 2b. WMP-internal suspension check (DC-WMP-212)
+            const suspendedRow = conn.get('SELECT suspended FROM wmp_mutation_counters WHERE task_id = ?', [input.taskId]);
+            if (suspendedRow && suspendedRow.suspended === 1) {
+                return err('TASK_NOT_EXECUTABLE', `Task ${input.taskId} is suspended`, 'DC-WMP-212');
+            }
+            // 3. Agent authorization check
+            if (callerAgentId !== task.assigned_agent) {
+                return err('UNAUTHORIZED', `Agent ${callerAgentId} is not authorized for task ${input.taskId}`, 'I-13');
+            }
+            // 5. Discard
+            if (input.key !== null) {
+                // Specific key discard — advance counter AFTER success (WMP-I5: failed ops get no position, BPB-001)
+                const discardResult = entryStore.discard(conn, input.taskId, input.key);
+                if (!discardResult.ok)
+                    return discardResult;
+                // 4a. Advance mutation counter only after single-key discard succeeds
+                const counterResult = mutationCounter.next(conn, input.taskId);
+                if (!counterResult.ok)
+                    return counterResult;
+                const mutationPosition = counterResult.value;
+                // 6. Emit event (DC-WMP-X15, Binding 14 — transaction-coupled)
+                try {
+                    eventSink.emit(WMP_EVENTS.ENTRY_DISCARDED, input.taskId, {
+                        key: input.key,
+                        freedBytes: discardResult.value.freedBytes,
+                        mutationPosition,
+                    });
+                }
+                catch { /* trace emission failure is non-fatal per I-48 */ }
+                return ok({
+                    discardedCount: 1,
+                    freedBytes: discardResult.value.freedBytes,
+                    mutationPosition,
+                });
+            }
+            // Discard all — advance counter BEFORE discard (AMB-WMP-06: always a visible mutation)
+            const counterResult = mutationCounter.next(conn, input.taskId);
+            if (!counterResult.ok)
+                return counterResult;
+            const mutationPosition = counterResult.value;
+            const discardAllResult = entryStore.discardAll(conn, input.taskId);
+            if (!discardAllResult.ok)
+                return discardAllResult;
+            // Emit event for discard-all (DC-WMP-X15)
+            try {
+                eventSink.emit(WMP_EVENTS.ENTRY_DISCARDED, input.taskId, {
+                    key: null,
+                    freedBytes: discardAllResult.value.freedBytes,
+                    discardedCount: discardAllResult.value.discardedCount,
+                    mutationPosition,
+                });
+            }
+            catch { /* trace emission failure is non-fatal per I-48 */ }
+            return ok({
+                discardedCount: discardAllResult.value.discardedCount,
+                freedBytes: discardAllResult.value.freedBytes,
+                mutationPosition,
+            });
+        },
+    });
+}
+// ============================================================================
+// Task Lifecycle Handler Implementation
+// ============================================================================
+export function createTaskLifecycleHandler(coordinator, entryStore) {
+    return Object.freeze({
+        onTaskTerminal(conn, taskId, missionId, terminalState) {
+            return coordinator.captureAtTerminal(conn, taskId, missionId, terminalState);
+        },
+        onTaskSuspended(conn, taskId, missionId) {
+            // 1. Set suspension flag
+            conn.run('INSERT INTO wmp_mutation_counters (task_id, counter, suspended) VALUES (?, 0, 1) ON CONFLICT(task_id) DO UPDATE SET suspended = 1', [taskId]);
+            // 2. Capture boundary snapshot at suspension (DC-WMP-213)
+            return coordinator.captureAtSuspension(conn, taskId, missionId);
+        },
+        onTaskResumed(conn, taskId, _missionId) {
+            // 1. Clear suspension flag
+            conn.run('UPDATE wmp_mutation_counters SET suspended = 0 WHERE task_id = ?', [taskId]);
+            // 2. Verify namespace integrity (DC-WMP-214)
+            // Entries survive suspension because writes/discards are rejected during suspension.
+            // Verify by confirming entries are readable.
+            const listResult = entryStore.listAll(conn, taskId);
+            if (!listResult.ok)
+                return listResult;
+            return ok(undefined);
+        },
+    });
+}
+// ============================================================================
+// Internal Reader Implementation (for CGP P2 — WmpInternalReader)
+// ============================================================================
+export function createInternalReader() {
+    return Object.freeze({
+        readLiveEntries(taskId) {
+            const conn = _connRef;
+            if (!conn)
+                return err('NO_CONNECTION', 'No database connection available', '§9.2');
+            const rows = conn.query('SELECT key, value, size_bytes, created_at, updated_at, mutation_position FROM working_memory_entries WHERE task_id = ? ORDER BY mutation_position ASC', [taskId]);
+            return ok(rows.map(r => ({
+                key: r.key,
+                value: r.value,
+                sizeBytes: r.size_bytes,
+                createdAt: r.created_at,
+                updatedAt: r.updated_at,
+                mutationPosition: r.mutation_position,
+            })));
+        },
+    });
+}
+// ============================================================================
+// Pre-Emission Capture Implementation (for CCP — WmpPreEmissionCapture)
+// ============================================================================
+export function createPreEmissionCaptureImpl(entryStore, coordinator) {
+    return Object.freeze({
+        capture(conn, taskId) {
+            // Check if WMP is initialized for this task
+            const initResult = entryStore.isInitialized(conn, taskId);
+            if (!initResult.ok)
+                return initResult;
+            if (!initResult.value) {
+                // Never-initialized — not_applicable (no snapshot needed)
+                return ok({ captureId: null, sourcingStatus: 'not_applicable' });
+            }
+            // Initialized — capture pre-emission snapshot
+            // Look up the mission_id from core_tasks
+            const taskRow = conn.get('SELECT mission_id FROM core_tasks WHERE id = ?', [taskId]);
+            if (!taskRow) {
+                // Debt 2: Missing task row means identity cannot be established — do not fabricate empty missionId
+                return { ok: false, error: { code: 'NOT_FOUND', message: `Task ${taskId} not found in core_tasks — cannot determine mission for WMP capture`, spec: 'S7' } };
+            }
+            const actualMissionId = taskRow.mission_id;
+            const emissionId = newId();
+            const captureResult = coordinator.capturePreEmission(conn, taskId, actualMissionId, emissionId);
+            if (!captureResult.ok)
+                return captureResult;
+            return ok({
+                captureId: captureResult.value.eventId,
+                sourcingStatus: 'not_verified',
+            });
+        },
+    });
+}
+//# sourceMappingURL=wmp_stores.js.map