@feigi/fleet-ctl 3.160.7 → 3.161.1

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.160.7",
3
+ "version": "3.161.1",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -0,0 +1,111 @@
1
+ // The Baseline Cell setting: the Cell a repository names as the one the router
2
+ // starts from, the cost guard compares every other Cell with and the quality
3
+ // floor reads. Phase 0 works it out once per run (phase0.mjs) and records it in
4
+ // the receipt as `baselineCell`; every other reader takes the receipt's, else
5
+ // the value saved here, else DEFAULT_BASELINE_CELL (phase0-receipt.mjs).
6
+ //
7
+ // The saved value is `.fleet/baseline-cell.json`, `{ "cell": "<cell>" }`: a valid
8
+ // `--baseline-cell` argument is saved and binds every later run until a run
9
+ // names another. A value is valid when it is a Cell (CELL) that has an
10
+ // implementer definition.
11
+ //
12
+ // Zero deps: node builtins and sibling modules only.
13
+
14
+ import { mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
15
+ import { dirname, join } from "node:path";
16
+ import { fileURLToPath } from "node:url";
17
+ import { CELL, CELL_DEF, DEFAULT_BASELINE_CELL } from "./ledger-grammar.mjs";
18
+
19
+ /** The saved value's file name, in the run's `.fleet/`. */
20
+ export const BASELINE_FILE = "baseline-cell.json";
21
+
22
+ // The implementer definitions the install ships: the directory the Cells a Baseline Cell may name are read from.
23
+ const SHIPPED_AGENTS = join(dirname(fileURLToPath(import.meta.url)), "..", "agents");
24
+
25
+ /**
26
+ * The Cells an implementer definition exists for in `agents`: `{ cells, why }`, `cells` a Set and `why` null, or,
27
+ * when the directory cannot be listed, `cells` empty and `why` saying so, so that no value is blamed for it.
28
+ */
29
+ export function definedCells(agents = SHIPPED_AGENTS) {
30
+ try {
31
+ return { cells: new Set(readdirSync(agents).map((file) => file.replace(/\.agent\.md$/, "")).filter((name) => CELL_DEF.test(name)).map((name) => name.slice("fleet-implementer-".length))), why: null };
32
+ } catch (e) {
33
+ return { cells: new Set(), why: `${agents} cannot be listed (${e.code ?? e.message})` };
34
+ }
35
+ }
36
+
37
+ /** Whether `value` is a valid Baseline Cell: a Cell with an implementer definition in `defined` (definedCells's `cells`). */
38
+ export const isBaselineCell = (value, defined) => typeof value === "string" && CELL.test(value) && defined.has(value);
39
+
40
+ /**
41
+ * The value saved in `fleetDir`'s `baseline-cell.json`: `{ state: "none" }` for no file, `{ state: "ok", cell }` for
42
+ * a valid Baseline Cell, or `{ state: "invalid", why }` for a file that cannot be read or parsed, holds no string
43
+ * `cell`, or names a Cell that is no valid Baseline Cell.
44
+ */
45
+ export function readSavedBaseline(fleetDir, defined = definedCells().cells) {
46
+ const file = join(fleetDir, BASELINE_FILE);
47
+ let text;
48
+ try {
49
+ text = readFileSync(file, "utf8");
50
+ } catch (e) {
51
+ return e.code === "ENOENT" ? { state: "none" } : { state: "invalid", why: `${file} cannot be read (${e.code ?? e.message})` };
52
+ }
53
+ let saved;
54
+ try { saved = JSON.parse(text); } catch { return { state: "invalid", why: `${file} is not JSON` }; }
55
+ const cell = saved !== null && typeof saved === "object" ? saved.cell : undefined;
56
+ if (typeof cell !== "string") return { state: "invalid", why: `${file} holds no string \`cell\`` };
57
+ if (!isBaselineCell(cell, defined)) return { state: "invalid", why: `${file} names ${JSON.stringify(cell)}, which is not a Cell with an implementer definition` };
58
+ return { state: "ok", cell };
59
+ }
60
+
61
+ /** Saves `cell` as the Baseline Cell of every later run, through a temp file and a rename. */
62
+ export function saveBaseline(fleetDir, cell) {
63
+ const file = join(fleetDir, BASELINE_FILE);
64
+ mkdirSync(fleetDir, { recursive: true });
65
+ writeFileSync(`${file}.tmp`, `${JSON.stringify({ cell }, null, 2)}\n`);
66
+ renameSync(`${file}.tmp`, file);
67
+ }
68
+
69
+ /**
70
+ * The Baseline Cell a run starts with and where it came from, once, off the argument, the saved value and what the
71
+ * install runs. Never refuses and never asks. `arg` is `--baseline-cell`'s value or null; `saved` is
72
+ * readSavedBaseline's answer; `defined` is definedCells's `cells`; `substitute(cell)` is the Cell the install runs in its
73
+ * place (ticket-router.mjs's defaultCellOf over the install read), `cell` itself where it runs it.
74
+ *
75
+ * A valid argument is the configured Cell and is to be saved (`save`); an invalid one is a notice, is not saved, and
76
+ * the run goes on to the saved value, else DEFAULT_BASELINE_CELL; an invalid saved value is a notice and the run uses
77
+ * DEFAULT_BASELINE_CELL, the file left as it is. A configured Cell the install cannot run is resolved to the nearest
78
+ * level it can, and a notice names both; the saved value stays as configured.
79
+ * @returns {{ cell: string, source: string, save: string|null, notices: string[] }}
80
+ */
81
+ export function resolveBaselineCell({ arg, saved, defined, substitute }) {
82
+ const notices = [];
83
+ let configured = null;
84
+ let source = null;
85
+ let save = null;
86
+ if (arg !== null) {
87
+ if (isBaselineCell(arg, defined)) {
88
+ configured = arg;
89
+ source = "--baseline-cell";
90
+ save = arg;
91
+ } else {
92
+ notices.push(`--baseline-cell ${JSON.stringify(arg)} is not a Cell with an implementer definition: ignored, and not saved`);
93
+ }
94
+ }
95
+ if (configured === null) {
96
+ if (saved.state === "ok") {
97
+ configured = saved.cell;
98
+ source = "the saved value";
99
+ } else {
100
+ if (saved.state === "invalid") notices.push(`the saved Baseline Cell is invalid (${saved.why}): this run uses ${DEFAULT_BASELINE_CELL}, and the file is left as it is`);
101
+ configured = DEFAULT_BASELINE_CELL;
102
+ source = "the default";
103
+ }
104
+ }
105
+ const cell = substitute(configured);
106
+ if (cell !== configured) {
107
+ notices.push(`the install does not run ${configured}: this run's Baseline Cell is ${cell}, the nearest level it runs (${configured} stays as configured)`);
108
+ source = `the substitute for ${configured}, from ${source}`;
109
+ }
110
+ return { cell, source, save, notices };
111
+ }
@@ -31,8 +31,8 @@
31
31
  import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
32
32
  import { computeSpend, attributeTools, mergeTools } from "./compute-spend.mjs";
33
33
  import { ompSessionTranscripts, foldOmpTranscript, ompMemberRecord } from "./member-record.mjs";
34
- import { readReceipt } from "./phase0-receipt.mjs";
35
- import { RECEIPT, RECEIPT_HELD, CLOSEOUT_RECEIPT, OBJECTIVES, isOmpSessionDirName } from "./ledger-grammar.mjs";
34
+ import { baselineIn, readReceipt } from "./phase0-receipt.mjs";
35
+ import { RECEIPT, RECEIPT_HELD, CLOSEOUT_RECEIPT, DEFAULT_BASELINE_CELL, OBJECTIVES, isOmpSessionDirName } from "./ledger-grammar.mjs";
36
36
  import { lastSegment } from "./pull-attribution.mjs";
37
37
  import { NAME, warnOnce, execRead } from "./board-common.mjs";
38
38
  import { ghBudget } from "./arg.mjs";
@@ -40,7 +40,7 @@ import { mergedReadPrs, issuesOfPrs } from "./compute-board.mjs";
40
40
  import { readCostGuard } from "./fleet-tick.mjs";
41
41
  import { parseFrontmatter } from "./tier-roles.mjs";
42
42
  import { isImplementer } from "./member-outcomes.mjs";
43
- import { FIT_FILE, validateTable } from "./ticket-router.mjs";
43
+ import { FIT_FILE, fitBaselineOf, startingTableOf, validateTable } from "./ticket-router.mjs";
44
44
  import { LabelMapUnreadable, readLabelMap } from "./label-map.mjs";
45
45
  import { FleetDirUnresolvable } from "./fleet-dir.mjs";
46
46
  // The heartbeat's liveness mark and the controller record beside it, read here
@@ -804,17 +804,17 @@ function damagedRecord(file, folded) {
804
804
  }
805
805
  }
