src/public-stats.ts

Functions

Imports

It imports src/env.ts, src/limits.ts, src/ops-snapshot.ts, src/time.ts. Imported by src/public-data.ts.

Source

1import { z } from "zod";
2import type { Env } from "./env";
3import { bounded } from "./limits";
4import { readSnapshot } from "./ops-snapshot";
5import { MINUTE_MS, DAY_MS } from "./time";
6
7// The public aggregate numbers (ruling capsid/rulings/system-explorer-2026-10-10.md,
8// section 3 and answer 5; design capsid/research/design-system-explorer.md, section 2;
9// docs/public-data.md). Counts, rates and medians over every namespace, agent and site
10// at once, computed once a UTC day over whole days ending at midnight. Never a title, a
11// body, a name, an email, error text, or a time of day: the only strings are the date
12// and the short sha /health already shows.
13//
14// A rate or median over fewer than FLOOR rows is null, so one job cannot be read off it.
15
16export const FLOOR = 10;
17
18const Count = z.number().int().min(0);
19const Rate = z.number().min(0).max(1).nullable();
20
21export const PublicStatsSchema = z.strictObject({
22  version: z.literal(1),
23  as_of: bounded(10).regex(/^\d{4}-\d{2}-\d{2}$/),
24  jobs: z.strictObject({
25    completed_7d: Count,
26    completed_30d: Count,
27    failed_30d: Count,
28    // Eight whole weeks, oldest first, each ending at a midnight.
29    completed_by_week: z.array(Count).length(8),
30    // The same eight weeks. The three weekly series added on 2026-10-23 are optional only so the
31    // explorer still parses a document the public build wrote before they existed.
32    failed_by_week: z.array(Count).length(8).optional(),
33    open: Count,
34    blocked: Count,
35    median_duration_minutes_30d: Count.nullable(),
36  }),
37  verification: z.strictObject({
38    evaluations_90d: Count,
39    agreement_rate_90d: Rate,
40    pr_merge_rate_90d: Rate,
41    ci_green_rate_90d: Rate,
42    // Agreement in each of the eight weeks, null for a week under the floor.
43    agreement_by_week: z.array(Rate).length(8).optional(),
44  }),
45  gates: z.strictObject({
46    waits_30d: Count,
47    median_wait_minutes_30d: Count.nullable(),
48    share_ended_by_policy_30d: Rate,
49    waits_by_week: z.array(Count).length(8).optional(),
50  }),
51  sites: z.strictObject({
52    watched: Count,
53    uptime_7d: Rate,
54    slots_measured_7d: Count,
55  }),
56  store: z.strictObject({ documents: Count, namespaces: Count }),
57  systems: z.strictObject({ public: Count, private: Count }).nullable(),
58  capsid: z.strictObject({ sha7: bounded(7).regex(/^[0-9a-f]{7}$|^unknown$/) }),
59});
60
61export type PublicStats = z.infer<typeof PublicStatsSchema>;
62
63/** The rows the numbers are computed from, each already limited to its window. */
64export interface StatsRows {
65  /** Jobs that finished (done or failed) in the last 56 days: status and when. */
66  finished: Array<{ status: string; updated_at: string }>;
67  /** Open jobs by status, read at the build. */
68  open: Array<{ status: string; n: number }>;
69  /** job_outcomes in the last 90 days. */
70  outcomes: Array<{ recorded_at: string; duration_minutes: number | null; prs_opened: number | null; prs_merged: number | null; ci_green: number | null; verified: string }>;
71  /** job_evaluations' agreement in the last 90 days, and when each was recorded. */
72  evaluations: Array<{ agreement: string; recorded_at: string }>;
73  /** Touches that ended a wait in the last 56 days, and when. */
74  waits: Array<{ actor_kind: string; waited_ms: number; at: string }>;
75  /** Each watched site's uptime ring ('1' up, '0' down, '-' not measured). */
76  rings: string[];
77  documents: number;
78  namespaces: number;
79  systems: { public: number; private: number } | null;
80  sha: string | undefined;
81}
82
83function rate(num: number, den: number): number | null {
84  return den < FLOOR ? null : Math.round((num / den) * 1000) / 1000;
85}
86
87function median(values: number[]): number | null {
88  if (values.length < FLOOR) return null;
89  const s = [...values].sort((a, b) => a - b);
90  const mid = Math.floor(s.length / 2);
91  return Math.round(s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2);
92}
93
94function verifiedFields(json: string): Record<string, unknown> {
95  try {
96    const parsed = JSON.parse(json);
97    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : {};
98  } catch {
99    // Corrupt means nothing verified, as in src/agent-record.ts.
100    return {};
101  }
102}
103
104/** Midnight UTC at the start of `now`'s day: every window ends here. */
105function windowEnd(now: Date): Date {
106  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
107}
108
109const since = (end: Date, days: number) => new Date(end.getTime() - days * DAY_MS).toISOString();
110
111/** The public numbers from their rows. Pure, and the only place the rules live. */
112export function summarize(rows: StatsRows, now: Date): PublicStats {
113  const end = windowEnd(now);
114  const endIso = end.toISOString();
115  const inWindow = (at: string, days: number) => at >= since(end, days) && at < endIso;
116
117  // Eight whole weeks, oldest first: each week's rows by the time field `at` names.
118  const weekly = <T>(items: T[], at: (item: T) => string): T[][] =>
119    Array.from({ length: 8 }, (_, i) => {
120      const from = since(end, (8 - i) * 7);
121      const to = since(end, (7 - i) * 7);
122      return items.filter((r) => at(r) >= from && at(r) < to);
123    });
124  const done = rows.finished.filter((r) => r.status === "done");
125  const byWeek = weekly(done, (r) => r.updated_at).map((w) => w.length);
126  const failedByWeek = weekly(rows.finished.filter((r) => r.status === "failed"), (r) => r.updated_at).map((w) => w.length);
127
128  const outcomes30 = rows.outcomes.filter((o) => inWindow(o.recorded_at, 30));
129  const outcomes90 = rows.outcomes.filter((o) => inWindow(o.recorded_at, 90));
130  // As src/agent-record.ts reads them: only fields the Worker verified feed a rate.
131  const mergeRows = outcomes90.filter((o) => {
132    const v = verifiedFields(o.verified);
133    return v.prs_opened === true && v.prs_merged === true;
134  });
135  const opened = mergeRows.reduce((t, o) => t + (o.prs_opened ?? 0), 0);
136  const merged = mergeRows.reduce((t, o) => t + (o.prs_merged ?? 0), 0);
137  const ciRows = outcomes90.filter((o) => verifiedFields(o.verified).ci_green === true && o.ci_green !== null);
138
139  const agreement = (evaluations: StatsRows["evaluations"]) => {
140    const agree = evaluations.filter((e) => e.agreement === "agree").length;
141    return rate(agree, agree + evaluations.filter((e) => e.agreement === "disagree").length);
142  };
143  const waits30 = rows.waits.filter((w) => inWindow(w.at, 30));
144
145  let up = 0;
146  let down = 0;
147  for (const ring of rows.rings) {
148    for (const c of ring) {
149      if (c === "1") up++;
150      else if (c === "0") down++;
151    }
152  }
153
154  const openOf = (status: string) => rows.open.filter((r) => r.status === status).reduce((t, r) => t + r.n, 0);
155  const sha = rows.sha && /^[0-9a-f]{7,40}$/.test(rows.sha) ? rows.sha.slice(0, 7) : "unknown";
156
157  return {
158    version: 1,
159    as_of: endIso.slice(0, 10),
160    jobs: {
161      completed_7d: done.filter((r) => inWindow(r.updated_at, 7)).length,
162      completed_30d: done.filter((r) => inWindow(r.updated_at, 30)).length,
163      failed_30d: rows.finished.filter((r) => r.status === "failed" && inWindow(r.updated_at, 30)).length,
164      completed_by_week: byWeek,
165      failed_by_week: failedByWeek,
166      open: openOf("queued") + openOf("claimed") + openOf("blocked"),
167      blocked: openOf("blocked"),
168      median_duration_minutes_30d: median(outcomes30.map((o) => o.duration_minutes).filter((d): d is number => typeof d === "number")),
169    },
170    verification: {
171      evaluations_90d: rows.evaluations.length,
172      agreement_rate_90d: agreement(rows.evaluations),
173      pr_merge_rate_90d: rate(merged, opened),
174      ci_green_rate_90d: rate(ciRows.filter((o) => o.ci_green === 1).length, ciRows.length),
175      agreement_by_week: weekly(rows.evaluations, (e) => e.recorded_at).map(agreement),
176    },
177    gates: {
178      waits_30d: waits30.length,
179      median_wait_minutes_30d: median(waits30.map((w) => w.waited_ms / MINUTE_MS)),
180      share_ended_by_policy_30d: rate(waits30.filter((w) => w.actor_kind === "policy").length, waits30.length),
181      waits_by_week: weekly(rows.waits, (w) => w.at).map((w) => w.length),
182    },
183    sites: { watched: rows.rings.length, uptime_7d: rate(up, up + down), slots_measured_7d: up + down },
184    store: { documents: rows.documents, namespaces: rows.namespaces },
185    systems: rows.systems,
186    capsid: { sha7: sha },
187  };
188}
189
190/** Reads the rows for summarize. Single-table reads, each bounded by its window. */
191export async function readStatsRows(env: Env, now: Date, systems: StatsRows["systems"]): Promise<StatsRows> {
192  const end = windowEnd(now);
193  const endIso = end.toISOString();
194  const db = env.DB;
195  const finished = await db
196    .prepare("SELECT status, updated_at FROM jobs WHERE status IN ('done', 'failed') AND updated_at >= ?1 AND updated_at < ?2")
197    .bind(since(end, 56), endIso)
198    .all<StatsRows["finished"][number]>();
199  const open = await db
200    .prepare("SELECT status, COUNT(*) AS n FROM jobs WHERE status IN ('queued', 'claimed', 'blocked') GROUP BY status")
201    .all<StatsRows["open"][number]>();
202  const outcomes = await db
203    .prepare("SELECT recorded_at, duration_minutes, prs_opened, prs_merged, ci_green, verified FROM job_outcomes WHERE recorded_at >= ?1 AND recorded_at < ?2")
204    .bind(since(end, 90), endIso)
205    .all<StatsRows["outcomes"][number]>();
206  const evaluations = await db
207    .prepare("SELECT agreement, recorded_at FROM job_evaluations WHERE recorded_at >= ?1 AND recorded_at < ?2")
208    .bind(since(end, 90), endIso)
209    .all<StatsRows["evaluations"][number]>();
210  const waits = await db
211    .prepare("SELECT actor_kind, waited_ms, at FROM job_touches WHERE waited_ms IS NOT NULL AND at >= ?1 AND at < ?2")
212    .bind(since(end, 56), endIso)
213    .all<StatsRows["waits"][number]>();
214  const documents = await db.prepare("SELECT COUNT(*) AS n FROM documents").first<{ n: number }>();
215  const namespaces = await db.prepare("SELECT COUNT(*) AS n FROM namespaces").first<{ n: number }>();
216  const snapshot = await readSnapshot(env);
217  return {
218    finished: finished.results ?? [],
219    open: open.results ?? [],
220    outcomes: outcomes.results ?? [],
221    evaluations: evaluations.results ?? [],
222    waits: waits.results ?? [],
223    rings: (snapshot?.sites ?? []).map((s) => s.ring),
224    documents: documents?.n ?? 0,
225    namespaces: namespaces?.n ?? 0,
226    systems,
227    sha: env.BUILD_SHA,
228  };
229}