@zaip-ai/cli 1.0.7 → 1.0.8

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-metric-contract.ts

@@ -0,0 +1,708 @@
+/**
+ * Versioned inventory for the local SQLite comparison dashboard.
+ *
+ * This is a descriptive, testable contract: it does not make SQLite a source
+ * of truth. Canonical Runs, entities and configuration remain the inputs, and
+ * the read model may always be discarded and rebuilt.
+ */
+export const SQLITE_METRIC_CONTRACT_VERSION = 1 as const;
+export const SQLITE_METRIC_TIMEZONE = "America/Sao_Paulo" as const;
+
+export type MetricFormat =
+  | "count"
+  | "duration_ms"
+  | "tokens"
+  | "currency_brl"
+  | "currency_usd"
+  | "timestamp"
+  | "text"
+  | "status";
+export type ExportPolicy = "xlsx-client-snapshot" | "not_exported";
+export type PaginationPolicy =
+  | "offset"
+  | "offset-or-cursor"
+  | "bounded-first-fold"
+  | "all-time-first-fold"
+  | "none";
+
+export interface MetricSurfaceContract {
+  /** Stable inventory key, including top-level tab and subtab/card/chart/table. */
+  id: string;
+  tab: "operations" | "cost-monitor" | "traceability" | "runtime";
+  surface: "tab" | "subtab" | "card" | "chart" | "table" | "view" | "endpoint";
+  canonical_source: readonly string[];
+  sqlite_view: string | null;
+  endpoint: string | null;
+  ui_component: string | null;
+  metrics: readonly MetricFormat[];
+  unit: string;
+  timezone: typeof SQLITE_METRIC_TIMEZONE | "source-instant" | "not-applicable";
+  filtering: string;
+  pagination: PaginationPolicy;
+  export: ExportPolicy;
+  nullability: string;
+  deduplication: string;
+}
+
+const canonicalRuns = [".agents/records/runs/**/*.jsonl"] as const;
+const canonicalRunMetrics = [".agents/records/runs/**/*.jsonl"] as const;
+const canonicalLifecycle = [
+  ".agents/records/{prds,specs,tasks,changes,executions,decisions}/**/*.md",
+] as const;
+const noExport = "not_exported" as const;
+const xlsx = "xlsx-client-snapshot" as const;
+const allFilters =
+  "from/to São Paulo calendar day; query; status; risk; provider; model; agent; phase where supported";
+const invocationDedupe =
+  "one row per canonical agent invocation/activity_key; source_event_key duplicates are rejected before aggregation";
+const unknown =
+  "NULL means unavailable/unknown and must not become zero; a known empty aggregate is 0";
+
+/** All allowlisted views exposed by GET /api/v2/sqlite-views?view=. */
+export const SQLITE_VIEW_CONTRACTS = [
+  [
+    "cost_monitor_daily",
+    "cost-monitor",
+    canonicalRunMetrics,
+    "period key, calls, duration, tokens, BRL/USD",
+    "offset",
+    xlsx,
+  ],
+  [
+    "cost_monitor_monthly",
+    "cost-monitor",
+    canonicalRunMetrics,
+    "period key, calls, duration, tokens, BRL/USD",
+    "offset",
+    xlsx,
+  ],
+  [
+    "cost_monitor_annual",
+    "cost-monitor",
+    canonicalRunMetrics,
+    "period key, calls, duration, tokens, BRL/USD",
+    "offset",
+    xlsx,
+  ],
+  [
+    "cost_monitor_overview_view",
+    "cost-monitor",
+    canonicalRunMetrics,
+    "period totals",
+    "offset",
+    noExport,
+  ],
+  [
+    "cost_monitor_executions",
+    "cost-monitor",
+    canonicalRunMetrics,
+    "execution totals",
+    "offset",
+    xlsx,
+  ],
+  [
+    "cost_monitor_agent_invocations",
+    "cost-monitor",
+    canonicalRunMetrics,
+    "agent invocation facts",
+    "offset",
+    xlsx,
+  ],
+  ["cost_monitor_zaip_agents", "cost-monitor", canonicalRunMetrics, "agent totals", "offset", xlsx],
+  ["cost_monitor_models", "cost-monitor", canonicalRunMetrics, "model totals", "offset", xlsx],
+  ["cost_monitor_providers", "cost-monitor", canonicalRunMetrics, "provider totals", "offset", xlsx],
+  ["cost_monitor_tasks", "cost-monitor", canonicalRunMetrics, "task totals", "offset", xlsx],
+  ["cost_monitor_specs", "cost-monitor", canonicalRunMetrics, "SPEC totals", "offset", xlsx],
+  ["cost_monitor_prds", "cost-monitor", canonicalRunMetrics, "PRD totals", "offset", xlsx],
+  [
+    "cost_monitor_conversations",
+    "cost-monitor",
+    canonicalRunMetrics,
+    "conversation totals",
+    "offset",
+    xlsx,
+  ],
+  [
+    "operations_work_list",
+    "operations",
+    canonicalLifecycle,
+    "work identity/status/risk",
+    "offset",
+    xlsx,
+  ],
+  [
+    "operations_work_kanban",
+    "operations",
+    canonicalLifecycle,
+    "work identity/status/risk",
+    "offset",
+    xlsx,
+  ],
+  ["operations_executions", "operations", canonicalRunMetrics, "execution totals", "offset", xlsx],
+  [
+    "operations_agent_invocations",
+    "operations",
+    canonicalRunMetrics,
+    "agent invocation facts",
+    "offset",
+    xlsx,
+  ],
+  [
+    "operations_conversations",
+    "operations",
+    canonicalRunMetrics,
+    "conversation totals",
+    "offset",
+    xlsx,
+  ],
+  [
+    "operations_decisions",
+    "operations",
+    canonicalLifecycle,
+    "decision identity/status",
+    "offset",
+    xlsx,
+  ],
+  [
+    "operations_changes",
+    "operations",
+    canonicalLifecycle,
+    "change identity/status",
+    "offset",
+    xlsx,
+  ],
+  ["operations_daily", "operations", canonicalRunMetrics, "daily operations totals", "offset", xlsx],
+  [
+    "operations_monthly",
+    "operations",
+    canonicalRunMetrics,
+    "monthly operations totals",
+    "offset",
+    xlsx,
+  ],
+  [
+    "operations_annual",
+    "operations",
+    canonicalRunMetrics,
+    "annual operations totals",
+    "offset",
+    xlsx,
+  ],
+  [
+    "first_fold_overview",
+    "operations",
+    canonicalRunMetrics,
+    "first-fold KPI periods",
+    "bounded-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_task_status",
+    "operations",
+    canonicalLifecycle,
+    "task status distribution",
+    "bounded-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_task_risk",
+    "operations",
+    canonicalLifecycle,
+    "task risk distribution",
+    "bounded-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_top_tasks",
+    "operations",
+    canonicalRunMetrics,
+    "top task facts",
+    "bounded-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_overview_all_time",
+    "operations",
+    canonicalRunMetrics,
+    "single-row all-time KPI totals",
+    "all-time-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_task_status_all_time",
+    "operations",
+    canonicalLifecycle,
+    "all-time task status distribution",
+    "all-time-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_task_risk_all_time",
+    "operations",
+    canonicalLifecycle,
+    "all-time task risk distribution",
+    "all-time-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_task_metrics_all_time",
+    "operations",
+    canonicalRunMetrics,
+    "all-time task averages",
+    "all-time-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_top_tasks_all_time",
+    "operations",
+    canonicalRunMetrics,
+    "five all-time tasks by deduplicated duration",
+    "all-time-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_spec_status_all_time",
+    "operations",
+    canonicalLifecycle,
+    "all-time SPEC status distribution",
+    "all-time-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_spec_classification_all_time",
+    "operations",
+    canonicalLifecycle,
+    "all-time SPEC task/rework classification",
+    "all-time-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_spec_metrics_all_time",
+    "operations",
+    canonicalRunMetrics,
+    "all-time SPEC averages",
+    "all-time-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_top_specs_all_time",
+    "operations",
+    canonicalRunMetrics,
+    "five all-time SPECs by root Run duration",
+    "all-time-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_prd_status_all_time",
+    "operations",
+    canonicalLifecycle,
+    "all-time PRD status distribution",
+    "all-time-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_prd_classification_all_time",
+    "operations",
+    canonicalLifecycle,
+    "all-time PRD task/rework classification",
+    "all-time-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_prd_metrics_all_time",
+    "operations",
+    canonicalRunMetrics,
+    "all-time PRD averages",
+    "all-time-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_top_prds_all_time",
+    "operations",
+    canonicalRunMetrics,
+    "five all-time PRDs by root Run duration",
+    "all-time-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_task",
+    "operations",
+    canonicalLifecycle,
+    "task summary",
+    "bounded-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_spec",
+    "operations",
+    canonicalLifecycle,
+    "SPEC summary",
+    "bounded-first-fold",
+    noExport,
+  ],
+  [
+    "first_fold_prd",
+    "operations",
+    canonicalLifecycle,
+    "PRD summary",
+    "bounded-first-fold",
+    noExport,
+  ],
+] as const satisfies readonly [
+  string,
+  "operations" | "cost-monitor",
+  readonly string[],
+  string,
+  PaginationPolicy,
+  ExportPolicy,
+][];
+
+export const SQLITE_METRIC_SURFACES: readonly MetricSurfaceContract[] = [
+  {
+    id: "operations",
+    tab: "operations",
+    surface: "tab",
+    canonical_source: canonicalLifecycle,
+    sqlite_view: "first_fold_overview",
+    endpoint: "/api/v2/operations?scope=quick",
+    ui_component: "OperationsPage",
+    metrics: ["count", "duration_ms", "tokens", "currency_brl"],
+    unit: "items/ms/tokens/BRL",
+    timezone: SQLITE_METRIC_TIMEZONE,
+    filtering: "period; global operations filters",
+    pagination: "bounded-first-fold",
+    export: noExport,
+    nullability: unknown,
+    deduplication: invocationDedupe,
+  },
+  {
+    id: "operations.kanban",
+    tab: "operations",
+    surface: "subtab",
+    canonical_source: canonicalLifecycle,
+    sqlite_view: "operations_work_kanban",
+    endpoint: "/api/v2/operations?scope=board",
+    ui_component: "UnifiedWorkBoard",
+    metrics: ["count", "status", "text"],
+    unit: "work items",
+    timezone: SQLITE_METRIC_TIMEZONE,
+    filtering: "period, stage, query, status, risk, origin, kind",
+    pagination: "offset",
+    export: xlsx,
+    nullability: "missing lifecycle fields remain null; no synthetic Task",
+    deduplication: "canonical ID once per board stage",
+  },
+  {
+    id: "operations.work-list",
+    tab: "operations",
+    surface: "subtab",
+    canonical_source: canonicalLifecycle,
+    sqlite_view: "operations_work_list",
+    endpoint: "/api/v2/operations?scope=detail",
+    ui_component: "UnifiedWorkList",
+    metrics: ["count", "status", "text"],
+    unit: "work items",
+    timezone: SQLITE_METRIC_TIMEZONE,
+    filtering: "period, query, status, risk, origin, kind",
+    pagination: "offset",
+    export: xlsx,
+    nullability: unknown,
+    deduplication: "canonical entity ID",
+  },
+  {
+    id: "operations.lifecycle-pages",
+    tab: "operations",
+    surface: "table",
+    canonical_source: canonicalLifecycle,
+    sqlite_view: "operations_changes; operations_decisions",
+    endpoint: "/api/v2/sqlite-views",
+    ui_component: "OperationsPage",
+    metrics: ["count", "status", "timestamp"],
+    unit: "entities",
+    timezone: SQLITE_METRIC_TIMEZONE,
+    filtering: "period, query, status, risk",
+    pagination: "offset",
+    export: xlsx,
+    nullability: unknown,
+    deduplication: "canonical entity ID",
+  },
+  {
+    id: "operations.execution-pages",
+    tab: "operations",
+    surface: "table",
+    canonical_source: canonicalRunMetrics,
+    sqlite_view: "operations_executions; operations_agent_invocations; operations_conversations",
+    endpoint: "/api/v2/sqlite-views",
+    ui_component: "OperationsPage",
+    metrics: ["count", "duration_ms", "tokens", "currency_brl", "status"],
+    unit: "invocations/ms/tokens/BRL",
+    timezone: SQLITE_METRIC_TIMEZONE,
+    filtering: allFilters,
+    pagination: "offset",
+    export: xlsx,
+    nullability: unknown,
+    deduplication: invocationDedupe,
+  },
+  {
+    id: "operations.period-summary",
+    tab: "operations",
+    surface: "table",
+    canonical_source: canonicalRunMetrics,
+    sqlite_view: "operations_daily; operations_monthly; operations_annual",
+    endpoint: "/api/v2/sqlite-views",
+    ui_component: "PeriodSummaryTable",
+    metrics: ["count", "duration_ms", "tokens", "currency_brl"],
+    unit: "period totals",
+    timezone: SQLITE_METRIC_TIMEZONE,
+    filtering: "from/to; period granularity",
+    pagination: "offset",
+    export: xlsx,
+    nullability: unknown,
+    deduplication: invocationDedupe,
+  },
+  {
+    id: "operations.kpi-cards-and-charts",
+    tab: "operations",
+    surface: "card",
+    canonical_source: canonicalRunMetrics,
+    sqlite_view:
+      "first_fold_overview; first_fold_task_status; first_fold_task_risk; first_fold_top_tasks",
+    endpoint: "/api/v2/operations?scope=quick",
+    ui_component: "OperationsOverview",
+    metrics: ["count", "duration_ms", "tokens", "currency_brl"],
+    unit: "filtered aggregate",
+    timezone: SQLITE_METRIC_TIMEZONE,
+    filtering: "from/to only; never partial detail navigation",
+    pagination: "bounded-first-fold",
+    export: noExport,
+    nullability: unknown,
+    deduplication: invocationDedupe,
+  },
+  {
+    id: "cost-monitor",
+    tab: "cost-monitor",
+    surface: "tab",
+    canonical_source: canonicalRunMetrics,
+    sqlite_view: "cost_monitor_overview_view",
+    endpoint: "/api/v2/cost-monitor?scope=summary",
+    ui_component: "CostMonitorPage",
+    metrics: ["duration_ms", "tokens", "currency_brl", "currency_usd"],
+    unit: "filtered aggregate",
+    timezone: SQLITE_METRIC_TIMEZONE,
+    filtering: allFilters,
+    pagination: "bounded-first-fold",
+    export: noExport,
+    nullability: unknown,
+    deduplication: invocationDedupe,
+  },
+  {
+    id: "cost.summary-cards",
+    tab: "cost-monitor",
+    surface: "card",
+    canonical_source: canonicalRunMetrics,
+    sqlite_view: "cost_monitor_overview_view",
+    endpoint: "/api/v2/cost-monitor?scope=summary",
+    ui_component: "CostSummary; CostPeriodAverageCards",
+    metrics: ["count", "duration_ms", "tokens", "currency_brl", "currency_usd"],
+    unit: "aggregate",
+    timezone: SQLITE_METRIC_TIMEZONE,
+    filtering: allFilters,
+    pagination: "bounded-first-fold",
+    export: noExport,
+    nullability: unknown,
+    deduplication: invocationDedupe,
+  },
+  {
+    id: "cost.charts",
+    tab: "cost-monitor",
+    surface: "chart",
+    canonical_source: canonicalRunMetrics,
+    sqlite_view: "cost_monitor_daily; cost_monitor_models",
+    endpoint: "/api/v2/sqlite-views",
+    ui_component: "CostCharts",
+    metrics: ["duration_ms", "tokens", "currency_brl", "currency_usd"],
+    unit: "aggregate",
+    timezone: SQLITE_METRIC_TIMEZONE,
+    filtering: allFilters,
+    pagination: "offset",
+    export: noExport,
+    nullability: "absent day is known zero; present row with absent financial fact is null",
+    deduplication: invocationDedupe,
+  },
+  {
+    id: "cost.period-tables",
+    tab: "cost-monitor",
+    surface: "table",
+    canonical_source: canonicalRunMetrics,
+    sqlite_view: "cost_monitor_daily; cost_monitor_monthly; cost_monitor_annual",
+    endpoint: "/api/v2/sqlite-views",
+    ui_component: "CostGroupsTable",
+    metrics: ["count", "duration_ms", "tokens", "currency_brl", "currency_usd"],
+    unit: "period totals",
+    timezone: SQLITE_METRIC_TIMEZONE,
+    filtering: allFilters,
+    pagination: "offset",
+    export: xlsx,
+    nullability: unknown,
+    deduplication: invocationDedupe,
+  },
+  {
+    id: "cost.dimension-tables",
+    tab: "cost-monitor",
+    surface: "table",
+    canonical_source: canonicalRunMetrics,
+    sqlite_view: "cost_monitor_zaip_agents; cost_monitor_models; cost_monitor_providers",
+    endpoint: "/api/v2/sqlite-views",
+    ui_component: "CostGroupsTable; CostModelsAuditTable",
+    metrics: ["count", "duration_ms", "tokens", "currency_brl", "currency_usd"],
+    unit: "dimension totals",
+    timezone: SQLITE_METRIC_TIMEZONE,
+    filtering: allFilters,
+    pagination: "offset",
+    export: xlsx,
+    nullability: "mixed provider/model is literal mixed; absent is null",
+    deduplication: invocationDedupe,
+  },
+  {
+    id: "cost.entity-tables",
+    tab: "cost-monitor",
+    surface: "table",
+    canonical_source: canonicalRunMetrics,
+    sqlite_view:
+      "cost_monitor_executions; cost_monitor_tasks; cost_monitor_specs; cost_monitor_prds; cost_monitor_conversations",
+    endpoint: "/api/v2/sqlite-views",
+    ui_component: "CompactLifecycleCostTable; MacroCostTable",
+    metrics: ["count", "duration_ms", "tokens", "currency_brl", "currency_usd"],
+    unit: "entity totals",
+    timezone: SQLITE_METRIC_TIMEZONE,
+    filtering: "from/to, query; entity relation",
+    pagination: "offset",
+    export: xlsx,
+    nullability: unknown,
+    deduplication: invocationDedupe,
+  },
+  {
+    id: "cost.agent-calls",
+    tab: "cost-monitor",
+    surface: "table",
+    canonical_source: canonicalRunMetrics,
+    sqlite_view: "cost_monitor_agent_invocations",
+    endpoint: "/api/v2/sqlite-views",
+    ui_component: "CostTables",
+    metrics: [
+      "count",
+      "duration_ms",
+      "tokens",
+      "currency_brl",
+      "currency_usd",
+      "timestamp",
+      "status",
+    ],
+    unit: "agent invocations",
+    timezone: SQLITE_METRIC_TIMEZONE,
+    filtering: allFilters,
+    pagination: "offset",
+    export: xlsx,
+    nullability: unknown,
+    deduplication: invocationDedupe,
+  },
+  {
+    id: "traceability",
+    tab: "traceability",
+    surface: "tab",
+    canonical_source: [...canonicalLifecycle, ...canonicalRuns],
+    sqlite_view: null,
+    endpoint: "/api/v2/tasks/:id/trace",
+    ui_component: "TraceabilityWorkspace",
+    metrics: ["text", "status", "timestamp"],
+    unit: "linked canonical artifacts",
+    timezone: "source-instant",
+    filtering: "explicit task ID",
+    pagination: "none",
+    export: noExport,
+    nullability: "missing relationship is null/empty, never inferred",
+    deduplication: "canonical IDs and run IDs",
+  },
+];
+
+export const SQLITE_METRIC_ENDPOINTS = [
+  "/api/v2/health",
+  "/api/v2/ready",
+  "/api/v2/snapshot",
+  "/api/v2/operations",
+  "/api/v2/operations/entities",
+  "/api/v2/operations/runs",
+  "/api/v2/operations/read-models",
+  "/api/v2/cost-monitor",
+  "/api/v2/sqlite-read-models",
+  "/api/v2/sqlite-views",
+  "/api/v2/tasks/:id",
+  "/api/v2/prds/:id",
+  "/api/v2/specs/:id",
+  "/api/v2/tasks/:id/trace",
+  "/api/v2/work-priority",
+  "/api/v2/reconcile-open-work",
+  "/api/v2/pricing",
+  "/api/v2/fx-rate",
+  "/api/v2/agent-catalog",
+  "/api/v2/agent-catalog-assets/:agentId",
+  "/api/v2/project-settings",
+] as const;
+
+/** UI navigation names are separate from SQL views so no subtab is implicit. */
+export const SQLITE_DASHBOARD_SUBTABS = {
+  operations: [
+    "work-kanban",
+    "work-list",
+    "changes",
+    "decisions",
+    "executions",
+    "runs",
+    "conversations",
+    "daily",
+    "monthly",
+    "yearly",
+  ],
+  costMonitor: [
+    "overview",
+    "agentCalls",
+    "executions",
+    "conversations",
+    "tasks",
+    "prds",
+    "specs",
+    "providers",
+    "agents",
+    "models",
+    "daily",
+    "monthly",
+    "annual",
+  ],
+  traceability: ["task-trace"],
+} as const;
+
+export function validateSqliteMetricContract(): string[] {
+  const errors: string[] = [];
+  const seen = new Set<string>();
+  for (const surface of SQLITE_METRIC_SURFACES) {
+    if (seen.has(surface.id)) errors.push(`duplicate surface: ${surface.id}`);
+    seen.add(surface.id);
+    if (surface.canonical_source.length === 0)
+      errors.push(`missing canonical source: ${surface.id}`);
+    if (
+      surface.sqlite_view !== null &&
+      !SQLITE_VIEW_CONTRACTS.some(
+        ([view]) => view === surface.sqlite_view || surface.sqlite_view?.split("; ").includes(view),
+      )
+    )
+      errors.push(`unknown SQLite view: ${surface.id}`);
+    if (
+      surface.endpoint !== null &&
+      !SQLITE_METRIC_ENDPOINTS.some((endpoint) => surface.endpoint?.startsWith(endpoint))
+    )
+      errors.push(`unknown endpoint: ${surface.id}`);
+    if (surface.nullability.length === 0 || surface.deduplication.length === 0)
+      errors.push(`missing data semantics: ${surface.id}`);
+  }
+  return errors;
+}