@zaip-ai/cli 1.3.8 → 1.4.2

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

@@ -0,0 +1,793 @@
+import {
+  consolidatedValue,
+  frontMatterRecord,
+  recordValue,
+  stringValue,
+  stringValues,
+} from "./sqlite-read-model-canonical-parsing.js";
+
+export {
+  consolidatedValue,
+  frontMatterRecord,
+  recordValue,
+  stringValue,
+  stringValues,
+} from "./sqlite-read-model-canonical-parsing.js";
+
+import {
+  estimateUsageCost,
+  type FxRate,
+  fxRateSchema,
+  inferProvider,
+  type PersistedTokenUsage,
+  type PricingCatalog,
+} from "@zaip-ai/costs";
+import type { RunV2Fold, UsageRecordedV2 } from "../../../../../packages/decisions/src/index.js";
+
+const MAX_RECONCILED_RUN_INTERVAL_MS = 2 * 3_600_000;
+
+export function saoPauloCurrentMonth(): { from: string; to: string } {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: "America/Sao_Paulo",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(new Date());
+  const value = Object.fromEntries(parts.map((part) => [part.type, part.value]));
+  const day = `${value.year}-${value.month}-${value.day}`;
+  return { from: `${value.year}-${value.month}-01`, to: day };
+}
+
+/** Only canonical inputs consumed by the fact or its direct dimensions. */
+
+export type AgentProfile = {
+  catalogId: string;
+  persona: string | null;
+  job: string | null;
+  role: string | null;
+};
+export type CanonicalEntity = {
+  kind: string;
+  id: string;
+  title: string | null;
+  status: string | null;
+  stage: string | null;
+  risk: string | null;
+  specId: string | null;
+  changeId: string | null;
+  occurredAt: string | null;
+  creationRunId: string | null;
+  completedRunId: string | null;
+};
+export type CanonicalArtifact = {
+  kind: "evidence" | "validation";
+  id: string;
+  occurredAt: string;
+  occurredDaySp: string;
+  taskId: string | null;
+  changeId: string | null;
+  runId: string | null;
+};
+export type CanonicalExecution = {
+  id: string;
+  status: string | null;
+  kind: string | null;
+  originType: string | null;
+  originId: string | null;
+  createdAt: string;
+  finishedAt: string | null;
+  sourcePath: string;
+};
+export type CanonicalChange = {
+  id: string;
+  title: string;
+  status: string;
+  risk: string;
+  sourceType: string;
+  sourceId: string;
+  sourceSpecId: string | null;
+  sourcePrdId: string | null;
+  requirementIds: string[];
+  acceptanceIds: string[];
+  taskIds: string[];
+  result: string | null;
+  createdAt: string;
+  sourcePath: string;
+};
+export type CanonicalDecision = {
+  id: string;
+  title: string;
+  origin: "human" | "agent";
+  scopeType: "change" | "execution";
+  scopeId: string;
+  createdAt: string;
+  sourcePath: string;
+};
+export function readCanonicalLifecycleRecords(rows: Array<{ path: string; content: string }>): {
+  executions: CanonicalExecution[];
+  changes: CanonicalChange[];
+  decisions: CanonicalDecision[];
+} {
+  const executions: CanonicalExecution[] = [];
+  const changes: CanonicalChange[] = [];
+  const decisions: CanonicalDecision[] = [];
+  for (const row of rows) {
+    const metadata = frontMatterRecord(row.content);
+    if (metadata === null) continue;
+    const id = stringValue(metadata.id);
+    const createdAt = stringValue(metadata.created_at);
+    if (id === null || createdAt === null || Number.isNaN(Date.parse(createdAt))) continue;
+    if (/^\.agents\/records\/executions\/.*\/execution\.md$/.test(row.path)) {
+      const origin = recordValue(metadata.origin);
+      const originType = stringValue(origin?.type);
+      const originId =
+        originType === "interaction"
+          ? stringValue(origin?.conversation_id)
+          : originType === "task"
+            ? stringValue(origin?.task_id)
+            : originType === "spec"
+              ? stringValue(origin?.spec_id)
+              : originType === "prd"
+                ? stringValue(origin?.prd_id)
+                : null;
+      executions.push({
+        id,
+        status: stringValue(metadata.status),
+        kind: stringValue(metadata.kind),
+        originType,
+        originId,
+        createdAt,
+        finishedAt: stringValue(metadata.finished_at),
+        sourcePath: row.path,
+      });
+      continue;
+    }
+    if (/^\.agents\/records\/changes\/.*\/change\.md$/.test(row.path)) {
+      const source = recordValue(metadata.source);
+      const sourceType = stringValue(source?.type);
+      const sourceId =
+        sourceType === "task"
+          ? stringValue(source?.task_id)
+          : sourceType === "spec"
+            ? stringValue(source?.spec_id)
+            : sourceType === "prd"
+              ? stringValue(source?.prd_id)
+              : null;
+      if (sourceType === null || sourceId === null) continue;
+      changes.push({
+        id,
+        title: stringValue(metadata.title) ?? id,
+        status: stringValue(metadata.status) ?? "unclassified",
+        risk: stringValue(metadata.risk) ?? "unclassified",
+        sourceType,
+        sourceId,
+        // A Change sourced from a PRD can still name its selected SPEC. Keep
+        // both canonical lineage links: choosing one by source.type loses the
+        // only evidence that a planned Task belongs to that SPEC.
+        sourceSpecId: stringValue(source?.spec_id),
+        sourcePrdId: stringValue(source?.prd_id),
+        requirementIds: stringValues(metadata.requirement_ids),
+        acceptanceIds: stringValues(metadata.acceptance_ids),
+        taskIds: stringValues(metadata.task_ids),
+        result: stringValue(metadata.result),
+        createdAt,
+        sourcePath: row.path,
+      });
+      continue;
+    }
+    if (/^\.agents\/records\/(changes|executions)\/.*\/decisions\/.*\.md$/.test(row.path)) {
+      const origin = metadata.origin;
+      const scopeType = metadata.scope_type;
+      const scopeId = stringValue(metadata.scope_id);
+      if (
+        (origin !== "human" && origin !== "agent") ||
+        (scopeType !== "change" && scopeType !== "execution") ||
+        scopeId === null
+      )
+        continue;
+      decisions.push({
+        id,
+        title: stringValue(metadata.title) ?? id,
+        origin,
+        scopeType,
+        scopeId,
+        createdAt,
+        sourcePath: row.path,
+      });
+    }
+  }
+  return { executions, changes, decisions };
+}
+
+/** Reads only scalar front matter from canonical records to enrich linked activities. */
+export function readCanonicalEntities(
+  rows: Array<{ path: string; content: string }>,
+): Map<string, CanonicalEntity> {
+  const entities = new Map<string, CanonicalEntity>();
+  for (const row of rows) {
+    const match = /^\.agents\/records\/(tasks|specs|prds|changes|executions|conversations)\//.exec(
+      row.path,
+    );
+    if (match === null) continue;
+    const frontMatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(row.content)?.[1];
+    if (frontMatter === undefined) continue;
+    const scalar = (key: string): string | null => {
+      const value = new RegExp(`^${key}:\\s*(.+?)\\s*$`, "m").exec(frontMatter)?.[1]?.trim();
+      if (value === undefined || value === "null") return null;
+      return value.replace(/^['"]|['"]$/g, "");
+    };
+    const id = scalar("id");
+    if (id === null) continue;
+    const kind = match[1]?.slice(0, -1);
+    if (kind === undefined) continue;
+    entities.set(`${kind}:${id}`, {
+      kind,
+      id,
+      title: scalar("title"),
+      status: scalar("status"),
+      stage: scalar("stage"),
+      risk: scalar("risk"),
+      specId: scalar("spec_id"),
+      changeId: scalar("change_id"),
+      occurredAt: scalar("created_at") ?? scalar("started_at") ?? scalar("recorded_at"),
+      creationRunId: scalar("creation_run_id"),
+      completedRunId: scalar("completed_run_id"),
+    });
+  }
+  return entities;
+}
+
+/** Catalog data is snapshotted into the fact so historical labels never change after a catalog edit. */
+export function readAgentProfiles(
+  catalog: string | undefined,
+  clients: string | undefined,
+): Map<string, AgentProfile> {
+  const profiles = new Map<string, AgentProfile>();
+  for (const block of (catalog ?? "").split(/^ {2}- id: /m).slice(1)) {
+    const catalogId = block.slice(0, block.indexOf("\n")).trim();
+    const agent = /\bcodex_name:\s*([^\s#]+)/.exec(block)?.[1] ?? null;
+    if (agent === null) continue;
+    const persona = /persona:\s*\{\s*nome:\s*([^,}\s]+),\s*cargo:\s*([^,}\s]+)\s*\}/.exec(block);
+    const role = /\brole:\s*([^\s#]+)/.exec(block)?.[1] ?? null;
+    const profile = {
+      catalogId,
+      persona: persona?.[1] ?? null,
+      job: persona?.[2] ?? null,
+      role,
+    };
+    // Runs before canonicalization used catalog IDs directly, while older
+    // host records used `zaip-` forms of deprecated IDs.  All of these are
+    // explicit identities from the catalog; no UI fallback is involved.
+    const identities = new Set([agent, catalogId]);
+    for (const alias of block.matchAll(
+      /^ {8}- kind:\s*(?:id|codex_name|codex_task_name)\s*\r?\n {10}value:\s*([^\s#]+)/gm,
+    )) {
+      const value = alias[1];
+      if (value !== undefined) identities.add(value);
+    }
+    for (const identity of [...identities]) {
+      if (identity.startsWith("agent-")) identities.add(`zaip-${identity}`);
+    }
+    for (const identity of identities) profiles.set(identity, profile);
+  }
+  // `codex` is the host client identity, not a delegable Agent Catalog
+  // member. Its canonical client profile makes the host classification
+  // explicit, while keeping it separate from ZAIP subagent routing.
+  if (/^ {2}- id:\s*codex\s*$/m.test(clients ?? "")) {
+    profiles.set("codex", {
+      catalogId: "client:codex",
+      persona: "codex",
+      job: "client_host",
+      role: "host",
+    });
+  }
+  return profiles;
+}
+
+export function activityKind(value: {
+  execution_id: string | null;
+  task_id: string | null;
+  spec_id: string | null;
+  prd_id: string | null;
+  phase: string | null;
+  purpose: string | null;
+}): "conversation" | "planning" | "development" {
+  if (value.prd_id !== null && value.execution_id === null) return "planning";
+  if (value.spec_id !== null && value.execution_id === null) return "planning";
+  if (value.phase === "planning" || value.purpose === "planning") return "planning";
+  if (
+    value.execution_id !== null ||
+    value.task_id !== null ||
+    value.phase === "execution" ||
+    value.purpose === "implementation"
+  )
+    return "development";
+  return "conversation";
+}
+
+export type ActivityMetric = number | null;
+
+export function knownSum(
+  records: readonly UsageRecordedV2[],
+  key: keyof PersistedTokenUsage,
+): ActivityMetric {
+  const values = records
+    .map((record) => record.tokens[key])
+    .filter((value): value is number => typeof value === "number");
+  return values.length === 0 ? null : values.reduce((sum, value) => sum + value, 0);
+}
+
+export function canonicalProvider(
+  value: string | null | undefined,
+  model: string | null,
+  client: string,
+): "openai" | "anthropic" | null {
+  if (value === "openai" || value === "anthropic") return value;
+  // The canonical sentinel denotes an absent source attribute. It must not be
+  // re-inferred from the dashboard client as a known provider.
+  if (value === "unavailable" || model === "unavailable") return null;
+  return model === null ? null : inferProvider(model, client, "");
+}
+
+export function factualDuration(record: UsageRecordedV2): boolean {
+  return (
+    typeof record.duration_ms === "number" &&
+    (record.duration_provenance === "observed" ||
+      record.duration_provenance === "reconciled" ||
+      record.duration_provenance === "legacy_inferred")
+  );
+}
+
+export type ResolvedSourceInterval = { start: string; end: string; duration: number };
+
+/**
+ * Reconciled usage is the closest canonical observation of when model work
+ * happened.  It wins over Run finalization elapsed time, which may include
+ * orchestration/capture lag or be recorded much later.
+ */
+export function resolvedSourceInterval(
+  records: readonly UsageRecordedV2[],
+): ResolvedSourceInterval | null {
+  const intervals = records.flatMap((record) => {
+    const start = record.source_started_at;
+    const end = record.source_finished_at;
+    const startMs = typeof start === "string" ? Date.parse(start) : Number.NaN;
+    const endMs = typeof end === "string" ? Date.parse(end) : Number.NaN;
+    return typeof start === "string" &&
+      typeof end === "string" &&
+      Number.isFinite(startMs) &&
+      Number.isFinite(endMs) &&
+      endMs > startMs &&
+      endMs - startMs <= MAX_RECONCILED_RUN_INTERVAL_MS
+      ? [{ start, end, startMs, endMs }]
+      : [];
+  });
+  if (intervals.length === 0) return null;
+  const start = intervals.reduce((earliest, interval) =>
+    interval.startMs < earliest.startMs ? interval : earliest,
+  );
+  const end = intervals.reduce((latest, interval) =>
+    interval.endMs > latest.endMs ? interval : latest,
+  );
+  return end.endMs - start.startMs <= MAX_RECONCILED_RUN_INTERVAL_MS
+    ? { start: start.start, end: end.end, duration: end.endMs - start.startMs }
+    : null;
+}
+
+export function resolveDurations(
+  records: readonly UsageRecordedV2[],
+  fold: RunV2Fold,
+): {
+  source: number | null;
+  effective: number | null;
+  provenance: string | null;
+  sourceStartedAt: string | null;
+  sourceFinishedAt: string | null;
+} {
+  const sourceInterval = resolvedSourceInterval(records);
+  if (sourceInterval !== null) {
+    return {
+      source: sourceInterval.duration,
+      effective: sourceInterval.duration,
+      provenance: "reconciled",
+      sourceStartedAt: sourceInterval.start,
+      sourceFinishedAt: sourceInterval.end,
+    };
+  }
+  if (
+    typeof fold.finished?.duration_ms === "number" &&
+    fold.finished.duration_provenance !== "estimated" &&
+    fold.finished.duration_provenance !== "unavailable"
+  ) {
+    return {
+      source: fold.finished.duration_ms,
+      effective: fold.finished.duration_ms,
+      provenance: fold.finished.duration_provenance ?? "observed",
+      sourceStartedAt: null,
+      sourceFinishedAt: null,
+    };
+  }
+  const factual = records.filter(factualDuration);
+  if (factual.length > 0) {
+    const source = factual.reduce((sum, record) => sum + (record.duration_ms ?? 0), 0);
+    const provenance =
+      consolidatedValue(factual.map((record) => record.duration_provenance)) ?? "observed";
+    return { source, effective: source, provenance, sourceStartedAt: null, sourceFinishedAt: null };
+  }
+  // A canonical Run pair can supply elapsed time when terminal records predate
+  // the explicit duration field.  Historical finalizers can however close a
+  // Run days later, so only a bounded interval is trusted as reconciliation.
+  const startedAt = Date.parse(fold.run.occurred_at);
+  const finishedAt =
+    typeof fold.finished?.occurred_at === "string"
+      ? Date.parse(fold.finished.occurred_at)
+      : Number.NaN;
+  if (
+    Number.isFinite(startedAt) &&
+    Number.isFinite(finishedAt) &&
+    finishedAt > startedAt &&
+    finishedAt - startedAt <= MAX_RECONCILED_RUN_INTERVAL_MS
+  ) {
+    return {
+      source: null,
+      effective: finishedAt - startedAt,
+      provenance: "reconciled",
+      sourceStartedAt: null,
+      sourceFinishedAt: null,
+    };
+  }
+  // Tokens and lifecycle timestamps are not a time source.  Absence stays
+  // absent: consumers must display unavailable rather than manufacture time.
+  return {
+    source: null,
+    effective: null,
+    provenance: null,
+    sourceStartedAt: null,
+    sourceFinishedAt: null,
+  };
+}
+
+export function latestFxRate(rows: Array<{ path: string; content: string }>): FxRate | null {
+  return (
+    rows
+      .flatMap((row) => {
+        try {
+          return [fxRateSchema.parse(JSON.parse(row.content))];
+        } catch {
+          return [];
+        }
+      })
+      .sort((left, right) => right.as_of.localeCompare(left.as_of))[0] ?? null
+  );
+}
+
+export function aggregateCost(
+  records: readonly UsageRecordedV2[],
+  fold: RunV2Fold,
+  catalog: PricingCatalog,
+  fxRate: FxRate | null,
+) {
+  let usd = 0;
+  let brl = 0;
+  let knownUsd = false;
+  let knownBrl = false;
+  let estimated = false;
+  const pricingModels: string[] = [];
+  const pricingSources: string[] = [];
+  for (const record of records) {
+    if (typeof record.cost.usd === "number") {
+      usd += record.cost.usd;
+      knownUsd = true;
+    }
+    if (typeof record.cost.brl === "number") {
+      brl += record.cost.brl;
+      knownBrl = true;
+    }
+    if (typeof record.cost.usd === "number" && typeof record.cost.brl === "number") continue;
+    if (record.tokens.total === null) continue;
+    if (record.tokens.total === 0) {
+      knownUsd = true;
+      knownBrl = true;
+      continue;
+    }
+    const model = record.model ?? fold.run.model;
+    if (model === null || model === "unavailable") continue;
+    const priced = estimateUsageCost({
+      provider: canonicalProvider(record.provider, model, fold.run.client),
+      model,
+      usage: record.tokens,
+      catalog,
+      fxRate,
+      serviceTier: record.runtime?.service_tier ?? null,
+    });
+    if (typeof record.cost.usd !== "number" && priced.estimated_usd !== null) {
+      usd += priced.estimated_usd;
+      knownUsd = true;
+      estimated = true;
+    }
+    if (typeof record.cost.brl !== "number" && priced.estimated_brl !== null) {
+      brl += priced.estimated_brl;
+      knownBrl = true;
+      estimated = true;
+    }
+    if (priced.pricing_model !== null) pricingModels.push(priced.pricing_model);
+    if (priced.pricing_source !== null) pricingSources.push(priced.pricing_source);
+  }
+  const totalTokens = knownSum(records, "total");
+  return {
+    usd: knownUsd ? Math.round(usd * 1_000_000) / 1_000_000 : null,
+    brl: knownBrl ? Math.round(brl * 1_000_000) / 1_000_000 : null,
+    method:
+      totalTokens === 0
+        ? "zero_no_llm_usage"
+        : estimated
+          ? "token_pricing_estimate"
+          : knownUsd || knownBrl
+            ? "canonical_recorded"
+            : null,
+    pricingModel: consolidatedValue(pricingModels),
+    pricingSource: consolidatedValue(pricingSources),
+    fxRate: knownBrl ? (fxRate?.rate ?? null) : null,
+  };
+}
+
+export function pricingModelForUsage(catalog: PricingCatalog, model: string | null) {
+  if (model === null) return null;
+  const normalizedModel = model.toLowerCase();
+  const matches = (identity: string) => {
+    const normalizedIdentity = identity.toLowerCase();
+    if (normalizedModel === normalizedIdentity) return true;
+    const suffix = normalizedModel.slice(normalizedIdentity.length);
+    return (
+      suffix.startsWith("@") ||
+      suffix.startsWith(":") ||
+      suffix.startsWith("/") ||
+      /^-\d{4}-\d{2}-\d{2}(?:$|[.:@/])/.test(suffix)
+    );
+  };
+  return (
+    catalog.models.find(
+      (candidate) => matches(candidate.id) || candidate.aliases.some((alias) => matches(alias)),
+    ) ?? null
+  );
+}
+
+/** Pricing columns needed to reproduce the Guide calculation at invocation grain. */
+export function usagePricingAudit(
+  record: UsageRecordedV2,
+  fold: RunV2Fold,
+  catalog: PricingCatalog,
+  fxRate: FxRate | null,
+) {
+  const model = record.model ?? fold.run.model;
+  const provider = canonicalProvider(record.provider, model, fold.run.client);
+  const serviceTier = record.runtime?.service_tier ?? null;
+  const pricingModel = pricingModelForUsage(catalog, model);
+  const actual =
+    model === null
+      ? null
+      : estimateUsageCost({
+          provider,
+          model,
+          usage: record.tokens,
+          catalog,
+          fxRate,
+          serviceTier,
+        });
+  const standard =
+    model === null
+      ? null
+      : estimateUsageCost({
+          provider,
+          model,
+          usage: record.tokens,
+          catalog,
+          fxRate,
+          serviceTier: "default",
+        });
+  const longContext =
+    pricingModel?.long_context_threshold_tokens !== null &&
+    pricingModel?.long_context_threshold_tokens !== undefined &&
+    (record.tokens.input ?? 0) > pricingModel.long_context_threshold_tokens;
+  const priority = serviceTier === "priority" || serviceTier === "fast";
+  const priorityAvailable = priority && !longContext;
+  const inputRate = pricingModel
+    ? priorityAvailable
+      ? (pricingModel.priority_input_per_million_usd ?? null)
+      : pricingModel.input_per_million_usd
+    : null;
+  const cachedRate = pricingModel
+    ? priorityAvailable
+      ? (pricingModel.priority_cached_input_per_million_usd ?? null)
+      : pricingModel.cached_input_per_million_usd
+    : null;
+  const outputRate = pricingModel
+    ? priorityAvailable
+      ? (pricingModel.priority_output_per_million_usd ?? null)
+      : pricingModel.output_per_million_usd
+    : null;
+  const reasoningRate = pricingModel
+    ? priorityAvailable
+      ? (pricingModel.priority_reasoning_per_million_usd ??
+        pricingModel.priority_output_per_million_usd ??
+        null)
+      : (pricingModel.reasoning_per_million_usd ?? pricingModel.output_per_million_usd)
+    : null;
+  // Priority + long-context has no published combined tariff. The Guide uses
+  // the published Standard long-context scenario in that case, matching the
+  // canonical historical estimate without inventing a price table.
+  const priced = actual?.estimated_usd !== null && actual !== null ? actual : standard;
+  const calculatedUsd = priced?.estimated_usd ?? null;
+  const standardUsd = standard?.estimated_usd ?? null;
+  const recordedUsd = record.cost.usd;
+  const effectiveUsd = recordedUsd ?? calculatedUsd;
+  const effectiveBrl =
+    record.cost.brl ??
+    actual?.estimated_brl ??
+    (effectiveUsd !== null && fxRate !== null
+      ? Math.round(effectiveUsd * fxRate.rate * 1_000_000) / 1_000_000
+      : null);
+  return {
+    provider,
+    model,
+    serviceTier,
+    uncachedInputTokens:
+      record.tokens.input === null
+        ? null
+        : Math.max(record.tokens.input - (record.tokens.cached_input ?? 0), 0),
+    visibleOutputTokens:
+      record.tokens.output === null
+        ? null
+        : Math.max(record.tokens.output - (record.tokens.reasoning ?? 0), 0),
+    inputRate,
+    cachedRate,
+    outputRate,
+    reasoningRate,
+    contextInputMultiplier: pricingModel
+      ? longContext
+        ? pricingModel.long_context_input_multiplier
+        : 1
+      : null,
+    contextOutputMultiplier: pricingModel
+      ? longContext
+        ? pricingModel.long_context_output_multiplier
+        : 1
+      : null,
+    speedCostMultiplier:
+      calculatedUsd !== null && standardUsd !== null && standardUsd > 0
+        ? Math.round((calculatedUsd / standardUsd) * 1000) / 1000
+        : null,
+    pricingScenario:
+      priority && longContext
+        ? "standard_long_context_fallback"
+        : priority
+          ? "priority"
+          : "standard",
+    standardUsd,
+    speedUpliftUsd:
+      calculatedUsd !== null && standardUsd !== null
+        ? Math.round((calculatedUsd - standardUsd) * 1_000_000) / 1_000_000
+        : null,
+    inputUsd: priced?.input_usd ?? null,
+    cachedInputUsd: priced?.cached_input_usd ?? null,
+    outputUsd: priced?.output_usd ?? null,
+    reasoningUsd: priced?.reasoning_usd ?? null,
+    calculatedUsd,
+    recordedUsd,
+    effectiveUsd,
+    effectiveBrl,
+    varianceUsd:
+      recordedUsd !== null && calculatedUsd !== null
+        ? Math.round((recordedUsd - calculatedUsd) * 1_000_000) / 1_000_000
+        : null,
+    pricingModel: priced?.pricing_model ?? null,
+    pricingSource: priced?.pricing_source ?? null,
+    fxRate: record.cost.fx_rate ?? fxRate?.rate ?? null,
+  };
+}
+
+export function saoPauloDay(timestamp: string): string {
+  const values = Object.fromEntries(
+    new Intl.DateTimeFormat("en", {
+      timeZone: "America/Sao_Paulo",
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+    })
+      .formatToParts(new Date(timestamp))
+      .filter((part) => part.type !== "literal")
+      .map((part) => [part.type, part.value]),
+  ) as { year: string; month: string; day: string };
+  return `${values.year}-${values.month}-${values.day}`;
+}
+
+export type TemporalInterval = { activityRowId: string; startMs: number; endMs: number };
+
+/**
+ * Splits every observed interval at every activity boundary and São Paulo day
+ * boundary. Each elementary segment is divided equally among the token-active
+ * activities covering it, making the materialized fact additive by activity,
+ * day, and every parent dimension.
+ */
+export function allocateAttributedTokenActiveMs(intervals: readonly TemporalInterval[]) {
+  const boundaries = new Set<number>();
+  for (const interval of intervals) {
+    boundaries.add(interval.startMs);
+    boundaries.add(interval.endMs);
+    for (let cursor = interval.startMs; cursor < interval.endMs; ) {
+      const nextDay =
+        Date.parse(`${saoPauloDay(new Date(cursor).toISOString())}T03:00:00.000Z`) + 86_400_000;
+      if (nextDay >= interval.endMs) break;
+      boundaries.add(nextDay);
+      cursor = nextDay;
+    }
+  }
+  const points = [...boundaries].sort((left, right) => left - right);
+  const allocated = new Map<string, { activityRowId: string; day: string; value: number }>();
+  for (let index = 0; index < points.length - 1; index += 1) {
+    const startMs = points[index]!;
+    const endMs = points[index + 1]!;
+    const active = intervals.filter(
+      (interval) => interval.startMs < endMs && interval.endMs > startMs,
+    );
+    if (active.length === 0 || endMs <= startMs) continue;
+    const share = (endMs - startMs) / active.length;
+    const day = saoPauloDay(new Date(startMs).toISOString());
+    for (const interval of active) {
+      const key = `${interval.activityRowId}:${day}`;
+      const previous = allocated.get(key);
+      allocated.set(key, {
+        activityRowId: interval.activityRowId,
+        day,
+        value: (previous?.value ?? 0) + share,
+      });
+    }
+  }
+  return [...allocated.values()];
+}
+
+/** A dashboard API boundary can be a date or an ISO instant. Normalize both
+ * to the same Sao Paulo calendar key used by Cost Monitor SQL buckets. */
+export function costMonitorFilterDay(value: string | null | undefined): string | null {
+  if (value === null || value === undefined) return null;
+  return /^\d{4}-\d{2}-\d{2}$/.test(value) ? value : saoPauloDay(value);
+}
+
+export function sumKnownDeveloperMetric(
+  rows: readonly Record<string, unknown>[],
+  field: string,
+): number | null {
+  const values = rows
+    .map((row) => row[field])
+    .filter((value): value is number => typeof value === "number" && Number.isFinite(value));
+  return values.length === 0 ? null : values.reduce((sum, value) => sum + value, 0);
+}
+
+/** Extracts the small artifact projection while the canonical file is already being read. */
+export function readCanonicalArtifact(source: string, content: string): CanonicalArtifact | null {
+  const kind = source.includes("/artifacts/evidence/")
+    ? "evidence"
+    : source.includes("/artifacts/validations/") || source.includes("/artifacts/tests/")
+      ? "validation"
+      : null;
+  if (kind === null) return null;
+  const frontMatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content)?.[1] ?? "";
+  const scalar = (key: string): string | null => {
+    const value = new RegExp(`^${key}:\\s*['"]?(.+?)['"]?\\s*$`, "m")
+      .exec(frontMatter)?.[1]
+      ?.trim();
+    return value === undefined || value === "null" ? null : value;
+  };
+  const occurredAt =
+    scalar("observed_at") ?? scalar("executed_at") ?? scalar("created_at") ?? scalar("recorded_at");
+  if (occurredAt === null || Number.isNaN(Date.parse(occurredAt))) return null;
+  return {
+    kind,
+    id: scalar("id") ?? source.slice(source.lastIndexOf("/") + 1, -3),
+    occurredAt,
+    occurredDaySp: saoPauloDay(occurredAt),
+    taskId: scalar("task_id"),
+    changeId: scalar("change_id"),
+    runId: scalar("run_id"),
+  };
+}