scene-capability-engine 3.6.3 → 3.6.5

package/lib/state/sce-state-store.js

@@ -21,6 +21,31 @@ function normalizeInteger(value, fallback = 0) {
   return parsed;
 }
 
+function normalizeBooleanValue(value, fallback = false) {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  const normalized = normalizeString(`${value || ''}`).toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) {
+    return false;
+  }
+  return fallback;
+}
+
+function normalizeNonNegativeInteger(value, fallback = 0) {
+  const parsed = Number.parseInt(`${value}`, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
 function parseJsonSafe(value, fallback) {
   if (typeof value !== 'string' || !value.trim()) {
     return fallback;
@@ -105,6 +130,14 @@ class SceStateStore {
       specs: {},
       tasks: {},
       refs: {},
+      timeline_snapshots: {},
+      scene_session_cycles: {},
+      agent_runtime: {},
+      errorbook_entry_index: {},
+      errorbook_incident_index: {},
+      governance_spec_scene_override: {},
+      governance_scene_index: {},
+      migration_records: {},
       auth_leases: {},
       auth_events: [],
       sequences: {
@@ -238,6 +271,142 @@ class SceStateStore {
 
       CREATE INDEX IF NOT EXISTS idx_auth_event_stream_ts
         ON auth_event_stream(event_timestamp);
+
+      CREATE TABLE IF NOT EXISTS timeline_snapshot_registry (
+        snapshot_id TEXT PRIMARY KEY,
+        created_at TEXT NOT NULL,
+        trigger TEXT,
+        event TEXT,
+        summary TEXT,
+        scene_id TEXT,
+        session_id TEXT,
+        command TEXT,
+        file_count INTEGER,
+        total_bytes INTEGER,
+        snapshot_path TEXT,
+        git_json TEXT,
+        source TEXT,
+        updated_at TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_timeline_snapshot_registry_created
+        ON timeline_snapshot_registry(created_at DESC);
+
+      CREATE TABLE IF NOT EXISTS scene_session_cycle_registry (
+        scene_id TEXT NOT NULL,
+        cycle INTEGER NOT NULL,
+        session_id TEXT NOT NULL,
+        status TEXT,
+        started_at TEXT,
+        completed_at TEXT,
+        source TEXT,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (scene_id, cycle)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_scene_session_cycle_registry_session
+        ON scene_session_cycle_registry(session_id);
+
+      CREATE TABLE IF NOT EXISTS agent_runtime_registry (
+        agent_id TEXT PRIMARY KEY,
+        machine_id TEXT,
+        instance_index INTEGER,
+        hostname TEXT,
+        registered_at TEXT,
+        last_heartbeat TEXT,
+        status TEXT,
+        current_task_json TEXT,
+        source TEXT,
+        updated_at TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_agent_runtime_registry_status
+        ON agent_runtime_registry(status);
+
+      CREATE TABLE IF NOT EXISTS state_migration_registry (
+        migration_id TEXT PRIMARY KEY,
+        component_id TEXT NOT NULL,
+        source_path TEXT,
+        mode TEXT NOT NULL,
+        status TEXT NOT NULL,
+        metrics_json TEXT,
+        detail_json TEXT,
+        started_at TEXT NOT NULL,
+        completed_at TEXT,
+        updated_at TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_state_migration_registry_component_started
+        ON state_migration_registry(component_id, started_at DESC);
+
+      CREATE TABLE IF NOT EXISTS errorbook_entry_index_registry (
+        entry_id TEXT PRIMARY KEY,
+        fingerprint TEXT,
+        title TEXT,
+        status TEXT,
+        quality_score INTEGER,
+        tags_json TEXT,
+        ontology_tags_json TEXT,
+        temporary_mitigation_active INTEGER,
+        temporary_mitigation_deadline_at TEXT,
+        occurrences INTEGER,
+        created_at TEXT,
+        updated_at TEXT,
+        source TEXT,
+        indexed_at TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_errorbook_entry_index_registry_status_updated
+        ON errorbook_entry_index_registry(status, updated_at DESC);
+
+      CREATE TABLE IF NOT EXISTS errorbook_incident_index_registry (
+        incident_id TEXT PRIMARY KEY,
+        fingerprint TEXT,
+        title TEXT,
+        symptom TEXT,
+        state TEXT,
+        attempt_count INTEGER,
+        created_at TEXT,
+        updated_at TEXT,
+        last_attempt_at TEXT,
+        resolved_at TEXT,
+        linked_entry_id TEXT,
+        source TEXT,
+        indexed_at TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_errorbook_incident_index_registry_state_updated
+        ON errorbook_incident_index_registry(state, updated_at DESC);
+
+      CREATE TABLE IF NOT EXISTS governance_spec_scene_override_registry (
+        spec_id TEXT PRIMARY KEY,
+        scene_id TEXT NOT NULL,
+        source TEXT,
+        rule_id TEXT,
+        updated_at TEXT,
+        indexed_at TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_governance_spec_scene_override_registry_scene
+        ON governance_spec_scene_override_registry(scene_id, updated_at DESC);
+
+      CREATE TABLE IF NOT EXISTS governance_scene_index_registry (
+        scene_id TEXT PRIMARY KEY,
+        total_specs INTEGER,
+        active_specs INTEGER,
+        completed_specs INTEGER,
+        stale_specs INTEGER,
+        spec_ids_json TEXT,
+        active_spec_ids_json TEXT,
+        stale_spec_ids_json TEXT,
+        generated_at TEXT,
+        scene_filter TEXT,
+        source TEXT,
+        indexed_at TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_governance_scene_index_registry_counts
+        ON governance_scene_index_registry(total_specs DESC, active_specs DESC);
     `);
   }
 
@@ -358,6 +527,157 @@ class SceStateStore {
     };
   }
 
+  _mapTimelineSnapshotRow(row) {
+    if (!row) {
+      return null;
+    }
+    return {
+      snapshot_id: normalizeString(row.snapshot_id),
+      created_at: normalizeIsoTimestamp(row.created_at) || null,
+      trigger: normalizeString(row.trigger) || null,
+      event: normalizeString(row.event) || null,
+      summary: normalizeString(row.summary) || null,
+      scene_id: normalizeString(row.scene_id) || null,
+      session_id: normalizeString(row.session_id) || null,
+      command: normalizeString(row.command) || null,
+      file_count: normalizeNonNegativeInteger(row.file_count, 0),
+      total_bytes: normalizeNonNegativeInteger(row.total_bytes, 0),
+      snapshot_path: normalizeString(row.snapshot_path) || null,
+      git: parseJsonSafe(row.git_json, {}) || {},
+      source: normalizeString(row.source) || null,
+      updated_at: normalizeIsoTimestamp(row.updated_at) || null
+    };
+  }
+
+  _mapSceneSessionCycleRow(row) {
+    if (!row) {
+      return null;
+    }
+    return {
+      scene_id: normalizeString(row.scene_id),
+      cycle: normalizeNonNegativeInteger(row.cycle, 0),
+      session_id: normalizeString(row.session_id),
+      status: normalizeString(row.status) || null,
+      started_at: normalizeIsoTimestamp(row.started_at) || null,
+      completed_at: normalizeIsoTimestamp(row.completed_at) || null,
+      source: normalizeString(row.source) || null,
+      updated_at: normalizeIsoTimestamp(row.updated_at) || null
+    };
+  }
+
+  _mapAgentRuntimeRow(row) {
+    if (!row) {
+      return null;
+    }
+    return {
+      agent_id: normalizeString(row.agent_id),
+      machine_id: normalizeString(row.machine_id) || null,
+      instance_index: normalizeNonNegativeInteger(row.instance_index, 0),
+      hostname: normalizeString(row.hostname) || null,
+      registered_at: normalizeIsoTimestamp(row.registered_at) || null,
+      last_heartbeat: normalizeIsoTimestamp(row.last_heartbeat) || null,
+      status: normalizeString(row.status) || null,
+      current_task: parseJsonSafe(row.current_task_json, null),
+      source: normalizeString(row.source) || null,
+      updated_at: normalizeIsoTimestamp(row.updated_at) || null
+    };
+  }
+
+  _mapStateMigrationRow(row) {
+    if (!row) {
+      return null;
+    }
+    return {
+      migration_id: normalizeString(row.migration_id),
+      component_id: normalizeString(row.component_id),
+      source_path: normalizeString(row.source_path) || null,
+      mode: normalizeString(row.mode) || null,
+      status: normalizeString(row.status) || null,
+      metrics: parseJsonSafe(row.metrics_json, {}) || {},
+      detail: parseJsonSafe(row.detail_json, {}) || {},
+      started_at: normalizeIsoTimestamp(row.started_at) || null,
+      completed_at: normalizeIsoTimestamp(row.completed_at) || null,
+      updated_at: normalizeIsoTimestamp(row.updated_at) || null
+    };
+  }
+
+  _mapErrorbookEntryIndexRow(row) {
+    if (!row) {
+      return null;
+    }
+    return {
+      entry_id: normalizeString(row.entry_id),
+      fingerprint: normalizeString(row.fingerprint) || null,
+      title: normalizeString(row.title) || null,
+      status: normalizeString(row.status) || null,
+      quality_score: normalizeNonNegativeInteger(row.quality_score, 0),
+      tags: normalizeStringArray(parseJsonSafe(row.tags_json, []), []),
+      ontology_tags: normalizeStringArray(parseJsonSafe(row.ontology_tags_json, []), []),
+      temporary_mitigation_active: Number(row.temporary_mitigation_active) === 1,
+      temporary_mitigation_deadline_at: normalizeIsoTimestamp(row.temporary_mitigation_deadline_at, '') || null,
+      occurrences: normalizeNonNegativeInteger(row.occurrences, 0),
+      created_at: normalizeIsoTimestamp(row.created_at, '') || null,
+      updated_at: normalizeIsoTimestamp(row.updated_at, '') || null,
+      source: normalizeString(row.source) || null,
+      indexed_at: normalizeIsoTimestamp(row.indexed_at, '') || null
+    };
+  }
+
+  _mapErrorbookIncidentIndexRow(row) {
+    if (!row) {
+      return null;
+    }
+    return {
+      incident_id: normalizeString(row.incident_id),
+      fingerprint: normalizeString(row.fingerprint) || null,
+      title: normalizeString(row.title) || null,
+      symptom: normalizeString(row.symptom) || null,
+      state: normalizeString(row.state) || null,
+      attempt_count: normalizeNonNegativeInteger(row.attempt_count, 0),
+      created_at: normalizeIsoTimestamp(row.created_at, '') || null,
+      updated_at: normalizeIsoTimestamp(row.updated_at, '') || null,
+      last_attempt_at: normalizeIsoTimestamp(row.last_attempt_at, '') || null,
+      resolved_at: normalizeIsoTimestamp(row.resolved_at, '') || null,
+      linked_entry_id: normalizeString(row.linked_entry_id) || null,
+      source: normalizeString(row.source) || null,
+      indexed_at: normalizeIsoTimestamp(row.indexed_at, '') || null
+    };
+  }
+
+  _mapGovernanceSpecSceneOverrideRow(row) {
+    if (!row) {
+      return null;
+    }
+    return {
+      spec_id: normalizeString(row.spec_id),
+      scene_id: normalizeString(row.scene_id),
+      source: normalizeString(row.source) || null,
+      rule_id: normalizeString(row.rule_id) || null,
+      updated_at: normalizeIsoTimestamp(row.updated_at, '') || null,
+      indexed_at: normalizeIsoTimestamp(row.indexed_at, '') || null
+    };
+  }
+
+  _mapGovernanceSceneIndexRow(row) {
+    if (!row) {
+      return null;
+    }
+    return {
+      scene_id: normalizeString(row.scene_id),
+      total_specs: normalizeNonNegativeInteger(row.total_specs, 0),
+      active_specs: normalizeNonNegativeInteger(row.active_specs, 0),
+      completed_specs: normalizeNonNegativeInteger(row.completed_specs, 0),
+      stale_specs: normalizeNonNegativeInteger(row.stale_specs, 0),
+      spec_ids: normalizeStringArray(parseJsonSafe(row.spec_ids_json, []), []),
+      active_spec_ids: normalizeStringArray(parseJsonSafe(row.active_spec_ids_json, []), []),
+      stale_spec_ids: normalizeStringArray(parseJsonSafe(row.stale_spec_ids_json, []), []),
+      generated_at: normalizeIsoTimestamp(row.generated_at, '') || null,
+      scene_filter: normalizeString(row.scene_filter) || null,
+      source: normalizeString(row.source) || null,
+      indexed_at: normalizeIsoTimestamp(row.indexed_at, '') || null
+    };
+  }
+
   async resolveOrCreateTaskRef(options = {}) {
     const sceneId = normalizeString(options.sceneId);
     const specId = normalizeString(options.specId);
@@ -885,6 +1205,966 @@ class SceStateStore {
       .filter(Boolean);
   }
 
+  async upsertTimelineSnapshotIndex(records = [], options = {}) {
+    const source = normalizeString(options.source) || 'file.timeline.index';
+    const nowIso = this.now();
+    const normalizedRecords = Array.isArray(records)
+      ? records.map((item) => ({
+        snapshot_id: normalizeString(item && item.snapshot_id),
+        created_at: normalizeIsoTimestamp(item && item.created_at, nowIso) || nowIso,
+        trigger: normalizeString(item && item.trigger) || null,
+        event: normalizeString(item && item.event) || null,
+        summary: normalizeString(item && item.summary) || null,
+        scene_id: normalizeString(item && item.scene_id) || null,
+        session_id: normalizeString(item && item.session_id) || null,
+        command: normalizeString(item && item.command) || null,
+        file_count: normalizeNonNegativeInteger(item && item.file_count, 0),
+        total_bytes: normalizeNonNegativeInteger(item && item.total_bytes, 0),
+        snapshot_path: normalizeString(item && (item.snapshot_path || item.path)) || null,
+        git: item && item.git && typeof item.git === 'object' ? item.git : {},
+        source,
+        updated_at: nowIso
+      }))
+        .filter((item) => item.snapshot_id)
+      : [];
+
+    if (this._useMemoryBackend()) {
+      for (const item of normalizedRecords) {
+        this._memory.timeline_snapshots[item.snapshot_id] = { ...item };
+      }
+      return {
+        success: true,
+        written: normalizedRecords.length,
+        total: Object.keys(this._memory.timeline_snapshots || {}).length
+      };
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    const statement = this._db.prepare(`
+      INSERT OR REPLACE INTO timeline_snapshot_registry(
+        snapshot_id, created_at, trigger, event, summary, scene_id, session_id, command,
+        file_count, total_bytes, snapshot_path, git_json, source, updated_at
+      )
+      VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    this._withTransaction(() => {
+      for (const item of normalizedRecords) {
+        statement.run(
+          item.snapshot_id,
+          item.created_at,
+          item.trigger,
+          item.event,
+          item.summary,
+          item.scene_id,
+          item.session_id,
+          item.command,
+          item.file_count,
+          item.total_bytes,
+          item.snapshot_path,
+          JSON.stringify(item.git || {}),
+          item.source,
+          item.updated_at
+        );
+      }
+    });
+
+    const totalRow = this._db
+      .prepare('SELECT COUNT(*) AS total FROM timeline_snapshot_registry')
+      .get();
+
+    return {
+      success: true,
+      written: normalizedRecords.length,
+      total: normalizeNonNegativeInteger(totalRow && totalRow.total, 0)
+    };
+  }
+
+  async listTimelineSnapshotIndex(options = {}) {
+    const limit = normalizeInteger(options.limit, 100);
+    const triggerFilter = normalizeString(options.trigger);
+    const snapshotIdFilter = normalizeString(options.snapshotId);
+
+    if (this._useMemoryBackend()) {
+      let rows = Object.values(this._memory.timeline_snapshots || {}).map((item) => ({ ...item }));
+      if (triggerFilter) {
+        rows = rows.filter((item) => normalizeString(item.trigger) === triggerFilter);
+      }
+      if (snapshotIdFilter) {
+        rows = rows.filter((item) => normalizeString(item.snapshot_id) === snapshotIdFilter);
+      }
+      rows.sort((left, right) => (Date.parse(right.created_at || '') || 0) - (Date.parse(left.created_at || '') || 0));
+      if (limit > 0) {
+        rows = rows.slice(0, limit);
+      }
+      return rows.map((row) => this._mapTimelineSnapshotRow({
+        ...row,
+        git_json: JSON.stringify(row.git || {})
+      }));
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    let query = `
+      SELECT snapshot_id, created_at, trigger, event, summary, scene_id, session_id, command,
+             file_count, total_bytes, snapshot_path, git_json, source, updated_at
+      FROM timeline_snapshot_registry
+    `;
+    const clauses = [];
+    const params = [];
+    if (triggerFilter) {
+      clauses.push('trigger = ?');
+      params.push(triggerFilter);
+    }
+    if (snapshotIdFilter) {
+      clauses.push('snapshot_id = ?');
+      params.push(snapshotIdFilter);
+    }
+    if (clauses.length > 0) {
+      query += ` WHERE ${clauses.join(' AND ')}`;
+    }
+    query += ' ORDER BY created_at DESC';
+    if (limit > 0) {
+      query += ' LIMIT ?';
+      params.push(limit);
+    }
+
+    const rows = this._db.prepare(query).all(...params);
+    return rows
+      .map((row) => this._mapTimelineSnapshotRow(row))
+      .filter(Boolean);
+  }
+
+  async upsertSceneSessionCycles(records = [], options = {}) {
+    const source = normalizeString(options.source) || 'file.session.scene-index';
+    const nowIso = this.now();
+    const normalizedRecords = Array.isArray(records)
+      ? records.map((item) => ({
+        scene_id: normalizeString(item && item.scene_id),
+        cycle: normalizeNonNegativeInteger(item && item.cycle, 0),
+        session_id: normalizeString(item && item.session_id),
+        status: normalizeString(item && item.status) || null,
+        started_at: normalizeIsoTimestamp(item && item.started_at, nowIso) || nowIso,
+        completed_at: normalizeIsoTimestamp(item && item.completed_at, '') || null,
+        source,
+        updated_at: nowIso
+      }))
+        .filter((item) => item.scene_id && item.cycle > 0 && item.session_id)
+      : [];
+
+    if (this._useMemoryBackend()) {
+      for (const item of normalizedRecords) {
+        const key = `${item.scene_id}::${item.cycle}`;
+        this._memory.scene_session_cycles[key] = { ...item };
+      }
+      return {
+        success: true,
+        written: normalizedRecords.length,
+        total: Object.keys(this._memory.scene_session_cycles || {}).length
+      };
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    const statement = this._db.prepare(`
+      INSERT OR REPLACE INTO scene_session_cycle_registry(
+        scene_id, cycle, session_id, status, started_at, completed_at, source, updated_at
+      )
+      VALUES(?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    this._withTransaction(() => {
+      for (const item of normalizedRecords) {
+        statement.run(
+          item.scene_id,
+          item.cycle,
+          item.session_id,
+          item.status,
+          item.started_at,
+          item.completed_at,
+          item.source,
+          item.updated_at
+        );
+      }
+    });
+
+    const totalRow = this._db
+      .prepare('SELECT COUNT(*) AS total FROM scene_session_cycle_registry')
+      .get();
+
+    return {
+      success: true,
+      written: normalizedRecords.length,
+      total: normalizeNonNegativeInteger(totalRow && totalRow.total, 0)
+    };
+  }
+
+  async listSceneSessionCycles(options = {}) {
+    const limit = normalizeInteger(options.limit, 100);
+    const sceneId = normalizeString(options.sceneId);
+
+    if (this._useMemoryBackend()) {
+      let rows = Object.values(this._memory.scene_session_cycles || {}).map((item) => ({ ...item }));
+      if (sceneId) {
+        rows = rows.filter((item) => normalizeString(item.scene_id) === sceneId);
+      }
+      rows.sort((left, right) => {
+        const sceneCompare = `${left.scene_id}`.localeCompare(`${right.scene_id}`);
+        if (sceneCompare !== 0) {
+          return sceneCompare;
+        }
+        return right.cycle - left.cycle;
+      });
+      if (limit > 0) {
+        rows = rows.slice(0, limit);
+      }
+      return rows.map((row) => this._mapSceneSessionCycleRow(row));
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    let query = `
+      SELECT scene_id, cycle, session_id, status, started_at, completed_at, source, updated_at
+      FROM scene_session_cycle_registry
+    `;
+    const params = [];
+    if (sceneId) {
+      query += ' WHERE scene_id = ?';
+      params.push(sceneId);
+    }
+    query += ' ORDER BY scene_id ASC, cycle DESC';
+    if (limit > 0) {
+      query += ' LIMIT ?';
+      params.push(limit);
+    }
+
+    const rows = this._db.prepare(query).all(...params);
+    return rows
+      .map((row) => this._mapSceneSessionCycleRow(row))
+      .filter(Boolean);
+  }
+
+  async upsertAgentRuntimeRecords(records = [], options = {}) {
+    const source = normalizeString(options.source) || 'file.agent-registry';
+    const nowIso = this.now();
+    const normalizedRecords = Array.isArray(records)
+      ? records.map((item) => ({
+        agent_id: normalizeString(item && item.agent_id),
+        machine_id: normalizeString(item && item.machine_id) || null,
+        instance_index: normalizeNonNegativeInteger(item && item.instance_index, 0),
+        hostname: normalizeString(item && item.hostname) || null,
+        registered_at: normalizeIsoTimestamp(item && item.registered_at, nowIso) || nowIso,
+        last_heartbeat: normalizeIsoTimestamp(item && item.last_heartbeat, nowIso) || nowIso,
+        status: normalizeString(item && item.status) || null,
+        current_task: item && item.current_task && typeof item.current_task === 'object'
+          ? item.current_task
+          : null,
+        source,
+        updated_at: nowIso
+      }))
+        .filter((item) => item.agent_id)
+      : [];
+
+    if (this._useMemoryBackend()) {
+      for (const item of normalizedRecords) {
+        this._memory.agent_runtime[item.agent_id] = { ...item };
+      }
+      return {
+        success: true,
+        written: normalizedRecords.length,
+        total: Object.keys(this._memory.agent_runtime || {}).length
+      };
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    const statement = this._db.prepare(`
+      INSERT OR REPLACE INTO agent_runtime_registry(
+        agent_id, machine_id, instance_index, hostname, registered_at, last_heartbeat, status, current_task_json, source, updated_at
+      )
+      VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    this._withTransaction(() => {
+      for (const item of normalizedRecords) {
+        statement.run(
+          item.agent_id,
+          item.machine_id,
+          item.instance_index,
+          item.hostname,
+          item.registered_at,
+          item.last_heartbeat,
+          item.status,
+          JSON.stringify(item.current_task),
+          item.source,
+          item.updated_at
+        );
+      }
+    });
+
+    const totalRow = this._db
+      .prepare('SELECT COUNT(*) AS total FROM agent_runtime_registry')
+      .get();
+
+    return {
+      success: true,
+      written: normalizedRecords.length,
+      total: normalizeNonNegativeInteger(totalRow && totalRow.total, 0)
+    };
+  }
+
+  async listAgentRuntimeRecords(options = {}) {
+    const limit = normalizeInteger(options.limit, 100);
+    const status = normalizeString(options.status);
+
+    if (this._useMemoryBackend()) {
+      let rows = Object.values(this._memory.agent_runtime || {}).map((item) => ({ ...item }));
+      if (status) {
+        rows = rows.filter((item) => normalizeString(item.status) === status);
+      }
+      rows.sort((left, right) => (Date.parse(right.last_heartbeat || '') || 0) - (Date.parse(left.last_heartbeat || '') || 0));
+      if (limit > 0) {
+        rows = rows.slice(0, limit);
+      }
+      return rows.map((row) => this._mapAgentRuntimeRow({
+        ...row,
+        current_task_json: JSON.stringify(row.current_task || null)
+      }));
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    let query = `
+      SELECT agent_id, machine_id, instance_index, hostname, registered_at, last_heartbeat, status, current_task_json, source, updated_at
+      FROM agent_runtime_registry
+    `;
+    const params = [];
+    if (status) {
+      query += ' WHERE status = ?';
+      params.push(status);
+    }
+    query += ' ORDER BY last_heartbeat DESC';
+    if (limit > 0) {
+      query += ' LIMIT ?';
+      params.push(limit);
+    }
+
+    const rows = this._db.prepare(query).all(...params);
+    return rows
+      .map((row) => this._mapAgentRuntimeRow(row))
+      .filter(Boolean);
+  }
+
+  async appendStateMigrationRecord(record = {}) {
+    const componentId = normalizeString(record.component_id || record.componentId);
+    if (!componentId) {
+      return null;
+    }
+    const migrationId = normalizeString(record.migration_id || record.migrationId)
+      || `migration-${Date.now()}-${crypto.randomBytes(3).toString('hex')}`;
+    const startedAt = normalizeIsoTimestamp(record.started_at || record.startedAt, this.now()) || this.now();
+    const completedAt = normalizeIsoTimestamp(record.completed_at || record.completedAt, '') || null;
+    const nowIso = this.now();
+    const normalized = {
+      migration_id: migrationId,
+      component_id: componentId,
+      source_path: normalizeString(record.source_path || record.sourcePath) || null,
+      mode: normalizeString(record.mode) || 'unknown',
+      status: normalizeString(record.status) || 'completed',
+      metrics: record.metrics && typeof record.metrics === 'object' ? record.metrics : {},
+      detail: record.detail && typeof record.detail === 'object' ? record.detail : {},
+      started_at: startedAt,
+      completed_at: completedAt,
+      updated_at: nowIso
+    };
+
+    if (this._useMemoryBackend()) {
+      this._memory.migration_records[normalized.migration_id] = { ...normalized };
+      return { ...normalized };
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    this._db
+      .prepare(`
+        INSERT OR REPLACE INTO state_migration_registry(
+          migration_id, component_id, source_path, mode, status, metrics_json, detail_json, started_at, completed_at, updated_at
+        )
+        VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `)
+      .run(
+        normalized.migration_id,
+        normalized.component_id,
+        normalized.source_path,
+        normalized.mode,
+        normalized.status,
+        JSON.stringify(normalized.metrics || {}),
+        JSON.stringify(normalized.detail || {}),
+        normalized.started_at,
+        normalized.completed_at,
+        normalized.updated_at
+      );
+
+    return this.listStateMigrations({ migrationId: normalized.migration_id, limit: 1 })
+      .then((rows) => (Array.isArray(rows) && rows.length > 0 ? rows[0] : null));
+  }
+
+  async listStateMigrations(options = {}) {
+    const limit = normalizeInteger(options.limit, 50);
+    const componentId = normalizeString(options.componentId);
+    const migrationId = normalizeString(options.migrationId);
+
+    if (this._useMemoryBackend()) {
+      let rows = Object.values(this._memory.migration_records || {}).map((item) => ({ ...item }));
+      if (componentId) {
+        rows = rows.filter((item) => normalizeString(item.component_id) === componentId);
+      }
+      if (migrationId) {
+        rows = rows.filter((item) => normalizeString(item.migration_id) === migrationId);
+      }
+      rows.sort((left, right) => (Date.parse(right.started_at || '') || 0) - (Date.parse(left.started_at || '') || 0));
+      if (limit > 0) {
+        rows = rows.slice(0, limit);
+      }
+      return rows.map((row) => this._mapStateMigrationRow({
+        ...row,
+        metrics_json: JSON.stringify(row.metrics || {}),
+        detail_json: JSON.stringify(row.detail || {})
+      }));
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    let query = `
+      SELECT migration_id, component_id, source_path, mode, status, metrics_json, detail_json, started_at, completed_at, updated_at
+      FROM state_migration_registry
+    `;
+    const clauses = [];
+    const params = [];
+    if (componentId) {
+      clauses.push('component_id = ?');
+      params.push(componentId);
+    }
+    if (migrationId) {
+      clauses.push('migration_id = ?');
+      params.push(migrationId);
+    }
+    if (clauses.length > 0) {
+      query += ` WHERE ${clauses.join(' AND ')}`;
+    }
+    query += ' ORDER BY started_at DESC';
+    if (limit > 0) {
+      query += ' LIMIT ?';
+      params.push(limit);
+    }
+
+    const rows = this._db.prepare(query).all(...params);
+    return rows
+      .map((row) => this._mapStateMigrationRow(row))
+      .filter(Boolean);
+  }
+
+  async upsertErrorbookEntryIndexRecords(records = [], options = {}) {
+    const source = normalizeString(options.source) || 'file.errorbook.index';
+    const nowIso = this.now();
+    const normalizedRecords = Array.isArray(records)
+      ? records.map((item) => ({
+        entry_id: normalizeString(item && (item.entry_id || item.id)),
+        fingerprint: normalizeString(item && item.fingerprint) || null,
+        title: normalizeString(item && item.title) || null,
+        status: normalizeString(item && item.status) || null,
+        quality_score: normalizeNonNegativeInteger(item && item.quality_score, 0),
+        tags: normalizeStringArray(item && item.tags, []),
+        ontology_tags: normalizeStringArray(item && item.ontology_tags, []),
+        temporary_mitigation_active: normalizeBooleanValue(item && item.temporary_mitigation_active, false),
+        temporary_mitigation_deadline_at: normalizeIsoTimestamp(item && item.temporary_mitigation_deadline_at, '') || null,
+        occurrences: normalizeNonNegativeInteger(item && item.occurrences, 0),
+        created_at: normalizeIsoTimestamp(item && item.created_at, '') || null,
+        updated_at: normalizeIsoTimestamp(item && item.updated_at, nowIso) || nowIso,
+        source,
+        indexed_at: nowIso
+      }))
+        .filter((item) => item.entry_id)
+      : [];
+
+    if (this._useMemoryBackend()) {
+      for (const item of normalizedRecords) {
+        this._memory.errorbook_entry_index[item.entry_id] = { ...item };
+      }
+      return {
+        success: true,
+        written: normalizedRecords.length,
+        total: Object.keys(this._memory.errorbook_entry_index || {}).length
+      };
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    const statement = this._db.prepare(`
+      INSERT OR REPLACE INTO errorbook_entry_index_registry(
+        entry_id, fingerprint, title, status, quality_score, tags_json, ontology_tags_json,
+        temporary_mitigation_active, temporary_mitigation_deadline_at, occurrences, created_at, updated_at, source, indexed_at
+      )
+      VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    this._withTransaction(() => {
+      for (const item of normalizedRecords) {
+        statement.run(
+          item.entry_id,
+          item.fingerprint,
+          item.title,
+          item.status,
+          item.quality_score,
+          JSON.stringify(item.tags || []),
+          JSON.stringify(item.ontology_tags || []),
+          item.temporary_mitigation_active ? 1 : 0,
+          item.temporary_mitigation_deadline_at,
+          item.occurrences,
+          item.created_at,
+          item.updated_at,
+          item.source,
+          item.indexed_at
+        );
+      }
+    });
+
+    const totalRow = this._db
+      .prepare('SELECT COUNT(*) AS total FROM errorbook_entry_index_registry')
+      .get();
+
+    return {
+      success: true,
+      written: normalizedRecords.length,
+      total: normalizeNonNegativeInteger(totalRow && totalRow.total, 0)
+    };
+  }
+
+  async listErrorbookEntryIndexRecords(options = {}) {
+    const limit = normalizeInteger(options.limit, 100);
+    const status = normalizeString(options.status);
+
+    if (this._useMemoryBackend()) {
+      let rows = Object.values(this._memory.errorbook_entry_index || {}).map((item) => ({ ...item }));
+      if (status) {
+        rows = rows.filter((item) => normalizeString(item.status) === status);
+      }
+      rows.sort((left, right) => (Date.parse(right.updated_at || '') || 0) - (Date.parse(left.updated_at || '') || 0));
+      if (limit > 0) {
+        rows = rows.slice(0, limit);
+      }
+      return rows.map((row) => this._mapErrorbookEntryIndexRow({
+        ...row,
+        tags_json: JSON.stringify(row.tags || []),
+        ontology_tags_json: JSON.stringify(row.ontology_tags || [])
+      }));
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    let query = `
+      SELECT entry_id, fingerprint, title, status, quality_score, tags_json, ontology_tags_json,
+             temporary_mitigation_active, temporary_mitigation_deadline_at, occurrences, created_at, updated_at, source, indexed_at
+      FROM errorbook_entry_index_registry
+    `;
+    const params = [];
+    if (status) {
+      query += ' WHERE status = ?';
+      params.push(status);
+    }
+    query += ' ORDER BY updated_at DESC';
+    if (limit > 0) {
+      query += ' LIMIT ?';
+      params.push(limit);
+    }
+
+    const rows = this._db.prepare(query).all(...params);
+    return rows
+      .map((row) => this._mapErrorbookEntryIndexRow(row))
+      .filter(Boolean);
+  }
+
+  async upsertErrorbookIncidentIndexRecords(records = [], options = {}) {
+    const source = normalizeString(options.source) || 'file.errorbook.incident-index';
+    const nowIso = this.now();
+    const normalizedRecords = Array.isArray(records)
+      ? records.map((item) => ({
+        incident_id: normalizeString(item && (item.incident_id || item.id)),
+        fingerprint: normalizeString(item && item.fingerprint) || null,
+        title: normalizeString(item && item.title) || null,
+        symptom: normalizeString(item && item.symptom) || null,
+        state: normalizeString(item && item.state) || null,
+        attempt_count: normalizeNonNegativeInteger(item && item.attempt_count, 0),
+        created_at: normalizeIsoTimestamp(item && item.created_at, '') || null,
+        updated_at: normalizeIsoTimestamp(item && item.updated_at, nowIso) || nowIso,
+        last_attempt_at: normalizeIsoTimestamp(item && item.last_attempt_at, '') || null,
+        resolved_at: normalizeIsoTimestamp(item && item.resolved_at, '') || null,
+        linked_entry_id: normalizeString(item && item.linked_entry_id) || null,
+        source,
+        indexed_at: nowIso
+      }))
+        .filter((item) => item.incident_id)
+      : [];
+
+    if (this._useMemoryBackend()) {
+      for (const item of normalizedRecords) {
+        this._memory.errorbook_incident_index[item.incident_id] = { ...item };
+      }
+      return {
+        success: true,
+        written: normalizedRecords.length,
+        total: Object.keys(this._memory.errorbook_incident_index || {}).length
+      };
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    const statement = this._db.prepare(`
+      INSERT OR REPLACE INTO errorbook_incident_index_registry(
+        incident_id, fingerprint, title, symptom, state, attempt_count,
+        created_at, updated_at, last_attempt_at, resolved_at, linked_entry_id, source, indexed_at
+      )
+      VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    this._withTransaction(() => {
+      for (const item of normalizedRecords) {
+        statement.run(
+          item.incident_id,
+          item.fingerprint,
+          item.title,
+          item.symptom,
+          item.state,
+          item.attempt_count,
+          item.created_at,
+          item.updated_at,
+          item.last_attempt_at,
+          item.resolved_at,
+          item.linked_entry_id,
+          item.source,
+          item.indexed_at
+        );
+      }
+    });
+
+    const totalRow = this._db
+      .prepare('SELECT COUNT(*) AS total FROM errorbook_incident_index_registry')
+      .get();
+
+    return {
+      success: true,
+      written: normalizedRecords.length,
+      total: normalizeNonNegativeInteger(totalRow && totalRow.total, 0)
+    };
+  }
+
+  async listErrorbookIncidentIndexRecords(options = {}) {
+    const limit = normalizeInteger(options.limit, 100);
+    const state = normalizeString(options.state);
+
+    if (this._useMemoryBackend()) {
+      let rows = Object.values(this._memory.errorbook_incident_index || {}).map((item) => ({ ...item }));
+      if (state) {
+        rows = rows.filter((item) => normalizeString(item.state) === state);
+      }
+      rows.sort((left, right) => (Date.parse(right.updated_at || '') || 0) - (Date.parse(left.updated_at || '') || 0));
+      if (limit > 0) {
+        rows = rows.slice(0, limit);
+      }
+      return rows.map((row) => this._mapErrorbookIncidentIndexRow(row));
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    let query = `
+      SELECT incident_id, fingerprint, title, symptom, state, attempt_count,
+             created_at, updated_at, last_attempt_at, resolved_at, linked_entry_id, source, indexed_at
+      FROM errorbook_incident_index_registry
+    `;
+    const params = [];
+    if (state) {
+      query += ' WHERE state = ?';
+      params.push(state);
+    }
+    query += ' ORDER BY updated_at DESC';
+    if (limit > 0) {
+      query += ' LIMIT ?';
+      params.push(limit);
+    }
+
+    const rows = this._db.prepare(query).all(...params);
+    return rows
+      .map((row) => this._mapErrorbookIncidentIndexRow(row))
+      .filter(Boolean);
+  }
+
+  async upsertGovernanceSpecSceneOverrideRecords(records = [], options = {}) {
+    const source = normalizeString(options.source) || 'file.spec-governance.spec-scene-overrides';
+    const nowIso = this.now();
+    const normalizedRecords = Array.isArray(records)
+      ? records.map((item) => ({
+        spec_id: normalizeString(item && item.spec_id),
+        scene_id: normalizeString(item && item.scene_id),
+        source: normalizeString(item && item.source) || source,
+        rule_id: normalizeString(item && item.rule_id) || null,
+        updated_at: normalizeIsoTimestamp(item && item.updated_at, nowIso) || nowIso,
+        indexed_at: nowIso
+      }))
+        .filter((item) => item.spec_id && item.scene_id)
+      : [];
+
+    if (this._useMemoryBackend()) {
+      for (const item of normalizedRecords) {
+        this._memory.governance_spec_scene_override[item.spec_id] = { ...item };
+      }
+      return {
+        success: true,
+        written: normalizedRecords.length,
+        total: Object.keys(this._memory.governance_spec_scene_override || {}).length
+      };
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    const statement = this._db.prepare(`
+      INSERT OR REPLACE INTO governance_spec_scene_override_registry(
+        spec_id, scene_id, source, rule_id, updated_at, indexed_at
+      )
+      VALUES(?, ?, ?, ?, ?, ?)
+    `);
+
+    this._withTransaction(() => {
+      for (const item of normalizedRecords) {
+        statement.run(
+          item.spec_id,
+          item.scene_id,
+          item.source,
+          item.rule_id,
+          item.updated_at,
+          item.indexed_at
+        );
+      }
+    });
+
+    const totalRow = this._db
+      .prepare('SELECT COUNT(*) AS total FROM governance_spec_scene_override_registry')
+      .get();
+
+    return {
+      success: true,
+      written: normalizedRecords.length,
+      total: normalizeNonNegativeInteger(totalRow && totalRow.total, 0)
+    };
+  }
+
+  async listGovernanceSpecSceneOverrideRecords(options = {}) {
+    const limit = normalizeInteger(options.limit, 100);
+    const sceneId = normalizeString(options.sceneId);
+    const specId = normalizeString(options.specId);
+
+    if (this._useMemoryBackend()) {
+      let rows = Object.values(this._memory.governance_spec_scene_override || {}).map((item) => ({ ...item }));
+      if (sceneId) {
+        rows = rows.filter((item) => normalizeString(item.scene_id) === sceneId);
+      }
+      if (specId) {
+        rows = rows.filter((item) => normalizeString(item.spec_id) === specId);
+      }
+      rows.sort((left, right) => (Date.parse(right.updated_at || '') || 0) - (Date.parse(left.updated_at || '') || 0));
+      if (limit > 0) {
+        rows = rows.slice(0, limit);
+      }
+      return rows.map((row) => this._mapGovernanceSpecSceneOverrideRow(row));
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    let query = `
+      SELECT spec_id, scene_id, source, rule_id, updated_at, indexed_at
+      FROM governance_spec_scene_override_registry
+    `;
+    const clauses = [];
+    const params = [];
+    if (sceneId) {
+      clauses.push('scene_id = ?');
+      params.push(sceneId);
+    }
+    if (specId) {
+      clauses.push('spec_id = ?');
+      params.push(specId);
+    }
+    if (clauses.length > 0) {
+      query += ` WHERE ${clauses.join(' AND ')}`;
+    }
+    query += ' ORDER BY updated_at DESC, spec_id ASC';
+    if (limit > 0) {
+      query += ' LIMIT ?';
+      params.push(limit);
+    }
+
+    const rows = this._db.prepare(query).all(...params);
+    return rows
+      .map((row) => this._mapGovernanceSpecSceneOverrideRow(row))
+      .filter(Boolean);
+  }
+
+  async upsertGovernanceSceneIndexRecords(records = [], options = {}) {
+    const source = normalizeString(options.source) || 'file.spec-governance.scene-index';
+    const nowIso = this.now();
+    const normalizedRecords = Array.isArray(records)
+      ? records.map((item) => ({
+        scene_id: normalizeString(item && item.scene_id),
+        total_specs: normalizeNonNegativeInteger(item && item.total_specs, 0),
+        active_specs: normalizeNonNegativeInteger(item && item.active_specs, 0),
+        completed_specs: normalizeNonNegativeInteger(item && item.completed_specs, 0),
+        stale_specs: normalizeNonNegativeInteger(item && item.stale_specs, 0),
+        spec_ids: normalizeStringArray(item && item.spec_ids, []),
+        active_spec_ids: normalizeStringArray(item && item.active_spec_ids, []),
+        stale_spec_ids: normalizeStringArray(item && item.stale_spec_ids, []),
+        generated_at: normalizeIsoTimestamp(item && item.generated_at, nowIso) || nowIso,
+        scene_filter: normalizeString(item && item.scene_filter) || null,
+        source: normalizeString(item && item.source) || source,
+        indexed_at: nowIso
+      }))
+        .filter((item) => item.scene_id)
+      : [];
+
+    if (this._useMemoryBackend()) {
+      for (const item of normalizedRecords) {
+        this._memory.governance_scene_index[item.scene_id] = { ...item };
+      }
+      return {
+        success: true,
+        written: normalizedRecords.length,
+        total: Object.keys(this._memory.governance_scene_index || {}).length
+      };
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    const statement = this._db.prepare(`
+      INSERT OR REPLACE INTO governance_scene_index_registry(
+        scene_id, total_specs, active_specs, completed_specs, stale_specs,
+        spec_ids_json, active_spec_ids_json, stale_spec_ids_json, generated_at,
+        scene_filter, source, indexed_at
+      )
+      VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    this._withTransaction(() => {
+      for (const item of normalizedRecords) {
+        statement.run(
+          item.scene_id,
+          item.total_specs,
+          item.active_specs,
+          item.completed_specs,
+          item.stale_specs,
+          JSON.stringify(item.spec_ids || []),
+          JSON.stringify(item.active_spec_ids || []),
+          JSON.stringify(item.stale_spec_ids || []),
+          item.generated_at,
+          item.scene_filter,
+          item.source,
+          item.indexed_at
+        );
+      }
+    });
+
+    const totalRow = this._db
+      .prepare('SELECT COUNT(*) AS total FROM governance_scene_index_registry')
+      .get();
+
+    return {
+      success: true,
+      written: normalizedRecords.length,
+      total: normalizeNonNegativeInteger(totalRow && totalRow.total, 0)
+    };
+  }
+
+  async listGovernanceSceneIndexRecords(options = {}) {
+    const limit = normalizeInteger(options.limit, 100);
+    const sceneId = normalizeString(options.sceneId);
+
+    if (this._useMemoryBackend()) {
+      let rows = Object.values(this._memory.governance_scene_index || {}).map((item) => ({ ...item }));
+      if (sceneId) {
+        rows = rows.filter((item) => normalizeString(item.scene_id) === sceneId);
+      }
+      rows.sort((left, right) => {
+        if (right.total_specs !== left.total_specs) {
+          return right.total_specs - left.total_specs;
+        }
+        return `${left.scene_id}`.localeCompare(`${right.scene_id}`);
+      });
+      if (limit > 0) {
+        rows = rows.slice(0, limit);
+      }
+      return rows.map((row) => this._mapGovernanceSceneIndexRow({
+        ...row,
+        spec_ids_json: JSON.stringify(row.spec_ids || []),
+        active_spec_ids_json: JSON.stringify(row.active_spec_ids || []),
+        stale_spec_ids_json: JSON.stringify(row.stale_spec_ids || [])
+      }));
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    let query = `
+      SELECT scene_id, total_specs, active_specs, completed_specs, stale_specs,
+             spec_ids_json, active_spec_ids_json, stale_spec_ids_json, generated_at,
+             scene_filter, source, indexed_at
+      FROM governance_scene_index_registry
+    `;
+    const params = [];
+    if (sceneId) {
+      query += ' WHERE scene_id = ?';
+      params.push(sceneId);
+    }
+    query += ' ORDER BY total_specs DESC, active_specs DESC, scene_id ASC';
+    if (limit > 0) {
+      query += ' LIMIT ?';
+      params.push(limit);
+    }
+
+    const rows = this._db.prepare(query).all(...params);
+    return rows
+      .map((row) => this._mapGovernanceSceneIndexRow(row))
+      .filter(Boolean);
+  }
+
   _resolveOrCreateTaskRefInMemory(options = {}) {
     const sceneId = normalizeString(options.sceneId);
     const specId = normalizeString(options.specId);