cogmem 3.7.1 → 3.7.3

package/dist/mcp/CoreMcpTools.js

@@ -16,6 +16,11 @@ const EPISODE_MESSAGE_SCHEMA = {
         text: STRING_SCHEMA,
         externalMessageId: STRING_SCHEMA,
         timestamp: NUMBER_SCHEMA,
+        threadId: STRING_SCHEMA,
+        turnId: STRING_SCHEMA,
+        turnSeq: NUMBER_SCHEMA,
+        localDate: STRING_SCHEMA,
+        eventOrdinal: NUMBER_SCHEMA,
     },
     required: ['role', 'text'],
 };
@@ -118,6 +123,7 @@ export function listCogmemMcpTools() {
                     projectId: STRING_SCHEMA, sessionId: STRING_SCHEMA, sourceAgent: STRING_SCHEMA,
                     role: { type: 'string', enum: ['user', 'assistant', 'agent', 'tool', 'system', 'narrator'] },
                     text: STRING_SCHEMA, externalMessageId: STRING_SCHEMA, timestamp: NUMBER_SCHEMA,
+                    threadId: STRING_SCHEMA, turnId: STRING_SCHEMA, turnSeq: NUMBER_SCHEMA, localDate: STRING_SCHEMA, eventOrdinal: NUMBER_SCHEMA,
                 },
                 required: ['projectId', 'sessionId', 'sourceAgent', 'role', 'text', 'externalMessageId'],
             },
@@ -144,6 +150,42 @@ export function listCogmemMcpTools() {
             inputSchema: { type: 'object', properties: { projectId: STRING_SCHEMA, sessionId: STRING_SCHEMA, limit: NUMBER_SCHEMA } },
             annotations: { title: 'Episode Status', readOnlyHint: true, destructiveHint: false, idempotentHint: true },
         },
