@xopcai/xopc 0.0.99 → 0.0.100

package/dist/src/session/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../../src/session/types.ts"],"sourcesContent":["// Session management types\n\nimport type { TranscriptStoredRow } from './session-context-for-llm.js';\n\nexport interface Message {\n  role: 'system' | 'user' | 'assistant' | 'tool' | 'toolResult';\n  /** Plain string or structured content blocks (tool calls, multimodal). */\n  content: string | unknown[];\n  timestamp?: string;\n  tool_call_id?: string;\n  tool_calls?: Array<{\n    id: string;\n    type: 'function';\n    function: {\n      name: string;\n      arguments: string;\n    };\n  }>;\n  tool_call_id$?: string;\n  toolName?: string;\n  isError?: boolean;\n  name?: string;\n  /** Token usage from the LLM response (assistant messages only). */\n  usage?: {\n    inputTokens?: number;\n    outputTokens?: number;\n    totalTokens?: number;\n  };\n  /** Webchat early-save / UI: inbound file metadata (no base64). Omitted when absent. */\n  attachments?: Array<{\n    type?: string;\n    mimeType?: string;\n    name?: string;\n    size?: number;\n    workspaceRelativePath?: string;\n  }>;\n}\n\n/** Session status enum */\nexport enum SessionStatus {\n  ACTIVE = 'active',\n  IDLE = 'idle',\n  ARCHIVED = 'archived',\n  PINNED = 'pinned',\n}\n\n/** Session routing metadata */\nexport interface SessionRoutingMeta {\n  agentId: string;\n  source: string;\n  accountId: string;\n  peerKind: string;\n  peerId: string;\n  threadId?: string;\n  scopeId?: string;\n  mainSessionKey?: string;\n  lastRoutePolicy?: 'main' | 'session';\n}\n\n/** Session-level statistics (per session) */\nexport interface SessionStats {\n  messageCount: number;\n  tokenCount: number;\n  turnCount?: number;\n  lastTurnAt?: number;\n}\n\n/** Global session statistics (aggregate) */\nexport interface GlobalSessionStats {\n  totalSessions: number;\n  activeSessions: number;\n  archivedSessions: number;\n  pinnedSessions: number;\n  totalMessages: number;\n  totalTokens: number;\n  oldestSession?: string;\n  newestSession?: string;\n  byChannel: Record<string, number>;\n}\n\n/** Session metadata (stored in index) */\nexport interface SessionMetadata {\n  key: string;\n  name?: string;\n  status: SessionStatus;\n  tags: string[];\n  createdAt: string;\n  updatedAt: string;\n  lastAccessedAt: string;\n  messageCount: number;\n  estimatedTokens: number;\n  compactedCount: number;\n  sourceChannel: string;\n  sourceChatId: string;\n  customData?: Record<string, unknown>;\n  /** Routing metadata */\n  routing?: SessionRoutingMeta;\n  /** Session statistics */\n  stats?: SessionStats;\n  /**\n   * High-level origin for filtering/UI (e.g. `cron`, `heartbeat`, `webchat`).\n   * Distinct from `sourceChannel` (routing namespace).\n   */\n  sessionType?: string;\n  /**\n   * Stable transcript document id (wrapped on-disk format), aligned with OpenClaw `sessionId`.\n   */\n  transcriptId?: string;\n  /** First activity time for this session row (ISO), from transcript header when available. */\n  sessionStartedAt?: string;\n  /** Last transcript write / interaction (ISO), updated on each persist. */\n  lastInteractionAt?: string;\n  /**\n   * Epoch ms when the last webchat run was aborted (`POST /api/agent/abort`).\n   * Used with `clientCreatedAtMs` on the next POST /api/agent to drop stale queued sends.\n   */\n  abortCutoffTimestamp?: number;\n}\n\n/** Summary of wrapped transcript (no duplicate message bodies). */\nexport interface SessionTranscriptSummary {\n  id: string;\n  version: number;\n  createdAt: string;\n  updatedAt: string;\n  compactionCount: number;\n}\n\n/** Session detail (metadata + messages) */\nexport interface SessionDetail extends SessionMetadata {\n  messages: Message[];\n  /** Present when loaded with `includeTranscriptSummary` (gateway `?include=transcript`). */\n  transcriptSummary?: SessionTranscriptSummary;\n  /** Present when loaded with `include=transcriptRows` (full on-disk rows, LLM + `kind: 'context'`). */\n  transcriptRows?: TranscriptStoredRow[];\n}\n\n/** Session list query parameters */\nexport interface SessionListQuery {\n  status?: SessionStatus | SessionStatus[];\n  /** Single `sourceChannel`, or comma-separated list (e.g. `telegram,weixin`). */\n  channel?: string;\n  tags?: string[];\n  search?: string;\n  sortBy?: 'updatedAt' | 'createdAt' | 'messageCount' | 'lastAccessedAt';\n  sortOrder?: 'asc' | 'desc';\n  limit?: number;\n  offset?: number;\n}\n\n/** Paginated result */\nexport interface PaginatedResult<T> {\n  items: T[];\n  total: number;\n  limit: number;\n  offset: number;\n  hasMore: boolean;\n}\n\n/** Export format */\nexport type ExportFormat = 'json' | 'markdown';\n\n/** Session export data */\nexport interface SessionExport {\n  version: string;\n  exportedAt: string;\n  metadata: SessionMetadata;\n  messages: Message[];\n  /** Full on-disk rows (LLM + `kind: 'context'`) for audit / round-trip. */\n  transcriptRows: TranscriptStoredRow[];\n}\n\n/** On-disk pre-compaction snapshot (OpenClaw-style checkpoint list). */\nexport interface CompactionCheckpointSummary {\n  id: string;\n  sizeBytes: number;\n  modifiedAt: string;\n}\n\nexport interface CompactionCheckpointDetail extends CompactionCheckpointSummary {\n  messageCount: number;\n}\n"],"mappings":";;AAuCA,IAAY,gBAAL,yBAAA,eAAA;AACL,eAAA,YAAA;AACA,eAAA,UAAA;AACA,eAAA,cAAA;AACA,eAAA,YAAA;;KACD"}
+{"version":3,"file":"types.js","names":[],"sources":["../../../src/session/types.ts"],"sourcesContent":["// Session management types\n\nimport type { TranscriptStoredRow } from './session-context-for-llm.js';\n\nexport interface Message {\n  role: 'system' | 'user' | 'assistant' | 'tool' | 'toolResult';\n  /** Plain string or structured content blocks (tool calls, multimodal). */\n  content: string | unknown[];\n  timestamp?: string;\n  tool_call_id?: string;\n  tool_calls?: Array<{\n    id: string;\n    type: 'function';\n    function: {\n      name: string;\n      arguments: string;\n    };\n  }>;\n  tool_call_id$?: string;\n  toolName?: string;\n  isError?: boolean;\n  name?: string;\n  /** Token usage from the LLM response (assistant messages only). */\n  usage?: {\n    inputTokens?: number;\n    outputTokens?: number;\n    totalTokens?: number;\n  };\n  /** Inbound attachment metadata (no base64). */\n  media?: Array<{\n    id: string;\n    bucket: string;\n    type: string;\n    mimeType: string;\n    name: string;\n    size: number;\n    uri: string;\n    path: string;\n  }>;\n}\n\n/** Session status enum */\nexport enum SessionStatus {\n  ACTIVE = 'active',\n  IDLE = 'idle',\n  ARCHIVED = 'archived',\n  PINNED = 'pinned',\n}\n\n/** Session routing metadata */\nexport interface SessionRoutingMeta {\n  agentId: string;\n  source: string;\n  accountId: string;\n  peerKind: string;\n  peerId: string;\n  threadId?: string;\n  scopeId?: string;\n  mainSessionKey?: string;\n  lastRoutePolicy?: 'main' | 'session';\n}\n\n/** Session-level statistics (per session) */\nexport interface SessionStats {\n  messageCount: number;\n  tokenCount: number;\n  turnCount?: number;\n  lastTurnAt?: number;\n}\n\n/** Global session statistics (aggregate) */\nexport interface GlobalSessionStats {\n  totalSessions: number;\n  activeSessions: number;\n  archivedSessions: number;\n  pinnedSessions: number;\n  totalMessages: number;\n  totalTokens: number;\n  oldestSession?: string;\n  newestSession?: string;\n  byChannel: Record<string, number>;\n}\n\n/** Session metadata (stored in index) */\nexport interface SessionMetadata {\n  key: string;\n  name?: string;\n  status: SessionStatus;\n  tags: string[];\n  createdAt: string;\n  updatedAt: string;\n  lastAccessedAt: string;\n  messageCount: number;\n  estimatedTokens: number;\n  compactedCount: number;\n  lastFlushedAt?: string;\n  flushCount?: number;\n  sourceChannel: string;\n  sourceChatId: string;\n  customData?: Record<string, unknown>;\n  /** Routing metadata */\n  routing?: SessionRoutingMeta;\n  /** Session statistics */\n  stats?: SessionStats;\n  /**\n   * High-level origin for filtering/UI (e.g. `cron`, `heartbeat`, `webchat`).\n   * Distinct from `sourceChannel` (routing namespace).\n   */\n  sessionType?: string;\n  /**\n   * Stable transcript document id (wrapped on-disk format), aligned with OpenClaw `sessionId`.\n   */\n  transcriptId?: string;\n  /** First activity time for this session row (ISO), from transcript header when available. */\n  sessionStartedAt?: string;\n  /** Last transcript write / interaction (ISO), updated on each persist. */\n  lastInteractionAt?: string;\n  /**\n   * Epoch ms when the last webchat run was aborted (`POST /api/agent/abort`).\n   * Used with `clientCreatedAtMs` on the next POST /api/agent to drop stale queued sends.\n   */\n  abortCutoffTimestamp?: number;\n}\n\n/** Summary of wrapped transcript (no duplicate message bodies). */\nexport interface SessionTranscriptSummary {\n  id: string;\n  version: number;\n  createdAt: string;\n  updatedAt: string;\n  compactionCount: number;\n}\n\n/** Session detail (metadata + messages) */\nexport interface SessionDetail extends SessionMetadata {\n  messages: Message[];\n  /** Present when loaded with `includeTranscriptSummary` (gateway `?include=transcript`). */\n  transcriptSummary?: SessionTranscriptSummary;\n  /** Present when loaded with `include=transcriptRows` (full on-disk rows, LLM + `kind: 'context'`). */\n  transcriptRows?: TranscriptStoredRow[];\n}\n\n/** Session list query parameters */\nexport interface SessionListQuery {\n  status?: SessionStatus | SessionStatus[];\n  /** Single `sourceChannel`, or comma-separated list (e.g. `telegram,weixin`). */\n  channel?: string;\n  tags?: string[];\n  search?: string;\n  sortBy?: 'updatedAt' | 'createdAt' | 'messageCount' | 'lastAccessedAt';\n  sortOrder?: 'asc' | 'desc';\n  limit?: number;\n  offset?: number;\n}\n\n/** Paginated result */\nexport interface PaginatedResult<T> {\n  items: T[];\n  total: number;\n  limit: number;\n  offset: number;\n  hasMore: boolean;\n}\n\n/** Export format */\nexport type ExportFormat = 'json' | 'markdown';\n\n/** Session export data */\nexport interface SessionExport {\n  version: string;\n  exportedAt: string;\n  metadata: SessionMetadata;\n  messages: Message[];\n  /** Full on-disk rows (LLM + `kind: 'context'`) for audit / round-trip. */\n  transcriptRows: TranscriptStoredRow[];\n}\n\n/** On-disk pre-compaction snapshot (OpenClaw-style checkpoint list). */\nexport interface CompactionCheckpointSummary {\n  id: string;\n  sizeBytes: number;\n  modifiedAt: string;\n}\n\nexport interface CompactionCheckpointDetail extends CompactionCheckpointSummary {\n  messageCount: number;\n}\n"],"mappings":";;AA0CA,IAAY,gBAAL,yBAAA,eAAA;AACL,eAAA,YAAA;AACA,eAAA,UAAA;AACA,eAAA,cAAA;AACA,eAAA,YAAA;;KACD"}