806
806
 
807
- // The installed router table, `router-table.json` beside the scripts, when
808
- // `validateTable` accepts it, else null: a card words a policy row that has no
807
+ // The installed router table, `router-table.json` beside the scripts, filled in for `baseline`, the run's
808
+ // Baseline Cell, when `validateTable` accepts it, else null: a card words a policy row that has no
809
809
  // row for its Stratum ("follows *") only off a table it could read. The table
810
810
  // ships beside the scripts, so one that is missing, will not parse or is
811
811
  // refused is a broken install, said once on stderr per fault rather than
812
812
  // passed off as "no table".
813
- export function readRouterTable(scriptDir) {
813
+ export function readRouterTable(scriptDir, baseline = DEFAULT_BASELINE_CELL) {
814
814
  const file = join(scriptDir, "router-table.json");
815
815
  let why;
816
816
  try {
817
- const t = validateTable(JSON.parse(readFileSync(file, "utf8")));
817
+ const t = validateTable(startingTableOf(JSON.parse(readFileSync(file, "utf8")), baseline));
818
818
  if (!(t instanceof Error)) return t;
819
819
  why = t.message;
820
820
  } catch (e) {
@@ -859,12 +859,13 @@ export function readCloseoutPr(stateDir) {
859
859
  // `.fleet/router-fit.json`: `{ status: "ok", fit }`, `{ status: "missing" }`
860
860
  // or `{ status: "unreadable", why }`. It is read as `route` reads it
861
861
  // (ticket-router.mjs's readFitBeside): the Fit is read whenever its `table`
862
- // passes `validateTable`, so the tab never says the starting table routes while
863
- // `route` routes by the Fit. The fields only the tab reads decide nothing:
862
+ // passes `validateTable` and was computed under `baseline`, the run's Baseline Cell, so the tab never says the
863
+ // starting table routes while `route` routes by the Fit, nor the Fit while it does not. The fields only the tab
864
+ // reads decide nothing:
864
865
  // `computed_at` and `guard_computed_at` are null where they are no string and
865
866
  // `tsv_blobs` null where it is no object, and the tab says each is not checked,
866
867
  // as it says of an `n_rows` that is no count.
867
- export function readFitFile(stateDir) {
868
+ export function readFitFile(stateDir, baseline = DEFAULT_BASELINE_CELL) {
868
869
  let text;
869
870
  try {
870
871
  text = readFileSync(join(stateDir, FIT_FILE), "utf8");
@@ -876,6 +877,8 @@ export function readFitFile(stateDir) {
876
877
  if (!isJsonObject(p)) return { status: "unreadable", why: "not a JSON object" };
877
878
  const table = validateTable(p.table);
878
879
  if (table instanceof Error) return { status: "unreadable", why: table.message };
880
+ const under = fitBaselineOf(table);
881
+ if (under !== baseline) return { status: "unreadable", why: `it was computed under the Baseline Cell ${under}, not this run's ${baseline}` };
879
882
  const stringOrNull = (v) => (typeof v === "string" ? v : null);
880
883
  return { status: "ok", fit: { computed_at: stringOrNull(p.computed_at), guard_computed_at: stringOrNull(p.guard_computed_at), tsv_blobs: isJsonObject(p.tsv_blobs) ? p.tsv_blobs : null, table } };
881
884
  }
@@ -1337,7 +1340,8 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, stateDir
1337
1340
  if (!existsSync(join(stateDir, RECEIPT))) readHeldImplementers(stateDir, implementers);
1338
1341
  readStampedImplementers(stateDir, ledger.sessions, implementers);
1339
1342
  }
1340
- const routerTable = readRouterTable(scriptDir);
1343
+ const baselineCell = stateDir === null ? null : baselineIn(stateDir).cell;
1344
+ const routerTable = readRouterTable(scriptDir, baselineCell ?? DEFAULT_BASELINE_CELL);
1341
1345
  // The heartbeat's mark, raw. readState() never throws — an absent
1342
1346
  // file is the ordinary state of a run whose heartbeat has not beaten yet,
1343
1347
  // and an unreadable or corrupt one announces itself on stderr and degrades
@@ -1374,7 +1378,7 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, stateDir
1374
1378
  // receipts, the reads carried as they were).
1375
1379
  const guard = stateDir === null ? { status: "missing" } : readGuardFile(stateDir);
1376
1380
  const guardJson = stateDir === null ? null : readGuardJson(stateDir);
1377
- const fit = stateDir === null ? { status: "missing" } : readFitFile(stateDir);
1381
+ const fit = stateDir === null ? { status: "missing" } : readFitFile(stateDir, baselineCell);
1378
1382
  const closeoutPr = stateDir === null ? null : readCloseoutPr(stateDir);
1379
1383
  const receipts = stateDir === null
1380
1384
  ? { phase0: null, closeout: null }
@@ -1388,6 +1392,6 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, stateDir
1388
1392
  : await Promise.all([carryModelRoles(prev?.modelRoles, now), carryCatalog(prev?.catalog, now), carryMainMetrics(prev?.mainMetrics, now, repoUrl)]);
1389
1393
  return { ledger, issues, prs, merged, closed, closedIssues, ci, prev, repo, repoUrl, workspace, port, spend, beat, ticked, acted, controller, stallOwner: stallOwnerOf, poolOk,
1390
1394
  roles, labelMapError,
1391
- poolCapped, prsOk, prsCapped, guard, guardJson, fit, receipts, closeoutPr, agents, modelRoles, catalog, mainMetrics, objective, implementers: [...implementers.values()], routerTable,
1395
+ poolCapped, prsOk, prsCapped, guard, guardJson, fit, receipts, closeoutPr, agents, modelRoles, catalog, mainMetrics, objective, baselineCell, implementers: [...implementers.values()], routerTable,
1392
1396
  now, interval };
1393
1397
  }
@@ -1,8 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
  // The per-cell readout: how many within-session comparisons each implementer
3
- // cell has against the policy cell, and whether that is enough to read it.
3
+ // cell has against the Baseline Cell, and whether that is enough to read it.
4
4
  //
5
- // cell-readout.mjs [--ticket-features <tsv>] [--member-outcomes <tsv>]
5
+ // cell-readout.mjs [--baseline-cell <cell>] [--ticket-features <tsv>] [--member-outcomes <tsv>]
6
6
  //
7
7
  // Inputs default to docs/metrics/ under the working directory. A Pull is a
8
8
  // ticket-features.tsv row; what it ran is the member-outcomes.tsv row with the
@@ -20,8 +20,10 @@
20
20
  // was the role's target at dispatch is recorded in neither file; that half of
21
21
  // the tier check is the run ledger's, not this readout's.
22
22
  //
23
- // COMPARISON. For a cell X other than slow-high, a comparison is one session
24
- // holding at least one admissible X row and at least one admissible slow-high
23
+ // COMPARISON. For a cell X other than the Baseline Cell — `--baseline-cell`,
24
+ // else the one the run's receipt records, else the saved value, else slow-high
25
+ // — a comparison is one session
26
+ // holding at least one admissible X row and at least one admissible Baseline Cell
25
27
  // row whose (`dispatch_model`, `effort`) differ from that X row's. A session
26
28
  // counts once however many rows it holds, and its date is its member-outcomes
27
29
  // `run_date`; a blank `run_date` means unknown, so that session is still a
@@ -47,11 +49,14 @@
47
49
  // malformed input, with nothing on stdout.
48
50
 
49
51
  import { readFileSync } from "node:fs";
52
+ import { dirname } from "node:path";
50
53
  import { makeDie, defineFlags } from "./arg.mjs";
51
54
  import { isCLI } from "./is-cli.mjs";
52
- import { POLICY_CELL } from "./ledger-grammar.mjs";
55
+ import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
56
+ import { CELL, DEFAULT_BASELINE_CELL } from "./ledger-grammar.mjs";
53
57
  import { formatTsv as formatMemberTsv, parseTsv as parseMemberTsv } from "./member-outcomes.mjs";
54
58
  import { admissibleRow, parseFeatures } from "./pull-attribution.mjs";
59
+ import { baselineIn } from "./phase0-receipt.mjs";
55
60
 
56
61
  const NAME = "cell-readout";
57
62
  export const GATE = Object.freeze({ comparisons: 10, runDates: 5 });
@@ -96,7 +101,7 @@ function indexMembers(members) {
96
101
  }
97
102
 
98
103
  /**
99
- * `cells`: one entry per cell other than the policy cell that has a
104
+ * `cells`: one entry per cell other than the Baseline Cell (`baseline`) that has a
100
105
  * ticket-features row, `{ cell, comparisons, runDates, dates, models, gated }`,
101
106
  * sorted by cell. `dates` is the comparisons' distinct run_dates, sorted;
102
107
  * `models` maps each `dispatch_model` of the cell's admissible rows to its row
@@ -104,18 +109,18 @@ function indexMembers(members) {
104
109
  * two ticket-features rows of one session+agent naming different cells, and on
105
110
  * a member-outcomes session+agent repeated with different fields.
106
111
  */
107
- export function readout({ features, members }) {
112
+ export function readout({ features, members, baseline = DEFAULT_BASELINE_CELL }) {
108
113
  const byKey = indexMembers(members);
109
114
  const pulls = pullsOf(features);
110
115
  const sessions = new Map();
111
116
  const cells = new Map();
112
117
  let unjoined = 0;
113
118
  for (const p of pulls.values()) {
114
- if (p.chosen_cell !== POLICY_CELL && !cells.has(p.chosen_cell)) cells.set(p.chosen_cell, new Map());
119
+ if (p.chosen_cell !== baseline && !cells.has(p.chosen_cell)) cells.set(p.chosen_cell, new Map());
115
120
  if (!byKey.has(key(p.session, p.agent))) unjoined++;
116
121
  const m = admissibleMember(p, byKey);
117
122
  if (!m) continue;
118
- if (p.chosen_cell !== POLICY_CELL) cells.get(p.chosen_cell).set(m.dispatchModel, (cells.get(p.chosen_cell).get(m.dispatchModel) ?? 0) + 1);
123
+ if (p.chosen_cell !== baseline) cells.get(p.chosen_cell).set(m.dispatchModel, (cells.get(p.chosen_cell).get(m.dispatchModel) ?? 0) + 1);
119
124
  if (!sessions.has(p.session)) sessions.set(p.session, { runDate: m.run_date, rows: [] });
120
125
  sessions.get(p.session).rows.push({ cell: p.chosen_cell, model: m.dispatchModel, effort: m.effort });
121
126
  }
@@ -124,7 +129,7 @@ export function readout({ features, members }) {
124
129
  let comparisons = 0;
125
130
  const dates = new Set();
126
131
  for (const { runDate, rows } of sessions.values()) {
127
- const base = rows.filter((r) => r.cell === POLICY_CELL);
132
+ const base = rows.filter((r) => r.cell === baseline);
128
133
  const compared = rows.some((x) => x.cell === cell && base.some((s) => s.model !== x.model || s.effort !== x.effort));
129
134
  if (!compared) continue;
130
135
  comparisons++;
@@ -147,7 +152,7 @@ function formatModels(models) {
147
152
  function main() {
148
153
  const die = makeDie(NAME);
149
154
  const { arg, sweep, stray } = defineFlags(die, {
150
- flags: { "ticket-features": "value", "member-outcomes": "value" },
155
+ flags: { "baseline-cell": "value", "ticket-features": "value", "member-outcomes": "value" },
151
156
  });
152
157
  sweep();
153
158
  stray();
@@ -174,13 +179,22 @@ function main() {
174
179
  return rows;
175
180
  });
176
181
 
177
- const { cells, unjoined } = readout({ features, members });
182
+ let baseline = arg("baseline-cell");
183
+ if (baseline === null) {
184
+ try {
185
+ baseline = baselineIn(dirname(fleetFile("cost-guard.json"))).cell;
186
+ } catch (e) {
187
+ if (!(e instanceof FleetDirUnresolvable)) throw e;
188
+ baseline = DEFAULT_BASELINE_CELL;
189
+ }
190
+ } else if (!CELL.test(baseline)) die(`--baseline-cell ${baseline} is not a Cell`);
191
+ const { cells, unjoined } = readout({ features, members, baseline });
178
192
  const lines = [];
179
193
  const notes = [];
180
194
  if (unjoined > 0) {
181
195
  notes.push(`${unjoined} ticket-features row${unjoined === 1 ? " has" : "s have"} no member-outcomes row — never admissible`);
182
196
  }
183
- if (cells.length === 0) notes.push(`no cell other than ${POLICY_CELL} has a ticket-features row`);
197
+ if (cells.length === 0) notes.push(`no cell other than ${baseline} has a ticket-features row`);
184
198
  for (const c of cells) {
185
199
  if (c.gated) lines.push(`${c.cell} ${c.comparisons} ${c.runDates} ${formatModels(c.models)}`);
186
200
  else notes.push(`${c.cell} below the gate: ${c.comparisons} comparisons across ${c.runDates} run_dates (needs ${GATE.comparisons} across ${GATE.runDates})`);
@@ -33,7 +33,7 @@
33
33
  // fleet-tick.mjs's I/O and main() never run here, main() being guarded on
34
34
  // argv[1].
35
35
  import { assessBeat, isStalled, isReported, stallReport, NO_OWNER } from "./fleet-state.mjs";
36
- import { parseToken, rowPr, premisesOf, HALT_CAUSES, REVIEW, CELL, POLICY_CELL, parseRoutedEntry, tierValues, cellValues, isRulePath } from "./ledger-grammar.mjs";
36
+ import { parseToken, rowPr, premisesOf, HALT_CAUSES, REVIEW, CELL, BARE_ROW_CELL, parseRoutedEntry, tierValues, cellValues, isRulePath } from "./ledger-grammar.mjs";
37
37
  import { latestFinisherAttempts, foldLedger, reviewOwed as reviewOwedState } from "./fleet-tick.mjs";
38
38
  import { computeCellEvidence } from "./compute-cell-evidence.mjs";
39
39
  import { admissibleRow, lastSegment } from "./pull-attribution.mjs";
@@ -438,7 +438,7 @@ export function cellLine({ row, issue, routed = [], agents = {}, members = new M
438
438
  const under = start === -1 ? names.slice(-1) : names.slice(start);
439
439
  const recorded = start === -1 ? null : entries.get(names[start]);
440
440
  const routing = recorded?.routing ?? null;
441
- const cell = routing?.cell ?? tierValues(row)[0] ?? cellValues(row)[0] ?? POLICY_CELL;
441
+ const cell = routing?.cell ?? tierValues(row)[0] ?? cellValues(row)[0] ?? BARE_ROW_CELL;
442
442
  const level = CELL.exec(cell)?.[2] ?? null;
443
443
  const expected = `fleet-implementer-${cell}`;
444
444
 
@@ -885,6 +885,7 @@ export function computeBoard(inputs) {
885
885
  mainMetrics: inputs.mainMetrics,
886
886
  table: inputs.routerTable,
887
887
  objective: inputs.objective,
888
+ baselineCell: inputs.baselineCell,
888
889
  pulls: tickets.filter((t) => t.cellLine).map((t) => ({ issue: t.issue, cell: t.cellLine.cell, mark: t.cellLine.mark, targets: t.cellLine.targets })),
889
890
  }),
890
891
  // The `omp config get modelRoles` read, carried tick to tick the way `ci`
@@ -35,10 +35,11 @@
35
35
  // checked where its figure would show.
36
36
 
37
37
  import { isDeepStrictEqual } from "node:util";
38
- import { CELL, OBJECTIVES, POLICY_CELL, STARTING_CELLS } from "./ledger-grammar.mjs";
38
+ import { CELL, DEFAULT_BASELINE_CELL, OBJECTIVES, startingSetOf } from "./ledger-grammar.mjs";
39
39
  import { costGuardFault } from "./fleet-tick.mjs";
40
- import { MIN_N, defaultCellOf, installOf, parseGuard, readGuard, rowDispatch, startingCellsOf, unrunnableCells } from "./ticket-router.mjs";
40
+ import { MIN_N, burnInCount, defaultCellOf, fitBaselineOf, installOf, parseGuard, readGuard, rowDispatch, startingCellsOf, unrunnableCells } from "./ticket-router.mjs";
41
41
  import { implementerCell, modelsEqual, parseModelRoute, resolveRole } from "./tier-roles.mjs";
42
+ import { tripEntry, tripWords } from "./trip-reasons.mjs";
42
43
 
43
44
  // The implementer Cells, in the order the guard section draws them: one per
44
45
  // definition, every role × level from low to max. All of them are drawn in
@@ -364,7 +365,7 @@ function guardHeading(g) {
364
365
  const state = g.verdict === "none" ? "holds-nothing-back" : g.verdict === "tripped" ? "trips" : "trips-nothing";
365
366
  const heading = state === "holds-nothing-back"
366
367
  ? `holds no Cell back until ${g.baseline.cell} has ${g.min_n} merged PRs: it has ${g.baseline.n}`
367
- : state === "trips" ? `trips ${g.tripped.join(", ")}` : "trips nothing";
368
+ : state === "trips" ? `trips ${g.tripped.map(tripEntry).map(tripWords).join(", ")}` : "trips nothing";
368
369
  const trip = count(g.trip_points);
369
370
  const source = [
370
371
  "this repository's runs",
@@ -400,8 +401,9 @@ function booked(entry, pulls) {
400
401
  // The Cells drawn: CELLS, then any the guard holds or a card names beyond them.
401
402
  const drawOrder = (held, pulls) => [...new Set([...CELLS, ...held, ...pulls.flatMap((p) => p.targets.map((t) => t.cell)).filter((c) => CELL.test(c))])];
402
403
 
403
- // `step` is the receipts' newest `metrics` step, newestStep's pick.
404
- function guardSection(read, receipts, step, modelRoles, pulls, recordsNote = null) {
404
+ // `step` is the receipts' newest `metrics` step, newestStep's pick; `baselineCell` the run's Baseline Cell, as
405
+ // computeCellEvidence resolves it.
406
+ function guardSection(read, receipts, step, modelRoles, pulls, recordsNote = null, baselineCell) {
405
407
  const label = readLabel(modelRoles);
406
408
  const refresh = newestRefresh(step);
407
409
  const notes = [];
@@ -418,7 +420,7 @@ function guardSection(read, receipts, step, modelRoles, pulls, recordsNote = nul
418
420
  : `${refresh.verb} at ${when(refresh.at)}: ${refresh.why}`);
419
421
  if (label !== null) notes.push(label);
420
422
  const byCell = new Map();
421
- const stub = { baseline: { cell: "slow-high" } };
423
+ const stub = { baseline: { cell: baselineCell } };
422
424
  return {
423
425
  state: "no-guard",
424
426
  heading: "no cost guard",
@@ -490,30 +492,33 @@ function failedFitFlag(step, p) {
490
492
  }
491
493
 
492
494
  // How a Pull is dispatched, for every group alike: what `route` does under the guard and the install
493
- // (installOf's, or null where it was not read).
494
- function dispatchHeading(table, guard, install) {
495
- if (guard === null) return `no cost guard: every Pull runs at ${defaultCellOf(install)}, the default Cell`;
495
+ // (installOf's, or null where it was not read), from `baseline`, the run's Baseline Cell.
496
+ function dispatchHeading(table, guard, install, baseline) {
497
+ if (guard === null) return `no cost guard: every Pull runs at ${defaultCellOf(install, baseline)}, the default Cell`;
496
498
  if (table === null) return null;
497
499
  if (table.burn_in) return "burn-in: every Pull is drawn over the starting Cells the guard has not tripped";
498
500
  return "every 5th Pull that is no chain head is drawn over its group's exploration Cells; the rest run the group's Cell";
499
501
  }
500
502
 
501
- // Merged PRs per counted starting Cell, against MIN_N: the counts burn-in is judged on —
502
- // the Fit's own guard counts while the Fit routes, the cost guard's while the
503
- // starting table does. Null with neither to count from. The Cells counted are
504
- // the ones the Fit recorded, or the install this cockpit reads runs while the
505
- // starting table routes (countedStartingCells); the heading says which set it
503
+ // Merged PRs per counted starting Cell, against MIN_N: the counts burn-in is judged on, which the cost guard has
504
+ // judged the starting set on — the Baseline Cell's own merged PRs and every other Cell's on the thinner side of the
505
+ // stretches it shares with it (ticket-router.mjs's burnInCount) — the Fit's own guard counts while the Fit routes,
506
+ // the cost guard's while the starting table does. Null with neither to count from. The Cells counted are
507
+ // the ones the Fit recorded, or the install this cockpit reads runs while the starting table
508
+ // routes (countedStartingCells); the heading says which set it
506
509
  // counted and which starting Cells it left out as unrunnable. It follows the
507
510
  // routing table's `burn_in`, and says "ended" only of counts that all reach
508
511
  // MIN_N: a Fit sets its flag off its own counts, but the starting table's flag
509
512
  // is its own, whatever the cost guard counts since.
510
- function burnInProgress(p, guard, table, inst) {
511
- const n = p !== null ? p.table.guard.n : guard?.n;
512
- if (!isRecord(n)) return null;
513
- const counted = countedStartingCells(p, inst);
514
- const left = STARTING_CELLS.filter((c) => !counted.includes(c));
513
+ function burnInProgress(p, guard, table, inst, baseline) {
514
+ const counts = p !== null ? p.table.guard : guard;
515
+ if (!isRecord(counts) || !isRecord(counts.n)) return null;
516
+ const under = p !== null ? fitBaselineOf(p.table) : baseline;
517
+ const counted = countedStartingCells(p, inst, baseline);
518
+ const left = startingSetOf(under).filter((c) => !counted.includes(c));
515
519
  const subset = left.length > 0;
516
- const cells = counted.map((cell) => ({ cell, n: count(n[cell]) ?? 0, of: MIN_N }));
520
+ const shared = isRecord(counts.shared) ? counts.shared : {};
521
+ const cells = counted.map((cell) => ({ cell, n: burnInCount({ n: counts.n, shared }, cell, under), of: MIN_N }));
517
522
  const done = cells.filter((c) => c.n >= MIN_N).length;
518
523
  const kind = subset ? "runnable starting" : "starting";
519
524
  const out = subset ? `; ${list(left)} unrunnable` : "";
@@ -528,22 +533,23 @@ function burnInProgress(p, guard, table, inst) {
528
533
  // The Cells the cost guard has tripped, in words, or null with no guard.
529
534
  function trippedWords(guard) {
530
535
  if (guard === null) return null;
531
- return guard.tripped.length === 0 ? "the cost guard has tripped no Cell" : `tripped by the cost guard: ${list(guard.tripped)}`;
536
+ return guard.tripped.length === 0 ? "the cost guard has tripped no Cell" : `tripped by the cost guard: ${list(guard.tripped.map(tripWords))}`;
532
537
  }
533
538
 
534
539
  // The starting Cells burn-in counts, in their order: the set the Fit recorded
535
540
  // while a Fit routes — every starting Cell for a Fit that records none, as
536
- // every Fit did — else those the cockpit's own install read runs, all three
537
- // while it has none.
538
- function countedStartingCells(p, inst) {
539
- return p === null ? startingCellsOf(inst.install) : fitStartingCells(p.table);
541
+ // every Fit did — else those the cockpit's own install read runs, the whole
542
+ // starting set while it has none.
543
+ function countedStartingCells(p, inst, baseline) {
544
+ return p === null ? startingCellsOf(inst.install, baseline) : fitStartingCells(p.table);
540
545
  }
541
546
 
542
- // The starting Cells a Fit's table records, in their order: all three for a table that records none, or none usable.
547
+ // The starting Cells a Fit's table records, in their order: its whole starting set for a table that records none, or none usable.
543
548
  function fitStartingCells(table) {
549
+ const set = startingSetOf(fitBaselineOf(table));
544
550
  const recorded = table.starting_cells;
545
- const valid = Array.isArray(recorded) && recorded.length > 0 && recorded.every((c) => STARTING_CELLS.includes(c));
546
- return valid ? STARTING_CELLS.filter((c) => recorded.includes(c)) : [...STARTING_CELLS];
551
+ const valid = Array.isArray(recorded) && recorded.length > 0 && recorded.every((c) => set.includes(c));
552
+ return valid ? set.filter((c) => recorded.includes(c)) : [...set];
547
553
  }
548
554
 
549
555
  // A notice for each counted starting Cell whose role's model changed and so restarted
@@ -553,10 +559,12 @@ function fitStartingCells(table) {
553
559
  function modelChanges(p) {
554
560
  if (p === null || !p.table.burn_in) return [];
555
561
  const root = isRecord(p.table.estimates?.["*"]) ? p.table.estimates["*"] : {};
562
+ const under = fitBaselineOf(p.table);
563
+ const counts = { n: p.table.guard.n, shared: isRecord(p.table.guard.shared) ? p.table.guard.shared : {} };
556
564
  return fitStartingCells(p.table).flatMap((cell) => {
557
565
  const e = root[cell];
558
566
  const older = isRecord(e?.older) ? Object.keys(e.older) : [];
559
- const k = count(p.table.guard.n[cell]) ?? 0;
567
+ const k = count(burnInCount(counts, cell, under)) ?? 0;
560
568
  if (older.length === 0 || typeof e.generation !== "string" || k >= MIN_N) return [];
561
569
  return [`${cell}'s model changed to ${e.generation}, after ${list(older)}: burn-in restarted, at ${k} of the ${MIN_N} merged PRs it needs`];
562
570
  });
@@ -591,16 +599,16 @@ function unrunnableView(inst) {
591
599
  return { heading, cells };
592
600
  }
593
601
 
594
- // The Cells a group draws over, in words: rowDispatch's draw, which is centred on
595
- // the group's `cost` row Cell whichever Objective routes the Pull. Null with no
596
- // guard, when nothing is drawn.
597
- function exploringWords(table, guard, stratum, inst) {
602
+ // The Cells a group draws over under `objective`, in words: rowDispatch's draw, which is centred on
603
+ // the group's `cost` row Cell whichever Objective routes the Pull and leaves out the Cells that Objective
604
+ // excludes. Null with no guard, when nothing is drawn. `baseline` is the run's Baseline Cell.
605
+ function exploringWords(table, guard, stratum, inst, objective, baseline) {
598
606
  if (guard === null) return null;
599
607
  if (!table.burn_in && inst.install === null) return `exploring: not checked: ${inst.why}`;
600
- const rd = rowDispatch({ table, guard, objective: "cost", stratum, install: inst.install });
608
+ const rd = rowDispatch({ table, guard, objective, stratum, install: inst.install, baseline });
601
609
  if (table.burn_in) {
602
610
  if (rd.draw !== null) return `drawn over ${list(rd.draw.cells)}`;
603
- const orUnrunnable = unrunnableCells(inst.install).some((c) => STARTING_CELLS.includes(c)) ? " or unrunnable" : "";
611
+ const orUnrunnable = unrunnableCells(inst.install).some((c) => startingSetOf(baseline).includes(c)) ? " or unrunnable" : "";
604
612
  return `draws nothing: every starting Cell is tripped${orUnrunnable}`;
605
613
  }
606
614
  const words = rd.draw === null ? "exploring nothing: no exploration Cell this install runs is left untripped" : `exploring ${list(rd.draw.cells)}`;
@@ -634,8 +642,8 @@ function intervalWords(range, objective) {
634
642
  // install does not run it (`install` is installOf's answer, null where the
635
643
  // cockpit has not read one), and each candidate's n (null where the table
636
644
  // carries no count), verdict and interval.
637
- function rowEntry(table, guard, modelRoles, objective, stratum, install) {
638
- const rd = rowDispatch({ table, guard, objective, stratum, install });
645
+ function rowEntry(table, guard, modelRoles, objective, stratum, install, baseline) {
646
+ const rd = rowDispatch({ table, guard, objective, stratum, install, baseline });
639
647
  const row = table.rows[objective][stratum];
640
648
  const record = isRecord(table.reasons?.[objective]?.[stratum]) ? table.reasons[objective][stratum] : null;
641
649
  const estimates = isRecord(table.estimates?.[stratum]) ? table.estimates[stratum] : {};
@@ -703,7 +711,7 @@ function groupOf(stratum) {
703
711
  * `#cells/row/<objective>/<stratum>` link lands on. A candidate's generation
704
712
  * check moves to one model-name line when every candidate named differs.
705
713
  */
706
- function fitView({ fit, starting, guard, routed, modelRoles, catalog, agents, step, objective }) {
714
+ function fitView({ fit, starting, guard, routed, modelRoles, catalog, agents, step, objective, baseline }) {
707
715
  const { fit: p, table, source } = routingTable(fit, starting);
708
716
  const raw = guard?.status === "ok" ? guard.guard : null;
709
717
  let labels = [];
@@ -718,15 +726,17 @@ function fitView({ fit, starting, guard, routed, modelRoles, catalog, agents, st
718
726
  const mark = "¹";
719
727
  const inst = installFrom(modelRoles, catalog, agents);
720
728
  const entry = (o, s) => {
721
- const e = rowEntry(table, routed, modelRoles, o, s, inst.install);
729
+ const e = rowEntry(table, routed, modelRoles, o, s, inst.install, baseline);
722
730
  return { ...e, candidates: e.candidates.map((c) => ({ ...c, nMark: s === "*" && differ.includes(c.cell) ? mark : null })) };
723
731
  };
724
732
  // A group's exploration Cells are centred on its `cost` row whichever
725
- // Objective routes the Pull, so each group's words are worked out once.
733
+ // Objective routes the Pull, but leave out the Cells the Objective itself excludes, so
734
+ // each Objective's words are worked out once.
726
735
  const exploring = new Map();
727
- const exploringOf = (s) => {
728
- if (!exploring.has(s)) exploring.set(s, exploringWords(table, routed, s, inst));
729
- return exploring.get(s);
736
+ const exploringOf = (o, s) => {
737
+ const key = `${o}\0${s}`;
738
+ if (!exploring.has(key)) exploring.set(key, exploringWords(table, routed, s, inst, o, baseline));
739
+ return exploring.get(key);
730
740
  };
731
741
  const line = (o, s, rest) => ({ stratum: s, ...groupOf(s), ...rest, anchor: `cells-row-${o}-${s}`, href: `#cells/row/${o}/${s}` });
732
742
  const objectives = OBJECTIVES.map((o) => ({
@@ -734,7 +744,7 @@ function fitView({ fit, starting, guard, routed, modelRoles, catalog, agents, st
734
744
  live: o === objective,
735
745
  lines: table === null
736
746
  ? [line(o, "*", { entry: null, exploring: null, unread: "no starting table read: the rows are not known" })]
737
- : Object.keys(table.rows[o]).map((s) => line(o, s, { entry: entry(o, s), exploring: exploringOf(s), unread: null })),
747
+ : Object.keys(table.rows[o]).map((s) => line(o, s, { entry: entry(o, s), exploring: exploringOf(o, s), unread: null })),
738
748
  }));
739
749
 
740
750
  const checks = objectives.flatMap((o) => o.lines.flatMap((l) => (l.entry === null ? [] : l.entry.candidates.map((c) => c.model)))).filter((m) => m !== null);
@@ -748,10 +758,10 @@ function fitView({ fit, starting, guard, routed, modelRoles, catalog, agents, st
748
758
  title: "The Fit that routes this run",
749
759
  flag: failedFitFlag(step, p),
750
760
  source,
751
- heading: dispatchHeading(table, routed, inst.install),
761
+ heading: dispatchHeading(table, routed, inst.install, baseline),
752
762
  labels,
753
763
  notices: modelChanges(p),
754
- burnIn: burnInProgress(p, routed, table, inst),
764
+ burnIn: burnInProgress(p, routed, table, inst, baseline),
755
765
  tripped: trippedWords(routed),
756
766
  unrunnable: unrunnableView(inst),
757
767
  modelLine,
@@ -929,14 +939,16 @@ function readersAlert(json) {
929
939
  * read, no Pull, no table, no Objective, no Fit.
930
940
  */
931
941
  export function computeCellEvidence({ guard, receipts, agents, modelRoles = null, catalog = null, pulls = [], table = null, objective = null, fit = null,
932
- guardJson = null, mainMetrics = null, closeoutPr = null, openPrs = null }) {
942
+ guardJson = null, mainMetrics = null, closeoutPr = null, openPrs = null, baselineCell = null }) {
933
943
  const routed = guard?.status === "ok" ? readGuard(guard.guard) : null;
944
+ // The run's Baseline Cell: the receipt's, else the cost guard's own record of it, else `slow-high`.
945
+ const baseline = baselineCell ?? (guard?.status === "ok" ? guard.guard.baseline.cell : DEFAULT_BASELINE_CELL);
934
946
  const step = newestStep(receipts);
935
947
  const records = recordsAgainstMain({ read: guard, fit, main: mainMetrics, closeoutPr, openPrs });
936
948
  return {
937
949
  alerts: [records.alert, noRulingAlert(guard), readersAlert(guardJson)].filter((a) => a !== null),
938
- policy: fitView({ fit, starting: table, guard, routed, modelRoles, catalog, agents, step: newestRefit(receipts), objective }),
939
- guard: guardSection(guard, receipts, step, modelRoles, pulls, records.note),
950
+ policy: fitView({ fit, starting: table, guard, routed, modelRoles, catalog, agents, step: newestRefit(receipts), objective, baseline }),
951
+ guard: guardSection(guard, receipts, step, modelRoles, pulls, records.note, baseline),
940
952
  declared: declaredSection(agents, modelRoles),
941
953
  };
942
954
  }