@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.
@@ -4,7 +4,7 @@
4
4
  // to its group is the one function that must never read differently between
5
5
  // the two.
6
6
  //
7
- // route [--session <dir|id>] [--objective cost|speed] --ticket <N> --arm A|B
7
+ // route [--session <dir|id>] [--objective cost|speed] [--baseline-cell <cell>] --ticket <N> --arm A|B
8
8
  // --impl-row <k> --issue <issue.json> --guard <cost-guard.json>
9
9
  // [--sizing <sizing.json>] [--table <router-table.json>]
10
10
  // [--chain-head] [--pending <tsv>]
@@ -30,8 +30,12 @@
30
30
  // an unreadable/invalid table: the caller does not dispatch then. With no
31
31
  // `--session`, the session is the one the phase-0 receipt
32
32
  // `.fleet/phase0.json` records, and with no `--objective` the objective
33
- // is; a receipt that records none is exit 2. Every Pull reads what the
34
- // install runs, burn-in, chain head and a missing guard included:
33
+ // is; a receipt that records none is exit 2. With no `--baseline-cell`, the
34
+ // Baseline Cell is the receipt's `baselineCell` (the Cell the router starts
35
+ // from, which the cost guard and the Fit compare every Cell with), else the
36
+ // saved value in `.fleet/baseline-cell.json`, else `slow-high`; one that is no
37
+ // Cell is exit 2. Every Pull reads what the install runs, burn-in, chain head
38
+ // and a missing guard included:
35
39
  // `modelRoles` (`omp config get modelRoles --json`, or the file
36
40
  // `--model-roles` names, holding that record), omp's model catalog
37
41
  // (`omp models --json`, or the file `--catalog` names) and the
@@ -58,12 +62,13 @@ import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } fr
58
62
  import { fileURLToPath } from "node:url";
59
63
  import { isCLI } from "./is-cli.mjs";
60
64
  import { makeDie, defineFlags, isDigits } from "./arg.mjs";
61
- import { CELL, OBJECTIVES, POLICY_CELL, STARTING_CELLS, drawCell, formatRouting, isRulePath, parseMember } from "./ledger-grammar.mjs";
62
- import { objectiveFromReceipt, sessionFromReceipt } from "./phase0-receipt.mjs";
65
+ import { CELL, DEFAULT_BASELINE_CELL, OBJECTIVES, drawCell, formatRouting, isRulePath, parseMember, startingSetOf } from "./ledger-grammar.mjs";
66
+ import { baselineCellFromReceipt, objectiveFromReceipt, sessionFromReceipt } from "./phase0-receipt.mjs";
63
67
  import {
64
68
  AttributionError, FEATURE_COLUMNS, OPTIONAL_COLUMNS, TRIP_POINTS, attribute, compareCells, generations, tally,
65
69
  } from "./pull-attribution.mjs";
66
70
  import { searchSplits, standing } from "./split-gate.mjs";
71
+ import { excludedCells, tripEntry, tripFault } from "./trip-reasons.mjs";
67
72
  import { LINE_REF, briefPaths, briefText } from "./ticket-text.mjs";
68
73
  import { catalogEntry, implementerCell, readOmpConfigValue, readOmpModelCatalog, resolveRole } from "./tier-roles.mjs";
69
74
 
@@ -83,9 +88,18 @@ const OMP_READ_TIMEOUT_MS = 10_000;
83
88
  // The fit's adoption floor (merged PRs per side) and margin.
84
89
  export const MIN_N = 20;
85
90
  const ADOPT_RATIO = 0.75;
86
- // Whether any starting Cell of `cells` (startingCellsOf's: the starting Cells the install runs) is short of MIN_N
87
- // merged PRs in a guard's `n`: burn-in holds while any is. A Cell the guard has no count for has 0.
88
- const anyStartingCellShort = (n, cells) => cells.some((c) => (n[c] ?? 0) < MIN_N);
91
+ /**
92
+ * The merged PRs a starting Cell is counted on in burn-in, from a guard's counts (parseGuard's `n` and `shared`): the
93
+ * Baseline Cell's own, and any other Cell's on its thinner side of the stretches it shares with the Baseline Cell,
94
+ * the counts the cost guard judges it on. A Cell the guard has no count for has 0.
95
+ */
96
+ export const burnInCount = (guard, cell, baseline) => (cell === baseline
97
+ ? guard.n[cell] ?? 0
98
+ : Math.min(guard.shared?.[cell]?.cell ?? 0, guard.shared?.[cell]?.base ?? 0));
99
+ // Whether any starting Cell of `cells` (startingCellsOf's: the starting Cells the install runs), or the Baseline Cell
100
+ // itself, is short of MIN_N merged PRs in a guard's counts: burn-in holds until the cost guard has judged every
101
+ // Cell of the starting set.
102
+ const anyStartingCellShort = (guard, cells, baseline) => [baseline, ...cells.filter((c) => c !== baseline)].some((c) => burnInCount(guard, c, baseline) < MIN_N);
89
103
  const KINDS = new Set(["bug", "enhancement", "documentation"]);
90
104
  const DAY_MS = 86_400_000;
91
105
 
@@ -364,9 +378,15 @@ export function validateTable(t) {
364
378
  }
365
379
  }
366
380
  if (typeof t.burn_in !== "boolean") return bad("`burn_in` is not a boolean");
381
+ // The Baseline Cell the table was computed under, which a Fit records and the starting table does not: the Cell
382
+ // `slow-high` when it records none.
383
+ if (t.baseline_cell !== undefined && (typeof t.baseline_cell !== "string" || !CELL.test(t.baseline_cell))) {
384
+ return bad("`baseline_cell` is not a cell token");
385
+ }
367
386
  // The starting Cells burn-in counted, which a Fit records and the starting table does not.
368
387
  const sc = t.starting_cells;