package/dist/src/storage/sqlite/index.d.ts

@@ -1,5 +1,8 @@
 export { resolveXopcDatabasePath, XOPC_DB_FILENAME } from './paths.js';
-export { XOPC_DB_SCHEMA_VERSION, SCHEMA_META_SCHEMA_VERSION_KEY, ensureXopcDatabaseSchema, readSchemaVersionForTest, } from './schema.js';
+export { XOPC_DB_SCHEMA_VERSION, XOPC_DB_BASELINE_SCHEMA_VERSION, SCHEMA_META_SCHEMA_VERSION_KEY, ensureXopcDatabaseSchema, readSchemaVersionForTest, readSchemaVersion, } from './schema.js';
+export { applyPendingMigrations, inspectSchemaMigrationStatus, resolveMigrationsDir, type SchemaMigrationStatus, } from './migrations/runner.js';
+export { DatabaseSchemaMigrationGapError, DatabaseSchemaTooNewError, } from './migrations/errors.js';
+export { discoverSqlMigrations, listRegisteredMigrationTargets } from './migrations/discover.js';
 export { closeXopcDatabase, getXopcDatabase, isXopcDatabaseOpen, openXopcDatabase, requireXopcDatabase, resetXopcDatabaseSingletonForTest, type OpenXopcDatabaseOptions, type XopcDatabase, } from './connection.js';
 export { getSqliteDatabase, runSqliteWriteTransaction } from './transaction.js';
 export { buildDefaultSessionMetadata, extractRoutingFromSessionKey, parseSessionKeySource, resolveAgentIdFromSessionKey, } from './session-metadata.js';

package/dist/src/storage/sqlite/index.js

@@ -1,5 +1,9 @@
 import { XOPC_DB_FILENAME, resolveXopcDatabasePath } from "../../config/paths-state.js";