+        {
+            name: 'cogmem_episode_audit_boundaries',
+            description: 'Read-only deterministic audit of episode boundary health. Does not write audit rows, repair, split, Dream, Atlas, or activation telemetry.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    projectId: STRING_SCHEMA, episodeId: STRING_SCHEMA, status: STRING_SCHEMA, limit: NUMBER_SCHEMA, cursor: STRING_SCHEMA,
+                    maxEvents: NUMBER_SCHEMA, maxDurationMs: NUMBER_SCHEMA, maxIdleGapMs: NUMBER_SCHEMA, timezone: STRING_SCHEMA,
+                },
+                required: ['projectId'],
+            },
+            annotations: { title: 'Audit Episode Boundaries', readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+        },
+        {
+            name: 'cogmem_episode_boundary_decisions',
+            description: 'Read-only project-scoped trace of episode boundary decisions, including CPU decision, reviewer decision, final decision, guard codes, and warnings.',
+            inputSchema: {
+                type: 'object',
+                properties: { projectId: STRING_SCHEMA, primaryEventId: STRING_SCHEMA, limit: NUMBER_SCHEMA },
+                required: ['projectId'],
+            },
+            annotations: { title: 'Episode Boundary Decisions', readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+        },
+        {
+            name: 'cogmem_episode_split_plan',
+            description: 'Read-only deterministic split preview for a single episode. Never calls repair or returns an apply command.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    projectId: STRING_SCHEMA, episodeId: STRING_SCHEMA, maxEvents: NUMBER_SCHEMA, maxDurationMs: NUMBER_SCHEMA,
+                    maxIdleGapMs: NUMBER_SCHEMA, timezone: STRING_SCHEMA, includeEventIds: { type: 'boolean' },
+                },
+                required: ['projectId', 'episodeId'],
+            },
+            annotations: { title: 'Plan Episode Split', readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+        },
         {
             name: 'cogmem_topic_list',
             description: 'List project-scoped user-shaped topic nodes and audited relations. Read-only.',
@@ -186,8 +228,8 @@ export function listCogmemMcpTools() {
             name: 'cogmem_episode_seal',
             description: 'Explicitly seal one episode and enqueue it for conditional Dream processing.',
             inputSchema: {
-                type: 'object', properties: { episodeId: STRING_SCHEMA, mode: { type: 'string', enum: ['soft', 'hard', 'manual', 'batch'] }, reason: STRING_SCHEMA },
-                required: ['episodeId'],
+                type: 'object', properties: { projectId: STRING_SCHEMA, episodeId: STRING_SCHEMA, mode: { type: 'string', enum: ['soft', 'hard', 'manual', 'batch'] }, reason: STRING_SCHEMA },
+                required: ['projectId', 'episodeId'],
             },
             annotations: { title: 'Seal Episode', readOnlyHint: false, destructiveHint: false, idempotentHint: true },
         },
@@ -330,8 +372,9 @@ export function listCogmemMcpTools() {
 }
 export async function callCogmemMcpTool(name, args, runtime = {}) {
     const input = args || {};
-    const opened = openRuntimeKernel(runtime);
+    let opened;
     try {
+        opened = openRuntimeKernel(runtime);
         switch (name) {
             case 'cogmem_remember_turn':
                 return await rememberTurn(opened.kernel, input);
@@ -354,6 +397,26 @@ export async function callCogmemMcpTool(name, args, runtime = {}) {
                 return await episodeImport(opened.kernel, input);
             case 'cogmem_episode_status':
                 return episodeStatus(opened.kernel, input);
+            case 'cogmem_episode_audit_boundaries':
+                return jsonResult(opened.kernel.auditEpisodeBoundaries({
+                    projectId: requiredString(input.projectId, 'projectId'), episodeId: optionalString(input.episodeId),
+                    status: optionalEpisodeStatus(input.status), limit: optionalNumber(input.limit), cursor: optionalString(input.cursor),
+                    maxEvents: optionalNumber(input.maxEvents), maxDurationMs: optionalNumber(input.maxDurationMs),
+                    maxIdleGapMs: optionalNumber(input.maxIdleGapMs), timezone: optionalString(input.timezone),
+                }));
+            case 'cogmem_episode_boundary_decisions':
+                return jsonResult({ decisions: opened.kernel.listEpisodeBoundaryDecisions({
+                        projectId: requiredString(input.projectId, 'projectId'),
+                        primaryEventId: optionalString(input.primaryEventId),
+                        limit: optionalNumber(input.limit),
+                    }) });
+            case 'cogmem_episode_split_plan':
+                return jsonResult(opened.kernel.planEpisodeSplit({
+                    projectId: requiredString(input.projectId, 'projectId'), episodeId: requiredString(input.episodeId, 'episodeId'),
+                    maxEvents: optionalNumber(input.maxEvents), maxDurationMs: optionalNumber(input.maxDurationMs),
+                    maxIdleGapMs: optionalNumber(input.maxIdleGapMs), timezone: optionalString(input.timezone),
+                    includeEventIds: input.includeEventIds === true,
+                }));
             case 'cogmem_topic_list': {
                 const projectId = requiredString(input.projectId, 'projectId');
                 return jsonResult({ topics: opened.kernel.userTopicPathRegistry.list(projectId), relations: opened.kernel.topicRelationGraph.list(projectId) });
@@ -372,7 +435,7 @@ export async function callCogmemMcpTool(name, args, runtime = {}) {
             case 'cogmem_episode_repair':
                 return jsonResult(episodeRepair(opened.kernel, input));
             case 'cogmem_episode_seal':
-                return jsonResult(opened.kernel.sealEpisode(requiredString(input.episodeId, 'episodeId'), {
+                return jsonResult(sealProjectEpisode(opened.kernel, requiredString(input.projectId, 'projectId'), requiredString(input.episodeId, 'episodeId'), {
                     mode: optionalEpisodeClosureMode(input.mode),
                     reason: optionalString(input.reason) || 'mcp_manual_seal',
                 }));
@@ -449,7 +512,7 @@ export async function callCogmemMcpTool(name, args, runtime = {}) {
         return jsonResult({ error: error instanceof Error ? error.message : String(error) }, true);
     }
     finally {
-        if (opened.shouldClose)
+        if (opened?.shouldClose)
             opened.kernel.close();
     }
 }
@@ -471,6 +534,8 @@ async function episodeAppend(kernel, input) {
         sourceAgent: requiredString(input.sourceAgent, 'sourceAgent'),
         role: requiredEpisodeRole(input.role), text,
         externalMessageId: requiredString(input.externalMessageId, 'externalMessageId'), timestamp: optionalNumber(input.timestamp),
+        threadId: optionalString(input.threadId), turnId: optionalString(input.turnId), turnSeq: optionalNumber(input.turnSeq),
+        localDate: optionalString(input.localDate), eventOrdinal: optionalNumber(input.eventOrdinal),
     }));
 }
 async function episodeImport(kernel, input) {
@@ -499,8 +564,13 @@ async function episodeImport(kernel, input) {
             autoIdentityUsed = true;
         return {
             role, text, timestamp,
+            threadId: optionalString(message.threadId),
+            turnId: optionalString(message.turnId),
+            turnSeq: optionalNumber(message.turnSeq),
+            localDate: optionalString(message.localDate),
+            eventOrdinal: optionalNumber(message.eventOrdinal),
             externalMessageId: suppliedIdentity
-                || stableIdentity({ role, text, timestamp }),
+                || stableIdentity({ role, text, timestamp, sourcePosition: optionalString(message.sourceRange) || optionalString(message.recordId) || index }),
         };
     });
     const results = [];
@@ -590,7 +660,7 @@ function episodeRepair(kernel, input) {
     if (operation === 'reclassify')
         return kernel.repairEpisode({
             operation, projectId, episodeId: requiredString(input.episodeId, 'episodeId'),
-            episodeType: optionalString(input.episodeType), topicPath: optionalString(input.topicPath), importance: optionalNumber(input.importance),
+            episodeType: optionalEpisodeType(input.episodeType), topicPath: optionalString(input.topicPath), importance: optionalNumber(input.importance),
         });
     if (operation === 'requeue-dream' || operation === 'invalidate-dream-run')
         return kernel.repairEpisode({
@@ -598,6 +668,12 @@ function episodeRepair(kernel, input) {
         });
     throw new Error(`invalid episode repair operation: ${operation}`);
 }
+function sealProjectEpisode(kernel, projectId, episodeId, input) {
+    const episode = kernel.getEpisode(episodeId);
+    if (!episode || episode.projectId !== projectId)
+        throw new Error(`episode_project_mismatch:${episodeId}`);
+    return kernel.sealEpisode(episodeId, input);
+}
 function dreamRecommendation(kernel, projectId, requestedMode) {
     const status = kernel.getEpisodeDreamStatus(projectId);
     const backlog = status.pending + status.retryScheduled;
@@ -789,7 +865,26 @@ function optionalProspectiveStatuses(value) {
     return statuses;
 }
 function optionalNumber(value) {
-    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    throw new Error('value must be a finite number');
+}
+function optionalEpisodeType(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    const allowed = new Set(['discussion', 'decision', 'correction', 'preference', 'goal', 'debugging', 'planning', 'prospective', 'general']);
+    if (typeof value !== 'string' || !allowed.has(value))
+        throw new Error('episodeType must be a valid episode type');
+    return value;
+}
+function optionalEpisodeStatus(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    if (value === 'open' || value === 'soft_sealed' || value === 'sealed')
+        return value;
+    throw new Error('status must be open, soft_sealed, or sealed');
 }
 function optionalTurnIngestMode(value) {
     if (value === undefined || value === null || value === '')

package/dist/mcp/server.js

@@ -5,7 +5,7 @@ import { callCogmemMcpTool, listCogmemMcpTools, } from './CoreMcpTools.js';
 export function createCogmemMcpServer(runtime = {}) {
     const server = new Server({
         name: 'cogmem-core',
-        version: '3.7.1',
+        version: '3.7.2',
     }, {
         capabilities: {
             tools: {},

package/dist/migrations/0028_episode_boundary_guardrails.d.ts

@@ -0,0 +1,3 @@
+import type { Migration } from '../types/Migration.js';
+export declare const migration_0028: Migration;
+//# sourceMappingURL=0028_episode_boundary_guardrails.d.ts.map

package/dist/migrations/0028_episode_boundary_guardrails.js

@@ -0,0 +1,47 @@
+export const migration_0028 = {
+    version: '0028',
+    description: 'episode boundary guardrail decision audit',
+    up(db) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS episode_boundary_decisions (
+        decision_id TEXT PRIMARY KEY,
+        project_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        source_agent TEXT,
+        thread_id TEXT,
+        primary_event_id TEXT NOT NULL,
+        previous_episode_id TEXT,
+        resulting_episode_id TEXT,
+        policy_version TEXT NOT NULL,
+        mode TEXT NOT NULL,
+        guard_action TEXT NOT NULL,
+        guard_codes_json TEXT NOT NULL,
+        metrics_json TEXT NOT NULL,
+        cpu_decision_json TEXT NOT NULL,
+        reviewer_invoked INTEGER NOT NULL,
+        reviewer_decision_json TEXT,
+        final_decision_json TEXT NOT NULL,
+        warnings_json TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_id, primary_event_id, policy_version)
+      );
+      CREATE INDEX IF NOT EXISTS idx_episode_boundary_project_created
+        ON episode_boundary_decisions(project_id, created_at);
+      CREATE INDEX IF NOT EXISTS idx_episode_boundary_previous
+        ON episode_boundary_decisions(previous_episode_id);
+      CREATE INDEX IF NOT EXISTS idx_episode_boundary_resulting
+        ON episode_boundary_decisions(resulting_episode_id);
+      CREATE INDEX IF NOT EXISTS idx_episode_boundary_primary
+        ON episode_boundary_decisions(primary_event_id);
+    `);
+    },
+    down(db) {
+        db.exec(`
+      DROP INDEX IF EXISTS idx_episode_boundary_primary;
+      DROP INDEX IF EXISTS idx_episode_boundary_resulting;
+      DROP INDEX IF EXISTS idx_episode_boundary_previous;
+      DROP INDEX IF EXISTS idx_episode_boundary_project_created;
+      DROP TABLE IF EXISTS episode_boundary_decisions;
+    `);
+    },
+};

package/dist/migrations/0029_episode_active_scope_guard.d.ts

@@ -0,0 +1,3 @@
+import type { Migration } from '../types/Migration.js';
+export declare const migration_0029: Migration;
+//# sourceMappingURL=0029_episode_active_scope_guard.d.ts.map

package/dist/migrations/0029_episode_active_scope_guard.js

@@ -0,0 +1,16 @@
+import { sealDuplicateOpenEpisodes } from '../episode/EpisodeActiveScopeGuard.js';
+export const migration_0029 = {
+    version: '0029',
+    description: 'episode active scope uniqueness guard',
+    up(db) {
+        sealDuplicateOpenEpisodes(db);
+        db.exec(`
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_episodes_one_active_scope
+        ON memory_episodes(project_id, session_id, COALESCE(source_agent, ''), COALESCE(conversation_thread_id, ''))
+        WHERE status = 'open';
+    `);
+    },
+    down(db) {
+        db.exec(`DROP INDEX IF EXISTS idx_memory_episodes_one_active_scope;`);
+    },
+};

package/dist/migrations/0030_memory_event_local_date_source.d.ts

@@ -0,0 +1,3 @@
+import type { Migration } from '../types/Migration.js';
+export declare const migration_0030: Migration;
+//# sourceMappingURL=0030_memory_event_local_date_source.d.ts.map

package/dist/migrations/0030_memory_event_local_date_source.js

@@ -0,0 +1,111 @@
+export const migration_0030 = {
+    version: '0030',
+    description: 'memory event local date source provenance',
+    up(db) {
+        if (db.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'memory_events'`).get()) {
+            const columns = new Set(db.prepare(`PRAGMA table_info(memory_events)`).all().map((row) => row.name));
+            if (!columns.has('local_date_source')) {
+                db.exec(`ALTER TABLE memory_events ADD COLUMN local_date_source TEXT NOT NULL DEFAULT 'legacy_unknown';`);
+            }
+            // 0030 is also responsible for recovering provenance that was already
+            // present in the legacy payload before the column existed.
+            const eventColumns = new Set(db.prepare(`PRAGMA table_info(memory_events)`).all().map((row) => row.name));
+            if (eventColumns.has('payload_json')) {
+                db.exec(`
+          UPDATE memory_events
+          SET local_date_source = CASE
+            WHEN json_valid(payload_json) AND json_extract(payload_json, '$.metadata.localDateSource') IN ('event_store_utc_default', 'generated_utc') THEN 'generated_utc'
+            WHEN json_valid(payload_json) AND json_extract(payload_json, '$.metadata.localDateSource') = 'explicit' THEN 'explicit'
+            WHEN local_date_source IN ('explicit', 'generated_utc') THEN local_date_source
+            ELSE 'legacy_unknown'
+          END;
+        `);
+            }
+        }
+        if (db.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'memory_episode_events'`).get()) {
+            const links = db.prepare(`
+        SELECT episode_id, event_id, position
+        FROM memory_episode_events
+        ORDER BY episode_id, position, event_id
+      `).all();
+            const positions = new Map();
+            let episodeId;
+            let nextPosition = 0;
+            for (const link of links) {
+                if (link.episode_id !== episodeId) {
+                    episodeId = link.episode_id;
+                    nextPosition = 0;
+                }
+                nextPosition += 1;
+                positions.set(`${link.episode_id}\u0000${link.event_id}`, nextPosition);
+            }
+            // Move through a disjoint temporary range so an existing unique index
+            // cannot observe an intermediate duplicate while positions are compacted.
+            const temporary = db.prepare(`UPDATE memory_episode_events SET position = ? WHERE episode_id = ? AND event_id = ?`);
+            for (const link of links)
+                temporary.run(-link.position - 1, link.episode_id, link.event_id);
+            for (const link of links)
+                temporary.run(positions.get(`${link.episode_id}\u0000${link.event_id}`) ?? 0, link.episode_id, link.event_id);
+            const hasEpisodes = Boolean(db.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'memory_episodes'`).get());
+            const hasEvents = Boolean(db.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'memory_events'`).get());
+            const eventColumns = hasEvents
+                ? new Set(db.prepare(`PRAGMA table_info(memory_events)`).all().map((row) => row.name))
+                : new Set();
+            const hasGlobalSeq = eventColumns.has('global_seq');
+            if (hasEpisodes) {
+                const episodes = db.prepare(`SELECT episode_id FROM memory_episodes`).all();
+                const first = db.prepare(`
+          SELECT event_id FROM memory_episode_events WHERE episode_id = ? ORDER BY position, event_id LIMIT 1
+        `);
+                const last = db.prepare(`
+          SELECT event_id FROM memory_episode_events WHERE episode_id = ? ORDER BY position DESC, event_id DESC LIMIT 1
+        `);
+                const count = db.prepare(`SELECT COUNT(*) AS count FROM memory_episode_events WHERE episode_id = ?`);
+                const rebuild = hasEvents && hasGlobalSeq ? db.prepare(`
+          UPDATE memory_episodes SET event_count = ?, start_event_id = COALESCE(?, start_event_id), end_event_id = COALESCE(?, end_event_id),
+            start_seq = COALESCE((SELECT global_seq FROM memory_events WHERE event_id = ?), start_seq),
+            end_seq = COALESCE((SELECT global_seq FROM memory_events WHERE event_id = ?), end_seq)
+          WHERE episode_id = ?
+        `) : db.prepare(`
+          UPDATE memory_episodes SET event_count = ?, start_event_id = COALESCE(?, start_event_id), end_event_id = COALESCE(?, end_event_id)
+          WHERE episode_id = ?
+        `);
+                for (const episode of episodes) {
+                    const actualCount = Number(count.get(episode.episode_id).count ?? 0);
+                    const firstEventId = first.get(episode.episode_id)?.event_id ?? null;
+                    const lastEventId = last.get(episode.episode_id)?.event_id ?? null;
+                    if (hasEvents && hasGlobalSeq)
+                        rebuild.run(actualCount, firstEventId, lastEventId, firstEventId, lastEventId, episode.episode_id);
+                    else
+                        rebuild.run(actualCount, firstEventId, lastEventId, episode.episode_id);
+                }
+            }
+            const receiptTable = Boolean(db.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'episode_closure_receipts'`).get());
+            if (receiptTable) {
+                const receipts = db.prepare(`SELECT receipt_id, episode_id, source_event_ids_json FROM episode_closure_receipts`).all();
+                const selectPosition = db.prepare(`SELECT event_id, position FROM memory_episode_events WHERE episode_id = ?`);
+                const updateReceipt = db.prepare(`UPDATE episode_closure_receipts SET source_event_ids_json = ? WHERE receipt_id = ?`);
+                for (const receipt of receipts) {
+                    let eventIds;
+                    try {
+                        const parsed = JSON.parse(receipt.source_event_ids_json);
+                        eventIds = Array.isArray(parsed) ? parsed.filter((id) => typeof id === 'string') : [];
+                    }
+                    catch {
+                        eventIds = [];
+                    }
+                    const positions = new Map(selectPosition.all(receipt.episode_id).map((row) => [row.event_id, row.position]));
+                    eventIds.sort((left, right) => (positions.get(left) ?? Number.MAX_SAFE_INTEGER) - (positions.get(right) ?? Number.MAX_SAFE_INTEGER));
+                    updateReceipt.run(JSON.stringify(eventIds), receipt.receipt_id);
+                }
+            }
+            db.exec(`
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_episode_events_episode_position_unique
+          ON memory_episode_events(episode_id, position);
+      `);
+        }
+    },
+    down() {
+        // SQLite cannot drop a column without rebuilding the table; keep the compatible additive column.
+    },
+};

package/dist/migrations/0031_episode_boundary_integrity_repair.d.ts

@@ -0,0 +1,7 @@
+import type { Migration } from '../types/Migration.js';
+/**
+ * An immutable repair migration for databases which claimed 0030 through
+ * `_meta` while only receiving a subset of its DDL/data work.
+ */
+export declare const migration_0031: Migration;
+//# sourceMappingURL=0031_episode_boundary_integrity_repair.d.ts.map

package/dist/migrations/0031_episode_boundary_integrity_repair.js

@@ -0,0 +1,124 @@
+import { sealDuplicateOpenEpisodes } from '../episode/EpisodeActiveScopeGuard.js';
+function tableExists(db, name) {
+    return Boolean(db.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?`).get(name));
+}
+function columns(db, table) {
+    return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((row) => row.name));
+}
+/**
+ * An immutable repair migration for databases which claimed 0030 through
+ * `_meta` while only receiving a subset of its DDL/data work.
+ */
+export const migration_0031 = {
+    version: '0031',
+    description: 'episode boundary integrity repair',
+    up(db) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS _episode_integrity_markers (
+        marker TEXT PRIMARY KEY,
+        applied_at INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS import_source_anchors (
+        project_id TEXT NOT NULL,
+        source_id TEXT NOT NULL,
+        import_anchor TEXT NOT NULL,
+        event_id TEXT NOT NULL UNIQUE,
+        content_hash TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        PRIMARY KEY (project_id, source_id, import_anchor)
+      );
+    `);
+        if (tableExists(db, 'memory_events')) {
+            if (!columns(db, 'memory_events').has('local_date_source')) {
+                db.exec(`ALTER TABLE memory_events ADD COLUMN local_date_source TEXT NOT NULL DEFAULT 'legacy_unknown';`);
+            }
+            if (columns(db, 'memory_events').has('payload_json')) {
+                db.exec(`
+          UPDATE memory_events
+          SET local_date_source = CASE
+            WHEN json_valid(payload_json) AND json_extract(payload_json, '$.metadata.localDateSource') IN ('event_store_utc_default', 'generated_utc') THEN 'generated_utc'
+            WHEN json_valid(payload_json) AND json_extract(payload_json, '$.metadata.localDateSource') = 'explicit' THEN 'explicit'
+            WHEN local_date_source IN ('explicit', 'generated_utc') THEN local_date_source
+            ELSE 'legacy_unknown'
+          END;
+        `);
+            }
+        }
+        if (tableExists(db, 'memory_episode_events')) {
+            const links = db.prepare(`
+        SELECT rowid, episode_id, event_id, position
+        FROM memory_episode_events
+        ORDER BY episode_id, position, event_id, rowid
+      `).all();
+            const temporary = db.prepare(`UPDATE memory_episode_events SET position = ? WHERE rowid = ?`);
+            const finalPosition = db.prepare(`UPDATE memory_episode_events SET position = ? WHERE rowid = ?`);
+            const counters = new Map();
+            for (const link of links)
+                temporary.run(-1_000_000_000 - link.rowid, link.rowid);
+            for (const link of links) {
+                const next = (counters.get(link.episode_id) ?? 0) + 1;
+                counters.set(link.episode_id, next);
+                finalPosition.run(next, link.rowid);
+            }
+            if (tableExists(db, 'memory_episodes')) {
+                const eventColumns = tableExists(db, 'memory_events') ? columns(db, 'memory_events') : new Set();
+                const hasGlobalSeq = eventColumns.has('global_seq');
+                const episodes = db.prepare(`SELECT episode_id FROM memory_episodes`).all();
+                const count = db.prepare(`SELECT COUNT(*) AS count FROM memory_episode_events WHERE episode_id = ?`);
+                const first = db.prepare(`SELECT event_id FROM memory_episode_events WHERE episode_id = ? ORDER BY position, event_id LIMIT 1`);
+                const last = db.prepare(`SELECT event_id FROM memory_episode_events WHERE episode_id = ? ORDER BY position DESC, event_id DESC LIMIT 1`);
+                const rebuild = hasGlobalSeq ? db.prepare(`
+          UPDATE memory_episodes SET event_count = ?, start_event_id = ?, end_event_id = ?,
+            start_seq = (SELECT global_seq FROM memory_events WHERE event_id = ?),
+            end_seq = (SELECT global_seq FROM memory_events WHERE event_id = ?)
+          WHERE episode_id = ?
+        `) : db.prepare(`
+          UPDATE memory_episodes SET event_count = ?, start_event_id = ?, end_event_id = ? WHERE episode_id = ?
+        `);
+                const deleteDependents = (episodeId) => {
+                    if (tableExists(db, 'episode_closure_receipts'))
+                        db.prepare(`DELETE FROM episode_closure_receipts WHERE episode_id = ?`).run(episodeId);
+                    if (tableExists(db, 'episode_dream_jobs'))
+                        db.prepare(`DELETE FROM episode_dream_jobs WHERE episode_id = ?`).run(episodeId);
+                    if (tableExists(db, 'episode_cross_refs'))
+                        db.prepare(`DELETE FROM episode_cross_refs WHERE episode_id = ? OR referenced_episode_id = ?`).run(episodeId, episodeId);
+                    if (tableExists(db, 'episode_boundary_decisions')) {
+                        db.prepare(`DELETE FROM episode_boundary_decisions WHERE previous_episode_id = ? OR resulting_episode_id = ?`).run(episodeId, episodeId);
+                    }
+                    db.prepare(`DELETE FROM memory_episodes WHERE episode_id = ?`).run(episodeId);
+                };
+                for (const episode of episodes) {
+                    const actual = Number(count.get(episode.episode_id).count ?? 0);
+                    if (actual === 0) {
+                        // The public schema has non-null pointers. An empty episode cannot
+                        // represent correct pointer state, so remove it atomically.
+                        deleteDependents(episode.episode_id);
+                        continue;
+                    }
+                    const firstEventId = first.get(episode.episode_id)?.event_id;
+                    const lastEventId = last.get(episode.episode_id)?.event_id;
+                    if (!firstEventId || !lastEventId)
+                        continue;
+                    if (hasGlobalSeq)
+                        rebuild.run(actual, firstEventId, lastEventId, firstEventId, lastEventId, episode.episode_id);
+                    else
+                        rebuild.run(actual, firstEventId, lastEventId, episode.episode_id);
+                }
+            }
+            db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_episode_events_episode_position_unique ON memory_episode_events(episode_id, position);`);
+        }
+        if (tableExists(db, 'memory_episodes')) {
+            sealDuplicateOpenEpisodes(db);
+            db.exec(`
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_episodes_one_active_scope
+          ON memory_episodes(project_id, session_id, COALESCE(source_agent, ''), COALESCE(conversation_thread_id, ''))
+          WHERE status = 'open';
+      `);
+        }
+        db.prepare(`INSERT OR REPLACE INTO _episode_integrity_markers (marker, applied_at) VALUES ('episode_boundary_integrity_0031', ?)`)
+            .run(Date.now());
+    },
+    down() {
+        // Integrity repairs are deliberately forward-only.
+    },
+};

package/dist/migrations/SchemaMigrationRunner.d.ts

@@ -19,11 +19,13 @@ export declare class SchemaMigrationRunner {
     constructor(db: Database, migrations: Migration[], options?: SchemaMigrationRunnerOptions);
     plan(): Migration[];
     run(options?: SchemaMigrationRunOptions): SchemaMigrationResult;
+    private ensureMigrationTable;
     currentVersion(): string | undefined;
     private appliedVersions;
     private schemaMigrationsTableExists;
     private legacySchemaVersion;
     private legacyCurrentVersion;
     private adoptLegacyVersion;
+    private migrationSchemaSatisfied;
 }
 //# sourceMappingURL=SchemaMigrationRunner.d.ts.map

package/dist/migrations/SchemaMigrationRunner.js

@@ -6,16 +6,8 @@ export class SchemaMigrationRunner {
         this.db = db;
         this.migrations = migrations;
         this.options = options;
-        if (this.options.readonly)
-            return;
-        this.db.exec(`
-      CREATE TABLE IF NOT EXISTS _schema_migrations (
-        version TEXT PRIMARY KEY,
-        description TEXT NOT NULL,
-        applied_at TEXT NOT NULL
-      );
-    `);
-        this.adoptLegacyVersion();
+        // Construction is read-only. Schema bookkeeping is created only when a
+        // non-dry run is explicitly requested.
     }
     plan() {
         const applied = this.appliedVersions();
@@ -24,10 +16,13 @@ export class SchemaMigrationRunner {
             .filter((migration) => !applied.has(migration.version));
     }
     run(options = {}) {
-        const pending = this.plan();
-        if (options.dryRun) {
+        if (options.dryRun || this.options.readonly) {
+            const pending = this.plan();
             return { pending: pending.map((item) => item.version), applied: [], currentVersion: this.currentVersion(), dryRun: true };
         }
+        this.ensureMigrationTable();
+        this.adoptLegacyVersion();
+        const pending = this.plan();
         const applied = [];
         const transaction = this.db.transaction(() => {
             for (const migration of pending) {
@@ -42,6 +37,15 @@ export class SchemaMigrationRunner {
         transaction();
         return { pending: pending.map((item) => item.version), applied, currentVersion: this.currentVersion(), dryRun: false };
     }
+    ensureMigrationTable() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS _schema_migrations (
+        version TEXT PRIMARY KEY,
+        description TEXT NOT NULL,
+        applied_at TEXT NOT NULL
+      );
+    `);
+    }
     currentVersion() {
         const legacyCurrent = this.legacyCurrentVersion();
         if (!this.schemaMigrationsTableExists()) {
@@ -56,7 +60,12 @@ export class SchemaMigrationRunner {
         const applied = new Set();
         const legacyVersion = this.legacySchemaVersion();
         for (const migration of this.migrations) {
-            if (legacyVersion !== undefined && Number.parseInt(migration.version, 10) <= legacyVersion) {
+            // `_meta.schema_version` was written by older kernels without a durable
+            // migration receipt. It is a hint only: adopting a high legacy version
+            // must not hide a partially applied integrity migration.
+            if (legacyVersion !== undefined
+                && Number.parseInt(migration.version, 10) <= legacyVersion
+                && this.migrationSchemaSatisfied(migration.version)) {
                 applied.add(migration.version);
             }
         }
@@ -64,7 +73,8 @@ export class SchemaMigrationRunner {
             return applied;
         }
         for (const row of this.db.prepare(`SELECT version FROM _schema_migrations`).all()) {
-            applied.add(row.version);
+            if (this.migrationSchemaSatisfied(row.version))
+                applied.add(row.version);
         }
         return applied;
     }
@@ -100,9 +110,30 @@ export class SchemaMigrationRunner {
       VALUES (?, ?, ?)
     `);
         for (const migration of this.migrations) {
-            if (Number.parseInt(migration.version, 10) <= legacyVersion) {
+            if (Number.parseInt(migration.version, 10) <= legacyVersion && this.migrationSchemaSatisfied(migration.version)) {
                 insert.run(migration.version, `adopted: ${migration.description}`, new Date(0).toISOString());
             }
         }
     }
+    migrationSchemaSatisfied(version) {
+        if (version === '0029') {
+            return Boolean(this.db.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = 'idx_memory_episodes_one_active_scope'`).get());
+        }
+        if (version === '0030') {
+            const eventTable = Boolean(this.db.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'memory_events'`).get());
+            const eventColumns = eventTable
+                ? new Set(this.db.prepare(`PRAGMA table_info(memory_events)`).all().map((row) => row.name))
+                : new Set();
+            const positionIndex = Boolean(this.db.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = 'idx_memory_episode_events_episode_position_unique'`).get());
+            return (!eventTable || eventColumns.has('local_date_source')) && positionIndex;
+        }
+        if (version === '0031') {
+            return Boolean(this.db.prepare(`
+        SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = '_episode_integrity_markers'
+      `).get()) && Boolean(this.db.prepare(`
+        SELECT 1 FROM _episode_integrity_markers WHERE marker = 'episode_boundary_integrity_0031'
+      `).get());
+        }
+        return true;
+    }
 }