@zaip-ai/cli 1.0.7 → 1.3.0

package/templates/.agents/dashboard/packages/local-runtime/src/server-operations-pages.ts

@@ -0,0 +1,354 @@
+import { posix } from "node:path";
+import type { WorkspaceLayout } from "@zaip-ai/core";
+import type { CostSummarySource } from "@zaip-ai/dashboard-cost-monitor/server";
+import type { Context } from "hono";
+export type OperationsCompactRun = NonNullable<CostSummarySource["run_metrics"]>[number] & {
+  execution_id?: string | null;
+  conversation_id?: string | null;
+  run_kind?: "run" | "subrun" | null;
+  agent?: string | null;
+};
+
+/** Aggregate entity views before pagination; raw Runs remain one row each. */
+export function aggregateOperationsPageRows(
+  rows: readonly OperationsCompactRun[],
+  kind: string,
+): OperationsCompactRun[] {
+  if (kind !== "executions" && kind !== "conversations") return [...rows];
+  const groups = new Map<
+    string,
+    OperationsCompactRun & {
+      duration_ms: number | null;
+      total_tokens: number | null;
+      cost: number | null;
+    }
+  >();
+  for (const row of rows) {
+    const key = kind === "executions" ? row.execution_id : row.conversation_id;
+    if (key === null || key === undefined) continue;
+    const current = groups.get(key) ?? {
+      ...row,
+      id: key,
+      duration_ms: null,
+      total_tokens: null,
+      cost: null,
+    };
+    // Entity duration represents source-observed root execution timing only.
+    // Tokens/cost remain additive over all captured invocations in that entity.
+    if (row.phase === "execution" && row.parent_run_id === null && row.duration_ms !== null)
+      current.duration_ms = (current.duration_ms ?? 0) + row.duration_ms;
+    if (row.total_tokens !== null)
+      current.total_tokens = (current.total_tokens ?? 0) + row.total_tokens;
+    if (row.cost !== null) current.cost = (current.cost ?? 0) + row.cost;
+    if (row.started_at < current.started_at) current.started_at = row.started_at;
+    if (
+      current.finished_at === null ||
+      (row.finished_at !== null && row.finished_at > current.finished_at)
+    )
+      current.finished_at = row.finished_at;
+    groups.set(key, current);
+  }
+  return [...groups.values()].sort((left, right) =>
+    right.started_at.localeCompare(left.started_at),
+  );
+}
+
+export function executionEntityPageRows(
+  entities: readonly {
+    id: string;
+    status: string | null;
+    updated_at: string;
+    data: Record<string, unknown> | null;
+  }[],
+  metrics: readonly OperationsCompactRun[],
+  kind: string,
+  from: string | null,
+  to: string | null,
+): OperationsCompactRun[] {
+  const byExecution = new Map<string, OperationsCompactRun[]>();
+  for (const metric of metrics) {
+    if (metric.execution_id === null || metric.execution_id === undefined) continue;
+    byExecution.set(metric.execution_id, [...(byExecution.get(metric.execution_id) ?? []), metric]);
+  }
+  return entities
+    .filter((entity) => {
+      const data = entity.data as {
+        kind?: unknown;
+        created_at?: unknown;
+        origin?: { type?: unknown };
+      } | null;
+      const created = typeof data?.created_at === "string" ? data.created_at : entity.updated_at;
+      return (
+        (from === null || created >= from) &&
+        (to === null || created <= to) &&
+        (kind === "executions" ||
+          (data?.kind === "interaction" && data.origin?.type === "interaction"))
+      );
+    })
+    .map((entity) => {
+      const data = entity.data as {
+        created_at?: unknown;
+        finished_at?: unknown;
+        kind?: unknown;
+        started_at?: unknown;
+        duration_ms?: unknown;
+        duration_provenance?: unknown;
+        origin?: { type?: unknown; conversation_id?: unknown; task_id?: unknown };
+      } | null;
+      const rows = byExecution.get(entity.id) ?? [];
+      const rootRuns = rows.filter(
+        (row) => row.phase === "execution" && row.parent_run_id === null,
+      );
+      const observedRootRuns = rootRuns.filter((row) => row.duration_ms !== null);
+      const observedExecutionFallback =
+        rootRuns.length === 0 &&
+        data?.duration_provenance === "observed" &&
+        typeof data?.duration_ms === "number" &&
+        data.duration_ms >= 0
+          ? data.duration_ms
+          : null;
+      const known = <K extends "total_tokens" | "cost">(key: K) => {
+        const values = rows
+          .map((row) => row[key])
+          .filter((value): value is number => value !== null);
+        return values.length === 0 ? null : values.reduce((sum, value) => sum + value, 0);
+      };
+      const started = typeof data?.created_at === "string" ? data.created_at : entity.updated_at;
+      return {
+        id: entity.id,
+        started_at: started,
+        finished_at: typeof data?.finished_at === "string" ? data.finished_at : null,
+        task_id: typeof data?.origin?.task_id === "string" ? data.origin.task_id : null,
+        execution_id: entity.id,
+        conversation_id:
+          typeof data?.origin?.conversation_id === "string" ? data.origin.conversation_id : null,
+        run_kind: data?.kind === "interaction" ? ("run" as const) : null,
+        phase: data?.kind === "interaction" ? "conversation" : "execution",
+        parent_run_id: null,
+        status: entity.status,
+        // Execution fallback is allowed only when its explicit provenance
+        // declares the same source-observed timing and no root Run is known.
+        duration_ms:
+          observedRootRuns.length === 0
+            ? observedExecutionFallback
+            : observedRootRuns.reduce((sum, row) => sum + (row.duration_ms ?? 0), 0),
+        lifecycle_elapsed_ms:
+          kind === "executions"
+            ? executionLifecycleElapsedMs(rows)
+            : lifecycleElapsedMs(
+                entity.status,
+                typeof data?.started_at === "string" ? data.started_at : null,
+                typeof data?.finished_at === "string" ? data.finished_at : null,
+              ),
+        total_tokens: known("total_tokens"),
+        cost: known("cost"),
+        currency: rows.find((row) => row.currency !== null)?.currency ?? null,
+        events: null,
+      };
+    })
+    .reduce<OperationsCompactRun[]>((result, row) => {
+      if (kind !== "conversations") return [...result, row];
+      const prior = result.find((value) => value.conversation_id === row.conversation_id);
+      if (prior === undefined) return [...result, { ...row, id: row.conversation_id ?? row.id }];
+      if (row.duration_ms !== null) prior.duration_ms = (prior.duration_ms ?? 0) + row.duration_ms;
+      if (row.total_tokens !== null)
+        prior.total_tokens = (prior.total_tokens ?? 0) + row.total_tokens;
+      if (row.cost !== null) prior.cost = (prior.cost ?? 0) + row.cost;
+      if (row.started_at > prior.started_at) {
+        prior.started_at = row.started_at;
+        prior.status = row.status;
+        prior.execution_id = row.execution_id;
+        prior.finished_at = row.finished_at;
+      } else if (
+        row.finished_at !== null &&
+        (prior.finished_at === null || row.finished_at > prior.finished_at)
+      ) {
+        prior.finished_at = row.finished_at;
+      }
+      return result;
+    }, [])
+    .sort((left, right) => right.started_at.localeCompare(left.started_at));
+}
+
+export function lifecycleElapsedMs(
+  status: string | null,
+  startedAt: string | null,
+  finishedAt: string | null,
+): number | null {
+  if (!new Set(["completed", "failed", "cancelled"]).has(status ?? "")) return null;
+  const start = startedAt === null ? Number.NaN : Date.parse(startedAt);
+  const end = finishedAt === null ? Number.NaN : Date.parse(finishedAt);
+  return Number.isFinite(start) && Number.isFinite(end) && end >= start ? end - start : null;
+}
+
+/** Execution elapsed is a diagnostic interval from proven terminal Runs, never updated_at/now. */
+export function executionLifecycleElapsedMs(rows: readonly OperationsCompactRun[]): number | null {
+  const terminal = new Set(["completed", "failed", "cancelled"]);
+  const unique = [...new Map(rows.map((row) => [row.id, row] as const)).values()];
+  const valid = unique.flatMap((row) => {
+    if (!terminal.has(row.status ?? "") || row.finished_at === null) return [];
+    const start = Date.parse(row.started_at);
+    const end = Date.parse(row.finished_at);
+    return Number.isFinite(start) && Number.isFinite(end) && end >= start ? [{ start, end }] : [];
+  });
+  if (valid.length === 0) return null;
+  return (
+    Math.max(...valid.map((value) => value.end)) - Math.min(...valid.map((value) => value.start))
+  );
+}
+
+type LifecyclePageEntity = {
+  id: string;
+  title: string | null;
+  status: string | null;
+  risk: string | null;
+  updated_at: string;
+  data: Record<string, unknown> | null;
+};
+
+export function changeEntityPageRows(
+  entities: readonly LifecyclePageEntity[],
+  layout: WorkspaceLayout,
+  from: string | null,
+  to: string | null,
+) {
+  return entities
+    .flatMap((entity) => {
+      const data = entity.data;
+      const createdAt = typeof data?.created_at === "string" ? data.created_at : null;
+      if (
+        createdAt === null ||
+        (from !== null && createdAt < from) ||
+        (to !== null && createdAt > to)
+      )
+        return [];
+      const source = data?.source;
+      if (source === null || typeof source !== "object" || !("type" in source)) return [];
+      const sourceRecord = source as Record<string, unknown>;
+      const validSource =
+        (sourceRecord.type === "task" && typeof sourceRecord.task_id === "string") ||
+        (sourceRecord.type === "spec" && typeof sourceRecord.spec_id === "string") ||
+        (sourceRecord.type === "prd" && typeof sourceRecord.prd_id === "string");
+      if (!validSource) return [];
+      return [
+        {
+          id: entity.id,
+          title: entity.title ?? (typeof data?.title === "string" ? data.title : entity.id),
+          created_at: createdAt,
+          status:
+            entity.status ?? (typeof data?.status === "string" ? data.status : "unclassified"),
+          risk: entity.risk ?? (typeof data?.risk === "string" ? data.risk : "unclassified"),
+          source: sourceRecord,
+          requirement_ids: stringArray(data?.requirement_ids),
+          acceptance_ids: stringArray(data?.acceptance_ids),
+          task_ids: stringArray(data?.task_ids),
+          result: typeof data?.result === "string" ? data.result : null,
+          artifact_path: layout.activePath("change", entity.id),
+        },
+      ];
+    })
+    .sort((left, right) => right.created_at.localeCompare(left.created_at));
+}
+
+export function decisionEntityPageRows(
+  entities: readonly LifecyclePageEntity[],
+  layout: WorkspaceLayout,
+  from: string | null,
+  to: string | null,
+) {
+  return entities
+    .flatMap((entity) => {
+      const data = entity.data;
+      const createdAt = typeof data?.created_at === "string" ? data.created_at : null;
+      if (
+        createdAt === null ||
+        (from !== null && createdAt < from) ||
+        (to !== null && createdAt > to) ||
+        (data?.origin !== "human" && data?.origin !== "agent") ||
+        (data?.scope_type !== "change" && data?.scope_type !== "execution") ||
+        typeof data?.scope_id !== "string"
+      )
+        return [];
+      return [
+        {
+          id: entity.id,
+          title: entity.title ?? (typeof data?.title === "string" ? data.title : entity.id),
+          origin: data.origin,
+          scope_type: data.scope_type,
+          scope_id: data.scope_id,
+          artifact_path: `${posix.dirname(layout.activePath(data.scope_type, data.scope_id))}/decisions/${entity.id}.md`,
+          created_at: createdAt,
+        },
+      ];
+    })
+    .sort((left, right) => right.created_at.localeCompare(left.created_at));
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+interface OperationsPageFilterValues {
+  query: string;
+  status: string;
+  risk: string;
+}
+
+export function operationsPageFilters(context: Context): OperationsPageFilterValues {
+  return {
+    query: (context.req.query("query") ?? "").trim().toLocaleLowerCase(),
+    status: (context.req.query("status") ?? "").trim(),
+    risk: (context.req.query("risk") ?? "").trim(),
+  };
+}
+
+export function filterOperationsMetricRows(
+  rows: readonly OperationsCompactRun[],
+  filters: OperationsPageFilterValues,
+): OperationsCompactRun[] {
+  return rows.filter((row) => {
+    if (filters.status && row.status !== filters.status) return false;
+    if (!filters.query) return true;
+    return [
+      row.id,
+      row.task_id,
+      row.execution_id,
+      row.conversation_id,
+      row.parent_run_id,
+      row.run_kind,
+      row.phase,
+      row.agent,
+    ].some(
+      (value) => typeof value === "string" && value.toLocaleLowerCase().includes(filters.query),
+    );
+  });
+}
+
+export function filterLifecyclePageRows(
+  rows: readonly Record<string, unknown>[],
+  filters: OperationsPageFilterValues,
+): Record<string, unknown>[] {
+  return rows.filter((row) => {
+    if (filters.status && row.status !== filters.status) return false;
+    if (filters.risk && row.risk !== filters.risk) return false;
+    if (!filters.query) return true;
+    return [
+      row.id,
+      row.title,
+      row.status,
+      row.risk,
+      row.source,
+      row.origin,
+      row.scope_type,
+      row.scope_id,
+    ]
+      .flatMap((value) =>
+        typeof value === "object" && value !== null ? Object.values(value) : [value],
+      )
+      .some(
+        (value) => typeof value === "string" && value.toLocaleLowerCase().includes(filters.query),
+      );
+  });
+}

package/templates/.agents/dashboard/packages/local-runtime/src/server-operations-runs-route.test.ts

@@ -0,0 +1,74 @@
+import type { CompactLifecycleDetail } from "@zaip-ai/lifecycle-manifests";
+import { describe, expect, it } from "vitest";
+import { compactOperationsPage } from "./server-operations-runs-route.js";
+
+const metric = (known_sum: number) => ({
+  known_sum,
+  unknown: 0,
+  complete: true,
+  coverage_ratio: 1,
+});
+
+describe("compactOperationsPage", () => {
+  it("keeps source duration distinct from the proved Execution lifecycle interval", () => {
+    const execution: CompactLifecycleDetail = {
+      id: "EXEC-1",
+      title: "Execution",
+      kind: "execution",
+      status: "completed",
+      risk: null,
+      occurred_at: "2026-08-07T12:00:00.000Z",
+      parent_id: null,
+      lifecycle_elapsed_ms: 90_000,
+      run_count: 1,
+      cost_currency: "BRL",
+      metrics: { duration: metric(60_000), total_tokens: metric(10), cost: metric(2) },
+    };
+    expect(
+      compactOperationsPage(
+        "executions",
+        { data_source: "lifecycle_daily_read_models", offset: 0, limit: 1, total: 1 },
+        [execution],
+      ).rows,
+    ).toMatchObject([
+      {
+        id: "EXEC-1",
+        execution_id: "EXEC-1",
+        duration_ms: 60_000,
+        lifecycle_elapsed_ms: 90_000,
+        total_tokens: 10,
+        cost: 2,
+      },
+    ]);
+  });
+
+  it("keeps Conversation lifecycle elapsed unavailable without its own canonical terminal interval", () => {
+    const conversation: CompactLifecycleDetail = {
+      id: "CONV-1",
+      title: "Conversation",
+      kind: "conversation",
+      status: "completed",
+      risk: null,
+      occurred_at: "2026-08-07T12:00:00.000Z",
+      parent_id: "EXEC-1",
+      lifecycle_elapsed_ms: null,
+      run_count: 1,
+      cost_currency: null,
+      metrics: { duration: metric(0), total_tokens: metric(0), cost: metric(0) },
+    };
+    expect(
+      compactOperationsPage(
+        "conversations",
+        { data_source: "lifecycle_daily_read_models", offset: 0, limit: 1, total: 1 },
+        [conversation],
+      ).rows,
+    ).toMatchObject([
+      {
+        id: "CONV-1",
+        execution_id: "EXEC-1",
+        conversation_id: "CONV-1",
+        lifecycle_elapsed_ms: null,
+      },
+    ]);
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/src/server-operations-runs-route.ts

@@ -0,0 +1,113 @@
+import type { WorkspaceFileSystem } from "@zaip-ai/core";
+import type { CostSummarySource } from "@zaip-ai/dashboard-cost-monitor/server";
+import { type CompactLifecycleDetail, LifecycleManifestStore } from "@zaip-ai/lifecycle-manifests";
+import type { Context, Hono } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import { pageDailyReadModel } from "./server-daily-read-models.js";
+import {
+  aggregateOperationsPageRows,
+  filterOperationsMetricRows,
+  operationsPageFilters,
+} from "./server-operations-pages.js";
+import { projectionPeriodFilter } from "./server-period.js";
+
+type AggregateReader = <T>(key: string, build: () => Promise<T>) => Promise<T>;
+type Responder = (
+  context: Context,
+  payload: unknown,
+  status: ContentfulStatusCode,
+  cache: boolean,
+) => Response;
+
+export function registerOperationsRunsRoute(
+  app: Hono,
+  filesystem: WorkspaceFileSystem,
+  readAggregate: AggregateReader,
+  respond: Responder,
+) {
+  app.on(["GET", "HEAD"], "/api/v2/operations/runs", async (context) => {
+    const offset = Math.max(0, Number.parseInt(context.req.query("offset") ?? "0", 10) || 0);
+    const limit = Math.min(
+      200,
+      Math.max(1, Number.parseInt(context.req.query("limit") ?? "100", 10) || 100),
+    );
+    const { from, to } = projectionPeriodFilter(context);
+    const kind = context.req.query("kind") ?? "runs";
+    const filters = operationsPageFilters(context);
+    const payload = await readAggregate(
+      `operations:runs:${kind}:${from ?? ""}:${to ?? ""}:${offset}:${limit}:${filters.query}:${filters.status}:${filters.risk}`,
+      async () => {
+        if (kind === "executions" || kind === "conversations") {
+          const snapshot = await new LifecycleManifestStore(filesystem).readDailyReadModels(kind);
+          if (snapshot !== null) {
+            const page = pageDailyReadModel(snapshot, kind, { from, to }, filters, offset, limit);
+            return compactOperationsPage(
+              kind,
+              page,
+              page.rows as readonly CompactLifecycleDetail[],
+            );
+          }
+        }
+        const summary = JSON.parse(
+          await filesystem.readText(".agents/records/lifecycle/summary.json"),
+        ) as CostSummarySource;
+        const sourceRows = (summary.run_metrics ?? []).filter(
+          (run) =>
+            (from === null || run.started_at >= from) &&
+            (to === null || run.started_at <= to) &&
+            (kind === "runs" ||
+              (kind === "conversations" &&
+                run.phase === "conversation" &&
+                run.conversation_id !== null) ||
+              (kind === "executions" && run.execution_id !== null)),
+        );
+        const rows = filterOperationsMetricRows(
+          aggregateOperationsPageRows(sourceRows, kind),
+          filters,
+        );
+        return {
+          data_source: "lifecycle_manifest_summary",
+          kind,
+          offset,
+          limit,
+          total: rows.length,
+          rows: rows.slice(offset, offset + limit),
+        };
+      },
+    );
+    return respond(context, payload, 200, true);
+  });
+}
+
+export function compactOperationsPage(
+  kind: "executions" | "conversations",
+  page: { data_source: string; offset: number; limit: number; total: number },
+  rows: readonly CompactLifecycleDetail[],
+) {
+  const known = (metric: CompactLifecycleDetail["metrics"]["duration"]) =>
+    metric.complete || metric.known_sum > 0 ? metric.known_sum : null;
+  return {
+    data_source: page.data_source,
+    kind,
+    offset: page.offset,
+    limit: page.limit,
+    total: page.total,
+    rows: rows.map((row) => ({
+      id: row.id,
+      started_at: row.occurred_at,
+      finished_at: null,
+      task_id: row.kind === "execution" ? row.parent_id : null,
+      execution_id: row.kind === "execution" ? row.id : row.parent_id,
+      conversation_id: row.kind === "conversation" ? row.id : null,
+      parent_run_id: null,
+      run_kind: "run" as const,
+      phase: row.kind,
+      status: row.status,
+      duration_ms: known(row.metrics.duration),
+      lifecycle_elapsed_ms: row.lifecycle_elapsed_ms ?? null,
+      total_tokens: known(row.metrics.total_tokens),
+      cost: known(row.metrics.cost),
+      currency: row.cost_currency,
+    })),
+  };
+}

package/templates/.agents/dashboard/packages/local-runtime/src/server-overview.test.ts

@@ -0,0 +1,68 @@
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { createDashboardApp } from "./server.js";
+
+const workspaceRoot = resolve(import.meta.dirname, "../../../../..");
+
+describe("dashboard overview transport", () => {
+  it("serves compact overview aggregates without transporting all Runs", async () => {
+    const app = createDashboardApp(workspaceRoot, "test-session");
+    const response = await app.request("/api/v2/operations?scope=overview", {
+      headers: { "x-zaip-session": "test-session" },
+    });
+
+    expect(response.status).toBe(200);
+    const payload = (await response.json()) as {
+      prds: unknown[];
+      runs: unknown[];
+      specs: unknown[];
+      tasks: unknown[];
+      summary?: { overview_metrics?: unknown };
+    };
+    if (payload.summary?.overview_metrics === undefined)
+      throw new Error("Operations overview payload has no summary metrics");
+    expect(payload).toMatchObject({ changes: [], executions: [], decisions: [] });
+    expect(payload.runs).toEqual([]);
+    expect(payload.summary.overview_metrics).toEqual(
+      expect.objectContaining({
+        duration_ms: expect.any(Number),
+        execution_day_count: expect.any(Number),
+        tokens: expect.any(Number),
+        cost_brl: expect.any(Number),
+      }),
+    );
+  });
+
+  it("serves the partial quick projection only when explicitly requested", async () => {
+    const app = createDashboardApp(workspaceRoot, "test-session");
+    const response = await app.request("/api/v2/operations?scope=quick", {
+      headers: { "x-zaip-session": "test-session" },
+    });
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject({
+      source: ".agents/records",
+      prds: expect.any(Array),
+      specs: expect.any(Array),
+      tasks: [],
+      changes: [],
+      executions: [],
+      runs: [],
+      decisions: [],
+      summary: {
+        overview_metrics: {
+          partial: true,
+          data_source: "lifecycle_manifest_summary",
+          duration_ms: expect.any(Number),
+          execution_day_count: expect.any(Number),
+          tokens: expect.any(Number),
+          cost_brl: expect.any(Number),
+          task_status_counts: expect.any(Object),
+          task_risk_counts: expect.any(Object),
+          top_tasks: expect.any(Array),
+        },
+      },
+    });
+    expect(response.headers.get("etag")).toMatch(/^".+"$/);
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/src/server-period.ts

@@ -0,0 +1,47 @@
+/** Date-only filters in the dashboard represent complete calendar days. */
+import type { Context } from "hono";
+
+export function projectionPeriodFilter(context: Pick<Context, "req">): {
+  from: string | null;
+  to: string | null;
+} {
+  const from = context.req.query("from") ?? null;
+  const to = context.req.query("to") ?? null;
+  return {
+    from: dateOnlyBoundary(from, "start"),
+    to: dateOnlyBoundary(to, "end"),
+  };
+}
+
+function dateOnlyBoundary(value: string | null, boundary: "start" | "end"): string | null {
+  if (value === null || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return value;
+  // Do not encode the current -03:00 offset. Historical Brazilian DST has a
+  // different offset, so the calendar contract must be resolved through IANA.
+  const start = saoPauloMidnight(value);
+  if (boundary === "start") return new Date(start).toISOString();
+  const [year, month, day] = value.split("-").map(Number) as [number, number, number];
+  const tomorrow = new Date(Date.UTC(year, month - 1, day + 1)).toISOString().slice(0, 10);
+  return new Date(saoPauloMidnight(tomorrow) - 1).toISOString();
+}
+
+function saoPauloMidnight(date: string): number {
+  const [year, month, day] = date.split("-").map(Number) as [number, number, number];
+  const localMidnight = Date.UTC(year, month - 1, day);
+  // Re-evaluate the offset after the first conversion so transitions around
+  // midnight remain tied to the IANA zone rather than a fixed historical UTC.
+  let instant = localMidnight - saoPauloOffsetMs(localMidnight);
+  instant = localMidnight - saoPauloOffsetMs(instant);
+  return instant;
+}
+
+function saoPauloOffsetMs(instant: number): number {
+  const zone = new Intl.DateTimeFormat("en-US", {
+    timeZone: "America/Sao_Paulo",
+    timeZoneName: "longOffset",
+  }).formatToParts(new Date(instant));
+  const offset = zone.find((part) => part.type === "timeZoneName")?.value ?? "GMT";
+  const match = /^GMT([+-])(\d{2}):(\d{2})$/.exec(offset);
+  if (match === null) return 0;
+  const minutes = Number(match[2]) * 60 + Number(match[3]);
+  return (match[1] === "+" ? 1 : -1) * minutes * 60_000;
+}