-import { SCHEMA_META_SCHEMA_VERSION_KEY, XOPC_DB_SCHEMA_VERSION, ensureXopcDatabaseSchema, readSchemaVersionForTest } from "./schema.js";
+import { SCHEMA_META_SCHEMA_VERSION_KEY, readSchemaVersion, readSchemaVersionForTest } from "./schema-version.js";
+import { discoverSqlMigrations, listRegisteredMigrationTargets } from "./migrations/discover.js";
+import { DatabaseSchemaMigrationGapError, DatabaseSchemaTooNewError } from "./migrations/errors.js";
+import { XOPC_DB_BASELINE_SCHEMA_VERSION, XOPC_DB_SCHEMA_VERSION, applyPendingMigrations, inspectSchemaMigrationStatus, resolveMigrationsDir } from "./migrations/runner.js";
+import { ensureXopcDatabaseSchema } from "./schema.js";
 import { closeXopcDatabase, getXopcDatabase, isXopcDatabaseOpen, openXopcDatabase, requireXopcDatabase, resetXopcDatabaseSingletonForTest } from "./connection.js";
 import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
 import { buildDefaultSessionMetadata, extractRoutingFromSessionKey, parseSessionKeySource, resolveAgentIdFromSessionKey } from "./session-metadata.js";
