@zaip-ai/cli 2.2.0 → 3.0.0

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

@@ -0,0 +1,762 @@
+import { DatabaseSync } from "node:sqlite";
+import { WorkspaceFileSystem } from "@zaip-ai/core";
+import type { CostSummarySource } from "@zaip-ai/dashboard-cost-monitor/server";
+import { attachAgentProductivity } from "./sqlite-agent-productivity.js";
+import {
+  readFirstFoldAllTime,
+  readFirstFoldBoardAllTime,
+  readFirstFoldMonthlyQuick,
+  readFirstFoldTopTasksAllTime,
+  readFirstFoldViewport,
+} from "./sqlite-first-fold-cache.js";
+import { operationsWorkListSqlRows } from "./sqlite-operations-work-list.js";
+import type { SqliteQueryContext } from "./sqlite-query-context.js";
+import {
+  queryActivityCostRows,
+  queryCostMonitorFactualDurationByDay,
+  queryCostMonitorFinancialActivityRows,
+  queryDeveloperCostAggregate,
+  queryInvocationCostRows,
+  queryInvocationTotals,
+  queryOperationsDeveloperAggregate,
+} from "./sqlite-query-financial.js";
+import { queryCostMonitorSummaryAggregate } from "./sqlite-query-summary.js";
+import {
+  queryCanonicalRunCountByDay,
+  queryDailyPeriods,
+  queryExecutionDurationByDay,
+  queryFirstFoldAggregate,
+  queryOverviewPage,
+  queryTopTasks,
+} from "./sqlite-query-timing.js";
+import { queryUncachedViewPage } from "./sqlite-query-view-page.js";
+import type {
+  SqliteFirstFoldAllTime,
+  SqliteFirstFoldAllTimeBoard,
+  SqliteFirstFoldMonthlyQuick,
+} from "./sqlite-read-model-first-fold-types.js";
+import { dbRelativePath, sqliteReadModelPath } from "./sqlite-read-model-schema.js";
+import {
+  type SqliteFirstFoldAggregate,
+  type SqliteFirstFoldViewport,
+  type SqliteSummaryKind,
+  type SqliteSummaryPage,
+  type SqliteViewName,
+  sqliteViewMetadata,
+} from "./sqlite-read-model-types.js";
+import { installLegacyViewAliases } from "./sqlite-snapshot-cache.js";
+export class SqliteReadModelFileSystem extends WorkspaceFileSystem {
+  private readonly executionDurationCache = new Map<string, Map<string, number>>();
+  private dailyAggregateRowsCache: Array<Record<string, number | string | null>> | null = null;
+  private firstFoldAllTimeCache: SqliteFirstFoldAllTime | null = null;
+  private firstFoldAllTimeBoardCache: SqliteFirstFoldAllTimeBoard | null = null;
+  private firstFoldTopTasksAllTimeCache: SqliteFirstFoldAllTime["top_tasks"] | null = null;
+  private firstFoldViewportCache: SqliteFirstFoldViewport | null = null;
+  private firstFoldMonthlyQuickCache: SqliteFirstFoldMonthlyQuick | null | undefined = undefined;
+  private firstFoldViewportTimings: Record<string, number> = {};
+  private metadataValues: Map<string, string> | null = null;
+  private readonly unfilteredViewPageCache = new Map<string, Array<Record<string, unknown>>>();
+  private readonly technicalPayloadRowsCache = new Map<string, Array<Record<string, unknown>>>();
+  private readonly viewPageResultCache = new Map<string, Record<string, unknown>>();
+  // Summary cards and temporal Cost tables consume the same aggregate. Keep
+  // exact filter results inside the immutable generation so a tab switch does
+  // not repeat its multi-second SQL scan.
+  private readonly costMonitorSummaryCache = new Map<string, CostSummarySource>();
+
+  canonicalSource(): ".agents/data" | ".agents/records" {
+    const current = this.database
+      .prepare("SELECT 1 FROM files WHERE path LIKE '.agents/data/%' LIMIT 1")
+      .get();
+    return current === undefined ? ".agents/records" : ".agents/data";
+  }
+  private dailyAggregateRows(): Array<Record<string, number | string | null>> {
+    if (this.dailyAggregateRowsCache === null) {
+      this.dailyAggregateRowsCache = this.database
+        .prepare("SELECT * FROM daily_aggregate_cache ORDER BY day")
+        .all() as Array<Record<string, number | string | null>>;
+    }
+    return this.dailyAggregateRowsCache;
+  }
+
+  private unfilteredViewRows(view: SqliteViewName): Array<Record<string, unknown>> {
+    const cached = this.unfilteredViewPageCache.get(view);
+    if (cached !== undefined) return cached;
+    const order = sqliteViewMetadata[view].order;
+    const rows = this.database.prepare(`SELECT * FROM ${view} ORDER BY ${order}`).all() as Array<
+      Record<string, unknown>
+    >;
+    this.unfilteredViewPageCache.set(view, rows);
+    return rows;
+  }
+
+  private technicalPayloadRows(payloadType: string): Array<Record<string, unknown>> {
+    const cached = this.technicalPayloadRowsCache.get(payloadType);
+    if (cached !== undefined) return cached;
+    const rows = (
+      this.database
+        .prepare("SELECT payload_json FROM zaip_aios_activities WHERE payload_type=?")
+        .all(payloadType) as Array<{ payload_json: string }>
+    ).flatMap(({ payload_json }) => {
+      try {
+        const parsed = JSON.parse(payload_json) as unknown;
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+          ? [parsed as Record<string, unknown>]
+          : [];
+      } catch {
+        return [];
+      }
+    });
+    this.technicalPayloadRowsCache.set(payloadType, rows);
+    return rows;
+  }
+  private database: DatabaseSync;
+  private readonly ownsDatabase: boolean;
+
+  constructor(root: string, database?: DatabaseSync) {
+    super(root);
+    this.ownsDatabase = database === undefined;
+    this.database = database ?? new DatabaseSync(sqliteReadModelPath(root), { readOnly: true });
+    // The aliases are TEMP views on this connection. The rebuilding writer
+    // needs them too because first-fold readers deliberately query through
+    // the same uncommitted transaction.
+    installLegacyViewAliases(this.database);
+  }
+
+  override async exists(path: string): Promise<boolean> {
+    const exact = this.database.prepare("SELECT 1 FROM files WHERE path = ? LIMIT 1").get(path);
+    const child = this.database
+      .prepare("SELECT 1 FROM files WHERE path LIKE ? LIMIT 1")
+      .get(`${path.replace(/\/$/, "")}/%`);
+    return exact !== undefined || child !== undefined;
+  }
+
+  override async readText(path: string): Promise<string> {
+    const row = this.database.prepare("SELECT content FROM files WHERE path = ?").get(path) as
+      | { content?: string }
+      | undefined;
+    if (row?.content === undefined)
+      throw Object.assign(new Error(`SQLite read model is missing ${path}`), { code: "ENOENT" });
+    return row.content;
+  }
+
+  override async readBytes(path: string): Promise<Buffer> {
+    return Buffer.from(await this.readText(path), "utf8");
+  }
+
+  override async readTextFrom(
+    path: string,
+    offset: number,
+  ): Promise<{ content: string; nextOffset: number }> {
+    const content = await this.readText(path);
+    const bytes = Buffer.from(content, "utf8");
+    return {
+      content: bytes.subarray(Math.min(offset, bytes.byteLength)).toString("utf8"),
+      nextOffset: bytes.byteLength,
+    };
+  }
+
+  override async listFiles(path: string, suffix = ""): Promise<readonly string[]> {
+    const prefix = `${path.replace(/\/$/, "")}/%`;
+    const rows = this.database
+      .prepare("SELECT path FROM files WHERE path LIKE ? ORDER BY path")
+      .all(prefix) as Array<{ path: string }>;
+    return rows.map((row) => row.path).filter((candidate) => candidate.endsWith(suffix));
+  }
+
+  override async listDirectories(path: string): Promise<readonly string[]> {
+    const prefix = `${path.replace(/\/$/, "")}/`;
+    const rows = this.database
+      .prepare("SELECT path FROM files WHERE path LIKE ?")
+      .all(`${prefix}%`) as Array<{ path: string }>;
+    return [
+      ...new Set(
+        rows
+          .map((row) => row.path.slice(prefix.length).split("/")[0])
+          .filter(Boolean)
+          .map((name) => `${path.replace(/\/$/, "")}/${name}`),
+      ),
+    ].sort();
+  }
+
+  close(): void {
+    if (this.ownsDatabase) this.database.close();
+  }
+
+  private reopen(): void {
+    this.database = new DatabaseSync(sqliteReadModelPath(this.root), { readOnly: true });
+    installLegacyViewAliases(this.database);
+    this.executionDurationCache.clear();
+    this.dailyAggregateRowsCache = null;
+    this.firstFoldAllTimeCache = null;
+    this.firstFoldAllTimeBoardCache = null;
+    this.firstFoldTopTasksAllTimeCache = null;
+    this.firstFoldViewportCache = null;
+    this.firstFoldMonthlyQuickCache = undefined;
+    this.firstFoldViewportTimings = {};
+    this.metadataValues = null;
+    // Public pages belong to the opened immutable SQLite generation. Never
+    // carry them across refresh/rebuild, even when this filesystem instance is
+    // reused by the launcher.
+    this.unfilteredViewPageCache.clear();
+    this.technicalPayloadRowsCache.clear();
+    this.costMonitorSummaryCache.clear();
+    this.viewPageResultCache.clear();
+  }
+
+  /** Reopen after an external atomic canonical read-model rebuild. */
+  refresh(): void {
+    this.database.close();
+    this.reopen();
+  }
+
+  /**
+   * Release the Windows read-only handle before replacing the generation.
+   * The prior snapshot is reopened when rebuilding fails, preserving a usable
+   * read model and surfacing the original rebuild error to the caller.
+   */
+  async rebuildAndRefresh(rebuild: () => Promise<unknown>): Promise<void> {
+    this.database.close();
+    try {
+      await rebuild();
+    } finally {
+      this.reopen();
+    }
+    // A successful refresh must leave the precise public Cost Monitor view
+    // usable before the server builds its response snapshot.
+    this.viewPage("cost_monitor_daily", { limit: 1, offset: 0 });
+  }
+
+  /**
+   * Wall-clock execution duration by Sao Paulo day. Root Runs define the
+   * execution envelope; child Runs are intentionally excluded because their
+   * time is already contained by the root. Concurrent roots are merged so the
+   * same clock interval is never counted twice.
+   */
+  executionDurationByDay(
+    filter: {
+      from: string | null;
+      to: string | null;
+      providers?: readonly string[];
+      models?: readonly string[];
+      agents?: readonly string[];
+      phases?: readonly string[];
+      statuses?: readonly string[];
+    },
+    taskId: string | null = null,
+  ): Map<string, number> {
+    return queryExecutionDurationByDay(this.queryContext(), filter, taskId);
+  }
+
+  canonicalRunCountByDay(filter: {
+    from: string | null;
+    to: string | null;
+    providers?: readonly string[];
+    models?: readonly string[];
+    agents?: readonly string[];
+    phases?: readonly string[];
+    statuses?: readonly string[];
+  }): Map<string, number> {
+    return queryCanonicalRunCountByDay(this.queryContext(), filter);
+  }
+
+  dailyPeriods(filter: { from: string | null; to: string | null }) {
+    return queryDailyPeriods(this.queryContext(), filter);
+  }
+
+  /** SQL-backed first-fold aggregate. SQLite SUM excludes unknown null facts. */
+  firstFoldAggregate(filter: { from: string | null; to: string | null }): SqliteFirstFoldAggregate {
+    return queryFirstFoldAggregate(this.queryContext(), filter);
+  }
+
+  /**
+   * Returns the materialized default-month inputs when they remain complete.
+   * A later month with no facts in this immutable generation is also an exact
+   * empty result; every month that may contain a fact continues through SQL.
+   */
+  firstFoldMonthlyQuick(filter: {
+    from: string | null;
+    to: string | null;
+  }): SqliteFirstFoldMonthlyQuick | null {
+    const read = readFirstFoldMonthlyQuick(this.database, this.firstFoldMonthlyQuickCache, filter);
+    this.firstFoldMonthlyQuickCache = read.cache;
+    return read.result;
+  }
+
+  firstFoldRelevantLatestDay(): string | null {
+    const row = this.database
+      .prepare(`SELECT MAX(day) AS day FROM (
+      SELECT occurred_day_sp AS day FROM activities
+      UNION ALL SELECT occurred_day_sp AS day FROM canonical_work_items
+      UNION ALL SELECT occurred_day_sp AS day FROM canonical_artifacts
+      UNION ALL SELECT occurred_day_sp AS day FROM canonical_run_index
+      UNION ALL SELECT occurred_day_sp AS day FROM attributed_token_active_facts
+    )`)
+      .get() as { day?: string | null };
+    return typeof row.day === "string" ? row.day : null;
+  }
+
+  firstFoldAllTime(): SqliteFirstFoldAllTime {
+    if (this.firstFoldAllTimeCache !== null) return this.firstFoldAllTimeCache;
+    this.firstFoldAllTimeCache = readFirstFoldAllTime(
+      this.database,
+      () => this.dailyAggregateRows().length,
+      this.firstFoldViewportAllTime(),
+    );
+    return this.firstFoldAllTimeCache;
+  }
+
+  firstFoldBoardAllTime(): SqliteFirstFoldAllTimeBoard {
+    if (this.firstFoldAllTimeBoardCache !== null) return this.firstFoldAllTimeBoardCache;
+    this.firstFoldAllTimeBoardCache = readFirstFoldBoardAllTime(this.database, () => {
+      const rows = operationsWorkListSqlRows(this.database);
+      return {
+        pages: {
+          task: rows.filter((row) => row.kind === "task" || row.kind === "standalone-task"),
+          spec: rows.filter((row) => row.kind === "spec"),
+          prd: rows.filter((row) => row.kind === "prd"),
+        },
+      };
+    });
+    return this.firstFoldAllTimeBoardCache;
+  }
+
+  firstFoldTopTasksAllTime(): SqliteFirstFoldAllTime["top_tasks"] {
+    if (this.firstFoldTopTasksAllTimeCache !== null) return this.firstFoldTopTasksAllTimeCache;
+    this.firstFoldTopTasksAllTimeCache = readFirstFoldTopTasksAllTime(this.database);
+    return this.firstFoldTopTasksAllTimeCache;
+  }
+
+  firstFoldViewportAllTime(): SqliteFirstFoldViewport {
+    if (this.firstFoldViewportCache !== null) return this.firstFoldViewportCache;
+    this.firstFoldViewportCache = readFirstFoldViewport(
+      this.database,
+      this.firstFoldViewportTimings,
+    );
+    return this.firstFoldViewportCache;
+  }
+
+  firstFoldViewportProfile(): Readonly<Record<string, number>> {
+    return this.firstFoldViewportTimings;
+  }
+
+  /** Top tasks from canonical activities, limited by the caller for first paint. */
+  topTasks(filter: { from: string | null; to: string | null }, limit = 5) {
+    return queryTopTasks(this.queryContext(), filter, limit);
+  }
+
+  canonicalTraceFiles(
+    markers: readonly string[],
+    maxContentLength?: number,
+  ): Array<{ path: string; content: string }> {
+    const selected = [...new Set(markers.filter(Boolean))];
+    if (selected.length === 0) return [];
+    if (
+      maxContentLength !== undefined &&
+      (!Number.isSafeInteger(maxContentLength) || maxContentLength < 0)
+    )
+      throw new Error("Invalid trace content bound");
+    const clauses = selected.map(() => "content LIKE ?").join(" OR ");
+    // SQL counts code points while the caller retains its UTF-16 length check.
+    // This conservative prefilter never excludes an otherwise admissible file.
+    const bound = maxContentLength === undefined ? "" : " AND length(content) <= ?";
+    return this.database
+      .prepare(`SELECT path, content FROM files
+        WHERE (path LIKE '.agents/data/%' OR path LIKE '.agents/records/%')${bound} AND (${clauses}) ORDER BY path`)
+      .all(
+        ...(maxContentLength === undefined ? [] : [maxContentLength]),
+        ...selected.map((marker) => `%${marker}%`),
+      ) as Array<{
+      path: string;
+      content: string;
+    }>;
+  }
+
+  taskTraceUsage(taskId: string) {
+    const runs = this.database
+      .prepare(`SELECT run_id, run_role, phase, duration_ms FROM canonical_run_index
+        WHERE task_id = ?`)
+      .all(taskId) as Array<{
+      run_id: string;
+      run_role: string;
+      phase: string | null;
+      duration_ms: number | null;
+    }>;
+    const financial = this.database
+      .prepare(`SELECT run_id, total_tokens, cost_brl FROM activities WHERE task_id = ?`)
+      .all(taskId) as Array<{
+      run_id: string;
+      total_tokens: number | null;
+      cost_brl: number | null;
+    }>;
+    const knownDurationRuns = runs.filter(
+      (run) =>
+        run.run_role === "root" && run.phase === "execution" && typeof run.duration_ms === "number",
+    ).length;
+    const durationByDay = this.executionDurationByDay({ from: null, to: null }, taskId);
+    const duration =
+      durationByDay.size === 0
+        ? null
+        : [...durationByDay.values()].reduce((sum, value) => sum + value, 0);
+    const knownTokens = financial.filter((row) => typeof row.total_tokens === "number");
+    const knownCosts = financial.filter((row) => typeof row.cost_brl === "number");
+    const metric = (value: number | null, known: number) => ({
+      value,
+      known_runs: known,
+      unknown_runs: Math.max(0, runs.length - known),
+      coverage_ratio: runs.length === 0 ? 1 : known / runs.length,
+    });
+    return {
+      run_count: runs.length,
+      duration_ms: metric(duration, knownDurationRuns),
+      total_tokens: metric(
+        knownTokens.length === 0
+          ? null
+          : knownTokens.reduce((sum, row) => sum + Number(row.total_tokens), 0),
+        knownTokens.length,
+      ),
+      cost: {
+        ...metric(
+          knownCosts.length === 0
+            ? null
+            : knownCosts.reduce((sum, row) => sum + Number(row.cost_brl), 0),
+          knownCosts.length,
+        ),
+        currency: knownCosts.length === 0 ? null : ("BRL" as const),
+      },
+    };
+  }
+
+  /** Cost Monitor agent population: canonical Agent Runs filtered by São Paulo calendar day. */
+  invocationTotals(filter: { from: string | null; to: string | null }): {
+    invocation_count: number;
+    llm_call_count: number | null;
+    total_tokens: number | null;
+    cost_usd: number | null;
+    cost_brl: number | null;
+  } {
+    return queryInvocationTotals(this.queryContext(), filter);
+  }
+
+  invocationCostRows(filter: {
+    from: string | null;
+    to: string | null;
+    providers?: readonly string[];
+    models?: readonly string[];
+    agents?: readonly string[];
+    phases?: readonly string[];
+    statuses?: readonly string[];
+    tasks?: readonly string[];
+    specs?: readonly string[];
+    prds?: readonly string[];
+    executions?: readonly string[];
+    changes?: readonly string[];
+  }) {
+    return queryInvocationCostRows(this.queryContext(), filter);
+  }
+
+  /**
+   * Attributed active-time facts for exactly the Cost Monitor financial
+   * population. This deliberately reads the same activity x Sao Paulo day
+   * fact used by Operations: recomputing a union from raw source intervals
+   * made the two surfaces disagree whenever sessions overlapped.
+   */
+  costMonitorFactualDurationByDay(
+    filter: Parameters<SqliteReadModelFileSystem["invocationCostRows"]>[0],
+    financialRows: readonly Record<string, unknown>[] = this.costMonitorFinancialActivityRows(
+      filter,
+    ),
+  ): Map<string, { known_sum: number; eligible_runs: number; known_runs: number }> {
+    return queryCostMonitorFactualDurationByDay(this.queryContext(), filter, financialRows);
+  }
+
+  /** Complete canonical Run population for global Cost Monitor aggregates. */
+  activityCostRows(filter: {
+    from: string | null;
+    to: string | null;
+    providers?: readonly string[];
+    models?: readonly string[];
+    agents?: readonly string[];
+    phases?: readonly string[];
+    statuses?: readonly string[];
+    tasks?: readonly string[];
+    specs?: readonly string[];
+    prds?: readonly string[];
+    executions?: readonly string[];
+    changes?: readonly string[];
+  }) {
+    return queryActivityCostRows(this.queryContext(), filter);
+  }
+
+  /** Cost Monitor's historical financial population, independent of Agent-only views. */
+  costMonitorFinancialActivityRows(
+    filter: Parameters<SqliteReadModelFileSystem["activityCostRows"]>[0],
+  ) {
+    return queryCostMonitorFinancialActivityRows(this.queryContext(), filter);
+  }
+
+  /**
+   * Aggregate-only Cost Monitor source. The SQL result is bounded to one row
+   * per selected day plus conversation/planning/execution and total rows; no
+   * activity-shaped record is returned to the server or serialized to HTTP.
+   */
+  developerCostAggregate(filter: {
+    from: string | null;
+    to: string | null;
+    accountIds?: readonly string[];
+  }) {
+    return queryDeveloperCostAggregate(this.queryContext(), filter);
+  }
+
+  /**
+   * Operations-only developer projection. It deliberately keeps the Cost
+   * Monitor aggregate unchanged: status, kind and risk are derived solely
+   * from canonical Task records linked to the developer's observed Task ids.
+   */
+  operationsDeveloperAggregate(filter: {
+    from: string | null;
+    to: string | null;
+    accountIds?: readonly string[];
+  }) {
+    return queryOperationsDeveloperAggregate(this.queryContext(), filter);
+  }
+
+  costMonitorSummaryAggregate(
+    filter: Parameters<SqliteReadModelFileSystem["activityCostRows"]>[0],
+  ): CostSummarySource {
+    return queryCostMonitorSummaryAggregate(this.queryContext(), filter);
+  }
+
+  /** Keyset cursor or LIMIT/OFFSET pagination for materialized work summaries. */
+  summaryPage(
+    kind: SqliteSummaryKind,
+    filter: {
+      from: string | null;
+      to: string | null;
+      status?: string;
+      risk?: string;
+      query?: string;
+    },
+    offset: number,
+    limit: number,
+    cursor: string | null = null,
+  ): SqliteSummaryPage {
+    // Entity summaries retain activity-derived historical coverage. Kanban is
+    // deliberately stricter and lists only canonical lifecycle records.
+    const table = "operations_work_summary";
+    const from = filter.from?.slice(0, 10) ?? null;
+    const to = filter.to?.slice(0, 10) ?? null;
+    const cursorValue = parseSummaryCursor(cursor);
+    const clauses = [
+      "entity_kind = ?",
+      "(? IS NULL OR occurred_day_sp >= ?)",
+      "(? IS NULL OR occurred_day_sp <= ?)",
+    ];
+    const values: Array<string | number | null> = [kind, from, from, to, to];
+    if (filter.status) {
+      clauses.push("status = ?");
+      values.push(filter.status);
+    }
+    if (filter.risk) {
+      clauses.push("risk = ?");
+      values.push(filter.risk);
+    }
+    if (filter.query) {
+      clauses.push("(id LIKE ? OR title LIKE ?)");
+      values.push(`%${filter.query}%`, `%${filter.query}%`);
+    }
+    const baseWhere = clauses.join(" AND ");
+    const baseValues = [...values];
+    if (cursorValue !== null) {
+      clauses.push("(occurred_at < ? OR (occurred_at = ? AND id < ?))");
+      values.push(cursorValue[0], cursorValue[0], cursorValue[1]);
+    }
+    const where = clauses.join(" AND ");
+    const total = Number(
+      (
+        this.database
+          .prepare(`SELECT COUNT(*) AS count FROM ${table} WHERE ${baseWhere}`)
+          .get(...baseValues) as { count: number }
+      ).count,
+    );
+    const pageOffset = cursorValue === null ? offset : 0;
+    const rows = this.database
+      .prepare(
+        `SELECT id, title, status, risk, occurred_at, occurred_day_sp,
+          invocation_count, llm_call_count, total_duration, total_tokens, total_cost_usd, total_cost_brl
+          FROM ${table} WHERE ${where} ORDER BY occurred_at DESC, id DESC LIMIT ? OFFSET ?`,
+      )
+      .all(...values, limit, pageOffset) as Array<Record<string, unknown>>;
+    const last = rows.at(-1);
+    return {
+      data_source: "sqlite_read_model",
+      kind,
+      offset: pageOffset,
+      limit,
+      total,
+      has_more: rows.length === limit && (cursorValue !== null || pageOffset + rows.length < total),
+      next_cursor:
+        last === undefined || rows.length < limit
+          ? null
+          : encodeSummaryCursor(String(last.occurred_at), String(last.id)),
+      rows,
+    };
+  }
+
+  /** Canonical page for the Board: keeps telemetry-only historical rows out. */
+  canonicalWorkPage(
+    kind: SqliteSummaryKind,
+    filter: { from: string | null; to: string | null },
+    offset: number,
+    limit: number,
+  ) {
+    return this.viewPage("operations_work_list", {
+      ...filter,
+      kind: kind === "task" ? "all-tasks" : kind,
+      offset,
+      limit,
+    });
+  }
+
+  overviewPage(period: "day" | "month" | "year", offset: number, limit: number) {
+    return queryOverviewPage(this.queryContext(), period, offset, limit);
+  }
+
+  viewPage(
+    view: SqliteViewName,
+    input: {
+      from?: string | null;
+      to?: string | null;
+      query?: string;
+      status?: string;
+      risk?: string;
+      provider?: string;
+      model?: string;
+      agent?: string;
+      phase?: string;
+      origin?: string;
+      workType?: string;
+      priority?: string;
+      kind?: "all" | "all-tasks" | "task" | "standalone-task" | "prd" | "spec";
+      offset?: number;
+      limit?: number;
+    },
+  ): ReturnType<SqliteReadModelFileSystem["uncachedViewPage"]> {
+    const key = `${view}:${JSON.stringify(input)}`;
+    const cached = this.viewPageResultCache.get(key);
+    if (cached !== undefined)
+      return structuredClone(cached) as ReturnType<SqliteReadModelFileSystem["uncachedViewPage"]>;
+    const result = this.uncachedViewPage(view, input);
+    if (view === "cost_monitor_zaip_agents") attachAgentProductivity(this.database, input, result);
+    if (this.viewPageResultCache.size >= 256) {
+      const oldest = this.viewPageResultCache.keys().next().value as string | undefined;
+      if (oldest !== undefined) this.viewPageResultCache.delete(oldest);
+    }
+    this.viewPageResultCache.set(key, structuredClone(result) as Record<string, unknown>);
+    return result;
+  }
+
+  /** Paginated allowlisted SQL view reader. Views are never interpolated from user input. */
+  private uncachedViewPage(
+    view: SqliteViewName,
+    input: {
+      from?: string | null;
+      to?: string | null;
+      query?: string;
+      status?: string;
+      risk?: string;
+      provider?: string;
+      model?: string;
+      agent?: string;
+      phase?: string;
+      origin?: string;
+      workType?: string;
+      priority?: string;
+      kind?: "all" | "all-tasks" | "task" | "standalone-task" | "prd" | "spec";
+      offset?: number;
+      limit?: number;
+    },
+  ) {
+    return queryUncachedViewPage(this.queryContext(), view, input);
+  }
+
+  metadata(): {
+    storage_mode: "sqlite_read_model";
+    db_path: string;
+    source_file_count: number;
+    excluded_source_count: number;
+    daily_aggregate_count: number;
+    activity_count: number;
+    canonical_run_count: number;
+    agent_run_count: number;
+    telemetry_summary_count: number;
+    unassisted_activity_count: number;
+  } {
+    if (this.metadataValues === null) {
+      this.metadataValues = new Map(
+        (
+          this.database.prepare("SELECT key, value FROM read_model_metadata").all() as Array<{
+            key: string;
+            value: string;
+          }>
+        ).map((row) => [row.key, row.value]),
+      );
+    }
+    const value = (key: string) => Number(this.metadataValues?.get(key) ?? 0);
+    return {
+      storage_mode: "sqlite_read_model",
+      db_path: process.env.ZAIP_SQLITE_DB_PATH ? "session-specific" : dbRelativePath,
+      source_file_count: value("source_file_count"),
+      excluded_source_count: value("excluded_source_count"),
+      daily_aggregate_count: value("daily_aggregate_count"),
+      activity_count: value("activity_count"),
+      canonical_run_count: value("canonical_run_count"),
+      agent_run_count: value("agent_run_count"),
+      telemetry_summary_count: value("telemetry_summary_count"),
+      unassisted_activity_count: value("unassisted_activity_count"),
+    };
+  }
+
+  projectionUpdatedAt(): string | null {
+    if (this.metadataValues === null) this.metadata();
+    const value = this.metadataValues?.get("snapshot_updated_at") ?? null;
+    return value !== null && Number.isFinite(Date.parse(value)) ? value : null;
+  }
+
+  latestTokenCollectedAt(): string | null {
+    if (this.metadataValues === null) this.metadata();
+    const value = this.metadataValues?.get("latest_token_collected_at") ?? null;
+    return value !== null && Number.isFinite(Date.parse(value)) ? value : null;
+  }
+
+  private queryContext(): SqliteQueryContext {
+    return {
+      database: this.database,
+      executionDurationCache: this.executionDurationCache,
+      costMonitorSummaryCache: this.costMonitorSummaryCache,
+      executionDurationByDay: this.executionDurationByDay.bind(this),
+      costMonitorFinancialActivityRows: this.costMonitorFinancialActivityRows.bind(this),
+      costMonitorFactualDurationByDay: this.costMonitorFactualDurationByDay.bind(this),
+      costMonitorSummaryAggregate: this.costMonitorSummaryAggregate.bind(this),
+      firstFoldMonthlyQuick: this.firstFoldMonthlyQuick.bind(this),
+      dailyAggregateRows: this.dailyAggregateRows.bind(this),
+      technicalPayloadRows: this.technicalPayloadRows.bind(this),
+      unfilteredViewRows: this.unfilteredViewRows.bind(this),
+    };
+  }
+}
+
+function encodeSummaryCursor(occurredAt: string, id: string): string {
+  return encodeURIComponent(JSON.stringify([occurredAt, id]));
+}
+
+function parseSummaryCursor(cursor: string | null): [string, string] | null {
+  if (cursor === null) return null;
+  try {
+    const parsed = JSON.parse(decodeURIComponent(cursor));
+    return Array.isArray(parsed) && typeof parsed[0] === "string" && typeof parsed[1] === "string"
+      ? [parsed[0], parsed[1]]
+      : null;
+  } catch {
+    return null;
+  }
+}