@feigi/fleet-ctl 3.160.6 → 3.161.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  // $ per merged PR, per implementer cell, and the cost guard over it.
3
3
  //
4
- // pr-cost.mjs [--guard] [--json] [--member-outcomes <tsv>] [--tier-outcomes <tsv>]
4
+ // pr-cost.mjs [--guard] [--json] [--baseline-cell <cell>] [--member-outcomes <tsv>] [--tier-outcomes <tsv>]
5
5
  // [--ticket-features <tsv>] [--pricing <json>] [--out <json>]
6
6
  //
7
7
  // Inputs: the three metrics TSVs (docs/metrics/ by default, relative to the
@@ -23,7 +23,7 @@
23
23
  //
24
24
  // 0 ok — no cell tripped
25
25
  // 3 at least one cell tripped; `tripped[]` names each
26
- // 4 no verdict — the baseline cell has fewer than MIN_N merged PRs
26
+ // 4 no verdict — the Baseline Cell has fewer than MIN_N merged PRs
27
27
  // 2 input error — nothing is written
28
28
  //
29
29
  // The exit status is the guard's carrier: the verdict never lives only in
@@ -31,6 +31,19 @@
31
31
  // fleet-tick's `router` row prints it today; a missing or unparseable file
32
32
  // means the default cell only, so deleting it cannot evade the guard.
33
33
  //
34
+ // THE BASELINE CELL is the Cell every other is compared with: `--baseline-cell`,
35
+ // else the one the run's phase-0 receipt records, else the value saved in
36
+ // `.fleet/baseline-cell.json`, else `slow-high`. "The baseline" below is it.
37
+ //
38
+ // WHY A CELL TRIPPED. A cell trips on `floor` (its fail rate TRIP_POINTS or
39
+ // more points above the baseline's), on `usd` (its $ per merged PR at or above
40
+ // the baseline's) or on `minutes` (its work time per merged PR at or above the
41
+ // baseline's, where both sides have a minutes figure), each over the stretches
42
+ // both were drawn in. A `tripped` entry is `{ cell, on: [<reason>, …] }`, and the
43
+ // verdict is `tripped` when any cell trips for any reason. Each Objective applies
44
+ // its own reasons (trip-reasons.mjs): the guard records, the router excludes. No
45
+ // trip state is kept: every run re-judges from the record.
46
+ //
34
47
  // BOOKING is pull-attribution.mjs's, the one the router's fit reads too: each
35
48
  // Pull in the window is a unit booked as routed to its `chosen_cell`, with
36
49
  // every implementer under it, its PR's review, fix and finisher members and
@@ -90,7 +103,10 @@
90
103
  // Pull contributes the implementer PRs that make it one. Beside `min_n` it
91
104
  // records `trip_points`, the floor's margin, `unmatched`, the report's list of
92
105
  // the cells not judged, and `tsv_blobs`: the git blob id of each TSV it read,
93
- // by the path it read it at.
106
+ // by the path it read it at. Each cell's entry also records `shared_merged`,
107
+ // `{ cell, base }`: its merged PRs and the baseline's over the stretches they
108
+ // share, which burn-in holds until both reach MIN_N — for every cell, including
109
+ // one under MIN_N merged PRs of its own.
94
110
 
95
111
  import { createHash } from "node:crypto";
96
112
  import { execFileSync } from "node:child_process";
@@ -103,7 +119,9 @@ import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
103
119
  import { isCLI } from "./is-cli.mjs";
104
120
  import { parseTsv as parseMemberTsv } from "./member-outcomes.mjs";
105
121
  import { AttributionError, TRIP_POINTS, attribute, compareCells, parseFeatures, tally } from "./pull-attribution.mjs";
106
- import { STARTING_CELLS } from "./ledger-grammar.mjs";
122
+ import { CELL, DEFAULT_BASELINE_CELL, startingSetOf } from "./ledger-grammar.mjs";
123
+ import { baselineIn } from "./phase0-receipt.mjs";
124
+ import { excludedCells, tripWords } from "./trip-reasons.mjs";
107
125
  import { RulingError, parseTierOutcomes } from "./tier-outcomes.mjs";
108
126
 
109
127
  const NAME = "pr-cost";
@@ -114,7 +132,6 @@ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
114
132
  // guard reads; the baseline is not cumulative over it, for a cell is compared
