src/agent-record.ts

Functions

Imports

It imports src/agents-schema.ts. Imported by src/jobs-transition.ts, src/status.ts.

Source

1// What a credential has actually done, from the outcome rows.
2//
3// COUNTS AND RATES, NEVER A SCORE. A composite number needs a weighting, which is an
4// opinion, and a single number invites a gate nobody wrote down. Every field is a
5// named count or a rate with a stated denominator.
6//
7// A rate with no denominator is null, not zero: an agent that opened no pull
8// requests has no merge rate, and 0% would rank it below one that merged one in ten.
9
10import { agentActor } from "./agents-schema";
11
12// What this module needs to know about a credential, and no more. Not
13// `AgentSummary` from status.ts: that module builds the summaries and then asks
14// for the records, so importing its type here would make the two import each other.
15export interface RecordSubject {
16  name: string;
17  kind: string;
18  namespaces: "*" | string[];
19}
20
21export interface AgentRecord {
22  // The actor string matched: `agent:<name>`, as jobs.claimed_by and
23  // job_outcomes.agent carry it.
24  actor: string;
25  jobs_done: number;
26  jobs_failed: number;
27  // From the jobs table: a blocked job has not ended, so it has no outcome row.
28  jobs_blocked: number;
29  // How many times this agent's jobs hit a gate, and how many times one was sent back
30  // in. Totals across finished jobs, not a count of jobs.
31  gates_hit: number;
32  resumed: number;
33  prs_opened: number;
34  prs_merged: number;
35  // prs_merged / prs_opened, 0 to 1, rounded to three places. null when this agent
36  // has opened none.
37  pr_merge_rate: number | null;
38  // Share of CI conclusions the Worker checked and found green. The denominator is
39  // ci_checked, not jobs_done: a job with no pull request has no CI, and counting it
40  // as a miss would punish a documentation job for not having a build.
41  ci_checked: number;
42  ci_green_rate: number | null;
43  // Whole minutes, median (one job left open over a weekend skews a mean).
44  median_duration_minutes: number | null;
45}
46
47// The rows the record is computed from. Grouped reads, one per shape, so the query
48// count does not grow with the number of credentials.
49export interface RecordRows {
50  // One row per finished job, from job_outcomes.
51  outcomes: Array<{
52    agent: string;
53    prs_opened: number | null;
54    prs_merged: number | null;
55    ci_green: number | null;
56    blocked_count: number;
57    resumed_count: number;
58    duration_minutes: number | null;
59    verified: string;
60  }>;
61  // One row per (claimed_by, status) from jobs.
62  jobs: Array<{ actor: string; status: string; n: number }>;
63}
64
65function rate(numerator: number, denominator: number): number | null {
66  if (denominator === 0) return null;
67  return Math.round((numerator / denominator) * 1000) / 1000;
68}
69
70function median(values: number[]): number | null {
71  if (values.length === 0) return null;
72  const sorted = [...values].sort((a, b) => a - b);
73  const mid = Math.floor(sorted.length / 2);
74  // An even count averages the two middles and rounds to whole minutes.
75  return sorted.length % 2 === 1 ? sorted[mid] : Math.round((sorted[mid - 1] + sorted[mid]) / 2);
76}
77
78// Only a verified field counts toward a rate. Counts are stored whether or not the
79// Worker could check them, because an unverified count is still better than nothing
80// on the row. A rate is a claim about a credential that a reader acts on, and one
81// built from numbers the credential reported about itself is that credential grading
82// its own work. So the rates read only fields the `verified` object says were checked.
83function verifiedFields(json: string): Record<string, boolean> {
84  try {
85    const parsed = JSON.parse(json);
86    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? (parsed as Record<string, boolean>) : {};
87  } catch {
88    // Corrupt means nothing verified: a rate is withheld, not invented.
89    return {};
90  }
91}
92
93export function recordFor(actor: string, rows: RecordRows): AgentRecord {
94  const mine = rows.outcomes.filter((o) => o.agent === actor);
95  const jobsByStatus = (status: string) =>
96    rows.jobs.filter((r) => r.actor === actor && r.status === status).reduce((total, r) => total + r.n, 0);
97
98  // Every outcome row carries the counts; only the verified ones feed the rates.
99  const prVerified = mine.filter((o) => verifiedFields(o.verified).prs_opened === true);
100  const prsOpened = prVerified.reduce((total, o) => total + (o.prs_opened ?? 0), 0);
101  // The merge rate reads only rows where both counts were verified, or a row verified
102  // on one side only would skew it.
103  const mergeVerified = prVerified.filter((o) => verifiedFields(o.verified).prs_merged === true);
104  const prsMerged = mergeVerified.reduce((total, o) => total + (o.prs_merged ?? 0), 0);
105  const prsOpenedForRate = mergeVerified.reduce((total, o) => total + (o.prs_opened ?? 0), 0);
106
107  const ciChecked = mine.filter((o) => verifiedFields(o.verified).ci_green === true && o.ci_green !== null);
108  const durations = mine.map((o) => o.duration_minutes).filter((d): d is number => typeof d === "number");
109
110  return {
111    actor,
112    // From job statuses, not outcome rows: both done and failed write an outcome.
113    jobs_done: jobsByStatus("done"),
114    jobs_failed: jobsByStatus("failed"),
115    jobs_blocked: jobsByStatus("blocked"),
116    gates_hit: mine.reduce((total, o) => total + o.blocked_count, 0),
117    resumed: mine.reduce((total, o) => total + o.resumed_count, 0),
118    prs_opened: prsOpened,
119    prs_merged: prsMerged,
120    pr_merge_rate: rate(prsMerged, prsOpenedForRate),
121    ci_checked: ciChecked.length,
122    ci_green_rate: rate(ciChecked.filter((o) => o.ci_green === 1).length, ciChecked.length),
123    median_duration_minutes: median(durations),
124  };
125}
126
127// One record per credential.
128export function recordsFrom(agents: RecordSubject[], rows: RecordRows): Record<string, AgentRecord> {
129  const out: Record<string, AgentRecord> = Object.create(null);
130  for (const agent of agents) {
131    out[agent.name] = recordFor(agentActor(agent.name), rows);
132  }
133  return out;
134}
135
136export async function loadRecordRows(db: D1Database): Promise<RecordRows> {
137  // Read whole rather than aggregated in SQL: which fields were verified lives in a
138  // JSON column no GROUP BY can read, and the aggregation stays a pure function.
139  //
140  // A superseded job's outcome row is left out: nothing was attempted on it, so it
141  // would record a failure that did not happen.
142  const outcomes = await db
143    .prepare(
144      `SELECT agent, prs_opened, prs_merged, ci_green, blocked_count, resumed_count, duration_minutes, verified
145       FROM job_outcomes o
146       WHERE NOT EXISTS (SELECT 1 FROM jobs j WHERE j.id = o.job_id AND j.status = 'superseded')`
147    )
148    .all<RecordRows["outcomes"][number]>();
149  const jobs = await db
150    .prepare(
151      `SELECT claimed_by AS actor, status, COUNT(*) AS n FROM jobs
152       WHERE claimed_by IS NOT NULL GROUP BY claimed_by, status`
153    )
154    .all<{ actor: string; status: string; n: number }>();
155  return { outcomes: outcomes.results ?? [], jobs: jobs.results ?? [] };
156}
157
158export async function loadAgentRecords(db: D1Database, agents: RecordSubject[]): Promise<Record<string, AgentRecord>> {
159  return recordsFrom(agents, await loadRecordRows(db));
160}