@zaip-ai/cli 2.2.0 → 2.6.0

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-read-model-rebuild.ts

@@ -0,0 +1,755 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { SqliteParsedSourceCache } from "./sqlite-incremental-cache.js";
+import { refreshFirstFoldPayloads } from "./sqlite-materialize-first-fold.js";
+import { materializeDashboardProjections } from "./sqlite-materialize-projections.js";
+import { materializeCanonicalRuns } from "./sqlite-materialize-runs.js";
+import {
+  type CanonicalChange,
+  type CanonicalDecision,
+  type CanonicalEntity,
+  type CanonicalExecution,
+  readCanonicalArtifact,
+  readCanonicalEntities,
+  readCanonicalLifecycleRecords,
+  saoPauloDay,
+  type TemporalInterval,
+} from "./sqlite-read-model-canonical.js";
+import { reportSqliteReadModelLaunchProgress } from "./sqlite-read-model-launch-progress.js";
+import {
+  hasReusableSnapshotPayloads,
+  persistedSourceCheckpoint,
+  readModelSchemaVersion,
+  requiredIndexes,
+  requiredPersistedTables,
+  requiredViews,
+  sqliteReadModelPath,
+  validateSqliteReadModelSchema,
+} from "./sqlite-read-model-schema.js";
+import { sourceFingerprint } from "./sqlite-read-model-source-fingerprint.js";
+import { readSnapshotFileCount } from "./sqlite-snapshot-cache.js";
+export async function rebuildSqliteReadModel(
+  workspaceRoot: string,
+  options: { forceCanonical?: boolean; preferExisting?: boolean } = {},
+): Promise<{
+  files: number;
+  path: string;
+  cache: "generation" | "seed" | "stale_seed" | "rebuilt";
+  fingerprint_ms: number;
+  materialize_ms: number;
+  refresh: {
+    reused_sources: number;
+    processed_sources: number;
+    added_sources: number;
+    changed_sources: number;
+    removed_sources: number;
+    canonical_runs_refolded: number;
+  };
+}> {
+  const path = sqliteReadModelPath(workspaceRoot);
+  // Bind immediately from the last complete transaction. The serving process
+  // checks canonical freshness in its worker before declaring this current.
+  if (options.preferExisting && !options.forceCanonical) {
+    try {
+      validateSqliteReadModelSchema(path);
+      const database = new DatabaseSync(path, { readOnly: true });
+      try {
+        if (hasReusableSnapshotPayloads(database)) {
+          const row = database
+            .prepare(
+              "SELECT value FROM zaip_vw_read_model_metadata WHERE key = 'source_file_count'",
+            )
+            .get() as { value: string };
+          return {
+            files: Number(row.value),
+            path,
+            cache: "stale_seed",
+            fingerprint_ms: 0,
+            materialize_ms: 0,
+            refresh: {
+              reused_sources: 0,
+              processed_sources: 0,
+              added_sources: 0,
+              changed_sources: 0,
+              removed_sources: 0,
+              canonical_runs_refolded: 0,
+            },
+          };
+        }
+      } finally {
+        database.close();
+      }
+    } catch {
+      // Missing, incompatible, or incomplete models require a canonical build.
+    }
+  }
+  const reportLaunchProgress = reportSqliteReadModelLaunchProgress;
+  const fingerprintStartedAt = performance.now();
+  reportLaunchProgress("source_fingerprint_started", 8, "Inventariando fontes canônicas.");
+  let sourceSnapshot = await sourceFingerprint(
+    workspaceRoot,
+    options.forceCanonical
+      ? { verifyContent: true }
+      : { previous: persistedSourceCheckpoint(path) },
+  );
+  let refresh = {
+    reused_sources: sourceSnapshot.reusedFiles,
+    processed_sources: sourceSnapshot.hashedFiles,
+    added_sources: 0,
+    changed_sources: 0,
+    removed_sources: 0,
+    canonical_runs_refolded: 0,
+  };
+  reportLaunchProgress("source_fingerprint_ready", 20, "Inventário canônico concluído.");
+  // Revalidate date-dependent payloads on every São Paulo calendar day.
+  let fingerprint = `${sourceSnapshot.fingerprint}\ncurrent_day=${saoPauloDay(new Date().toISOString())}`;
+  const fingerprintMs = Math.round(performance.now() - fingerprintStartedAt);
+  const existingFiles = readSnapshotFileCount(
+    path,
+    fingerprint,
+    readModelSchemaVersion,
+    hasReusableSnapshotPayloads,
+  );
+  if (existingFiles !== null && !options.forceCanonical && sourceSnapshot.hashedFiles === 0) {
+    validateSqliteReadModelSchema(path);
+    return {
+      files: existingFiles,
+      path,
+      cache: "generation",
+      fingerprint_ms: fingerprintMs,
+      materialize_ms: 0,
+      refresh,
+    };
+  }
+
+  reportLaunchProgress(
+    "source_inventory",
+    52,
+    `Encontradas ${sourceSnapshot.candidates.length} fontes canônicas.`,
+  );
+  await mkdir(dirname(path), { recursive: true });
+  const database = new DatabaseSync(path);
+  let completedFiles = 0;
+  try {
+    database.exec("PRAGMA busy_timeout=180000; PRAGMA journal_mode=WAL; BEGIN IMMEDIATE;");
+    try {
+      // Another process may have finished an update while this writer waited.
+      // Capture canonical inputs only after acquiring exclusive writer ownership.
+      sourceSnapshot = await sourceFingerprint(
+        workspaceRoot,
+        options.forceCanonical
+          ? { verifyContent: true }
+          : { previous: persistedSourceCheckpoint(path) },
+      );
+      refresh = {
+        reused_sources: sourceSnapshot.reusedFiles,
+        processed_sources: sourceSnapshot.hashedFiles,
+        added_sources: 0,
+        changed_sources: 0,
+        removed_sources: 0,
+        canonical_runs_refolded: 0,
+      };
+      fingerprint = `${sourceSnapshot.fingerprint}\ncurrent_day=${saoPauloDay(new Date().toISOString())}`;
+      // Keep the previous canonical bytes available while the transaction
+      // decides which sources changed.  `files` is a persisted view over
+      // typed technical payloads, so a matching checkpoint can be reused
+      // without touching the canonical filesystem again.  A missing source
+      // is deliberately absent from `sourceSnapshot` and is therefore not
+      // copied into the next materialization.
+      const persistedFiles = new Map(
+        (() => {
+          try {
+            return database
+              .prepare("SELECT path, content, content_sha256 FROM zaip_vw_files")
+              .all() as Array<{ path: string; content: string; content_sha256: string }>;
+          } catch {
+            // An older or incomplete schema takes the bootstrap path below.
+            return [] as Array<{ path: string; content: string; content_sha256: string }>;
+          }
+        })().map((row) => [row.path, row] as const),
+      );
+      const existing = database
+        .prepare("SELECT name, type FROM sqlite_master WHERE name NOT LIKE 'sqlite_%'")
+        .all() as Array<{ name: string; type: string }>;
+      const hasPersistentSchema =
+        !options.forceCanonical &&
+        requiredPersistedTables.every((name) =>
+          existing.some((entry) => entry.type === "table" && entry.name === name),
+        ) &&
+        requiredIndexes.every((name) =>
+          existing.some((entry) => entry.type === "index" && entry.name === name),
+        ) &&
+        requiredViews.every((name) =>
+          existing.some((entry) => entry.type === "view" && entry.name === name),
+        ) &&
+        (() => {
+          try {
+            const schemaVersion = database
+              .prepare("SELECT value FROM zaip_vw_read_model_metadata WHERE key='schema_version'")
+              .get() as { value?: string } | undefined;
+            database
+              .prepare(
+                "SELECT source_path, ctime_ms, file_identity FROM zaip_vw_read_model_source_state LIMIT 1",
+              )
+              .all();
+            return schemaVersion?.value === readModelSchemaVersion;
+          } catch {
+            return false;
+          }
+        })();
+      const persistedSourceHashes = new Map(
+        (() => {
+          try {
+            return database
+              .prepare("SELECT source_path, source_hash FROM zaip_vw_read_model_source_state")
+              .all() as Array<{ source_path: string; source_hash: string }>;
+          } catch {
+            return [] as Array<{ source_path: string; source_hash: string }>;
+          }
+        })().map((row) => [row.source_path, row.source_hash] as const),
+      );
+      refresh = {
+        ...refresh,
+        added_sources: sourceSnapshot.candidates.filter(
+          (candidate) => !persistedSourceHashes.has(candidate.source),
+        ).length,
+        changed_sources: sourceSnapshot.candidates.filter((candidate) => {
+          const previous = persistedSourceHashes.get(candidate.source);
+          return previous !== undefined && previous !== candidate.contentHash;
+        }).length,
+        removed_sources: [...persistedSourceHashes.keys()].filter(
+          (source) => !sourceSnapshot.candidates.some((candidate) => candidate.source === source),
+        ).length,
+      };
+      const changedCandidates = sourceSnapshot.candidates.filter(
+        (candidate) => persistedSourceHashes.get(candidate.source) !== candidate.contentHash,
+      );
+      const removedSources = [...persistedSourceHashes.keys()].filter(
+        (source) => !sourceSnapshot.candidates.some((candidate) => candidate.source === source),
+      );
+      if (hasPersistentSchema && changedCandidates.length === 0 && removedSources.length === 0) {
+        const oldFingerprint = database
+          .prepare("SELECT value FROM zaip_vw_read_model_metadata WHERE key='source_fingerprint'")
+          .get() as { value: string };
+        const checkpoint = persistedSourceCheckpoint(path);
+        for (const candidate of sourceSnapshot.candidates) {
+          const old = checkpoint.get(candidate.source);
+          if (
+            old &&
+            (old.mtimeMs !== candidate.mtimeMs ||
+              old.ctimeMs !== candidate.ctimeMs ||
+              old.fileIdentity !== candidate.fileIdentity)
+          )
+            database
+              .prepare(`UPDATE zaip_aios_activities SET payload_json=json_set(payload_json,'$.mtime_ms',?,'$.ctime_ms',?,'$.file_identity',?,'$.size_bytes',?)
+              WHERE payload_type='source_state' AND activity_key=?`)
+              .run(
+                String(candidate.mtimeMs),
+                String(candidate.ctimeMs),
+                candidate.fileIdentity,
+                candidate.size,
+                `source_state:${candidate.source}`,
+              );
+        }
+        database
+          .prepare(
+            "UPDATE zaip_aios_activities SET payload_json=json_set(payload_json,'$.value',?) WHERE payload_type='metadata' AND activity_key='metadata:source_fingerprint'",
+          )
+          .run(fingerprint);
+        if (
+          oldFingerprint.value.split("\ncurrent_day=")[1] !== fingerprint.split("\ncurrent_day=")[1]
+        ) {
+          database.exec(
+            "DELETE FROM zaip_aios_activities WHERE payload_type IN ('cost_monitor_summary_month_cache','first_fold_monthly_quick_cache')",
+          );
+          refreshFirstFoldPayloads(workspaceRoot, database);
+        }
+        database.exec("COMMIT;");
+        return {
+          files: sourceSnapshot.candidates.length,
+          path,
+          cache: "rebuilt",
+          fingerprint_ms: fingerprintMs,
+          materialize_ms: Math.round(performance.now() - fingerprintStartedAt),
+          refresh,
+        };
+      }
+      const candidateBySource = new Map(
+        sourceSnapshot.candidates.map((candidate) => [candidate.source, candidate]),
+      );
+      const changedSources = new Set([
+        ...changedCandidates.map((candidate) => candidate.source),
+        ...removedSources,
+      ]);
+      const previousActivities = hasPersistentSchema
+        ? (database
+            .prepare("SELECT * FROM zaip_aios_activities WHERE payload_type IS NULL")
+            .all() as Array<Record<string, any>>)
+        : [];
+      const previousRunIndex = hasPersistentSchema
+        ? (database.prepare("SELECT * FROM zaip_vw_canonical_run_index").all() as Array<
+            Record<string, any>
+          >)
+        : [];
+      const previousUsage = hasPersistentSchema
+        ? (database.prepare("SELECT * FROM zaip_vw_invocation_usage_segments").all() as Array<
+            Record<string, any>
+          >)
+        : [];
+      const previousDurations = hasPersistentSchema
+        ? (database.prepare("SELECT * FROM zaip_vw_attributed_token_active_facts").all() as Array<
+            Record<string, any>
+          >)
+        : [];
+      const durationByRun = new Map(previousRunIndex.map((row) => [row.run_id, row.duration_ms]));
+      const intervalFor = (
+        row: Record<string, any>,
+        duration: number | null,
+      ): TemporalInterval | null => {
+        if (!(row.total_tokens > 0) || duration === null || duration < 0) return null;
+        const startMs = Date.parse(row.source_started_at ?? row.occurred_at);
+        const endMs = Date.parse(row.source_finished_at ?? "") || startMs + duration;
+        return Number.isFinite(startMs) && Number.isFinite(endMs) && endMs > startMs
+          ? { activityRowId: row.activity_row_id, startMs, endMs }
+          : null;
+      };
+      const oldIntervals = previousActivities.flatMap((row) => {
+        const interval = intervalFor(row, durationByRun.get(row.run_id) ?? null);
+        return interval ? [interval] : [];
+      });
+      const configurationChanged = [...changedSources].some(
+        (source) =>
+          source.startsWith(".agents/config/pricing/") ||
+          source === ".agents/config/agents/catalog.yaml" ||
+          source === ".agents/config/clients.yaml" ||
+          source.includes("/historical-developer-attribution/"),
+      );
+      const entityChanged = [...changedSources].some((source) =>
+        /^\.agents\/(?:data|records)\/(tasks|specs|prds)\//.test(source),
+      );
+      const changedCreationRunIds = new Set<string>();
+      if (hasPersistentSchema)
+        for (const source of changedSources) {
+          if (!/^\.agents\/(?:data|records)\/specs\//.test(source)) continue;
+          const cached = database
+            .prepare(
+              "SELECT payload_json FROM zaip_aios_activities WHERE payload_type='parsed_source' AND activity_key=?",
+            )
+            .get(`parsed_source:entities:${source}`) as { payload_json: string } | undefined;
+          if (cached)
+            for (const [, entity] of JSON.parse(cached.payload_json) as Array<
+              [string, CanonicalEntity]
+            >)
+              if (entity.creationRunId) changedCreationRunIds.add(entity.creationRunId);
+        }
+      const dirtyRunIds = new Set(
+        previousActivities
+          .filter((row) => configurationChanged || changedSources.has(row.source_path))
+          .map((row) => String(row.run_id)),
+      );
+      // A newly-added alternate layout has no prior activity row, but can name
+      // the same Run already materialized from the current layout. Mark that
+      // Run dirty before retaining canonical facts so the later preferred fold
+      // replaces it instead of colliding with a preserved run-index row.
+      for (const source of changedSources) {
+        const match = /^\.agents\/(?:data|records)\/runs\/.*\/([^/]+)\.jsonl$/.exec(source);
+        if (match?.[1]) dirtyRunIds.add(match[1]);
+      }
+      // A parent identity change may affect descendants even when their own bytes are unchanged.
+      let expanded = true;
+      while (expanded) {
+        expanded = false;
+        for (const row of previousActivities)
+          if (dirtyRunIds.has(row.parent_run_id) && !dirtyRunIds.has(row.run_id)) {
+            dirtyRunIds.add(row.run_id);
+            expanded = true;
+          }
+      }
+      const quote = (name: string) => `"${name.replaceAll('"', '""')}"`;
+      if (!hasPersistentSchema) {
+        for (const entry of existing.filter((entry) => entry.type === "view"))
+          database.exec(`DROP VIEW IF EXISTS ${quote(entry.name)}`);
+        for (const entry of existing.filter((entry) => entry.type === "table"))
+          database.exec(`DROP TABLE IF EXISTS ${quote(entry.name)}`);
+      } else {
+        // A refresh keeps the physical schema and source payload identities.
+        // Only derived facts are replaced; stable files/checkpoints survive
+        // untouched, while changed and removed sources are deleted below.
+        database.exec(`
+          DELETE FROM zaip_aios_activities
+          WHERE payload_type IS NOT NULL AND payload_type NOT IN ('file', 'source_state', 'parsed_source', 'usage_segment', 'run_index', 'duration_allocation', 'shared_creation_allocation', 'work_item', 'execution', 'change', 'decision', 'cost_dimension_aggregate_v1', 'cost_agent_invocation_projection_v1');
+          DELETE FROM zaip_dim_zaip_agent;
+          DELETE FROM zaip_dim_llm_model;
+          DELETE FROM zaip_dim_provider;
+        `);
+        try {
+          database.exec(
+            "DELETE FROM developer_cost_projection; DELETE FROM cost_invocation_dimension_facts;",
+          );
+        } catch {
+          // Older compatible models do not have every optional projection.
+        }
+      }
+      database.exec(`
+        CREATE TEMP TABLE files (path TEXT PRIMARY KEY, content TEXT NOT NULL, mtime_ms REAL NOT NULL, size_bytes INTEGER NOT NULL, content_sha256 TEXT NOT NULL, artifact_kind TEXT, artifact_id TEXT, artifact_occurred_at TEXT, artifact_occurred_day_sp TEXT, artifact_task_id TEXT, artifact_change_id TEXT, artifact_run_id TEXT);
+        CREATE TEMP TABLE read_model_source_state (source_path TEXT PRIMARY KEY, source_hash TEXT NOT NULL, mtime_ms TEXT NOT NULL, ctime_ms TEXT NOT NULL, size_bytes INTEGER NOT NULL, file_identity TEXT NOT NULL, source_kind TEXT NOT NULL, last_processed_at TEXT NOT NULL);
+        CREATE TEMP TABLE read_model_metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+        CREATE TEMP TABLE canonical_work_items (entity_kind TEXT NOT NULL, id TEXT NOT NULL, title TEXT, status TEXT, stage TEXT, risk TEXT, spec_id TEXT, change_id TEXT, creation_run_id TEXT, completed_run_id TEXT, occurred_at TEXT NOT NULL, occurred_day_sp TEXT NOT NULL, PRIMARY KEY(entity_kind, id));
+        CREATE TEMP TABLE canonical_executions (id TEXT PRIMARY KEY, status TEXT, kind TEXT, origin_type TEXT, origin_id TEXT, created_at TEXT NOT NULL, occurred_day_sp TEXT NOT NULL, finished_at TEXT, source_path TEXT NOT NULL);
+        CREATE TEMP TABLE canonical_changes (id TEXT PRIMARY KEY, title TEXT NOT NULL, status TEXT NOT NULL, risk TEXT NOT NULL, source_type TEXT NOT NULL, source_id TEXT NOT NULL, source_spec_id TEXT, source_prd_id TEXT, requirement_ids_json TEXT NOT NULL, acceptance_ids_json TEXT NOT NULL, task_ids_json TEXT NOT NULL, result TEXT, created_at TEXT NOT NULL, occurred_day_sp TEXT NOT NULL, source_path TEXT NOT NULL);
+        CREATE TEMP TABLE canonical_decisions (id TEXT PRIMARY KEY, title TEXT NOT NULL, origin TEXT NOT NULL, scope_type TEXT NOT NULL, scope_id TEXT NOT NULL, created_at TEXT NOT NULL, occurred_day_sp TEXT NOT NULL, source_path TEXT NOT NULL);
+        CREATE TEMP TABLE canonical_run_index (run_id TEXT PRIMARY KEY, occurred_at TEXT NOT NULL, occurred_day_sp TEXT NOT NULL, task_id TEXT, phase TEXT, run_role TEXT NOT NULL, duration_ms REAL, source_event_count INTEGER NOT NULL, zaip_agent TEXT, provider TEXT, model TEXT, status TEXT);
+        CREATE TEMP TABLE invocation_usage_segments (
+          agent_invocation_id TEXT NOT NULL, provider TEXT, model TEXT, service_tier TEXT, reasoning_effort TEXT,
+          input_tokens REAL, cached_input_tokens REAL, uncached_input_tokens REAL,
+          output_tokens REAL, reasoning_tokens REAL, visible_output_tokens REAL, total_tokens REAL,
+          input_rate_usd_per_million REAL, cached_input_rate_usd_per_million REAL,
+          output_rate_usd_per_million REAL, reasoning_rate_usd_per_million REAL,
+          context_input_multiplier REAL, context_output_multiplier REAL, speed_cost_multiplier REAL, pricing_scenario TEXT,
+          standard_cost_usd REAL, speed_uplift_usd REAL,
+          input_cost_usd REAL, cached_input_cost_usd REAL, output_cost_usd REAL, reasoning_cost_usd REAL,
+          calculated_cost_usd REAL, recorded_cost_usd REAL, cost_variance_usd REAL,
+          cost_usd REAL, cost_brl REAL, cost_method TEXT, pricing_model TEXT, pricing_source TEXT, fx_rate REAL
+        );
+        CREATE TABLE IF NOT EXISTS zaip_aios_activities (
+          activity_row_id TEXT PRIMARY KEY, activity_source_kind TEXT NOT NULL, activity_key TEXT NOT NULL,
+          source_path TEXT NOT NULL, source_hash TEXT NOT NULL, source_occurred_at TEXT, recorded_at TEXT NOT NULL, version_activity_id TEXT,
+          source_last_event_id TEXT, source_last_sequence INTEGER,
+          work_item_kind TEXT, title TEXT, work_item_status TEXT, work_stage TEXT, risk TEXT,
+          run_role TEXT NOT NULL, root_run_id TEXT NOT NULL, parent_run_id TEXT,
+          agent_run_id TEXT, root_agent_run_id TEXT, parent_agent_run_id TEXT, agent_run_role TEXT, delegation_depth INTEGER,
+          agent_invocation_id TEXT, root_agent_invocation_id TEXT, parent_agent_invocation_id TEXT, invocation_kind TEXT,
+          execution_id TEXT, task_id TEXT, spec_id TEXT, prd_id TEXT, change_id TEXT, conversation_id TEXT, run_id TEXT,
+          occurred_at TEXT, occurred_day_sp TEXT, execution_kind TEXT, entrypoint TEXT, work_type TEXT, phase TEXT, purpose TEXT, status TEXT, activity_kind TEXT,
+          zaip_agent TEXT, zaip_agent_persona TEXT, zaip_agent_job TEXT, zaip_agent_role TEXT, agent_catalog_id TEXT, agent_catalog_hash TEXT,
+          client TEXT, provider TEXT, model TEXT, service_tier TEXT, reasoning_effort TEXT,
+          developer_account_id TEXT, developer_login TEXT, developer_attribution_source TEXT,
+          source_duration_ms REAL, source_started_at TEXT, source_finished_at TEXT, duration_ms REAL, duration_provenance TEXT, input_tokens REAL, cached_input_tokens REAL, output_tokens REAL, reasoning_tokens REAL, total_tokens REAL, token_source TEXT, usage_event_count INTEGER, llm_call_count INTEGER,
+          cost_usd REAL, cost_brl REAL, cost_method TEXT, pricing_model TEXT, pricing_source TEXT, fx_rate REAL, source_event_count INTEGER,
+          root_run_duration REAL, sub_run_duration REAL,
+          payload_type TEXT, payload_json TEXT
+        );`);
+      database.exec(`
+        CREATE TABLE IF NOT EXISTS zaip_dim_zaip_agent (
+          zaip_agent TEXT PRIMARY KEY, catalog_id TEXT, persona TEXT, job TEXT, role TEXT, catalog_hash TEXT
+        );
+        CREATE TABLE IF NOT EXISTS zaip_dim_llm_model (
+          model TEXT PRIMARY KEY
+        );
+        CREATE TABLE IF NOT EXISTS zaip_dim_provider (
+          provider TEXT PRIMARY KEY
+        );
+      `);
+      // One materialized temporal fact at the activity (one canonical Run)
+      // grain.  It is the only additive Tempo measure exposed to projections.
+      // NULL means the fact is genuinely unknown; 0 is an observed known zero.
+      database.exec(`CREATE TEMP TABLE attributed_token_active_facts (
+        activity_row_id TEXT NOT NULL,
+        occurred_day_sp TEXT NOT NULL,
+        attributed_token_active_ms REAL NOT NULL,
+        PRIMARY KEY(activity_row_id, occurred_day_sp)
+      );`);
+      database.exec(
+        "CREATE INDEX IF NOT EXISTS zaip_activities_payload ON zaip_aios_activities(payload_type, activity_key)",
+      );
+      const parsedSources = new SqliteParsedSourceCache(database);
+      const sourceHashFor = (source: string) => candidateBySource.get(source)?.contentHash ?? "";
+      const insertRows = (table: string, rows: Array<Record<string, any>>) => {
+        if (!rows.length) return;
+        const columns = Object.keys(rows[0]!);
+        const statement = database.prepare(
+          `INSERT INTO ${table}(${columns.join(",")}) VALUES (${columns.map(() => "?").join(",")})`,
+        );
+        for (const row of rows) statement.run(...columns.map((column) => row[column] ?? null));
+      };
+      insertRows(
+        "canonical_run_index",
+        previousRunIndex.filter((row) => !dirtyRunIds.has(row.run_id)),
+      );
+      const dirtyInvocationIds = new Set(
+        previousActivities
+          .filter((row) => dirtyRunIds.has(row.run_id))
+          .map((row) => row.agent_invocation_id),
+      );
+      insertRows(
+        "invocation_usage_segments",
+        previousUsage.filter((row) => !dirtyInvocationIds.has(row.agent_invocation_id)),
+      );
+      insertRows("attributed_token_active_facts", previousDurations);
+      for (const runId of dirtyRunIds)
+        database
+          .prepare("DELETE FROM zaip_aios_activities WHERE payload_type IS NULL AND run_id=?")
+          .run(runId);
+      for (const source of removedSources)
+        database
+          .prepare(
+            "DELETE FROM zaip_aios_activities WHERE payload_type='parsed_source' AND source_path=?",
+          )
+          .run(source);
+      const insert = database.prepare(
+        "INSERT INTO files(path, content, mtime_ms, size_bytes, content_sha256, artifact_kind, artifact_id, artifact_occurred_at, artifact_occurred_day_sp, artifact_task_id, artifact_change_id, artifact_run_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+      );
+      const insertSourceState = database.prepare(
+        "INSERT INTO read_model_source_state(source_path, source_hash, mtime_ms, ctime_ms, size_bytes, file_identity, source_kind, last_processed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+      );
+      let files = 0;
+      const skipped = 0;
+      const sourceReadBatchSize = 32;
+      for (
+        let offset = 0;
+        offset < sourceSnapshot.candidates.length;
+        offset += sourceReadBatchSize
+      ) {
+        const batch = sourceSnapshot.candidates.slice(offset, offset + sourceReadBatchSize);
+        // Parallel reads reduce cold I/O latency, while the following ordered
+        // loop retains deterministic SQLite inserts and canonical projections.
+        const contents = await Promise.all(
+          batch.map(async (candidate) => {
+            const previous = persistedFiles.get(candidate.source);
+            if (previous?.content_sha256 === candidate.contentHash) return previous.content;
+            // The fingerprint captured a stable stat/hash pair. Any read
+            // failure here must abort the transaction, preserving the prior
+            // complete model instead of treating an inaccessible file as a
+            // deletion.
+            const content = await readFile(candidate.path, "utf8");
+            if (createHash("sha256").update(content).digest("hex") !== candidate.contentHash)
+              throw new Error(`Canonical source changed during refresh: ${candidate.source}`);
+            return content;
+          }),
+        );
+        for (let index = 0; index < batch.length; index += 1) {
+          const candidate = batch[index];
+          const content = contents[index];
+          if (candidate === undefined || content === undefined) continue;
+          const { source, mtimeMs, ctimeMs, size, fileIdentity } = candidate;
+          const sourceHash = candidate.contentHash;
+          const sourceKind = source.includes("/runs/")
+            ? "run"
+            : source.includes("/artifacts/evidence/")
+              ? "evidence"
+              : source.includes("/artifacts/validations/") || source.includes("/artifacts/tests/")
+                ? "validation"
+                : source.startsWith(".agents/config/")
+                  ? "config"
+                  : "entity";
+          const artifact = parsedSources.read("artifact", source, sourceHash, () =>
+            readCanonicalArtifact(source, content),
+          );
+          insert.run(
+            source,
+            content,
+            mtimeMs,
+            size,
+            sourceHash,
+            artifact?.kind ?? null,
+            artifact?.id ?? null,
+            artifact?.occurredAt ?? null,
+            artifact?.occurredDaySp ?? null,
+            artifact?.taskId ?? null,
+            artifact?.changeId ?? null,
+            artifact?.runId ?? null,
+          );
+          insertSourceState.run(
+            source,
+            sourceHash,
+            String(mtimeMs),
+            String(ctimeMs),
+            size,
+            fileIdentity,
+            sourceKind,
+            new Date().toISOString(),
+          );
+          files += 1;
+        }
+        const completedPercent =
+          52 + Math.round(((offset + batch.length) / sourceSnapshot.candidates.length) * 20);
+        reportLaunchProgress(
+          "source_import",
+          completedPercent,
+          `Lidas ${Math.min(offset + batch.length, sourceSnapshot.candidates.length)} de ${sourceSnapshot.candidates.length} fontes.`,
+        );
+      }
+      reportLaunchProgress("projection_build", 74, "Organizando fatos e projeções do banco local.");
+      const canonicalRows = database
+        .prepare(
+          "SELECT path, content FROM files WHERE (path LIKE '.agents/data/%' OR path LIKE '.agents/records/%') AND path NOT LIKE '.agents/data/runs/%' AND path NOT LIKE '.agents/records/runs/%' ORDER BY CASE WHEN path LIKE '.agents/data/%' THEN 1 ELSE 0 END, path",
+        )
+        .all() as Array<{ path: string; content: string }>;
+      const canonicalEntities = new Map<string, CanonicalEntity>(
+        canonicalRows.flatMap((row) =>
+          parsedSources.read<Array<[string, CanonicalEntity]>>(
+            "entities",
+            row.path,
+            sourceHashFor(row.path),
+            () => [...readCanonicalEntities([row])],
+          ),
+        ),
+      );
+      for (const row of canonicalRows)
+        if (changedSources.has(row.path) && /^\.agents\/(?:data|records)\/specs\//.test(row.path))
+          for (const [, entity] of parsedSources.read<Array<[string, CanonicalEntity]>>(
+            "entities",
+            row.path,
+            sourceHashFor(row.path),
+            () => [...readCanonicalEntities([row])],
+          ))
+            if (entity.creationRunId) changedCreationRunIds.add(entity.creationRunId);
+      const insertCanonicalWorkItem = database.prepare(
+        "INSERT INTO canonical_work_items(entity_kind, id, title, status, stage, risk, spec_id, change_id, creation_run_id, completed_run_id, occurred_at, occurred_day_sp) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+      );
+      for (const entity of canonicalEntities.values()) {
+        if (
+          (entity.kind !== "task" && entity.kind !== "spec" && entity.kind !== "prd") ||
+          entity.occurredAt === null ||
+          Number.isNaN(Date.parse(entity.occurredAt))
+        )
+          continue;
+        insertCanonicalWorkItem.run(
+          entity.kind,
+          entity.id,
+          entity.title,
+          entity.status,
+          entity.stage,
+          entity.risk,
+          entity.specId,
+          entity.changeId,
+          entity.creationRunId,
+          entity.completedRunId,
+          entity.occurredAt,
+          saoPauloDay(entity.occurredAt),
+        );
+      }
+      const canonicalLifecycle = {
+        executions: [] as CanonicalExecution[],
+        changes: [] as CanonicalChange[],
+        decisions: [] as CanonicalDecision[],
+      };
+      for (const row of canonicalRows) {
+        const parsed = parsedSources.read("lifecycle", row.path, sourceHashFor(row.path), () =>
+          readCanonicalLifecycleRecords([row]),
+        );
+        canonicalLifecycle.executions.push(...parsed.executions);
+        canonicalLifecycle.changes.push(...parsed.changes);
+        canonicalLifecycle.decisions.push(...parsed.decisions);
+      }
+      // Both supported layouts can coexist during an upgrade. SQL ordering puts
+      // .agents/data last, so the installed current record wins by stable ID.
+      canonicalLifecycle.executions = [
+        ...new Map(canonicalLifecycle.executions.map((item) => [item.id, item])).values(),
+      ];
+      canonicalLifecycle.changes = [
+        ...new Map(canonicalLifecycle.changes.map((item) => [item.id, item])).values(),
+      ];
+      canonicalLifecycle.decisions = [
+        ...new Map(canonicalLifecycle.decisions.map((item) => [item.id, item])).values(),
+      ];
+      const insertCanonicalExecution = database.prepare(
+        "INSERT INTO canonical_executions(id, status, kind, origin_type, origin_id, created_at, occurred_day_sp, finished_at, source_path) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+      );
+      for (const entity of canonicalLifecycle.executions)
+        insertCanonicalExecution.run(
+          entity.id,
+          entity.status,
+          entity.kind,
+          entity.originType,
+          entity.originId,
+          entity.createdAt,
+          saoPauloDay(entity.createdAt),
+          entity.finishedAt,
+          entity.sourcePath,
+        );
+      const insertCanonicalChange = database.prepare(
+        "INSERT INTO canonical_changes(id, title, status, risk, source_type, source_id, source_spec_id, source_prd_id, requirement_ids_json, acceptance_ids_json, task_ids_json, result, created_at, occurred_day_sp, source_path) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+      );
+      for (const entity of canonicalLifecycle.changes)
+        insertCanonicalChange.run(
+          entity.id,
+          entity.title,
+          entity.status,
+          entity.risk,
+          entity.sourceType,
+          entity.sourceId,
+          entity.sourceSpecId,
+          entity.sourcePrdId,
+          JSON.stringify(entity.requirementIds),
+          JSON.stringify(entity.acceptanceIds),
+          JSON.stringify(entity.taskIds),
+          entity.result,
+          entity.createdAt,
+          saoPauloDay(entity.createdAt),
+          entity.sourcePath,
+        );
+      const insertCanonicalDecision = database.prepare(
+        "INSERT INTO canonical_decisions(id, title, origin, scope_type, scope_id, created_at, occurred_day_sp, source_path) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+      );
+      for (const entity of canonicalLifecycle.decisions)
+        insertCanonicalDecision.run(
+          entity.id,
+          entity.title,
+          entity.origin,
+          entity.scopeType,
+          entity.scopeId,
+          entity.createdAt,
+          saoPauloDay(entity.createdAt),
+          entity.sourcePath,
+        );
+      const runMaterialization = materializeCanonicalRuns({
+        database,
+        previousActivities,
+        parsedSources,
+        refresh,
+        hasPersistentSchema,
+        dirtyRunIds,
+        changedSources,
+        oldIntervals,
+        canonicalEntities,
+        entityChanged,
+      });
+
+      // A single authoring sub-Run can create several sibling SPECs. Keep the
+      // Run canonical and attach deterministic shares only to the macro read
+      // model. Payload rows stay outside `activities`, preventing global
+      // Run/Cost totals from counting that Run more than once.
+      materializeDashboardProjections({
+        ...runMaterialization,
+        database,
+        canonicalEntities,
+        changedCreationRunIds,
+        hasPersistentSchema,
+        files,
+        skipped,
+        fingerprint,
+      });
+      refreshFirstFoldPayloads(workspaceRoot, database);
+      database.exec("COMMIT;");
+      reportLaunchProgress(
+        "projection_finalize",
+        80,
+        "Finalizando índices do banco persistente do dashboard.",
+      );
+      completedFiles = files;
+    } catch (error) {
+      database.exec("ROLLBACK;");
+      throw error;
+    }
+    // Reclaim the transaction log when no reader pins an older snapshot.
+    // With the default zero busy timeout this never waits on a dashboard read;
+    // a busy checkpoint leaves the valid WAL for the next synchronization.
+    database.exec("PRAGMA busy_timeout=0; PRAGMA wal_checkpoint(TRUNCATE);");
+  } finally {
+    database.close();
+  }
+  const materializeStartedAt = fingerprintStartedAt + fingerprintMs;
+  reportLaunchProgress("snapshot_ready", 86, "O banco SQLite persistente está pronto.");
+  validateSqliteReadModelSchema(path);
+  return {
+    files: completedFiles,
+    path,
+    cache: "rebuilt",
+    fingerprint_ms: fingerprintMs,
+    materialize_ms: Math.round(performance.now() - materializeStartedAt),
+    refresh,
+  };
+}