115
133
  // with the baseline only over the stretches in which both were drawn.
116
134
  export const WINDOW_START = "2026-10-03";
117
- export const BASELINE_CELL = "slow-high";
118
135
  export const MIN_N = 20;
119
136
  export const EXIT = { ok: 0, tripped: 3, none: 4 };
120
137
  export const GH_PR_LIMIT = 1000;
@@ -172,28 +189,35 @@ function median(xs) {
172
189
  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
173
190
  }
174
191
 
175
- // Whether `m`, `compareCells`' comparison of a cell with the baseline, has MIN_N merged PRs on each side. They are
192
+ // Whether `m`, `compareCells`' comparison of a cell with the Baseline Cell, has MIN_N merged PRs on each side. They are
176
193
  // counted over the stretches both were drawn in, so a cell is never judged on a handful of matched Pulls because
177
194
  // it has many unmatched ones.
178
195
  const judged = (m) => m.cell.merged >= MIN_N && m.base.merged >= MIN_N;
179
196
 
180
- // The trip rule, over the stretches in which both cells were drawn (`cell` and `base` are the two cells' newest
181
- // generations' counted Pulls, as `compareCells` reads them): the cell's fail rate TRIP_POINTS or more points above
182
- // the baseline's, in integer counts, or its $ per merged PR at least the baseline's. The $ leg takes the unrounded
183
- // figures: the cent-rounded ones are for display, and a trip is sticky, so a cell cheaper by under half a cent
184
- // must not trip on rounding alone. A cell that shares no stretch with the baseline, or has under MIN_N merged PRs
185
- // on either side in those it shares, is not judged and does not trip. `tripsOn` holds the rule on a comparison,
186
- // `trips` on two cells' Pulls.
187
- const tripsOn = (m) => judged(m) && (m.underFloor || (m.cell.usd_per_merged !== null && m.cell.usd_per_merged >= m.base.usd_per_merged));
188
- export function trips(cell, base) {
189
- return tripsOn(compareCells(cell, base));
197
+ // Why a cell trips, over the stretches in which both cells were drawn (`m` is `compareCells`' comparison of the
198
+ // cell's and the Baseline Cell's newest generations' counted Pulls): `floor`, its fail rate TRIP_POINTS or more
199
+ // points above the Baseline Cell's, in integer counts; `usd`, its $ per merged PR at least the Baseline Cell's;
200
+ // `minutes`, its work time per merged PR at least the Baseline Cell's, where both sides have a minutes figure. A
201
+ // figure takes the unrounded values: the cent-rounded ones are for display, so a cell cheaper by under half a cent
202
+ // must not trip on rounding alone. None where the cell shares no stretch with the Baseline Cell, or has under MIN_N
203
+ // merged PRs on either side in those it shares: it is not judged and does not trip. A reason holds a cell back
204
+ // under the Objectives trip-reasons.mjs says.
205
+ const tripReasonsOn = (m) => {
206
+ if (!judged(m)) return [];
207
+ const atLeast = (key) => m.cell[key] !== null && m.base[key] !== null && m.cell[key] >= m.base[key];
208
+ return [m.underFloor && "floor", atLeast("usd_per_merged") && "usd", atLeast("minutes_per_merged") && "minutes"].filter(Boolean);
209
+ };
210
+
211
+ /** The reasons `cell`'s Pulls trip against `base`'s, as the guard reads them over their shared stretches; none when it does not trip. */
212
+ export function tripReasons(cell, base) {
213
+ return tripReasonsOn(compareCells(cell, base));
190
214
  }
191
215
 
192
- export function computeReport({ members, tiers, features, prs, routerTable = null, pricing = null, windowStart = WINDOW_START }) {
216
+ export function computeReport({ members, tiers, features, prs, routerTable = null, pricing = null, windowStart = WINDOW_START, baselineCell = DEFAULT_BASELINE_CELL }) {
193
217
  const units = attribute({ features, members, tiers, prs, windowStart });
194
218
  const tallies = new Map(tally(units).map((t) => [t.cell, t]));
195
219
  const meanUsd = (t) => (t.merged ? t.spend / t.merged : null);
196
- const base = tallies.get(BASELINE_CELL) ?? null;
220
+ const base = tallies.get(baselineCell) ?? null;
197
221
  // The PRs behind each generation's `no_ruling` and `pending` counts, as the
198
222
  // top-level `pending` list prints them: ascending, each once.
199
223
  const behind = new Map();
@@ -218,6 +242,7 @@ export function computeReport({ members, tiers, features, prs, routerTable = nul
218
242
  n_failed: g.failed,
219
243
  fail_rate: g.claims ? round(g.failed / g.claims) : null,
220
244
  mean_usd: round(meanUsd(g), 2),
245
+ mean_minutes: round(g.merged ? g.workS / 60 / g.merged : null, 2),
221
246
  median_usd: round(median(g.pulls.filter((u) => u.merged).map((u) => u.spend)), 2),
222
247
  by_hand: g.by_hand,
223
248
  no_ruling: g.no_ruling,
@@ -225,39 +250,53 @@ export function computeReport({ members, tiers, features, prs, routerTable = nul
225
250
  pending: g.pending,
226
251
  pending_prs: prList(held?.pending_prs),
227
252
  router_usd: round(g.pulls.reduce((s, u) => s + routerUsd(u.pull), 0), 4),
228
- usd_diff_ci95: !newest || cell === BASELINE_CELL || !base ? null : compareCells(g.pulls, base.pulls).range("usd"),
253
+ usd_diff_ci95: !newest || cell === baselineCell || !base ? null : compareCells(g.pulls, base.pulls).range("usd"),
229
254
  left_out: g.left_out,
230
255
  unpriced: g.unpriced,
231
256
  untimed: g.untimed,
232
257
  };
233
258
  };
259
+ // Each cell's newest generation held to the Baseline Cell's (`compareCells`), once: null with no Baseline Cell.
260
+ const vsBase = new Map([...tallies.values()].map((t) => [t.cell, base === null ? null : compareCells(t.pulls, base.pulls)]));
261
+ // Each cell's newest generation's merged PRs on each side of the stretches it shares with the Baseline Cell, which
262
+ // the trip loop below judges it on and burn-in holds until: recorded for every cell, those the loop skips for
263
+ // want of merged PRs of their own included. The Baseline Cell shares every stretch with itself.
264
+ const sharedMerged = (t) => {
265
+ const m = vsBase.get(t.cell);
266
+ return m === null ? { cell: 0, base: 0 } : { cell: m.cell.merged, base: m.base.merged };
267
+ };
234
268
  const figures = [...tallies.values()].map((t) => ({
235
269
  ...figuresOf(t.cell, t, true),
270
+ shared_merged: sharedMerged(t),
236
271
  excluded: t.excluded,
237
272
  older: t.older.map((o) => figuresOf(t.cell, o, false)),
238
273
  }));
239
274
 
240
275
  // The guard, over each cell's newest generation alone.
241
- const b = figures.find((f) => f.cell === BASELINE_CELL) ?? { generation: null, n_merged: 0, mean_usd: null, fail_rate: null };
242
- const baseline = { cell: BASELINE_CELL, generation: b.generation, n: b.n_merged, mean_usd: b.mean_usd, fail_rate: b.fail_rate };
243
- // Each cell is held to the baseline over the stretches in which both were drawn (`compareCells`): `judged` is
244
- // whether MIN_N merged PRs a side there let the trip rule apply, and `tripsOn` the rule. A cell short of them is
245
- // `unmatched`.
276
+ const b = figures.find((f) => f.cell === baselineCell) ?? { generation: null, n_merged: 0, mean_usd: null, mean_minutes: null, fail_rate: null };
277
+ const baseline = { cell: baselineCell, generation: b.generation, n: b.n_merged, mean_usd: b.mean_usd, mean_minutes: b.mean_minutes, fail_rate: b.fail_rate };
278
+ // Each cell is held to the Baseline Cell over the stretches in which both were drawn (`compareCells`): `judged` is
279
+ // whether MIN_N merged PRs a side there let the trip rule apply, and `tripReasonsOn` the rule. A cell short of them
280
+ // is `unmatched`. A tripped entry is `{ cell, on }`, `on` the reasons it tripped on.
246
281
  const tripped = [];
247
282
  const unmatched = [];
248
283
  if (baseline.n >= MIN_N) {
249
284
  for (const t of tallies.values()) {
250
- if (t.cell === BASELINE_CELL || t.merged < MIN_N) continue;
251
- const m = compareCells(t.pulls, base.pulls);
285
+ if (t.cell === baselineCell || t.merged < MIN_N) continue;
286
+ const m = vsBase.get(t.cell);
252
287
  if (!judged(m)) unmatched.push(t.cell);
253
- else if (tripsOn(m)) tripped.push(t.cell);
288
+ else {
289
+ const on = tripReasonsOn(m);
290
+ if (on.length > 0) tripped.push({ cell: t.cell, on });
291
+ }
254
292
  }
255
293
  }
256
294
  const verdict = baseline.n < MIN_N ? "none" : tripped.length ? "tripped" : "ok";
257
- // Retire: every non-default starting Cell tripped before any row of either
258
- // objective's set adopted one.
259
- const adopted = Object.values(routerTable?.rows ?? {}).some((set) => Object.values(set).some((c) => c !== BASELINE_CELL));
260
- const retire = !adopted && STARTING_CELLS.filter((c) => c !== BASELINE_CELL).every((c) => tripped.includes(c));
295
+ // Retire: every starting Cell but the Baseline Cell excluded under `cost` before any row of either objective's set
296
+ // adopted a Cell other than it.
297
+ const adopted = Object.values(routerTable?.rows ?? {}).some((set) => Object.values(set).some((c) => c !== null && c !== baselineCell));
298
+ const costOut = excludedCells(tripped, "cost");
299
+ const retire = !adopted && startingSetOf(baselineCell).filter((c) => c !== baselineCell).every((c) => costOut.includes(c));
261
300
 
262
301
  return {
263
302
  window_start: windowStart,
@@ -336,8 +375,8 @@ const TSV_COLUMNS = [
336
375
  // per older generation of that cell, which carries none.
337
376
  export function formatReport(report) {
338
377
  const guardOf = (f) => {
339
- if (f.cell === BASELINE_CELL) return "baseline";
340
- if (report.tripped.includes(f.cell)) return "tripped";
378
+ if (f.cell === report.baseline.cell) return "baseline";
379
+ if (report.tripped.some((t) => t.cell === f.cell)) return "tripped";
341
380
  if (report.unmatched.includes(f.cell)) return "unmatched";
342
381
  return f.n_merged >= MIN_N && report.verdict !== "none" ? "ok" : `n<${MIN_N}`;
343
382
  };
@@ -349,7 +388,7 @@ export function formatReport(report) {
349
388
  for (const o of f.older) lines.push(line(o, "older"));
350
389
  }
351
390
  const b = report.baseline;
352
- lines.push(`# verdict: ${report.verdict} (baseline ${b.cell} n=${b.n}/${MIN_N}${report.tripped.length ? `; tripped ${report.tripped.join(" ")}` : ""})${report.retire ? " — retire: every non-default starting Cell tripped" : ""}`);
391
+ lines.push(`# verdict: ${report.verdict} (baseline ${b.cell} n=${b.n}/${MIN_N}${report.tripped.length ? `; tripped ${report.tripped.map(tripWords).join("; ")}` : ""})${report.retire ? " — retire: every starting Cell but the baseline tripped under cost" : ""}`);
353
392
  lines.push(`# window_start ${report.window_start}; pending PRs: ${report.pending.length ? report.pending.join(" ") : "none"}`);
354
393
  const ab = report.ab;
355
394
  lines.push(ab.status === "not-run"
@@ -407,7 +446,7 @@ function main() {
407
446
  const die = makeDie(NAME);
408
447
  const { arg, has, sweep, stray } = defineFlags(die, {
409
448
  flags: {
410
- guard: "bool", json: "bool", "member-outcomes": "value", "tier-outcomes": "value",
449
+ guard: "bool", json: "bool", "baseline-cell": "value", "member-outcomes": "value", "tier-outcomes": "value",
411
450
  "ticket-features": "value", pricing: "value", out: "value",
412
451
  },
413
452
  });
@@ -464,8 +503,17 @@ function main() {
464
503
  throw e;
465
504
  }
466
505
 
506
+ // The Baseline Cell: `--baseline-cell`, else the run's own — the receipt's, the saved value, `slow-high` — read
507
+ // from the `.fleet/` the guard is written to.
508
+ let baselineCell = arg("baseline-cell");
509
+ if (baselineCell === null) {
510
+ let fleetDir = null;
511
+ try { fleetDir = dirname(arg("out") ?? fleetFile("cost-guard.json")); } catch (e) { if (!(e instanceof FleetDirUnresolvable)) throw e; }
512
+ baselineCell = fleetDir === null ? DEFAULT_BASELINE_CELL : baselineIn(fleetDir).cell;
513
+ } else if (!CELL.test(baselineCell)) die(`--baseline-cell ${baselineCell} is not a Cell`);
514
+
467
515
  let report;
468
- try { report = computeReport({ members, tiers, features, prs, routerTable, pricing }); }
516
+ try { report = computeReport({ members, tiers, features, prs, routerTable, pricing, baselineCell }); }
469
517
  catch (e) {
470
518
  if (e instanceof RulingError) die(`${tiersPath}: ${e.message}`);
471
519
  if (e instanceof AttributionError) die(e.message);
package/scripts/pull.mjs CHANGED
@@ -146,7 +146,7 @@ import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
146
146
  import { gitEnv } from "./git-env.mjs";
147
147
  import { isCLI } from "./is-cli.mjs";
148
148
  import { LabelMapUnreadable, readLabelMap } from "./label-map.mjs";
149
- import { EXCLUDED_REASON, POLICY_CELL, memberTokens, parseRouting, parseToken, premisesOf, priorUse, pullEnded, readRetired, replacementName, settledMemberTokens, tierValues } from "./ledger-grammar.mjs";
149
+ import { EXCLUDED_REASON, BARE_ROW_CELL, memberTokens, parseRouting, parseToken, premisesOf, priorUse, pullEnded, readRetired, replacementName, settledMemberTokens, tierValues } from "./ledger-grammar.mjs";
150
150
  import { sessionFromReceipt } from "./phase0-receipt.mjs";
151
151
  import { LINE_REF, briefPaths, briefText, outOfScope, strandedRuling, ticketText } from "./ticket-text.mjs";
152
152
 
@@ -1008,7 +1008,7 @@ class Pull {
1008
1008
  // The Routing itself goes to `## Routed` in the same write. The row's
1009
1009
  // settled member tokens are carried ahead of the member: a rewrite drops
1010
1010
  // none, and the earlier `tier=` and `cell=` words are the earlier member's.
1011
- const carrier = draw !== "-" ? ` · tier=${cell}` : cell !== POLICY_CELL ? ` · cell=${cell}` : "";
1011
+ const carrier = draw !== "-" ? ` · tier=${cell}` : cell !== BARE_ROW_CELL ? ` · cell=${cell}` : "";
1012
1012
  const text = [...carriedTokens(this.ledgerRows(), st.ticket), `${st.member}${carrier}`].join(" · ");
1013
1013
  const r = this.script("row", "ledger.mjs", ["row", String(st.ticket), text, "--routing", st.route.line]);
1014
1014
  if (r.status !== 0) return this.stop(withText(`ledger.mjs row failed (${r.how})`, r));
@@ -1,19 +1,15 @@
1
1
  {
2
2
  "window_start": null,
3
3
  "n_rows": 0,
4
- "cells": [
5
- "slow-high",
6
- "task-high",
7
- "smol-high"
8
- ],
4
+ "cells": null,
9
5
  "burn_in": true,
10
6
  "splits": {},
11
7
  "rows": {
12
8
  "cost": {
13
- "*": "slow-high"
9
+ "*": null
14
10
  },
15
11
  "speed": {
16
- "*": "slow-high"
12
+ "*": null
17
13
  }
18
14
  },
19
15
  "classifier": {
@@ -24,7 +20,7 @@
24
20
  "reasons": {
25
21
  "cost": {
26
22
  "*": {
27
- "cell": "slow-high",
23
+ "cell": null,
28
24
  "reason": "unjudged",
29
25
  "cells": {},
30
26
  "pairs": []
@@ -32,7 +28,7 @@
32
28
  },
33
29
  "speed": {
34
30
  "*": {
35
- "cell": "slow-high",
31
+ "cell": null,
36
32
  "reason": "unjudged",
37
33
  "cells": {},
38
34
  "pairs": []