369
- if (sc !== undefined && (!Array.isArray(sc) || sc.length === 0 || new Set(sc).size !== sc.length || !sc.every((c) => STARTING_CELLS.includes(c)))) {
388
+ const set = startingSetOf(fitBaselineOf(t));
389
+ if (sc !== undefined && (!Array.isArray(sc) || sc.length === 0 || new Set(sc).size !== sc.length || !sc.every((c) => set.includes(c)))) {
370
390
  return bad("`starting_cells` is not a non-empty list of starting Cells, each once");
371
391
  }
372
392
  const cl = t.classifier;
@@ -377,16 +397,18 @@ export function validateTable(t) {
377
397
  if (g === null || typeof g !== "object" || !Array.isArray(g.tripped) || g.n === null || typeof g.n !== "object") {
378
398
  return bad("`guard` is not `{ tripped: [], n: {} }`");
379
399
  }
400
+ const fault = g.tripped.map(tripFault).find((why) => why !== null);
401
+ if (fault !== undefined) return bad(`\`guard\`: ${fault}`);
380
402
  return t;
381
403
  }
382
404
 
383
405
  /**
384
406
  * Arm B runs only once a classifier has passed its gate and some row of the
385
- * run's own objective's set is not the default: it decides a paid classifier
386
- * call for one Pull, which the other set's rows never route.
407
+ * run's own objective's set is not the Baseline Cell: it decides a paid
408
+ * classifier call for one Pull, which the other set's rows never route.
387
409
  */
388
- export function bArmLive(table, objective) {
389
- return table.classifier.b !== null && Object.values(table.rows[objective]).some((c) => c !== POLICY_CELL);
410
+ export function bArmLive(table, objective, baseline = DEFAULT_BASELINE_CELL) {
411
+ return table.classifier.b !== null && Object.values(table.rows[objective]).some((c) => c !== baseline);
390
412
  }
391
413
 
392
414
  /** The row a group routes by: its own, else the `*` row's — as a name no node of the table holds does, such as a group a Routing filed under another table names. */
@@ -429,25 +451,28 @@ export function isRunnable(install, cell) {
429
451
  export const unrunnableCells = (install) => (install === null ? [] : [...install.defined].filter((c) => !isRunnable(install, c)).sort());
430
452
 
431
453
  /**
432
- * The starting Cells `install` runs, in their order: the Cells burn-in counts and draws. All three where the install
433
- * was not read, and where it runs none of them, so that an install that cannot run them is no reason to end burn-in.
454
+ * The starting Cells of `baseline` that `install` runs, in their order: the Cells burn-in counts and draws. All of
455
+ * them where the install was not read, and where it runs none of them, so that an install that cannot run them is no
456
+ * reason to end burn-in.
434
457
  */
435
- export function startingCellsOf(install) {
436
- const runs = STARTING_CELLS.filter((c) => isRunnable(install, c));
437
- return runs.length > 0 ? runs : [...STARTING_CELLS];
458
+ export function startingCellsOf(install, baseline = DEFAULT_BASELINE_CELL) {
459
+ const set = startingSetOf(baseline);
460
+ const runs = set.filter((c) => isRunnable(install, c));
461
+ return runs.length > 0 ? runs : set;
438
462
  }
439
463
 
440
464
  /**
441
- * The Cell a Pull runs where the router holds no row's Cell back: POLICY_CELL while `install` (installOf's, or null)
442
- * runs it, else the nearest level of its role that the install runs and has an implementer definition for — downward
443
- * first, the direction omp lowers to, then upward. POLICY_CELL again when its role has no such level.
465
+ * The Cell a Pull runs where the router holds no row's Cell back: `baseline`, the run's Baseline Cell, while `install`
466
+ * (installOf's, or null) runs it, else the nearest level of its role that the install runs and has an implementer
467
+ * definition for — downward first, the direction omp lowers to, then upward. `baseline` again when its role has no
468
+ * such level.
444
469
  */
445
- export function defaultCellOf(install) {
446
- if (isRunnable(install, POLICY_CELL)) return POLICY_CELL;
447
- const [, role, level] = CELL.exec(POLICY_CELL);
470
+ export function defaultCellOf(install, baseline = DEFAULT_BASELINE_CELL) {
471
+ if (isRunnable(install, baseline)) return baseline;
472
+ const [, role, level] = CELL.exec(baseline);
448
473
  const usable = install.ladders[role].filter((l) => install.defined.has(`${role}-${l}`));
449
474
  const at = usable.findLast((l) => rank(l) < rank(level)) ?? usable.find((l) => rank(l) > rank(level));
450
- return at === undefined ? POLICY_CELL : `${role}-${at}`;
475
+ return at === undefined ? baseline : `${role}-${at}`;
451
476
  }
452
477
 
453
478
  /**
@@ -471,47 +496,56 @@ export function explorationCells(centre, ladders) {
471
496
 
472
497
  /**
473
498
  * The Cells an exploring Pull may draw, before the guard's tripped Cells and the install's unrunnable ones leave any
474
- * out: burn-in draws the starting Cells, whatever `cells` the table holds; a draw after it the exploration Cells
475
- * around `centre`, the group's `cost` row Cell, that `install` (installOf's) can run — none when the install was not
476
- * read (null). The fit judges `burn_in` over the starting Cells the install runs, so the Cells that end burn-in are
477
- * the Cells it draws.
499
+ * out: burn-in draws the starting set of `baseline`, whatever `cells` the table holds; a draw after it the exploration
500
+ * Cells around `centre`, the group's `cost` row Cell, that `install` (installOf's) can run — none when the install was
501
+ * not read (null). The fit judges `burn_in` over the starting Cells the install runs, so the Cells that end burn-in
502
+ * are the Cells it draws.
478
503
  */
479
- const drawPool = (table, centre, install) => {
480
- if (table.burn_in) return STARTING_CELLS;
504
+ const drawPool = (table, centre, install, baseline) => {
505
+ if (table.burn_in) return startingSetOf(baseline);
481
506
  if (install === null) return [];
482
507
  return explorationCells(centre, install.ladders).filter((c) => install.defined.has(c));
483
508
  };
484
509
 
485
510
  /**
486
- * What `route` does with one row under one guard, with no per-Pull input.
487
- * `guard` is readGuard's answer or null. `install` is installOf's answer, or
488
- * null where it was not read: no Cell is unrunnable there, and an every-5th
489
- * draw has no Cell. `policy` is the row's Cell, or the default cell
490
- * (defaultCellOf) when there is no guard, the row's Cell is tripped or the
491
- * row's Cell is unrunnable; `reason` is `guard-missing`,
492
- * `table-cell-unrunnable`, `table-cell-tripped` or `ok`, a Cell both
493
- * unrunnable and tripped being `table-cell-unrunnable`. `draw` is what an
494
- * exploring Pull picks from — `by` `burn-in` (every Pull) or `every-5th` —
495
- * over `cells`: drawPool()'s Cells less the tripped and the unrunnable,
496
- * centred on the `cost` row's Cell for the stratum as the guard and the
497
- * install leave it (the default cell when that row's Cell is tripped or
498
- * unrunnable), whichever objective routes the row. `draw` is null with no
499
- * guard and when no Cell is left.
511
+ * What `route` does with one row under one guard, with no per-Pull input. `guard` is readGuard's answer or null.
512
+ * `install` is installOf's answer, or null where it was not read: no Cell is unrunnable there, and an every-5th draw
513
+ * has no Cell. `baseline` is the run's Baseline Cell. The run's Objective excludes the tripped Cells whose reasons it
514
+ * holds a Cell back on (`cost` on `floor` or `usd`, `speed` on `floor` or `minutes`): `policy` is the row's Cell, or
515
+ * the default cell (defaultCellOf) when there is no guard, the row's Cell is excluded or the row's Cell is
516
+ * unrunnable; `reason` is `guard-missing`, `table-cell-unrunnable`, `table-cell-tripped` or `ok`, a Cell both
517
+ * unrunnable and excluded being `table-cell-unrunnable`. `draw` is what an exploring Pull picks from — `by`
518
+ * `burn-in` (every Pull) or `every-5th` — over `cells`: drawPool()'s Cells less those the Objective excludes and
519
+ * the unrunnable, centred on the `cost` row's Cell for the stratum as `cost`'s exclusions and the install leave it
520
+ * (the default cell when that row's Cell is excluded or unrunnable), whichever Objective routes the row. `draw` is
521
+ * null with no guard and when no Cell is left.
500
522
  * @returns {{ policy: string, reason: "guard-missing"|"table-cell-unrunnable"|"table-cell-tripped"|"ok", draw: null | { by: "burn-in"|"every-5th", cells: string[] } }}
501
523
  */
502
- export function rowDispatch({ table, guard, objective, stratum, install = null }) {
503
- const fallback = defaultCellOf(install);
504
- if (guard === null) return { policy: fallback, reason: "guard-missing", draw: null };
505
- const tripped = new Set(guard.tripped);
524
+ export const rowDispatch = ({ table, guard, objective, stratum, install = null, baseline = DEFAULT_BASELINE_CELL }) =>
525
+ dispatchRow({ table, guard, objective, stratum, install, baseline }).dispatch;
526
+
527
+ // rowDispatch's answer as `dispatch`, and `heldBack`: whether the draw's pool for the group held a Cell `objective`
528
+ // excludes, which the Routing records as `guard-tripped`. Under a guard the dispatch is worked out from `out`, the
529
+ // Cells `objective` excludes; `unrunnable` and `adjust(cell, excluded)`, which replaces an excluded or unrunnable
530
+ // Cell by the default; and `pool`, drawPool()'s Cells for the group, centred on its `cost` row's Cell as `cost`'s
531
+ // exclusions leave it.
532
+ function dispatchRow({ table, guard, objective, stratum, install, baseline }) {
533
+ const fallback = defaultCellOf(install, baseline);
534
+ if (guard === null) return { dispatch: { policy: fallback, reason: "guard-missing", draw: null }, heldBack: false };
535
+ const out = new Set(excludedCells(guard.tripped, objective));
536
+ const costOut = new Set(excludedCells(guard.tripped, "cost"));
506
537
  const unrunnable = (cell) => !isRunnable(install, cell);
507
- const adjust = (cell) => (tripped.has(cell) || unrunnable(cell) ? fallback : cell);
538
+ const adjust = (cell, excluded) => (excluded.has(cell) || unrunnable(cell) ? fallback : cell);
539
+ const pool = drawPool(table, adjust(rowFor(table.rows.cost, stratum), costOut), install, baseline);
508
540
  const row = rowFor(table.rows[objective], stratum);
509
- const by = table.burn_in ? "burn-in" : "every-5th";
510
- const cells = drawPool(table, adjust(rowFor(table.rows.cost, stratum)), install).filter((c) => !tripped.has(c) && !unrunnable(c));
541
+ const cells = pool.filter((c) => !out.has(c) && !unrunnable(c));
511
542
  return {
512
- policy: adjust(row),
513
- reason: unrunnable(row) ? "table-cell-unrunnable" : tripped.has(row) ? "table-cell-tripped" : "ok",
514
- draw: cells.length > 0 ? { by, cells } : null,
543
+ dispatch: {
544
+ policy: adjust(row, out),
545
+ reason: unrunnable(row) ? "table-cell-unrunnable" : out.has(row) ? "table-cell-tripped" : "ok",
546
+ draw: cells.length > 0 ? { by: table.burn_in ? "burn-in" : "every-5th", cells } : null,
547
+ },
548
+ heldBack: pool.some((c) => out.has(c)),
515
549
  };
516
550
  }
517
551
 
@@ -524,24 +558,39 @@ function readJson(path) {
524
558
  try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
525
559
  }
526
560
 
561
+ // Orders `{ cell, … }` entries by their Cell's name.
562
+ const byCellName = (a, b) => (a.cell < b.cell ? -1 : a.cell > b.cell ? 1 : 0);
563
+
527
564
  /**
528
565
  * `cost-guard.json` as the router reads it: `{ ok: true, guard }`, reduced to
529
566
  * what the router reads, or `{ ok: false, why }` when it refuses the file. `raw` is the parsed
530
- * file, `null` for one that is missing or will not parse.
567
+ * file, `null` for one that is missing or will not parse. `tripped` is each tripped Cell once, sorted, as
568
+ * `{ cell, on }` (trip-reasons.mjs's tripEntry): a bare Cell name, as a guard wrote before a trip recorded why, has
569
+ * `on` null. `n` is each Cell's merged PRs and `shared` the merged PRs on each side of the stretches it shares with
570
+ * the Baseline Cell, `{ cell, base }`: a Cell whose entry carries none has none.
531
571
  */
532
572
  export function parseGuard(raw) {
533
573
  if (raw === null || typeof raw !== "object") return { ok: false, why: "not a JSON object" };
534
574
  if (!Array.isArray(raw.tripped)) return { ok: false, why: "`tripped` is not a list" };
535
575
  if (!Array.isArray(raw.cells)) return { ok: false, why: "`cells` is not a list" };
536
- const tripped = raw.tripped.map((t) => (typeof t === "string" ? t : t?.cell));
537
- const bad = tripped.findIndex((t) => typeof t !== "string" || !CELL.test(t));
538
- if (bad !== -1) return { ok: false, why: `\`tripped\` names ${JSON.stringify(raw.tripped[bad])}, which is not a Cell` };
576
+ const fault = raw.tripped.map(tripFault).find((why) => why !== null);
577
+ if (fault !== undefined) return { ok: false, why: fault };
578
+ const byCell = new Map();
579
+ for (const e of raw.tripped.map(tripEntry)) {
580
+ const held = byCell.get(e.cell);
581
+ if (held === undefined) byCell.set(e.cell, e);
582
+ else byCell.set(e.cell, { cell: e.cell, on: held.on === null || e.on === null ? null : [...new Set([...held.on, ...e.on])] });
583
+ }
539
584
  const n = {};
585
+ const shared = {};
586
+ const count = (v) => Number.isInteger(v) && v >= 0;
540
587
  for (const c of raw.cells) {
541
588
  if (typeof c?.cell !== "string" || !Number.isFinite(c?.n)) return { ok: false, why: "a `cells` entry has no string `cell` or no finite `n`" };
542
589
  n[c.cell] = c.n;
590
+ if (count(c.shared_merged?.cell) && count(c.shared_merged?.base)) shared[c.cell] = { cell: c.shared_merged.cell, base: c.shared_merged.base };
543
591
  }
544
- return { ok: true, guard: { tripped: [...new Set(tripped)].sort(), n, window_start: typeof raw.window_start === "string" ? raw.window_start : null } };
592
+ const tripped = [...byCell.values()].sort(byCellName);
593
+ return { ok: true, guard: { tripped, n, shared, window_start: typeof raw.window_start === "string" ? raw.window_start : null } };
545
594
  }
546
595
 
547
596
  /** `cost-guard.json` reduced to what the router reads, or null when missing or unparseable. */
@@ -553,12 +602,32 @@ export function readGuard(raw) {
553
602
  /** The Fit's file name: metrics-refresh.mjs writes it beside the cost guard, and `route` reads it there. */
554
603
  export const FIT_FILE = "router-fit.json";
555
604
 
605
+ /**
606
+ * The starting table `raw`, the table file the install ships, for a run whose Baseline Cell is `baseline`: the file
607
+ * names no Cell, so its `cells` are the starting set of `baseline` and every Cell it leaves open — each `*` row and
608
+ * each `*` reason's `cell` — is `baseline`. A table that names its Cells is its own, filled in none.
609
+ */
610
+ export function startingTableOf(raw, baseline = DEFAULT_BASELINE_CELL) {
611
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return raw;
612
+ const isObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
613
+ const filled = (set, fill) => (isObject(set) ? Object.fromEntries(Object.entries(set).map(([k, v]) => [k, fill(v)])) : set);
614
+ const perObjective = (field, fill) => (isObject(raw[field]) ? Object.fromEntries(Object.entries(raw[field]).map(([o, set]) => [o, filled(set, fill)])) : raw[field]);
615
+ return {
616
+ ...raw,
617
+ cells: raw.cells ?? startingSetOf(baseline),
618
+ rows: perObjective("rows", (cell) => cell ?? baseline),
619
+ reasons: perObjective("reasons", (record) => (isObject(record) ? { ...record, cell: record.cell ?? baseline } : record)),
620
+ };
621
+ }
622
+
556
623
  /**
557
624
  * The table the Fit beside `guardPath` holds, `{ table, fallback: null }`, or `{ table: null, fallback }` when
558
625
  * there is none to route by: `fallback` is the Routing `REASON` that names why — `fit-missing` for no file,
559
- * `fit-unreadable` for one that will not read or parse, `fit-invalid` for one whose `table` validateTable refuses.
626
+ * `fit-unreadable` for one that will not read or parse, `fit-invalid` for one whose `table` validateTable refuses or
627
+ * that was computed under another Baseline Cell than `baseline`, the run's (a Fit that records none was computed
628
+ * under `slow-high`).
560
629
  */
561
- export function readFitBeside(guardPath) {
630
+ export function readFitBeside(guardPath, baseline = DEFAULT_BASELINE_CELL) {
562
631
  let text;
563
632
  try {
564
633
  text = readFileSync(join(dirname(guardPath), FIT_FILE), "utf8");
@@ -568,9 +637,13 @@ export function readFitBeside(guardPath) {
568
637
  let fit;
569
638
  try { fit = JSON.parse(text); } catch { return { table: null, fallback: "fit-unreadable" }; }
570
639
  const table = validateTable(fit?.table);
571
- return table instanceof Error ? { table: null, fallback: "fit-invalid" } : { table, fallback: null };
640
+ if (table instanceof Error || fitBaselineOf(table) !== baseline) return { table: null, fallback: "fit-invalid" };
641
+ return { table, fallback: null };
572
642
  }
573
643
 
644
+ /** The Baseline Cell a validated Fit table was computed under: the one it records, else `slow-high`. */
645
+ export const fitBaselineOf = (table) => table.baseline_cell ?? DEFAULT_BASELINE_CELL;
646
+
574
647
  /** The sizing verdict on a live B Pull: `{ src, label, usd }`, or null when it is unusable. */
575
648
  function readSizing(raw, classifier) {
576
649
  if (raw === null || typeof raw !== "object" || raw.source !== classifier.b) return null;
@@ -617,12 +690,16 @@ export function assignmentProb({ burnIn, chainHead, cell, policy, cells }) {
617
690
  * but the paths the brief names, which `named_lines` reads under `root`, the
618
691
  * checkout. `version` is the install's, `plugin_version` on the row. The
619
692
  * ticket's group is the node the tree's walk ends at (stratumOf), and the row
620
- * set's row for it routes the Pull. The exploration draw ignores the objective:
621
- * it is centred on the cell the `cost` set routes the group to, whichever set
622
- * routes the Pull, so a Pull draws the same cell under both. `install` is
693
+ * set's row for it routes the Pull. `baseline` is the run's Baseline Cell. The
694
+ * Pull applies its own Objective's exclusions (rowDispatch): a Cell that
695
+ * Objective excludes is neither routed nor drawn, and a Cell it does not is
696
+ * both. The exploration draw is centred on the cell the `cost` set routes the
697
+ * group to, as `cost`'s exclusions leave it, whichever set routes the Pull.
698
+ * `install` is
623
699
  * installOf's answer, or null where it was not read, which checks no Cell
624
700
  * against the install and leaves an every-5th Pull nothing to draw. The
625
- * Routing's `UNRUNNABLE` is unrunnableCells(install). A live B Pull
701
+ * Routing's `UNRUNNABLE` is unrunnableCells(install), and its `TRIPPED` the
702
+ * Cells the Objective excludes. A live B Pull
626
703
  * records its sizing verdict and routes as an A Pull does: a label names no
627
704
  * group of the tree. `fallback` is readFitBeside's REASON when `table` is the
628
705
  * starting table standing in for a Fit, else null: it is the first thing that
@@ -632,8 +709,8 @@ export function assignmentProb({ burnIn, chainHead, cell, policy, cells }) {
632
709
  * @returns {{ line: string, row: Record<string,string> }}
633
710
  */
634
711
  export function route({
635
- session, ticket, arm, implRow, chainHead = false, issue, sizing = null, guard, table, objective, now = Date.now(),
636
- root = process.cwd(), version = installVersion(), fallback = null, install = null,
712
+ session, ticket, arm, implRow, chainHead = false, issue, sizing = null, guard, table, objective, baseline = DEFAULT_BASELINE_CELL,
713
+ now = Date.now(), root = process.cwd(), version = installVersion(), fallback = null, install = null,
637
714
  }) {
638
715
  let reason = null;
639
716
  const degrade = (r) => { reason ??= r; };
@@ -650,7 +727,7 @@ export function route({
650
727
  let sizingSrc = "rule";
651
728
  let sizingPre = "";
652
729
  let routerUsd = "";
653
- if (arm === "B" && bArmLive(table, objective)) {
730
+ if (arm === "B" && bArmLive(table, objective, baseline)) {
654
731
  const sized = readSizing(sizing, table.classifier);
655
732
  if (sized === null) {
656
733
  degrade("no-sizing");
@@ -660,31 +737,29 @@ export function route({
660
737
  }
661
738
  }
662
739
 
663
- const dispatch = (o) => rowDispatch({ table, guard, objective: o, stratum, install });
664
- const policyRow = dispatch(objective);
665
- const drawRow = dispatch("cost");
666
- if (policyRow.reason !== "ok") degrade(policyRow.reason);
740
+ const { dispatch: dispatched, heldBack } = dispatchRow({ table, guard, objective, stratum, install, baseline });
741
+ if (dispatched.reason !== "ok") degrade(dispatched.reason);
667
742
  // With no guard the default cell is the only one: the guard cannot be
668
743
  // evaded by deleting it.
669
- const policy = policyRow.policy;
744
+ const policy = dispatched.policy;
670
745
  let cell = policy;
671
746
  let draw = null;
672
747
  let by = null;
673
748
  if (guard !== null) {
674
749
  const exploring = table.burn_in || (implRow % EXPLORE_EVERY === 0 && !chainHead);
675
750
  if (exploring) {
676
- if (drawPool(table, drawRow.policy, install).some((c) => guard.tripped.includes(c))) degrade("guard-tripped");
677
- if (drawRow.draw !== null) {
751
+ if (heldBack) degrade("guard-tripped");
752
+ if (dispatched.draw !== null) {
678
753
  // rowDispatch's `cells` never hold the `cost` row's Cell: nothing more to withhold.
679
- const d = drawCell({ session, ticket, policyCell: null, cells: drawRow.draw.cells });
754
+ const d = drawCell({ session, ticket, policyCell: null, cells: dispatched.draw.cells });
680
755
  cell = d.cell;
681
756
  draw = { k: d.k, K: d.K };
682
- by = drawRow.draw.by;
757
+ by = dispatched.draw.by;
683
758
  }
684
759
  }
685
760
  }
686
761
  reason ??= "ok";
687
- const prob = assignmentProb({ burnIn: table.burn_in, chainHead, cell, policy, cells: drawRow.draw?.cells ?? [] });
762
+ const prob = assignmentProb({ burnIn: table.burn_in, chainHead, cell, policy, cells: dispatched.draw?.cells ?? [] });
688
763
 
689
764
  const row = {
690
765
  run_date: sessionDate(session), session, agent: `impl-${ticket}`, ticket: String(ticket),
@@ -696,7 +771,7 @@ export function route({
696
771
  policy, cell, draw, by, stratum,
697
772
  brief: metrics === null ? null : Number(metrics.brief_chars), criteria: metrics === null ? null : Number(metrics.criteria),
698
773
  parent: m.parent === "" ? null : Number(m.parent),
699
- sized: sizingPre === "" ? null : sizingPre, objective, tripped: guard?.tripped ?? [], unrunnable: unrunnableCells(install), reason,
774
+ sized: sizingPre === "" ? null : sizingPre, objective, tripped: guard === null ? [] : excludedCells(guard.tripped, objective), unrunnable: unrunnableCells(install), reason,
700
775
  });
701
776
  return { line, row };
702
777
  }
@@ -808,32 +883,36 @@ const unjudged = () => ({ cell: null, reason: "unjudged", cells: {}, pairs: [] }
808
883
  /**
809
884
  * One row's cell under one objective — a node's of the tree — and why. The
810
885
  * quality floor is held twice: by the guard over every group's Pulls together,
811
- * whose trip takes a cell out of every row and out of the exploration draw,
812
- * and per row by the fit, which refuses a cell under the floor that row alone.
813
- * The floor is measured against the default cell under both objectives. Every
814
- * figure read is the cell's newest generation's, the default cell's included,
886
+ * whose `floor` trip takes a cell out of every row and out of the exploration
887
+ * draw, and per row by the fit, which refuses a cell under the floor that row
888
+ * alone. The floor is measured against `baseline`, the run's Baseline Cell,
889
+ * under both objectives. Every
890
+ * figure read is the cell's newest generation's, the Baseline Cell's included,
815
891
  * and every comparison is `compareCells`': two cells over the stretches in
816
892
  * which both were drawn, the stretches pooled, so a base's other weeks move
817
893
  * no verdict and a shift that hits every cell at once cancels in every gap.
818
894
  * The one test it does not cancel in is ADOPT_RATIO's, a ratio of the two
819
895
  * figures: a shift that raises both by the same amount brings the ratio nearer
820
896
  * 1, so it can move a candidate from qualifying to `too-dear` or `too-slow`.
821
- * `pulls` holds the row's counted Pulls per cell (`estimate()`'s); `baseCell`
822
- * is the cell the row holds unless a candidate qualifies: the default cell
823
- * under `cost`, the `cost` row's cell under `speed`. The figure is $ per
897
+ * `pulls` holds the row's counted Pulls per cell (`estimate()`'s); `excluded`
898
+ * the Cells the run's objective excludes (the guard's trips on a reason it
899
+ * holds a Cell back on); `baseCell`
900
+ * is the cell the row holds unless a candidate qualifies: the Baseline Cell
901
+ * under `cost`, the `cost` row's cell under `speed` as `speed`'s exclusions
902
+ * leave it. The figure is $ per
824
903
  * merged PR under `cost` and minutes of work time per merged PR under `speed`.
825
904
  *
826
905
  * A candidate is a cell of `cells` other than the base. Its `verdict`, the
827
- * first that applies: `tripped` by the guard; `too-few`, under MIN_N merged
906
+ * first that applies: `tripped`, excluded by the guard under this objective; `too-few`, under MIN_N merged
828
907
  * PRs in the row, on either side, in the stretches it shares with the base or
829
- * with the default cell (none shared, none counted); `under-floor` against the
830
- * default cell there; `too-dear` (`cost`) or `too-slow` (`speed`), above
908
+ * with the Baseline Cell (none shared, none counted); `under-floor` against the
909
+ * Baseline Cell there; `too-dear` (`cost`) or `too-slow` (`speed`), above
831
910
  * ADOPT_RATIO of the base's figure, both figures over the stretches it shares
832
911
  * with the base; `not-reliably-cheaper` or `not-reliably-faster`, its `range`
833
912
  * does not lie wholly below zero (its upper end, as `bootstrapDiffCI` returns
834
913
  * it, is not below zero) or there is none; else it `qualifies`. A candidate
835
914
  * past `too-few` records whether it is `under_floor`, the floor's `bar` (the
836
- * default cell's fail rate over the stretches it shares with the candidate,
915
+ * Baseline Cell's fail rate over the stretches it shares with the candidate,
837
916
  * plus TRIP_POINTS, rounded as a fail rate is, for reading only: the floor
838
917
  * compares counts) and its `range`, the bootstrap 95% range of (candidate −
839
918
  * base) figure over the Pulls of those stretches; the others record null for
@@ -846,20 +925,20 @@ const unjudged = () => ({ cell: null, reason: "unjudged", cells: {}, pairs: [] }
846
925
  * lower fail rate wins, then the lower figure, then the name; each is the
847
926
  * qualifier's gap to the base over the stretches it shares with it.
848
927
  *
849
- * `reason`, why the row holds `cell`: `unjudged` (the default cell or the
850
- * base, or every untripped candidate, is under MIN_N merged PRs; `cell` is
928
+ * `reason`, why the row holds `cell`: `unjudged` (the Baseline Cell or the
929
+ * base, or every unexcluded candidate, is under MIN_N merged PRs; `cell` is
851
930
  * null), `no-qualifier` (the base), or, for the winner, `sole-qualifier`,
852
931
  * `reliably-cheaper` or `reliably-faster` (every other qualifier was
853
932
  * dropped), or what put it ahead of the next of the rest: `lower-fail-rate`,
854
933
  * `lower-usd` or `fewer-minutes`, or `name`.
855
934
  */
856
- function judge(objective, pulls = {}, cells, tripped, baseCell) {
935
+ function judge(objective, pulls = {}, cells, excluded, baseCell, baseline) {
857
936
  const { figure, metric, over, unreliable, better, reliably, ahead } = JUDGE[objective];
858
937
  const record = unjudged();
859
938
  const pullsOf = (c) => pulls[c] ?? [];
860
939
  const mergedOf = (c) => pullsOf(c).filter((u) => u.merged).length;
861
- // A default cell or base short of MIN_N merged PRs has none to give any candidate, whichever stretches they share.
862
- if (mergedOf(POLICY_CELL) < MIN_N || mergedOf(baseCell) < MIN_N) return record;
940
+ // A Baseline Cell or base short of MIN_N merged PRs has none to give any candidate, whichever stretches they share.
941
+ if (mergedOf(baseline) < MIN_N || mergedOf(baseCell) < MIN_N) return record;
863
942
  // JSON writes −0 as 0, so a recorded end is 0 either way: normalise it here.
864
943
  const range = (m) => m.range(metric)?.map((x) => x + 0) ?? null;
865
944
  const reliablyBelow = (r) => r !== null && r[1] < 0;
@@ -871,12 +950,12 @@ function judge(objective, pulls = {}, cells, tripped, baseCell) {
871
950
  let judged = false;
872
951
  for (const c of cells) {
873
952
  if (c === baseCell) continue;
874
- if (tripped.has(c)) {
953
+ if (excluded.has(c)) {
875
954
  record.cells[c] = { verdict: "tripped", under_floor: null, bar: null, range: null };
876
955
  continue;
877
956
  }
878
957
  const vsBase = compareCells(pullsOf(c), pullsOf(baseCell));
879
- const vsFloor = baseCell === POLICY_CELL ? vsBase : compareCells(pullsOf(c), pullsOf(POLICY_CELL));
958
+ const vsFloor = baseCell === baseline ? vsBase : compareCells(pullsOf(c), pullsOf(baseline));
880
959
  if (!enough(vsBase) || !enough(vsFloor)) {
881
960
  record.cells[c] = { verdict: "too-few", under_floor: null, bar: null, range: null };
882
961
  continue;
@@ -921,79 +1000,92 @@ function judge(objective, pulls = {}, cells, tripped, baseCell) {
921
1000
  return { ...record, cell: win, reason };
922
1001
  }
923
1002
 
924
- /** A `cost` row: `judge()` from the default cell, by $ per merged PR. */
925
- function judgeRow(pulls, cells, tripped) {
926
- return judge("cost", pulls, cells, tripped, POLICY_CELL);
1003
+ /** A `cost` row: `judge()` from the Baseline Cell, by $ per merged PR, over the Cells `cost` excludes. */
1004
+ function judgeRow(pulls, cells, excluded, baseline) {
1005
+ return judge("cost", pulls, cells, excluded, baseline, baseline);
927
1006
  }
928
1007
 
929
- /** A `speed` row: `judge()` from the `cost` row's cell, by minutes of work time per merged PR. */
930
- function judgeSpeedRow(pulls, cells, tripped, costCell) {
931
- return judge("speed", pulls, cells, tripped, costCell);
1008
+ /** A `speed` row: `judge()` from `base`, the `cost` row's cell as `speed`'s exclusions leave it, by minutes of work time per merged PR, over the Cells `speed` excludes. */
1009
+ function judgeSpeedRow(pulls, cells, excluded, base, baseline) {
1010
+ return judge("speed", pulls, cells, excluded, base, baseline);
932
1011
  }
933
1012
 
934
1013
  /**
935
1014
  * The re-fit table, over the tree `prior.splits` holds: this makes no split
936
- * and takes none away (fitTree grows the tree). `guard` is `{ tripped, n, window_start }` (readGuard's
937
- * shape). `rows` and `reasons` hold one set per
1015
+ * and takes none away (fitTree grows the tree). `guard` is `{ tripped, n, shared, window_start }` (readGuard's
1016
+ * shape). `baseline` is the run's Baseline Cell, which the table records as `baseline_cell`: its `cells` are the
1017
+ * Baseline Cell's starting set (startingSetOf), the Cells the fit judges, and the fit adds no Cell. `rows` and
1018
+ * `reasons` hold one set per
938
1019
  * objective, and each a row or record for every node. `reasons.cost` holds
939
- * `judgeRow()`'s record, its `cell` the cell the node's `cost` row holds: a
1020
+ * `judgeRow()`'s record, judged with the Cells `cost` excludes, its `cell` the cell the node's `cost` row holds: a
940
1021
  * node whose record has no cell holds its parent's `cost` row, as a ticket
941
- * there follows the parent, and an unjudged root holds the default cell.
1022
+ * there follows the parent, and an unjudged root holds the Baseline Cell.
942
1023
  * `reasons.speed` holds `judgeSpeedRow()`'s record for each node with a `cost`
943
- * row of its own (the root always has one), from that row's cell, the base when
944
- * the record has no cell; a node with none holds its parent's `speed` row and
945
- * an `unjudged` record. `cells` is the prior's: the fit adds no Cell. `burn_in`
946
- * holds until every Cell of `startingCells` has MIN_N merged PRs on its newest
947
- * generation (`guard.n`, which starts again at 0 when a role's model changes):
948
- * no other Cell the table holds ends it or holds it, whatever its merged PRs.
1024
+ * row of its own (the root always has one), judged with the Cells `speed` excludes, from that row's cell as
1025
+ * `speed`'s exclusions leave it — the Baseline Cell where `speed` excludes it — which the record's `cell` falls
1026
+ * back to when it has none; a node with none holds its parent's `speed` row and
1027
+ * an `unjudged` record. `burn_in`
1028
+ * holds until the guard has judged every Cell of `startingCells`: the Baseline Cell has MIN_N merged PRs on its
1029
+ * newest generation (`guard.n`, which starts again at 0 when a role's model changes) and every other Cell MIN_N on
1030
+ * each side of the stretches it shares with it (`guard.shared`): no other Cell the table holds ends it or holds it,
1031
+ * whatever its merged PRs.
949
1032
  * `startingCells` are the starting Cells the install runs (startingCellsOf) —
950
- * all three when absent — and the table records them as `starting_cells`, so
1033
+ * the whole starting set when absent — and the table records them as `starting_cells`, so
951
1034
  * the records, the guard, the prior and that set fit the same table again.
952
1035
  * Throws on a `startingCells` that is empty, which would end burn-in on no
953
- * count at all, or that names a Cell that is no starting Cell.
1036
+ * count at all, or that names a Cell that is no starting Cell of `baseline`.
954
1037
  */
955
- export function fitTable({ prior, features, members, verdicts, guard, startingCells = STARTING_CELLS }) {
1038
+ export function fitTable({ prior, features, members, verdicts, guard, baseline = DEFAULT_BASELINE_CELL, startingCells = startingSetOf(baseline) }) {
956
1039
  const window = guard.window_start ?? prior.window_start ?? null;
957
- return tableOver({ prior, ...fitPulls({ features, members, verdicts, window }), guard, window, startingCells });
1040
+ return tableOver({ prior, ...fitPulls({ features, members, verdicts, window }), guard, window, baseline, startingCells });
958
1041
  }
959
1042
 
960
1043
  // The table over the tree `prior.splits` holds, from the fit's Pulls (fitPulls') booked to its groups.
961
- function tableOver({ prior, units: unbooked, order, guard, window, startingCells }) {
962
- if (startingCells.length === 0 || !startingCells.every((c) => STARTING_CELLS.includes(c))) {
1044
+ function tableOver({ prior, units: unbooked, order, guard, window, baseline, startingCells }) {
1045
+ const set = startingSetOf(baseline);
1046
+ if (startingCells.length === 0 || !startingCells.every((c) => set.includes(c))) {
963
1047
  throw new Error(`startingCells is not a non-empty list of starting Cells: ${JSON.stringify(startingCells)}`);
964
1048
  }
965
1049
  const nodes = treeNodes(prior.splits);
966
1050
  const units = book(unbooked, prior);
967
1051
  const { estimates, pulls } = estimate(units, order, nodes);
968
- const tripped = new Set(guard.tripped);
1052
+ const out = { cost: new Set(excludedCells(guard.tripped, "cost")), speed: new Set(excludedCells(guard.tripped, "speed")) };
969
1053
 
970
1054
  // The rows and their reasons over the table's `cells`: a fitted table's `reasons` cover exactly its `cells`.
971
1055
  const rows = { cost: {}, speed: {} };
972
1056
  const reasons = { cost: {}, speed: {} };
973
1057
  for (const s of nodes) {
974
1058
  const up = parentOf(s);
975
- const cost = judgeRow(pulls[s], prior.cells, tripped);
1059
+ const cost = judgeRow(pulls[s], set, out.cost, baseline);
976
1060
  const own = cost.cell !== null || up === null;
977
- const costCell = cost.cell ?? (up === null ? POLICY_CELL : rows.cost[up]);
978
- const speed = own ? judgeSpeedRow(pulls[s], prior.cells, tripped, costCell) : unjudged();
979
- const speedCell = speed.cell ?? (own ? costCell : rows.speed[up]);
1061
+ const costCell = cost.cell ?? (up === null ? baseline : rows.cost[up]);
1062
+ // `speed` starts from, and falls back to, the `cost` row's Cell as its own exclusions leave it.
1063
+ const speedBase = out.speed.has(costCell) ? baseline : costCell;
1064
+ const speed = own ? judgeSpeedRow(pulls[s], set, out.speed, speedBase, baseline) : unjudged();
1065
+ const speedCell = speed.cell ?? (own ? speedBase : rows.speed[up]);
980
1066
  rows.cost[s] = costCell;
981
1067
  rows.speed[s] = speedCell;
982
1068
  reasons.cost[s] = { ...cost, cell: costCell };
983
1069
  reasons.speed[s] = { ...speed, cell: speedCell };
984
1070
  }
1071
+ const shared = guard.shared ?? {};
985
1072
  return {
986
1073
  window_start: window,
987
1074
  n_rows: units.length,
988
- cells: prior.cells,
989
- burn_in: anyStartingCellShort(guard.n, startingCells),
1075
+ baseline_cell: baseline,
1076
+ cells: [...set],
1077
+ burn_in: anyStartingCellShort(guard, startingCells, baseline),
990
1078
  starting_cells: [...startingCells],
991
1079
  splits: prior.splits,
992
1080
  rows,
993
1081
  classifier: prior.classifier,
994
1082
  estimates,
995
1083
  reasons,
996
- guard: { tripped: [...tripped].sort(), n: Object.fromEntries(Object.keys(guard.n).sort().map((c) => [c, guard.n[c]])) },
1084
+ guard: {
1085
+ tripped: guard.tripped.map(tripEntry).sort(byCellName),
1086
+ n: Object.fromEntries(Object.keys(guard.n).sort().map((c) => [c, guard.n[c]])),
1087
+ shared: Object.fromEntries(Object.keys(shared).sort().map((c) => [c, shared[c]])),
1088
+ },
997
1089
  };
998
1090
  }
999
1091
 
@@ -1043,8 +1135,10 @@ function treeOf(cuts) {
1043
1135
  }
1044
1136
 
1045
1137
  /**
1046
- * The tree the fit grows, and what the gate found. The group searched is every counted Pull of the table's Cells the
1047
- * guard has not tripped, that records the probability its Cell was assigned with (the rest are `left_out`): the gate
1138
+ * The tree the fit grows, and what the gate found. The group searched is every counted Pull of the run's starting set
1139
+ * (`baseline`'s) that the guard has not tripped on a reason `cost` excludes (`excluded`: one tree serves both
1140
+ * Objectives and is scored on $, so a Cell tripped on `minutes` alone stays in the search), that records the
1141
+ * probability its Cell was assigned with (the rest are `left_out`): the gate
1048
1142
  * weighs each Pull by it. `previous` is the `gate` record of the last Fit that computed, or null. The tree is the root
1049
1143
  * and, when the best split passes both tests and passed on the same input or inputs at the last Fit too, that split;
1050
1144
  * the starting table's own tree is not read. `gate.records` is a digest of the Cells and Pulls searched: a Fit whose
@@ -1052,8 +1146,8 @@ function treeOf(cuts) {
1052
1146
  * keeps that Fit's `passed` and `stands`, and a first pass cannot stand on the same records twice. `gate.passed`,
1053
1147
  * `gate.stands` and `gate.records` are what the next Fit reads.
1054
1148
  */
1055
- function growTree({ prior, units, order, tripped, previous }) {
1056
- const cells = prior.cells.includes(POLICY_CELL) ? [POLICY_CELL, ...prior.cells.filter((c) => c !== POLICY_CELL && !tripped.has(c))] : [];
1149
+ function growTree({ units, order, excluded, previous, baseline }) {
1150
+ const cells = [baseline, ...startingSetOf(baseline).filter((c) => c !== baseline && !excluded.has(c))];
1057
1151
  const pulls = [];
1058
1152
  let leftOut = 0;
1059
1153
  for (const { pulls: counted } of tally(units, order).filter((t) => cells.includes(t.cell))) {
@@ -1099,11 +1193,11 @@ function growTree({ prior, units, order, tripped, previous }) {
1099
1193
  * fitTable's.
1100
1194
  * @returns {{ table: object, gate: { records: string, scored: number, left_out: number, best: object|null, passed: string[], stands: string[] } }}
1101
1195
  */
1102
- export function fitTree({ prior, features, members, verdicts, guard, previous = null, startingCells = STARTING_CELLS }) {
1196
+ export function fitTree({ prior, features, members, verdicts, guard, previous = null, baseline = DEFAULT_BASELINE_CELL, startingCells = startingSetOf(baseline) }) {
1103
1197
  const window = guard.window_start ?? prior.window_start ?? null;
1104
1198
  const fitted = fitPulls({ features, members, verdicts, window });
1105
- const { gate, splits } = growTree({ prior, ...fitted, tripped: new Set(guard.tripped), previous });
1106
- return { table: tableOver({ prior: { ...prior, splits }, ...fitted, guard, window, startingCells }), gate };
1199
+ const { gate, splits } = growTree({ ...fitted, excluded: new Set(excludedCells(guard.tripped, "cost")), previous, baseline });
1200
+ return { table: tableOver({ prior: { ...prior, splits }, ...fitted, guard, window, baseline, startingCells }), gate };
1107
1201
  }
1108
1202
 
1109
1203
  /**
@@ -1140,7 +1234,7 @@ function main() {
1140
1234
  const die = makeDie(NAME);
1141
1235
  const F = defineFlags(die, {
1142
1236
  flags: {
1143
- session: "value", objective: "value", ticket: "value", arm: "value", "impl-row": "value", issue: "value",
1237
+ session: "value", objective: "value", "baseline-cell": "value", ticket: "value", arm: "value", "impl-row": "value", issue: "value",
1144
1238
  sizing: "value", guard: "value", table: "value", pending: "value", "chain-head": "bool", "model-roles": "value", catalog: "value", agents: "value",
1145
1239
  },
1146
1240
  positionals: ["route"],
@@ -1150,12 +1244,17 @@ function main() {
1150
1244
  if (!process.argv.slice(2).includes("route")) die("usage: ticket-router.mjs route …");
1151
1245
  const need = (name) => F.arg(name) ?? die(`route needs --${name}`);
1152
1246
 
1247
+ // `--baseline-cell` omitted is the Baseline Cell the receipt records, else the saved value, else `slow-high`.
1248
+ let baseline = F.arg("baseline-cell");
1249
+ if (baseline === null) baseline = baselineCellFromReceipt().cell;
1250
+ else if (!CELL.test(baseline)) die(`--baseline-cell ${baseline} is not a Cell`);
1251
+
1153
1252
  // With no `--table`, routes by the Fit beside `--guard`, else by the starting table.
1154
- const fit = F.arg("table") === null && F.arg("guard") !== null ? readFitBeside(F.arg("guard")) : null;
1253
+ const fit = F.arg("table") === null && F.arg("guard") !== null ? readFitBeside(F.arg("guard"), baseline) : null;
1155
1254
  const tablePath = F.arg("table") ?? DEFAULT_TABLE;
1156
1255
  let table = fit?.table ?? null;
1157
1256
  if (table === null) {
1158
- try { table = JSON.parse(readFileSync(tablePath, "utf8")); } catch (e) { die(`cannot read the router table ${tablePath}: ${e.message}`); }
1257
+ try { table = startingTableOf(JSON.parse(readFileSync(tablePath, "utf8")), baseline); } catch (e) { die(`cannot read the router table ${tablePath}: ${e.message}`); }
1159
1258
  const valid = validateTable(table);
1160
1259
  if (valid instanceof Error) die(`${tablePath}: ${valid.message}`);
1161
1260
  }
@@ -1196,7 +1295,7 @@ function main() {
1196
1295
  // draws after burn-in are the group's exploration Cells. A read that fails or does not answer in OMP_READ_TIMEOUT_MS,
1197
1296
  // a `modelRoles` that is no record and a catalog with no `models` list leave the Pull's Cells unchecked and its
1198
1297
  // every-5th draw empty, and warn, never the exit; so does a read that holds nothing to run: a role that runs at no
1199
- // level, no implementer definition, or no level of the default Cell's role that is both run and defined.
1298
+ // level, no implementer definition, or no level of the Baseline Cell's role that is both run and defined.
1200
1299
  const warn = (what) => process.stderr.write(`${NAME}: WARNING ${what}\n`);
1201
1300
  const agents = F.arg("agents") ?? AGENTS_DIR;
1202
1301
  const { install, why } = readInstall({ modelRoles: F.arg("model-roles"), catalog: F.arg("catalog"), agents });
@@ -1208,13 +1307,13 @@ function main() {
1208
1307
  warn(`this install runs ${unrun.join(", ")} at no level (modelRoles names no model for it, or one omp's catalog lists at none) — no Cell of ${unrun.length === 1 ? "that role" : "those roles"} is routed or drawn`);
1209
1308
  }
1210
1309
  if (install.defined.size === 0) warn(`${agents} holds no implementer definition — no exploration Cell is drawn`);
1211
- if (!isRunnable(install, POLICY_CELL) && defaultCellOf(install) === POLICY_CELL) {
1212
- warn(`no level of ${POLICY_CELL}'s role runs here with an implementer definition — ${POLICY_CELL} stays the default Cell`);
1310
+ if (!isRunnable(install, baseline) && defaultCellOf(install, baseline) === baseline) {
1311
+ warn(`no level of ${baseline}'s role runs here with an implementer definition — ${baseline} stays the default Cell`);
1213
1312
  }
1214
1313
  }
1215
1314
  const { line, row } = route({
1216
1315
  session, ticket: Number(ticket), arm, implRow: Number(implRowArg), chainHead,
1217
- issue: readJson(issuePath), sizing: readJson(F.arg("sizing")), guard, table, objective, root, version,
1316
+ issue: readJson(issuePath), sizing: readJson(F.arg("sizing")), guard, table, objective, baseline, root, version,
1218
1317
  fallback: fit?.fallback ?? null, install,
1219
1318
  });
1220
1319
  const pending = F.arg("pending") ?? join(dirname(guardPath), "ticket-features.pending.tsv");