@@ -10,4 +14,4 @@ import { appendCronRun, deleteCronRunsForJob, readAllCronRuns, readCronJobHistor
 import { deleteNoteRecord, getNoteRecord, listNoteRecords, upsertNoteRecord } from "./notes-repository.js";
 import { resolveAgentIdFromMemoriesDir, searchMemoryIndex, syncMemoryIndex } from "./memory-index-repository.js";
 import { deleteSessionConfig, getSessionConfig, hasSessionConfig, setSessionConfig, updateSessionConfig } from "./config-repository.js";
-export { SCHEMA_META_SCHEMA_VERSION_KEY, XOPC_DB_FILENAME, XOPC_DB_SCHEMA_VERSION, appendCronRun, appendTranscriptEntry, buildDefaultSessionMetadata, buildGlobalSessionStats, captureCompactionCheckpoint, classifyStoredRow, closeXopcDatabase, deleteCronRunsForJob, deleteNoteRecord, deleteSessionConfig, deleteSessionRecord, ensureSessionRecord, ensureXopcDatabaseSchema, estimateTokensFromMessages, extractFtsContent, extractRoutingFromSessionKey, findSessionKeyByTranscriptId, getCompactionCheckpointDetail, getCurrentTranscriptId, getGlobalSessionStats, getNoteRecord, getSessionConfig, getSessionMetadata, getSessionPersistedLevels, getSqliteDatabase, getXopcDatabase, hasSessionConfig, incrementSessionStatsOnAppend, isXopcDatabaseOpen, listCompactionCheckpoints, listNoteRecords, listSessionMetadata, listSessionsByAgent, loadCheckpointRows, loadLlmMessagesForSession, loadTranscriptRows, loadTranscriptRowsForSession, metadataToSessionInsert, openXopcDatabase, paginateTranscriptMessages, parseSessionKeySource, patchSessionMetadata, readAllCronRuns, readCronJobHistory, readSchemaVersionForTest, replaceTranscriptRows, requireXopcDatabase, resetSessionRecord, resetXopcDatabaseSingletonForTest, resolveAgentIdFromMemoriesDir, resolveAgentIdFromSessionKey, resolveSessionAgentId, resolveXopcDatabasePath, restoreCompactionCheckpoint, runSqliteWriteTransaction, searchMemoryIndex, sessionConfigRowToConfig, sessionRowToMetadata, setSessionConfig, syncMemoryIndex, transcriptEntryRowToStoredRow, updateSessionConfig, updateSessionStats, upsertNoteRecord };
+export { DatabaseSchemaMigrationGapError, DatabaseSchemaTooNewError, SCHEMA_META_SCHEMA_VERSION_KEY, XOPC_DB_BASELINE_SCHEMA_VERSION, XOPC_DB_FILENAME, XOPC_DB_SCHEMA_VERSION, appendCronRun, appendTranscriptEntry, applyPendingMigrations, buildDefaultSessionMetadata, buildGlobalSessionStats, captureCompactionCheckpoint, classifyStoredRow, closeXopcDatabase, deleteCronRunsForJob, deleteNoteRecord, deleteSessionConfig, deleteSessionRecord, discoverSqlMigrations, ensureSessionRecord, ensureXopcDatabaseSchema, estimateTokensFromMessages, extractFtsContent, extractRoutingFromSessionKey, findSessionKeyByTranscriptId, getCompactionCheckpointDetail, getCurrentTranscriptId, getGlobalSessionStats, getNoteRecord, getSessionConfig, getSessionMetadata, getSessionPersistedLevels, getSqliteDatabase, getXopcDatabase, hasSessionConfig, incrementSessionStatsOnAppend, inspectSchemaMigrationStatus, isXopcDatabaseOpen, listCompactionCheckpoints, listNoteRecords, listRegisteredMigrationTargets, listSessionMetadata, listSessionsByAgent, loadCheckpointRows, loadLlmMessagesForSession, loadTranscriptRows, loadTranscriptRowsForSession, metadataToSessionInsert, openXopcDatabase, paginateTranscriptMessages, parseSessionKeySource, patchSessionMetadata, readAllCronRuns, readCronJobHistory, readSchemaVersion, readSchemaVersionForTest, replaceTranscriptRows, requireXopcDatabase, resetSessionRecord, resetXopcDatabaseSingletonForTest, resolveAgentIdFromMemoriesDir, resolveAgentIdFromSessionKey, resolveMigrationsDir, resolveSessionAgentId, resolveXopcDatabasePath, restoreCompactionCheckpoint, runSqliteWriteTransaction, searchMemoryIndex, sessionConfigRowToConfig, sessionRowToMetadata, setSessionConfig, syncMemoryIndex, transcriptEntryRowToStoredRow, updateSessionConfig, updateSessionStats, upsertNoteRecord };

package/dist/src/storage/sqlite/migrations/002_add_flush_columns.sql

@@ -0,0 +1,3 @@
+-- Migration: Add memory flush tracking columns to sessions table
+ALTER TABLE sessions ADD COLUMN last_flushed_at TEXT;
+ALTER TABLE sessions ADD COLUMN flush_count INTEGER NOT NULL DEFAULT 0;

package/dist/src/storage/sqlite/migrations/discover.d.ts

@@ -0,0 +1,4 @@
+import type { SqlMigration } from './types.js';
+export declare function discoverSqlMigrations(migrationsDir: string): SqlMigration[];
+export declare function validateMigrationSequence(migrations: SqlMigration[]): void;
+export declare function listRegisteredMigrationTargets(migrationsDir: string): number[];

package/dist/src/storage/sqlite/migrations/discover.js

@@ -0,0 +1,38 @@
+import { join } from "node:path";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+//#region src/storage/sqlite/migrations/discover.ts
+/** Matches `002_add_notes_index.sql` → target version 2. */
+const MIGRATION_FILENAME = /^(\d{3})_[\w-]+\.sql$/;
+function discoverSqlMigrations(migrationsDir) {
+	if (!existsSync(migrationsDir)) return [];
+	const migrations = [];
+	for (const entry of readdirSync(migrationsDir, { withFileTypes: true })) {
+		if (!entry.isFile()) continue;
+		const match = MIGRATION_FILENAME.exec(entry.name);
+		if (!match) continue;
+		const targetVersion = Number.parseInt(match[1], 10);
+		if (!Number.isInteger(targetVersion) || targetVersion < 2) throw new Error(`Invalid SQLite migration filename "${entry.name}" (target version must be >= 2)`);
+		migrations.push({
+			targetVersion,
+			filename: entry.name,
+			sql: readFileSync(join(migrationsDir, entry.name), "utf8")
+		});
+	}
+	migrations.sort((a, b) => a.targetVersion - b.targetVersion);
+	validateMigrationSequence(migrations);
+	return migrations;
+}
+function validateMigrationSequence(migrations) {
+	for (let index = 0; index < migrations.length; index++) {
+		const expected = index + 2;
+		const actual = migrations[index].targetVersion;
+		if (actual !== expected) throw new Error(`SQLite migration sequence gap: expected migration to version ${expected}, found ${migrations[index].filename} (v${actual})`);
+	}
+}
+function listRegisteredMigrationTargets(migrationsDir) {
+	return discoverSqlMigrations(migrationsDir).map((migration) => migration.targetVersion);
+}
+//#endregion
+export { discoverSqlMigrations, listRegisteredMigrationTargets, validateMigrationSequence };
+
+//# sourceMappingURL=discover.js.map

package/dist/src/storage/sqlite/migrations/discover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.js","names":[],"sources":["../../../../../src/storage/sqlite/migrations/discover.ts"],"sourcesContent":["import { existsSync, readdirSync, readFileSync } from 'node:fs';\nimport { join } from 'node:path';\n\nimport type { SqlMigration } from './types.js';\n\n/** Matches `002_add_notes_index.sql` → target version 2. */\nconst MIGRATION_FILENAME = /^(\\d{3})_[\\w-]+\\.sql$/;\n\nexport function discoverSqlMigrations(migrationsDir: string): SqlMigration[] {\n  if (!existsSync(migrationsDir)) {\n    return [];\n  }\n\n  const migrations: SqlMigration[] = [];\n  for (const entry of readdirSync(migrationsDir, { withFileTypes: true })) {\n    if (!entry.isFile()) continue;\n    const match = MIGRATION_FILENAME.exec(entry.name);\n    if (!match) continue;\n    const targetVersion = Number.parseInt(match[1]!, 10);\n    if (!Number.isInteger(targetVersion) || targetVersion < 2) {\n      throw new Error(\n        `Invalid SQLite migration filename \"${entry.name}\" (target version must be >= 2)`,\n      );\n    }\n    migrations.push({\n      targetVersion,\n      filename: entry.name,\n      sql: readFileSync(join(migrationsDir, entry.name), 'utf8'),\n    });\n  }\n\n  migrations.sort((a, b) => a.targetVersion - b.targetVersion);\n  validateMigrationSequence(migrations);\n  return migrations;\n}\n\nexport function validateMigrationSequence(migrations: SqlMigration[]): void {\n  for (let index = 0; index < migrations.length; index++) {\n    const expected = index + 2;\n    const actual = migrations[index]!.targetVersion;\n    if (actual !== expected) {\n      throw new Error(\n        `SQLite migration sequence gap: expected migration to version ${expected}, ` +\n          `found ${migrations[index]!.filename} (v${actual})`,\n      );\n    }\n  }\n}\n\nexport function listRegisteredMigrationTargets(migrationsDir: string): number[] {\n  return discoverSqlMigrations(migrationsDir).map((migration) => migration.targetVersion);\n}\n"],"mappings":";;;;AAMA,MAAM,qBAAqB;AAE3B,SAAgB,sBAAsB,eAAuC;AAC3E,KAAI,CAAC,WAAW,cAAc,CAC5B,QAAO,EAAE;CAGX,MAAM,aAA6B,EAAE;AACrC,MAAK,MAAM,SAAS,YAAY,eAAe,EAAE,eAAe,MAAM,CAAC,EAAE;AACvE,MAAI,CAAC,MAAM,QAAQ,CAAE;EACrB,MAAM,QAAQ,mBAAmB,KAAK,MAAM,KAAK;AACjD,MAAI,CAAC,MAAO;EACZ,MAAM,gBAAgB,OAAO,SAAS,MAAM,IAAK,GAAG;AACpD,MAAI,CAAC,OAAO,UAAU,cAAc,IAAI,gBAAgB,EACtD,OAAM,IAAI,MACR,sCAAsC,MAAM,KAAK,iCAClD;AAEH,aAAW,KAAK;GACd;GACA,UAAU,MAAM;GAChB,KAAK,aAAa,KAAK,eAAe,MAAM,KAAK,EAAE,OAAO;GAC3D,CAAC;;AAGJ,YAAW,MAAM,GAAG,MAAM,EAAE,gBAAgB,EAAE,cAAc;AAC5D,2BAA0B,WAAW;AACrC,QAAO;;AAGT,SAAgB,0BAA0B,YAAkC;AAC1E,MAAK,IAAI,QAAQ,GAAG,QAAQ,WAAW,QAAQ,SAAS;EACtD,MAAM,WAAW,QAAQ;EACzB,MAAM,SAAS,WAAW,OAAQ;AAClC,MAAI,WAAW,SACb,OAAM,IAAI,MACR,gEAAgE,SAAS,UAC9D,WAAW,OAAQ,SAAS,KAAK,OAAO,GACpD;;;AAKP,SAAgB,+BAA+B,eAAiC;AAC9E,QAAO,sBAAsB,cAAc,CAAC,KAAK,cAAc,UAAU,cAAc"}

package/dist/src/storage/sqlite/migrations/discover.ts

@@ -0,0 +1,52 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { SqlMigration } from './types.js';
+
+/** Matches `002_add_notes_index.sql` → target version 2. */
+const MIGRATION_FILENAME = /^(\d{3})_[\w-]+\.sql$/;
+
+export function discoverSqlMigrations(migrationsDir: string): SqlMigration[] {
+  if (!existsSync(migrationsDir)) {
+    return [];
+  }
+
+  const migrations: SqlMigration[] = [];
+  for (const entry of readdirSync(migrationsDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    const match = MIGRATION_FILENAME.exec(entry.name);
+    if (!match) continue;
+    const targetVersion = Number.parseInt(match[1]!, 10);
+    if (!Number.isInteger(targetVersion) || targetVersion < 2) {
+      throw new Error(
+        `Invalid SQLite migration filename "${entry.name}" (target version must be >= 2)`,
+      );
+    }
+    migrations.push({
+      targetVersion,
+      filename: entry.name,
+      sql: readFileSync(join(migrationsDir, entry.name), 'utf8'),
+    });
+  }
+
+  migrations.sort((a, b) => a.targetVersion - b.targetVersion);
+  validateMigrationSequence(migrations);
+  return migrations;
+}
+
+export function validateMigrationSequence(migrations: SqlMigration[]): void {
+  for (let index = 0; index < migrations.length; index++) {
+    const expected = index + 2;
+    const actual = migrations[index]!.targetVersion;
+    if (actual !== expected) {
+      throw new Error(
+        `SQLite migration sequence gap: expected migration to version ${expected}, ` +
+          `found ${migrations[index]!.filename} (v${actual})`,
+      );
+    }
+  }
+}
+
+export function listRegisteredMigrationTargets(migrationsDir: string): number[] {
+  return discoverSqlMigrations(migrationsDir).map((migration) => migration.targetVersion);
+}

package/dist/src/storage/sqlite/migrations/errors.d.ts

@@ -0,0 +1,11 @@
+export declare class DatabaseSchemaTooNewError extends Error {
+    readonly dbVersion: number;
+    readonly appVersion: number;
+    constructor(dbVersion: number, appVersion: number);
+}
+export declare class DatabaseSchemaMigrationGapError extends Error {
+    readonly dbVersion: number;
+    readonly appVersion: number;
+    readonly missingVersion: number;
+    constructor(dbVersion: number, appVersion: number, missingVersion: number);
+}

package/dist/src/storage/sqlite/migrations/errors.js

@@ -0,0 +1,27 @@
+//#region src/storage/sqlite/migrations/errors.ts
+var DatabaseSchemaTooNewError = class extends Error {
+	dbVersion;
+	appVersion;
+	constructor(dbVersion, appVersion) {
+		super(`xopc database schema version ${dbVersion} is newer than this app supports (${appVersion}). Upgrade xopc to a newer release or restore xopc.db from backup.`);
+		this.name = "DatabaseSchemaTooNewError";
+		this.dbVersion = dbVersion;
+		this.appVersion = appVersion;
+	}
+};
+var DatabaseSchemaMigrationGapError = class extends Error {
+	dbVersion;
+	appVersion;
+	missingVersion;
+	constructor(dbVersion, appVersion, missingVersion) {
+		super(`xopc database schema version ${dbVersion} requires migration to v${missingVersion}, but no migration file is bundled with this app (supports up to v${appVersion}). Upgrade xopc to a release that includes the missing migration.`);
+		this.name = "DatabaseSchemaMigrationGapError";
+		this.dbVersion = dbVersion;
+		this.appVersion = appVersion;
+		this.missingVersion = missingVersion;
+	}
+};
+//#endregion
+export { DatabaseSchemaMigrationGapError, DatabaseSchemaTooNewError };
+
+//# sourceMappingURL=errors.js.map

package/dist/src/storage/sqlite/migrations/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../../../../../src/storage/sqlite/migrations/errors.ts"],"sourcesContent":["export class DatabaseSchemaTooNewError extends Error {\n  readonly dbVersion: number;\n  readonly appVersion: number;\n\n  constructor(dbVersion: number, appVersion: number) {\n    super(\n      `xopc database schema version ${dbVersion} is newer than this app supports (${appVersion}). ` +\n        'Upgrade xopc to a newer release or restore xopc.db from backup.',\n    );\n    this.name = 'DatabaseSchemaTooNewError';\n    this.dbVersion = dbVersion;\n    this.appVersion = appVersion;\n  }\n}\n\nexport class DatabaseSchemaMigrationGapError extends Error {\n  readonly dbVersion: number;\n  readonly appVersion: number;\n  readonly missingVersion: number;\n\n  constructor(dbVersion: number, appVersion: number, missingVersion: number) {\n    super(\n      `xopc database schema version ${dbVersion} requires migration to v${missingVersion}, ` +\n        `but no migration file is bundled with this app (supports up to v${appVersion}). ` +\n        'Upgrade xopc to a release that includes the missing migration.',\n    );\n    this.name = 'DatabaseSchemaMigrationGapError';\n    this.dbVersion = dbVersion;\n    this.appVersion = appVersion;\n    this.missingVersion = missingVersion;\n  }\n}\n"],"mappings":";AAAA,IAAa,4BAAb,cAA+C,MAAM;CACnD;CACA;CAEA,YAAY,WAAmB,YAAoB;AACjD,QACE,gCAAgC,UAAU,oCAAoC,WAAW,oEAE1F;AACD,OAAK,OAAO;AACZ,OAAK,YAAY;AACjB,OAAK,aAAa;;;AAItB,IAAa,kCAAb,cAAqD,MAAM;CACzD;CACA;CACA;CAEA,YAAY,WAAmB,YAAoB,gBAAwB;AACzE,QACE,gCAAgC,UAAU,0BAA0B,eAAe,oEACd,WAAW,mEAEjF;AACD,OAAK,OAAO;AACZ,OAAK,YAAY;AACjB,OAAK,aAAa;AAClB,OAAK,iBAAiB"}

package/dist/src/storage/sqlite/migrations/errors.ts

@@ -0,0 +1,32 @@
+export class DatabaseSchemaTooNewError extends Error {
+  readonly dbVersion: number;
+  readonly appVersion: number;
+
+  constructor(dbVersion: number, appVersion: number) {
+    super(
+      `xopc database schema version ${dbVersion} is newer than this app supports (${appVersion}). ` +
+        'Upgrade xopc to a newer release or restore xopc.db from backup.',
+    );
+    this.name = 'DatabaseSchemaTooNewError';
+    this.dbVersion = dbVersion;
+    this.appVersion = appVersion;
+  }
+}
+
+export class DatabaseSchemaMigrationGapError extends Error {
+  readonly dbVersion: number;
+  readonly appVersion: number;
+  readonly missingVersion: number;
+
+  constructor(dbVersion: number, appVersion: number, missingVersion: number) {
+    super(
+      `xopc database schema version ${dbVersion} requires migration to v${missingVersion}, ` +
+        `but no migration file is bundled with this app (supports up to v${appVersion}). ` +
+        'Upgrade xopc to a release that includes the missing migration.',
+    );
+    this.name = 'DatabaseSchemaMigrationGapError';
+    this.dbVersion = dbVersion;
+    this.appVersion = appVersion;
+    this.missingVersion = missingVersion;
+  }
+}

package/dist/src/storage/sqlite/migrations/runner.d.ts

@@ -0,0 +1,22 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ApplyMigrationsOptions } from './types.js';
+/** Baseline schema version applied from schema.sql on first open. */
+export declare const XOPC_DB_BASELINE_SCHEMA_VERSION = 2;
+/** Latest schema version this release supports (increment when adding migrations). */
+export declare const XOPC_DB_SCHEMA_VERSION = 2;
+export declare function resolveMigrationsDir(override?: string): string;
+/**
+ * Apply sequential SQL migrations from (currentVersion + 1) through targetVersion.
+ * Each step runs in its own transaction and updates schema_meta on success.
+ */
+export declare function applyPendingMigrations(db: DatabaseSync, options?: ApplyMigrationsOptions): number;
+export type SchemaMigrationStatus = {
+    dbVersion: number;
+    appVersion: number;
+    pendingVersions: number[];
+    isTooNew: boolean;
+    hasMigrationGap: boolean;
+    missingVersion: number | null;
+};
+/** Inspect schema version without mutating the database. */
+export declare function inspectSchemaMigrationStatus(db: DatabaseSync, options?: Pick<ApplyMigrationsOptions, 'migrationsDir' | 'targetVersion'>): SchemaMigrationStatus;

package/dist/src/storage/sqlite/migrations/runner.js

@@ -0,0 +1,97 @@
+import { createLogger } from "../../../utils/logger/index.js";
+import { init_logger } from "../../../utils/logger.js";
+import { readSchemaVersion, setSchemaVersion } from "../schema-version.js";
+import { discoverSqlMigrations } from "./discover.js";
+import { DatabaseSchemaMigrationGapError, DatabaseSchemaTooNewError } from "./errors.js";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+//#region src/storage/sqlite/migrations/runner.ts
+init_logger();
+const log = createLogger("Sqlite:Migrations");
+/** Baseline schema version applied from schema.sql on first open. */
+const XOPC_DB_BASELINE_SCHEMA_VERSION = 2;
+/** Latest schema version this release supports (increment when adding migrations). */
+const XOPC_DB_SCHEMA_VERSION = 2;
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+function resolveMigrationsDir(override) {
+	if (override) return override;
+	const siblingDir = join(MODULE_DIR, "migrations");
+	if (existsSync(siblingDir)) return siblingDir;
+	return MODULE_DIR;
+}
+function migrationByTarget(migrations, targetVersion) {
+	return migrations.find((migration) => migration.targetVersion === targetVersion);
+}
+function applySingleMigration(db, migration) {
+	log.info({
+		targetVersion: migration.targetVersion,
+		file: migration.filename
+	}, "Applying SQLite migration");
+	db.exec("BEGIN IMMEDIATE");
+	try {
+		db.exec(migration.sql);
+		setSchemaVersion(db, migration.targetVersion);
+		db.exec("COMMIT");
+	} catch (error) {
+		try {
+			db.exec("ROLLBACK");
+		} catch {}
+		const em = error instanceof Error ? error.message : String(error);
+		throw new Error(`SQLite migration to v${migration.targetVersion} (${migration.filename}) failed: ${em}`, { cause: error });
+	}
+}
+/**
+* Apply sequential SQL migrations from (currentVersion + 1) through targetVersion.
+* Each step runs in its own transaction and updates schema_meta on success.
+*/
+function applyPendingMigrations(db, options = {}) {
+	const targetVersion = options.targetVersion ?? 2;
+	let currentVersion = readSchemaVersion(db);
+	if (currentVersion > targetVersion) throw new DatabaseSchemaTooNewError(currentVersion, targetVersion);
+	if (currentVersion >= targetVersion) return currentVersion;
+	const migrations = discoverSqlMigrations(resolveMigrationsDir(options.migrationsDir));
+	while (currentVersion < targetVersion) {
+		const nextVersion = currentVersion + 1;
+		const migration = migrationByTarget(migrations, nextVersion);
+		if (!migration) throw new DatabaseSchemaMigrationGapError(currentVersion, targetVersion, nextVersion);
+		applySingleMigration(db, migration);
+		currentVersion = nextVersion;
+	}
+	return currentVersion;
+}
+/** Inspect schema version without mutating the database. */
+function inspectSchemaMigrationStatus(db, options = {}) {
+	const appVersion = options.targetVersion ?? 2;
+	const dbVersion = readSchemaVersion(db);
+	if (dbVersion > appVersion) return {
+		dbVersion,
+		appVersion,
+		pendingVersions: [],
+		isTooNew: true,
+		hasMigrationGap: false,
+		missingVersion: null
+	};
+	const migrations = discoverSqlMigrations(resolveMigrationsDir(options.migrationsDir));
+	const pendingVersions = [];
+	let hasMigrationGap = false;
+	let missingVersion = null;
+	for (let version = dbVersion + 1; version <= appVersion; version++) if (migrationByTarget(migrations, version)) pendingVersions.push(version);
+	else {
+		hasMigrationGap = true;
+		missingVersion = version;
+		break;
+	}
+	return {
+		dbVersion,
+		appVersion,
+		pendingVersions,
+		isTooNew: false,
+		hasMigrationGap,
+		missingVersion
+	};
+}
+//#endregion
+export { XOPC_DB_BASELINE_SCHEMA_VERSION, XOPC_DB_SCHEMA_VERSION, applyPendingMigrations, inspectSchemaMigrationStatus, resolveMigrationsDir };
+
+//# sourceMappingURL=runner.js.map

package/dist/src/storage/sqlite/migrations/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","names":[],"sources":["../../../../../src/storage/sqlite/migrations/runner.ts"],"sourcesContent":["import { existsSync } from 'node:fs';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nimport type { DatabaseSync } from 'node:sqlite';\n\nimport { createLogger } from '../../../utils/logger.js';\nimport { readSchemaVersion, setSchemaVersion } from '../schema-version.js';\nimport { discoverSqlMigrations } from './discover.js';\nimport {\n  DatabaseSchemaMigrationGapError,\n  DatabaseSchemaTooNewError,\n} from './errors.js';\nimport type { ApplyMigrationsOptions, SqlMigration } from './types.js';\n\nconst log = createLogger('Sqlite:Migrations');\n\n/** Baseline schema version applied from schema.sql on first open. */\nexport const XOPC_DB_BASELINE_SCHEMA_VERSION = 2;\n\n/** Latest schema version this release supports (increment when adding migrations). */\nexport const XOPC_DB_SCHEMA_VERSION = 2;\n\nconst MODULE_DIR = dirname(fileURLToPath(import.meta.url));\n\nexport function resolveMigrationsDir(override?: string): string {\n  if (override) {\n    return override;\n  }\n  // Packaged Electron gateway bundle: `out/server/index.js` + `out/server/migrations/`.\n  const siblingDir = join(MODULE_DIR, 'migrations');\n  if (existsSync(siblingDir)) {\n    return siblingDir;\n  }\n  // Dev / dist: SQL files live next to `migrations/runner.js`.\n  return MODULE_DIR;\n}\n\nfunction migrationByTarget(\n  migrations: SqlMigration[],\n  targetVersion: number,\n): SqlMigration | undefined {\n  return migrations.find((migration) => migration.targetVersion === targetVersion);\n}\n\nfunction applySingleMigration(db: DatabaseSync, migration: SqlMigration): void {\n  log.info({ targetVersion: migration.targetVersion, file: migration.filename }, 'Applying SQLite migration');\n  db.exec('BEGIN IMMEDIATE');\n  try {\n    db.exec(migration.sql);\n    setSchemaVersion(db, migration.targetVersion);\n    db.exec('COMMIT');\n  } catch (error) {\n    try {\n      db.exec('ROLLBACK');\n    } catch {\n      /* preserve original error */\n    }\n    const em = error instanceof Error ? error.message : String(error);\n    throw new Error(\n      `SQLite migration to v${migration.targetVersion} (${migration.filename}) failed: ${em}`,\n      { cause: error },\n    );\n  }\n}\n\n/**\n * Apply sequential SQL migrations from (currentVersion + 1) through targetVersion.\n * Each step runs in its own transaction and updates schema_meta on success.\n */\nexport function applyPendingMigrations(\n  db: DatabaseSync,\n  options: ApplyMigrationsOptions = {},\n): number {\n  const targetVersion = options.targetVersion ?? XOPC_DB_SCHEMA_VERSION;\n  let currentVersion = readSchemaVersion(db);\n\n  if (currentVersion > targetVersion) {\n    throw new DatabaseSchemaTooNewError(currentVersion, targetVersion);\n  }\n\n  if (currentVersion >= targetVersion) {\n    return currentVersion;\n  }\n\n  const migrations = discoverSqlMigrations(resolveMigrationsDir(options.migrationsDir));\n\n  while (currentVersion < targetVersion) {\n    const nextVersion = currentVersion + 1;\n    const migration = migrationByTarget(migrations, nextVersion);\n    if (!migration) {\n      throw new DatabaseSchemaMigrationGapError(currentVersion, targetVersion, nextVersion);\n    }\n    applySingleMigration(db, migration);\n    currentVersion = nextVersion;\n  }\n\n  return currentVersion;\n}\n\nexport type SchemaMigrationStatus = {\n  dbVersion: number;\n  appVersion: number;\n  pendingVersions: number[];\n  isTooNew: boolean;\n  hasMigrationGap: boolean;\n  missingVersion: number | null;\n};\n\n/** Inspect schema version without mutating the database. */\nexport function inspectSchemaMigrationStatus(\n  db: DatabaseSync,\n  options: Pick<ApplyMigrationsOptions, 'migrationsDir' | 'targetVersion'> = {},\n): SchemaMigrationStatus {\n  const appVersion = options.targetVersion ?? XOPC_DB_SCHEMA_VERSION;\n  const dbVersion = readSchemaVersion(db);\n  const isTooNew = dbVersion > appVersion;\n\n  if (isTooNew) {\n    return {\n      dbVersion,\n      appVersion,\n      pendingVersions: [],\n      isTooNew: true,\n      hasMigrationGap: false,\n      missingVersion: null,\n    };\n  }\n\n  const migrations = discoverSqlMigrations(resolveMigrationsDir(options.migrationsDir));\n  const pendingVersions: number[] = [];\n  let hasMigrationGap = false;\n  let missingVersion: number | null = null;\n\n  for (let version = dbVersion + 1; version <= appVersion; version++) {\n    if (migrationByTarget(migrations, version)) {\n      pendingVersions.push(version);\n    } else {\n      hasMigrationGap = true;\n      missingVersion = version;\n      break;\n    }\n  }\n\n  return {\n    dbVersion,\n    appVersion,\n    pendingVersions,\n    isTooNew: false,\n    hasMigrationGap,\n    missingVersion,\n  };\n}\n"],"mappings":";;;;;;;;;aAMwD;AASxD,MAAM,MAAM,aAAa,oBAAoB;;AAG7C,MAAa,kCAAkC;;AAG/C,MAAa,yBAAyB;AAEtC,MAAM,aAAa,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC;AAE1D,SAAgB,qBAAqB,UAA2B;AAC9D,KAAI,SACF,QAAO;CAGT,MAAM,aAAa,KAAK,YAAY,aAAa;AACjD,KAAI,WAAW,WAAW,CACxB,QAAO;AAGT,QAAO;;AAGT,SAAS,kBACP,YACA,eAC0B;AAC1B,QAAO,WAAW,MAAM,cAAc,UAAU,kBAAkB,cAAc;;AAGlF,SAAS,qBAAqB,IAAkB,WAA+B;AAC7E,KAAI,KAAK;EAAE,eAAe,UAAU;EAAe,MAAM,UAAU;EAAU,EAAE,4BAA4B;AAC3G,IAAG,KAAK,kBAAkB;AAC1B,KAAI;AACF,KAAG,KAAK,UAAU,IAAI;AACtB,mBAAiB,IAAI,UAAU,cAAc;AAC7C,KAAG,KAAK,SAAS;UACV,OAAO;AACd,MAAI;AACF,MAAG,KAAK,WAAW;UACb;EAGR,MAAM,KAAK,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AACjE,QAAM,IAAI,MACR,wBAAwB,UAAU,cAAc,IAAI,UAAU,SAAS,YAAY,MACnF,EAAE,OAAO,OAAO,CACjB;;;;;;;AAQL,SAAgB,uBACd,IACA,UAAkC,EAAE,EAC5B;CACR,MAAM,gBAAgB,QAAQ,iBAAA;CAC9B,IAAI,iBAAiB,kBAAkB,GAAG;AAE1C,KAAI,iBAAiB,cACnB,OAAM,IAAI,0BAA0B,gBAAgB,cAAc;AAGpE,KAAI,kBAAkB,cACpB,QAAO;CAGT,MAAM,aAAa,sBAAsB,qBAAqB,QAAQ,cAAc,CAAC;AAErF,QAAO,iBAAiB,eAAe;EACrC,MAAM,cAAc,iBAAiB;EACrC,MAAM,YAAY,kBAAkB,YAAY,YAAY;AAC5D,MAAI,CAAC,UACH,OAAM,IAAI,gCAAgC,gBAAgB,eAAe,YAAY;AAEvF,uBAAqB,IAAI,UAAU;AACnC,mBAAiB;;AAGnB,QAAO;;;AAaT,SAAgB,6BACd,IACA,UAA2E,EAAE,EACtD;CACvB,MAAM,aAAa,QAAQ,iBAAA;CAC3B,MAAM,YAAY,kBAAkB,GAAG;AAGvC,KAFiB,YAAY,WAG3B,QAAO;EACL;EACA;EACA,iBAAiB,EAAE;EACnB,UAAU;EACV,iBAAiB;EACjB,gBAAgB;EACjB;CAGH,MAAM,aAAa,sBAAsB,qBAAqB,QAAQ,cAAc,CAAC;CACrF,MAAM,kBAA4B,EAAE;CACpC,IAAI,kBAAkB;CACtB,IAAI,iBAAgC;AAEpC,MAAK,IAAI,UAAU,YAAY,GAAG,WAAW,YAAY,UACvD,KAAI,kBAAkB,YAAY,QAAQ,CACxC,iBAAgB,KAAK,QAAQ;MACxB;AACL,oBAAkB;AAClB,mBAAiB;AACjB;;AAIJ,QAAO;EACL;EACA;EACA;EACA,UAAU;EACV;EACA;EACD"}

package/dist/src/storage/sqlite/migrations/runner.ts

@@ -0,0 +1,153 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { DatabaseSync } from 'node:sqlite';
+
+import { createLogger } from '../../../utils/logger.js';
+import { readSchemaVersion, setSchemaVersion } from '../schema-version.js';
+import { discoverSqlMigrations } from './discover.js';
+import {
+  DatabaseSchemaMigrationGapError,
+  DatabaseSchemaTooNewError,
+} from './errors.js';
+import type { ApplyMigrationsOptions, SqlMigration } from './types.js';
+
+const log = createLogger('Sqlite:Migrations');
+
+/** Baseline schema version applied from schema.sql on first open. */
+export const XOPC_DB_BASELINE_SCHEMA_VERSION = 2;
+
+/** Latest schema version this release supports (increment when adding migrations). */
+export const XOPC_DB_SCHEMA_VERSION = 2;
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+
+export function resolveMigrationsDir(override?: string): string {
+  if (override) {
+    return override;
+  }
+  // Packaged Electron gateway bundle: `out/server/index.js` + `out/server/migrations/`.
+  const siblingDir = join(MODULE_DIR, 'migrations');
+  if (existsSync(siblingDir)) {
+    return siblingDir;
+  }
+  // Dev / dist: SQL files live next to `migrations/runner.js`.
+  return MODULE_DIR;
+}
+
+function migrationByTarget(
+  migrations: SqlMigration[],
+  targetVersion: number,
+): SqlMigration | undefined {
+  return migrations.find((migration) => migration.targetVersion === targetVersion);
+}
+
+function applySingleMigration(db: DatabaseSync, migration: SqlMigration): void {
+  log.info({ targetVersion: migration.targetVersion, file: migration.filename }, 'Applying SQLite migration');
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    db.exec(migration.sql);
+    setSchemaVersion(db, migration.targetVersion);
+    db.exec('COMMIT');
+  } catch (error) {
+    try {
+      db.exec('ROLLBACK');
+    } catch {
+      /* preserve original error */
+    }
+    const em = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `SQLite migration to v${migration.targetVersion} (${migration.filename}) failed: ${em}`,
+      { cause: error },
+    );
+  }
+}
+
+/**
+ * Apply sequential SQL migrations from (currentVersion + 1) through targetVersion.
+ * Each step runs in its own transaction and updates schema_meta on success.
+ */
+export function applyPendingMigrations(
+  db: DatabaseSync,
+  options: ApplyMigrationsOptions = {},
+): number {
+  const targetVersion = options.targetVersion ?? XOPC_DB_SCHEMA_VERSION;
+  let currentVersion = readSchemaVersion(db);
+
+  if (currentVersion > targetVersion) {
+    throw new DatabaseSchemaTooNewError(currentVersion, targetVersion);
+  }
+
+  if (currentVersion >= targetVersion) {
+    return currentVersion;
+  }
+
+  const migrations = discoverSqlMigrations(resolveMigrationsDir(options.migrationsDir));
+
+  while (currentVersion < targetVersion) {
+    const nextVersion = currentVersion + 1;
+    const migration = migrationByTarget(migrations, nextVersion);
+    if (!migration) {
+      throw new DatabaseSchemaMigrationGapError(currentVersion, targetVersion, nextVersion);
+    }
+    applySingleMigration(db, migration);
+    currentVersion = nextVersion;
+  }
+
+  return currentVersion;
+}
+
+export type SchemaMigrationStatus = {
+  dbVersion: number;
+  appVersion: number;
+  pendingVersions: number[];
+  isTooNew: boolean;
+  hasMigrationGap: boolean;
+  missingVersion: number | null;
+};
+
+/** Inspect schema version without mutating the database. */
+export function inspectSchemaMigrationStatus(
+  db: DatabaseSync,
+  options: Pick<ApplyMigrationsOptions, 'migrationsDir' | 'targetVersion'> = {},
+): SchemaMigrationStatus {
+  const appVersion = options.targetVersion ?? XOPC_DB_SCHEMA_VERSION;
+  const dbVersion = readSchemaVersion(db);
+  const isTooNew = dbVersion > appVersion;
+
+  if (isTooNew) {
+    return {
+      dbVersion,
+      appVersion,
+      pendingVersions: [],
+      isTooNew: true,
+      hasMigrationGap: false,
+      missingVersion: null,
+    };
+  }
+
+  const migrations = discoverSqlMigrations(resolveMigrationsDir(options.migrationsDir));
+  const pendingVersions: number[] = [];
+  let hasMigrationGap = false;
+  let missingVersion: number | null = null;
+
+  for (let version = dbVersion + 1; version <= appVersion; version++) {
+    if (migrationByTarget(migrations, version)) {
+      pendingVersions.push(version);
+    } else {
+      hasMigrationGap = true;
+      missingVersion = version;
+      break;
+    }
+  }
+
+  return {
+    dbVersion,
+    appVersion,
+    pendingVersions,
+    isTooNew: false,
+    hasMigrationGap,
+    missingVersion,
+  };
+}

