scene-capability-engine 3.6.2 → 3.6.4

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

@@ -1,4 +1,5 @@
-const path = require('path');
+const path = require('path');
+const crypto = require('crypto');
 const fs = require('fs-extra');
 
 const DEFAULT_BACKEND = 'sqlite';
@@ -20,6 +21,14 @@ function normalizeInteger(value, fallback = 0) {
   return parsed;
 }
 
+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;
@@ -31,6 +40,27 @@ function parseJsonSafe(value, fallback) {
   }
 }
 
+function normalizeStringArray(value, fallback = []) {
+  if (!Array.isArray(value)) {
+    return [...fallback];
+  }
+  return value
+    .map((item) => normalizeString(item))
+    .filter(Boolean);
+}
+
+function normalizeIsoTimestamp(value, fallback = '') {
+  const normalized = normalizeString(value);
+  if (!normalized) {
+    return normalizeString(fallback);
+  }
+  const parsed = Date.parse(normalized);
+  if (!Number.isFinite(parsed)) {
+    return normalizeString(fallback);
+  }
+  return new Date(parsed).toISOString();
+}
+
 function formatSegment(value) {
   const normalized = normalizeInteger(value, 0);
   if (normalized <= 0) {
@@ -83,6 +113,12 @@ class SceStateStore {
       specs: {},
       tasks: {},
       refs: {},
+      timeline_snapshots: {},
+      scene_session_cycles: {},
+      agent_runtime: {},
+      migration_records: {},
+      auth_leases: {},
+      auth_events: [],
       sequences: {
         scene_next: 1,
         spec_next_by_scene: {},
@@ -181,6 +217,106 @@ class SceStateStore {
 
       CREATE INDEX IF NOT EXISTS idx_studio_event_stream_job_ts
         ON studio_event_stream(job_id, event_timestamp);
+
+      CREATE TABLE IF NOT EXISTS auth_lease_registry (
+        lease_id TEXT PRIMARY KEY,
+        subject TEXT NOT NULL,
+        role TEXT NOT NULL,
+        scope_json TEXT NOT NULL,
+        reason TEXT,
+        metadata_json TEXT,
+        issued_at TEXT NOT NULL,
+        expires_at TEXT NOT NULL,
+        revoked_at TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_auth_lease_registry_expires
+        ON auth_lease_registry(expires_at);
+
+      CREATE TABLE IF NOT EXISTS auth_event_stream (
+        event_id TEXT PRIMARY KEY,
+        event_timestamp TEXT NOT NULL,
+        event_type TEXT NOT NULL,
+        action TEXT,
+        actor TEXT,
+        lease_id TEXT,
+        result TEXT,
+        target TEXT,
+        detail_json TEXT,
+        created_at TEXT NOT NULL
+      );
+
+      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);
     `);
   }
 
@@ -264,6 +400,117 @@ class SceStateStore {
     };
   }
 
+  _mapAuthLeaseRow(row) {
+    if (!row) {
+      return null;
+    }
+    return {
+      lease_id: normalizeString(row.lease_id),
+      subject: normalizeString(row.subject),
+      role: normalizeString(row.role),
+      scope: normalizeStringArray(parseJsonSafe(row.scope_json, []), ['project:*']),
+      reason: normalizeString(row.reason) || null,
+      metadata: parseJsonSafe(row.metadata_json, {}) || {},
+      issued_at: normalizeIsoTimestamp(row.issued_at) || null,
+      expires_at: normalizeIsoTimestamp(row.expires_at) || null,
+      revoked_at: normalizeIsoTimestamp(row.revoked_at) || null,
+      created_at: normalizeIsoTimestamp(row.created_at) || null,
+      updated_at: normalizeIsoTimestamp(row.updated_at) || null
+    };
+  }
+
+  _mapAuthEventRow(row) {
+    if (!row) {
+      return null;
+    }
+    return {
+      event_id: normalizeString(row.event_id),
+      event_timestamp: normalizeIsoTimestamp(row.event_timestamp) || null,
+      event_type: normalizeString(row.event_type),
+      action: normalizeString(row.action) || null,
+      actor: normalizeString(row.actor) || null,
+      lease_id: normalizeString(row.lease_id) || null,
+      result: normalizeString(row.result) || null,
+      target: normalizeString(row.target) || null,
+      detail: parseJsonSafe(row.detail_json, {}) || {},
+      created_at: normalizeIsoTimestamp(row.created_at) || null
+    };
+  }
+
+  _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
+    };
+  }
+
   async resolveOrCreateTaskRef(options = {}) {
     const sceneId = normalizeString(options.sceneId);
     const specId = normalizeString(options.specId);
@@ -510,6 +757,763 @@ class SceStateStore {
     return events;
   }
 
+  async issueAuthLease(options = {}) {
+    const subject = normalizeString(options.subject) || 'unknown';
+    const role = normalizeString(options.role) || 'maintainer';
+    const scope = normalizeStringArray(options.scope, ['project:*']);
+    const reason = normalizeString(options.reason) || null;
+    const metadata = options.metadata && typeof options.metadata === 'object'
+      ? options.metadata
+      : {};
+    const issuedAt = normalizeIsoTimestamp(options.issued_at || options.issuedAt, this.now()) || this.now();
+    const ttlMinutes = normalizeInteger(options.ttl_minutes || options.ttlMinutes, 15);
+    const fallbackExpiresAt = new Date(
+      (Date.parse(issuedAt) || Date.now()) + (Math.max(ttlMinutes, 1) * 60 * 1000)
+    ).toISOString();
+    const expiresAt = normalizeIsoTimestamp(options.expires_at || options.expiresAt, fallbackExpiresAt) || fallbackExpiresAt;
+    const leaseId = normalizeString(options.lease_id || options.leaseId)
+      || `lease-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+    const nowIso = this.now();
+
+    if (this._useMemoryBackend()) {
+      return this._issueAuthLeaseInMemory({
+        leaseId,
+        subject,
+        role,
+        scope,
+        reason,
+        metadata,
+        issuedAt,
+        expiresAt,
+        nowIso
+      });
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    this._db
+      .prepare(`
+        INSERT OR REPLACE INTO auth_lease_registry(
+          lease_id, subject, role, scope_json, reason, metadata_json, issued_at, expires_at, revoked_at, created_at, updated_at
+        )
+        VALUES(?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?)
+      `)
+      .run(
+        leaseId,
+        subject,
+        role,
+        JSON.stringify(scope),
+        reason,
+        JSON.stringify(metadata),
+        issuedAt,
+        expiresAt,
+        nowIso,
+        nowIso
+      );
+
+    return this.getAuthLease(leaseId);
+  }
+
+  async getAuthLease(leaseId) {
+    const normalizedLeaseId = normalizeString(leaseId);
+    if (!normalizedLeaseId) {
+      return null;
+    }
+
+    if (this._useMemoryBackend()) {
+      const row = this._memory.auth_leases[normalizedLeaseId];
+      return row
+        ? {
+          ...row,
+          scope: normalizeStringArray(row.scope, ['project:*']),
+          metadata: { ...(row.metadata || {}) }
+        }
+        : null;
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    const row = this._db
+      .prepare(`
+        SELECT lease_id, subject, role, scope_json, reason, metadata_json, issued_at, expires_at, revoked_at, created_at, updated_at
+        FROM auth_lease_registry
+        WHERE lease_id = ?
+      `)
+      .get(normalizedLeaseId);
+    return this._mapAuthLeaseRow(row);
+  }
+
+  async listAuthLeases(options = {}) {
+    const activeOnly = options.activeOnly !== false;
+    const limit = normalizeInteger(options.limit, 20);
+    const nowIso = this.now();
+
+    if (this._useMemoryBackend()) {
+      let rows = Object.values(this._memory.auth_leases || {}).map((item) => ({
+        ...item,
+        scope: normalizeStringArray(item.scope, ['project:*']),
+        metadata: { ...(item.metadata || {}) }
+      }));
+      if (activeOnly) {
+        const nowTime = Date.parse(nowIso) || Date.now();
+        rows = rows.filter((item) => {
+          const revokedAt = normalizeString(item.revoked_at);
+          if (revokedAt) {
+            return false;
+          }
+          const expiresAt = Date.parse(item.expires_at || '') || 0;
+          return expiresAt > nowTime;
+        });
+      }
+      rows.sort((left, right) => (Date.parse(right.created_at || '') || 0) - (Date.parse(left.created_at || '') || 0));
+      return limit > 0 ? rows.slice(0, limit) : rows;
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    const query = activeOnly
+      ? `
+        SELECT lease_id, subject, role, scope_json, reason, metadata_json, issued_at, expires_at, revoked_at, created_at, updated_at
+        FROM auth_lease_registry
+        WHERE revoked_at IS NULL AND expires_at > ?
+        ORDER BY created_at DESC
+        LIMIT ?
+      `
+      : `
+        SELECT lease_id, subject, role, scope_json, reason, metadata_json, issued_at, expires_at, revoked_at, created_at, updated_at
+        FROM auth_lease_registry
+        ORDER BY created_at DESC
+        LIMIT ?
+      `;
+
+    const statement = this._db.prepare(query);
+    const rows = activeOnly
+      ? statement.all(nowIso, limit)
+      : statement.all(limit);
+    return rows
+      .map((row) => this._mapAuthLeaseRow(row))
+      .filter(Boolean);
+  }
+
+  async revokeAuthLease(leaseId, options = {}) {
+    const normalizedLeaseId = normalizeString(leaseId);
+    if (!normalizedLeaseId) {
+      return null;
+    }
+    const revokedAt = normalizeIsoTimestamp(options.revoked_at || options.revokedAt, this.now()) || this.now();
+
+    if (this._useMemoryBackend()) {
+      const existing = this._memory.auth_leases[normalizedLeaseId];
+      if (!existing) {
+        return null;
+      }
+      existing.revoked_at = revokedAt;
+      existing.updated_at = revokedAt;
+      this._memory.auth_leases[normalizedLeaseId] = existing;
+      return {
+        ...existing,
+        scope: normalizeStringArray(existing.scope, ['project:*']),
+        metadata: { ...(existing.metadata || {}) }
+      };
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    this._db
+      .prepare('UPDATE auth_lease_registry SET revoked_at = ?, updated_at = ? WHERE lease_id = ?')
+      .run(revokedAt, revokedAt, normalizedLeaseId);
+    return this.getAuthLease(normalizedLeaseId);
+  }
+
+  async appendAuthEvent(event = {}) {
+    const eventType = normalizeString(event.event_type || event.eventType);
+    if (!eventType) {
+      return false;
+    }
+    const eventId = normalizeString(event.event_id || event.eventId)
+      || `auth-evt-${Date.now()}-${crypto.randomBytes(3).toString('hex')}`;
+    const timestamp = normalizeIsoTimestamp(event.event_timestamp || event.timestamp, this.now()) || this.now();
+    const normalizedEvent = {
+      event_id: eventId,
+      event_timestamp: timestamp,
+      event_type: eventType,
+      action: normalizeString(event.action) || null,
+      actor: normalizeString(event.actor) || null,
+      lease_id: normalizeString(event.lease_id || event.leaseId) || null,
+      result: normalizeString(event.result) || null,
+      target: normalizeString(event.target) || null,
+      detail: event.detail && typeof event.detail === 'object'
+        ? event.detail
+        : {}
+    };
+
+    if (this._useMemoryBackend()) {
+      const existingIndex = this._memory.auth_events
+        .findIndex((item) => normalizeString(item.event_id) === eventId);
+      const row = {
+        ...normalizedEvent,
+        created_at: this.now()
+      };
+      if (existingIndex >= 0) {
+        this._memory.auth_events[existingIndex] = row;
+      } else {
+        this._memory.auth_events.push(row);
+      }
+      this._memory.auth_events.sort((left, right) => {
+        const l = Date.parse(left.event_timestamp || '') || 0;
+        const r = Date.parse(right.event_timestamp || '') || 0;
+        return l - r;
+      });
+      return true;
+    }
+
+    if (!await this.ensureReady()) {
+      return false;
+    }
+
+    this._db
+      .prepare(`
+        INSERT OR REPLACE INTO auth_event_stream(
+          event_id, event_timestamp, event_type, action, actor, lease_id, result, target, detail_json, created_at
+        )
+        VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `)
+      .run(
+        normalizedEvent.event_id,
+        normalizedEvent.event_timestamp,
+        normalizedEvent.event_type,
+        normalizedEvent.action,
+        normalizedEvent.actor,
+        normalizedEvent.lease_id,
+        normalizedEvent.result,
+        normalizedEvent.target,
+        JSON.stringify(normalizedEvent.detail || {}),
+        this.now()
+      );
+    return true;
+  }
+
+  async listAuthEvents(options = {}) {
+    const limit = normalizeInteger(options.limit, 50);
+
+    if (this._useMemoryBackend()) {
+      const rows = [...this._memory.auth_events]
+        .sort((left, right) => (Date.parse(right.event_timestamp || '') || 0) - (Date.parse(left.event_timestamp || '') || 0))
+        .map((row) => ({
+          ...row,
+          detail: row.detail && typeof row.detail === 'object' ? row.detail : {}
+        }));
+      return limit > 0 ? rows.slice(0, limit) : rows;
+    }
+
+    if (!await this.ensureReady()) {
+      return null;
+    }
+
+    const query = limit > 0
+      ? `
+        SELECT event_id, event_timestamp, event_type, action, actor, lease_id, result, target, detail_json, created_at
+        FROM auth_event_stream
+        ORDER BY event_timestamp DESC
+        LIMIT ?
+      `
+      : `
+        SELECT event_id, event_timestamp, event_type, action, actor, lease_id, result, target, detail_json, created_at
+        FROM auth_event_stream
+        ORDER BY event_timestamp DESC
+      `;
+
+    const statement = this._db.prepare(query);
+    const rows = limit > 0 ? statement.all(limit) : statement.all();
+    return rows
+      .map((row) => this._mapAuthEventRow(row))
+      .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);
+  }
+
   _resolveOrCreateTaskRefInMemory(options = {}) {
     const sceneId = normalizeString(options.sceneId);
     const specId = normalizeString(options.specId);
@@ -566,6 +1570,30 @@ class SceStateStore {
     this._memory.refs[taskRef] = row;
     return { ...row, metadata: { ...(row.metadata || {}) } };
   }
+
+  _issueAuthLeaseInMemory(options = {}) {
+    const leaseId = normalizeString(options.leaseId)
+      || `lease-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+    const row = {
+      lease_id: leaseId,
+      subject: normalizeString(options.subject) || 'unknown',
+      role: normalizeString(options.role) || 'maintainer',
+      scope: normalizeStringArray(options.scope, ['project:*']),
+      reason: normalizeString(options.reason) || null,
+      metadata: options.metadata && typeof options.metadata === 'object' ? { ...options.metadata } : {},
+      issued_at: normalizeIsoTimestamp(options.issuedAt, this.now()) || this.now(),
+      expires_at: normalizeIsoTimestamp(options.expiresAt, this.now()) || this.now(),
+      revoked_at: null,
+      created_at: normalizeIsoTimestamp(options.nowIso, this.now()) || this.now(),
+      updated_at: normalizeIsoTimestamp(options.nowIso, this.now()) || this.now()
+    };
+    this._memory.auth_leases[leaseId] = row;
+    return {
+      ...row,
+      scope: normalizeStringArray(row.scope, ['project:*']),
+      metadata: { ...(row.metadata || {}) }
+    };
+  }
 }
 
 const STORE_CACHE = new Map();