package/dist/src/storage/sqlite/migrations/types.d.ts

@@ -0,0 +1,12 @@
+/** One on-disk SQL migration file (target schema version after apply). */
+export type SqlMigration = {
+    targetVersion: number;
+    filename: string;
+    sql: string;
+};
+export type ApplyMigrationsOptions = {
+    /** Override migrations directory (tests). Defaults to `<schema-module>/migrations`. */
+    migrationsDir?: string;
+    /** Target schema version. Defaults to {@link XOPC_DB_SCHEMA_VERSION}. */
+    targetVersion?: number;
+};

package/dist/src/storage/sqlite/migrations/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/storage/sqlite/migrations/types.ts

@@ -0,0 +1,13 @@
+/** One on-disk SQL migration file (target schema version after apply). */
+export type SqlMigration = {
+  targetVersion: number;
+  filename: string;
+  sql: string;
+};
+
+export type ApplyMigrationsOptions = {
+  /** Override migrations directory (tests). Defaults to `<schema-module>/migrations`. */
+  migrationsDir?: string;
+  /** Target schema version. Defaults to {@link XOPC_DB_SCHEMA_VERSION}. */
+  targetVersion?: number;
+};

package/dist/src/storage/sqlite/row-mappers.d.ts

@@ -23,6 +23,8 @@ export type SessionRow = {
     message_count: number;
     estimated_tokens: number;
     compacted_count: number;
+    last_flushed_at: string | null;
+    flush_count: number;
     thinking_level: string | null;
     verbose_level: string | null;
 };
@@ -68,6 +70,8 @@ export declare function metadataToSessionInsert(sessionKey: string, transcriptId
     messageCount: number;
     estimatedTokens: number;
     compactedCount: number;
+    lastFlushedAt: string | null;
+    flushCount: number;
     thinkingLevel: string | null;
     verboseLevel: string | null;
 };

package/dist/src/storage/sqlite/row-mappers.js

@@ -45,6 +45,8 @@ function sessionRowToMetadata(sessionKey, row) {
 		messageCount: row.message_count,
 		estimatedTokens: row.estimated_tokens,
 		compactedCount: row.compacted_count,
+		lastFlushedAt: row.last_flushed_at ?? void 0,
+		flushCount: row.flush_count,
 		transcriptId: row.current_transcript_id,
 		stats: {
 			messageCount: row.message_count,
@@ -76,6 +78,8 @@ function metadataToSessionInsert(sessionKey, transcriptId, metadata, thinkingLev
 		messageCount: metadata.messageCount,
 		estimatedTokens: metadata.estimatedTokens,
 		compactedCount: metadata.compactedCount,
+		lastFlushedAt: metadata.lastFlushedAt ?? null,
+		flushCount: metadata.flushCount ?? 0,
 		thinkingLevel: thinkingLevel ?? null,
 		verboseLevel: verboseLevel ?? null
 	};