@feigi/fleet-ctl 3.144.4 → 3.146.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
  // The cockpit's Cell evidence tab, as a value: computeCellEvidence() turns what
2
2
  // gather() read (the cost guard, the receipts' `metrics` steps, the installed
3
3
  // definitions, the installed router table and package, the carried `modelRoles`
4
- // read, the Preview fit) into the model the page lays out.
4
+ // read, the Fit) into the model the page lays out.
5
5
  // Pure, like compute-board.mjs, which calls it and puts the answer in
6
6
  // `board.json` as `cellEvidence`: no file, no process, no clock. Every word the
7
7
  // tab shows is built here, so a test pins it where it is made and the page only
@@ -14,11 +14,16 @@
14
14
  // routes-now side the Cell the installed router table plus the workspace's guard
15
15
  // route to, why, and how a Pull on that row is dispatched (ticket-router.mjs's
16
16
  // rowDispatch, the function `route` itself calls), and on the evidence-favours
17
- // side the same for the Preview fit's table (`.fleet/router-preview.json`, which
18
- // metrics-refresh.mjs writes beside the guard), marked where its Cell differs.
19
- // The receipts' newest `metrics` step, which the guard section quotes when there
20
- // is no guard, also feeds the evidence-favours side: a refit that step says
21
- // failed, with no fit written after it, is said in that side's heading.
17
+ // side the same for the Fit's table (`.fleet/router-fit.json`, which
18
+ // metrics-refresh.mjs writes beside the guard at phase 0), marked where its Cell
19
+ // differs. The installed table is the starting table: `route` with no `--table`
20
+ // routes by the Fit beside its `--guard`, and by the installed table only when
21
+ // that Fit is missing, unreadable or invalid, so routes now lays out the
22
+ // installed table, not always the one `route` routes by.
23
+ // The receipts' newest `metrics` step is what the guard section quotes when there
24
+ // is no guard; the newest one that tried a refit feeds the evidence-favours side:
25
+ // a refit that step says failed, with no fit written after it, is said in that
26
+ // side's heading.
22
27
  // Figures show only from a guard `readCostGuard` (fleet-tick.mjs, the reader
23
28
  // the tick judges the file by) accepts; `guard` here is that reader's own
24
29
  // answer, `{ status: "ok", guard }` or
@@ -35,11 +40,18 @@ import { costGuardFault } from "./fleet-tick.mjs";
35
40
  import { MIN_N, parseGuard, readGuard, rowDispatch } from "./ticket-router.mjs";
36
41
  import { implementerCell, modelsEqual, parseModelRoute, resolveRole } from "./tier-roles.mjs";
37
42
 
38
- // The implementer Cells, in the order the guard section draws them. All five are
39
- // drawn in every state: a card or a rescue can name any of them, and no link may
40
- // point at nothing. A Cell the guard holds beyond these is drawn after them
41
- // rather than left out.
42
- export const CELLS = Object.freeze(["slow-high", "task-high", "smol-high", "slow-medium", "task-max"]);
43
+ // The implementer Cells, in the order the guard section draws them: one per
44
+ // definition, every role × level from low to max. All of them are drawn in
45
+ // every state: a card or a rescue can name any of them, and no link may point
46
+ // at nothing. The five Cells that had definitions first keep their order; the
47
+ // rest follow by role (slow, task, smol), each role's levels low to max. A
48
+ // Cell the guard holds beyond these is drawn after them rather than left out.
49
+ export const CELLS = Object.freeze([
50
+ "slow-high", "task-high", "smol-high", "slow-medium", "task-max",
51
+ "slow-low", "slow-xhigh", "slow-max",
52
+ "task-low", "task-medium", "task-xhigh",
53
+ "smol-low", "smol-medium", "smol-xhigh", "smol-max",
54
+ ]);
43
55
 
44
56
  const MINUS = "−";
45
57
  const SUPERSCRIPT = "⁰¹²³⁴⁵⁶⁷⁸⁹";
@@ -112,19 +124,30 @@ function tierRoute(role, level, generation, modelRoles) {
112
124
 
113
125
  // ---------------------------------------------------------------------------
114
126
  // The newest `metrics` step of the phase 0 and close-out receipts: the guard
115
- // section quotes it when there is no guard, and evidence favours reads a failed refit off it.
127
+ // section quotes it when there is no guard. Evidence favours reads a failed
128
+ // refit off the newest one that tried a refit instead.
116
129
  // ---------------------------------------------------------------------------
117
130
 
118
131
  // `step` is `{ status, at, output }` or null. A step that has not run carries no
119
132
  // refresh to quote.
120
133
  const ran = (step) => step != null && step.status !== "pending" && Number.isFinite(Date.parse(step.at));
121
134
 
135
+ // The newest of `steps` by `at`; on equal times, the first. Null for none.
136
+ const newest = (steps) => (steps.length === 0 ? null : steps.reduce((a, b) => (Date.parse(b.at) > Date.parse(a.at) ? b : a)));
137
+
122
138
  // The newest `metrics` step of the two receipts that has run, by `at`; on equal
123
139
  // times, phase 0's. Null when neither receipt has run one.
124
140
  function newestStep(receipts) {
125
- const steps = [receipts?.phase0, receipts?.closeout].filter(ran);
126
- if (steps.length === 0) return null;
127
- return steps.reduce((a, b) => (Date.parse(b.at) > Date.parse(a.at) ? b : a));
141
+ return newest([receipts?.phase0, receipts?.closeout].filter(ran));
142
+ }
143
+
144
+ // The newest `metrics` step of the two receipts that tried a refit — its output
145
+ // carries a `metrics-refresh: fit:` line — picked as newestStep picks. A
146
+ // close-out's step, which runs with `--no-fit` and computes no Fit, and a step
147
+ // that stopped before its refit tried none, so neither hides an earlier
148
+ // failure. Null when neither receipt's step tried one.
149
+ function newestRefit(receipts) {
150
+ return newest([receipts?.phase0, receipts?.closeout].filter((s) => ran(s) && /metrics-refresh: fit: /.test(String(s.output ?? ""))));
128
151
  }
129
152
 
130
153
  // metrics-refresh's own line from a step's output: the cost-guard duty's, else
@@ -149,11 +172,11 @@ function newestRefresh(step) {
149
172
  return { verb, at: step.at, why };
150
173
  }
151
174
 
152
- // Why the Preview fit's refit failed, off a `metrics` step's output: the rest of
153
- // metrics-refresh's `preview: failed — ` line, trimmed, or null when the output
175
+ // Why the Fit failed, off a `metrics` step's output: the rest of
176
+ // metrics-refresh's `fit: failed — ` line, trimmed, or null when the output
154
177
  // has none. Found anywhere in a line, as refreshLine finds its own.
155
178
  export function refitFailure(output) {
156
- const m = /metrics-refresh: preview: failed — ([^\n]*)/.exec(String(output ?? ""));
179
+ const m = /metrics-refresh: fit: failed — ([^\n]*)/.exec(String(output ?? ""));
157
180
  return m === null ? null : m[1].trim();
158
181
  }
159
182
 
@@ -367,7 +390,7 @@ function booked(entry, pulls) {
367
390
  return out;
368
391
  }
369
392
 
370
- // The Cells drawn: the five, then any the guard holds or a card names beyond them.
393
+ // The Cells drawn: CELLS, then any the guard holds or a card names beyond them.
371
394
  const drawOrder = (held, pulls) => [...new Set([...CELLS, ...held, ...pulls.flatMap((p) => p.targets.map((t) => t.cell)).filter((c) => CELL.test(c))])];
372
395
 
373
396
  // `step` is the receipts' newest `metrics` step, newestStep's pick.
@@ -478,7 +501,7 @@ function routesSource(table, install, repoUrl) {
478
501
 
479
502
  // The Cells short of `MIN_N` merged PRs in the table's `guard.n`, in the table's
480
503
  // order, as one phrase: past tense for an installed table, whose counts are what
481
- // its fit saw ("had"), present for the Preview fit, whose counts are the
504
+ // its fit saw ("had"), present for the Fit, whose counts are the
482
505
  // workspace's own now ("has", "have").
483
506
  function shortWords(table, tense = "past") {
484
507
  const short = table.cells.filter((c) => (table.guard.n[c] ?? 0) < MIN_N).map((c) => [c, table.guard.n[c] ?? 0]);
@@ -542,7 +565,7 @@ function intervalWords(range, objective) {
542
565
  }
543
566
 
544
567
  // One row of a table under the guard — the installed table for routes now, the
545
- // Preview fit's for evidence favours: the Cell it routes to and why, its
568
+ // Fit's for evidence favours: the Cell it routes to and why, its
546
569
  // dispatch, and each candidate's n (null where the table carries no count),
547
570
  // verdict and interval.
548
571
  function rowEntry(table, guard, modelRoles, objective, stratum) {
@@ -613,22 +636,23 @@ function routesNow({ table, guard, modelRoles, install, repoUrl, checkout }) {
613
636
  }
614
637
 
615
638
  // ---------------------------------------------------------------------------
616
- // Policy rows: what the evidence favours — the Preview fit, `.fleet/router-preview.json`.
639
+ // Policy rows: what the evidence favours — the Fit, `.fleet/router-fit.json`.
617
640
  // ---------------------------------------------------------------------------
618
641
 
619
642
  const FAVOURS = "evidence favours";
620
643
 
621
- // The evidence-favours side with no Preview fit to lay out: its heading says
644
+ // The evidence-favours side with no Fit to lay out: its heading says
622
645
  // why, and its column is empty — nothing is unknown there, there is nothing to show.
623
646
  const noFit = (heading, labels = []) => ({
624
- title: FAVOURS, source: { text: "Preview fit", check: null }, heading, labels, footnotes: [], rows: null, unread: null,
647
+ title: FAVOURS, source: { text: "Fit", check: null }, heading, labels, footnotes: [], rows: null, unread: null,
625
648
  });
626
649
 
627
- // The newest refit failed: `step` is the receipts' newest `metrics` step, `p`
628
- // the Preview fit read, null when none was. Said while that step's output holds
629
- // the failed line and no fit was written after it — a `computed_at` before the
630
- // step's `at`, or one that is no time. A later step, a fit written after this
631
- // one, or the receipt no longer read clears it.
650
+ // The newest refit failed: `step` is the receipts' newest `metrics` step that
651
+ // tried a refit, newestRefit's pick, `p` the Fit read, null when none was. Said
652
+ // while that step's output holds the failed line and no fit was written after
653
+ // it — a `computed_at` before the step's `at`, or one that is no time. A later
654
+ // step that tried a refit, a fit written after this one, or the receipt no
655
+ // longer read clears it; a close-out step, which tries none, does not.
632
656
  function refitLabel(step, p) {
633
657
  if (step === null) return [];
634
658
  const why = refitFailure(step.output);
@@ -638,7 +662,7 @@ function refitLabel(step, p) {
638
662
  return [`the newest refit failed at ${when(step.at)}: ${why}`];
639
663
  }
640
664
 
641
- // The Preview fit's heading labels, against `raw`, the guard on disk, `routed`,
665
+ // The Fit's heading labels, against `raw`, the guard on disk, `routed`,
642
666
  // readGuard's answer for it, `table`, the installed one, and `records`, whether
643
667
  // the fit read the guard's files: fitted beside another guard, on other records,
644
668
  // or against another prior. The prior is
@@ -646,7 +670,7 @@ function refitLabel(step, p) {
646
670
  // `splits`, and `window_start` when the guard gives none — so a release that changes only
647
671
  // what the fit recomputes, or `fitted_commit` and `version`, raises nothing: the
648
672
  // next phase 0's refit would come out the same.
649
- function previewLabels(p, raw, routed, table, records) {
673
+ function fitLabels(p, raw, routed, table, records) {
650
674
  const labels = [];
651
675
  if (p.guard_computed_at !== raw.computed_at) labels.push(`fitted beside the guard of ${when(p.guard_computed_at)}, not this one`);
652
676
  if (records === null) labels.push("fitted on the guard's records: not checked: this guard predates the blob ids it needs");
@@ -678,19 +702,19 @@ function nDiffers(p, raw, records) {
678
702
  }).map((e) => e.cell);
679
703
  }
680
704
 
681
- // The evidence-favours side: the Preview fit's table laid out row by row under
705
+ // The evidence-favours side: the Fit's table laid out row by row under
682
706
  // the workspace's guard, as routes now lays out the installed one, each row's
683
- // Cell marked where it differs from the Cell routes now gives that row. `preview`
684
- // is gather's read, `{ status: "ok", preview } | { status: "missing" } | {
707
+ // Cell marked where it differs from the Cell routes now gives that row. `fit`
708
+ // is gather's read, `{ status: "ok", fit } | { status: "missing" } | {
685
709
  // status: "unreadable", why }`; `guard` readCostGuard's answer and `routed`
686
710
  // readGuard's for the same file, null when the router reads none; `step` the
687
- // receipts' newest `metrics` step, newestStep's pick; `mark` the footnote mark
711
+ // receipts' newest `metrics` step that tried a refit, newestRefit's pick; `mark` the footnote mark
688
712
  // its n footnote takes.
689
- function evidenceFavours({ preview, guard, routed, table, modelRoles, step, mark }) {
690
- if (routed === null) return noFit("no Preview fit: it is written only beside a cost guard");
691
- if (preview?.status === "unreadable") return noFit(`no Preview fit read: ${preview.why}`, refitLabel(step, null));
692
- if (preview?.status !== "ok") return noFit("no Preview fit yet: the next phase 0 writes one", refitLabel(step, null));
693
- const p = preview.preview;
713
+ function evidenceFavours({ fit: read, guard, routed, table, modelRoles, step, mark }) {
714
+ if (routed === null) return noFit("no Fit: it is written only beside a cost guard");
715
+ if (read?.status === "unreadable") return noFit(`no Fit read: ${read.why}`, refitLabel(step, null));
716
+ if (read?.status !== "ok") return noFit("no Fit yet: the next phase 0 writes one", refitLabel(step, null));
717
+ const p = read.fit;
694
718
  const fit = p.table;
695
719
  const raw = guard.guard;
696
720
  // Whether the fit read the guard's files: null when the guard names no blob
@@ -708,9 +732,9 @@ function evidenceFavours({ preview, guard, routed, table, modelRoles, step, mark
708
732
  };
709
733
  return {
710
734
  title: FAVOURS,
711
- source: { text: ["Preview fit", "this repository's runs", `computed ${when(p.computed_at)}`, plural(fit.n_rows, "Pull")].join(" · "), check: null },
735
+ source: { text: ["Fit", "this repository's runs", `computed ${when(p.computed_at)}`, plural(fit.n_rows, "Pull")].join(" · "), check: null },
712
736
  heading: fit.burn_in ? `stage ${fit.stage}: ${shortWords(fit, "present") ?? "every Cell has its merged PRs"}` : null,
713
- labels: [...refitLabel(step, p), ...previewLabels(p, raw, routed, table, records)],
737
+ labels: [...refitLabel(step, p), ...fitLabels(p, raw, routed, table, records)],
714
738
  footnotes: differ.length === 0 ? [] : [{ mark, text: `${list(differ)}: the guard counts merges by GitHub's state, the fit by Rulings, and the fit admits only drawn or rule-sized Pulls` }],
715
739
  rows: Object.fromEntries(OBJECTIVES.map((o) => [o,
716
740
  Object.fromEntries(Object.keys(fit.rows[o]).map((s) => [s, entry(o, s)])),
@@ -813,14 +837,18 @@ function prIsOpen(pr, openPrs) {
813
837
  return openPrs.capped === true ? null : false;
814
838
  }
815
839
 
816
- // The guard's and the Preview fit's TSV blob ids against main's. `alert` is the
840
+ // The guard's and the Fit's TSV blob ids against main's. `alert` is the
817
841
  // alert while the records are not on main, else null; `note`, in its place, is
818
842
  // a note under the guard section's heading: a check that could not run is never
819
843
  // an alert, so an offline cockpit raises none. `main` is the carried read of
820
844
  // `docs/metrics`, `{ value: { blobs }, readAt, error }`, `blobs` null for a 404.
821
845
  // A guard that names no blob ids has nothing to compare, and neither has one
822
- // whose cockpit read nothing (`main` null).
823
- function recordsAgainstMain({ read, preview, main, closeoutPr, openPrs }) {
846
+ // whose cockpit read nothing (`main` null). The Fit is compared only while it
847
+ // was fitted beside this guard: a guard written after it — a close-out's,
848
+ // which computes no Fit, or one whose refit failed — moves on alone, and
849
+ // evidence favours' heading already says the Fit was fitted beside another
850
+ // guard.
851
+ function recordsAgainstMain({ read, fit, main, closeoutPr, openPrs }) {
824
852
  const none = { alert: null, note: null };
825
853
  if (main == null || read?.status !== "ok") return none;
826
854
  const g = read.guard;
@@ -833,7 +861,7 @@ function recordsAgainstMain({ read, preview, main, closeoutPr, openPrs }) {
833
861
  if (blobs === null) return { alert: null, note: "records against main: main holds no metrics yet" };
834
862
  if (!isRecord(blobs)) return unchecked("main's docs/metrics not read yet");
835
863
 
836
- const mine = preview?.status === "ok" ? preview.preview : null;
864
+ const mine = fit?.status === "ok" && fit.fit.guard_computed_at === g.computed_at ? fit.fit : null;
837
865
  const held = (ids, path) => (isRecord(ids) && Object.hasOwn(ids, path) ? ids[path] : undefined);
838
866
  const paths = [...new Set([...Object.keys(g.tsv_blobs), ...(mine === null ? [] : Object.keys(mine.tsv_blobs))])].sort();
839
867
  const lines = [];
@@ -848,14 +876,14 @@ function recordsAgainstMain({ read, preview, main, closeoutPr, openPrs }) {
848
876
  if (!gd && !fd) continue;
849
877
  guardDiffers ||= gd;
850
878
  fitDiffers ||= fd;
851
- const said = [guardId === undefined ? null : fitId === guardId ? `the guard and the Preview fit read ${blob8(guardId)}` : `the guard read ${blob8(guardId)}`,
852
- fitId === undefined || fitId === guardId ? null : `the Preview fit read ${blob8(fitId)}`].filter(Boolean);
879
+ const said = [guardId === undefined ? null : fitId === guardId ? `the guard and the Fit read ${blob8(guardId)}` : `the guard read ${blob8(guardId)}`,
880
+ fitId === undefined || fitId === guardId ? null : `the Fit read ${blob8(fitId)}`].filter(Boolean);
853
881
  lines.push(`${path}: ${said.join(", ")}; main holds ${onMain === undefined ? "none" : blob8(onMain)}`);
854
882
  }
855
883
  if (lines.length === 0) return none;
856
884
 
857
885
  const both = guardDiffers && fitDiffers;
858
- const subject = both ? "the guard and the Preview fit" : guardDiffers ? "the guard" : "the Preview fit";
886
+ const subject = both ? "the guard and the Fit" : guardDiffers ? "the guard" : "the Fit";
859
887
  const pr = Number.isInteger(closeoutPr?.number) ? closeoutPr.number : null;
860
888
  const open = prIsOpen(pr, openPrs);
861
889
  const computed = guardDiffers ? g.computed_at : mine.computed_at;
@@ -869,7 +897,7 @@ function recordsAgainstMain({ read, preview, main, closeoutPr, openPrs }) {
869
897
  const committed = Date.parse(closeoutPr.at);
870
898
  if (!Number.isFinite(committed)) return unchecked(`the close-out receipt records no time for PR #${pr}'s commit step`);
871
899
  const built = Date.parse(computed);
872
- if (!Number.isFinite(built)) return unchecked(`the ${guardDiffers ? "guard" : "Preview fit"} records no time it was computed`);
900
+ if (!Number.isFinite(built)) return unchecked(`the ${guardDiffers ? "guard" : "Fit"} records no time it was computed`);
873
901
  sentence = built <= committed
874
902
  ? `${subject} ${both ? "count" : "counts"} the rows of open PR #${pr}, not on main yet`
875
903
  : `${subject} ${both ? "lack" : "lacks"} the rows of open PR #${pr}`;
@@ -921,20 +949,20 @@ function readersAlert(json) {
921
949
  * cellLine). `table` is the installed router table `validateTable` accepted or
922
950
  * null, `install` the install's `{ name, version, repository, error }`
923
951
  * (`repository` its url), `repoUrl` the workspace's, `objective` the live
924
- * run's Objective or null between runs, and `preview` the Preview fit as gather
925
- * read `.fleet/router-preview.json`: `{ status: "ok", preview: { computed_at,
952
+ * run's Objective or null between runs, and `fit` the Fit as gather
953
+ * read `.fleet/router-fit.json`: `{ status: "ok", fit: { computed_at,
926
954
  * guard_computed_at, tsv_blobs, prior, table } }`, `{ status: "missing" }` or
927
955
  * `{ status: "unreadable", why }`. An input left out reads as nothing
928
956
  * read: a missing guard, no receipt, no definitions, no `modelRoles` read, no
929
- * Pull, no table, no install, no Objective, no Preview fit.
957
+ * Pull, no table, no install, no Objective, no Fit.
930
958
  */
931
- export function computeCellEvidence({ guard, receipts, agents, modelRoles = null, pulls = [], table = null, install = null, repoUrl = null, objective = null, preview = null,
959
+ export function computeCellEvidence({ guard, receipts, agents, modelRoles = null, pulls = [], table = null, install = null, repoUrl = null, objective = null, fit = null,
932
960
  guardJson = null, mainMetrics = null, closeoutPr = null, openPrs = null, checkoutTable = null }) {
933
961
  const routed = guard?.status === "ok" ? readGuard(guard.guard) : null;
934
962
  const routes = routesNow({ table, guard: routed, modelRoles, install, repoUrl, checkout: checkoutTable });
935
963
  const step = newestStep(receipts);
936
- const favours = evidenceFavours({ preview, guard, routed, table, modelRoles, step, mark: superscript(routes.footnotes.length + 1) });
937
- const records = recordsAgainstMain({ read: guard, preview, main: mainMetrics, closeoutPr, openPrs });
964
+ const favours = evidenceFavours({ fit, guard, routed, table, modelRoles, step: newestRefit(receipts), mark: superscript(routes.footnotes.length + 1) });
965
+ const records = recordsAgainstMain({ read: guard, fit, main: mainMetrics, closeoutPr, openPrs });
938
966
  return {
939
967
  alerts: [records.alert, noRulingAlert(guard), readersAlert(guardJson)].filter((a) => a !== null),
940
968
  policy: policyRowsView({ sides: [routes, favours], objective }),
@@ -910,7 +910,9 @@ export const isRulePath = (x) => typeof x === "string" && RULE_PATH.test(x);
910
910
  // receipt, and every Routing names the one it routed by.
911
911
  export const OBJECTIVES = Object.freeze(["cost", "speed"]);
912
912
  const DRAWN_BY = Object.freeze(["burn-in", "every-5th"]);
913
- export const ROUTING_REASONS = Object.freeze(["ok", "no-issue-json", "no-sizing", "guard-missing", "guard-tripped", "table-cell-tripped"]);
913
+ export const ROUTING_REASONS = Object.freeze([
914
+ "ok", "no-issue-json", "no-sizing", "guard-missing", "guard-tripped", "table-cell-tripped", "fit-missing", "fit-unreadable", "fit-invalid",
915
+ ]);
914
916
  const SIZINGS = Object.freeze(["light", "heavy"]);
915
917
  const ROUTING_KEYS = Object.freeze(["POLICY", "CELL", "DRAW", "BY", "STRATUM", "BRIEF", "CRITERIA", "PARENT", "SIZED", "OBJECTIVE", "TRIPPED", "REASON"]);
916
918
  const PARENT_AT = ROUTING_KEYS.indexOf("PARENT");
@@ -2,13 +2,15 @@
2
2
  // The run's metrics duties that keep the router's inputs current: move the
3
3
  // pending ticket-features rows into the tracked corpus, widen a member-outcomes
4
4
  // corpus written before its latest columns, refresh the cost guard over it, then
5
- // write the Preview fit beside that guard.
5
+ // write the Fit beside that guard.
6
6
  //
7
- // metrics-refresh.mjs [--repo <dir>]
7
+ // metrics-refresh.mjs [--repo <dir>] [--no-fit]
8
8
  //
9
9
  // --repo the workspace whose `.fleet/` and `docs/metrics/` the duties read
10
10
  // and write; default the main checkout of the repository the cwd is
11
11
  // in, where the router script appends its pending rows
12
+ // --no-fit the duties only, no Fit: close-out passes it, so a run computes
13
+ // one Fit, at its phase 0, and each close-out's rows route the next run
12
14
  //
13
15
  // DRAIN. `ticket-router.mjs route` appends one row per Pull to
14
16
  // `.fleet/ticket-features.pending.tsv`; this moves them into
@@ -59,28 +61,34 @@
59
61
  // (no verdict yet — the baseline cell has too few merged PRs) are verdicts the
60
62
  // router and `fleet-tick.mjs` consume, not failures; any other non-zero exit is.
61
63
  //
62
- // PREVIEW FIT. After the cost guard wrote a guard, and only then, the Router's
63
- // fit (`ticket-router.mjs`'s fitTable) runs in-process over the working-tree
64
- // TSVs the guard just read and the guard just written, with the installed
65
- // router table (`router-table.json` beside the scripts) as its prior and no
66
- // commit. It writes `.fleet/router-preview.json` through a temp file and a
67
- // rename: `computed_at`, `guard_computed_at` (the guard's own `computed_at`),
68
- // `tsv_blobs` (the git blob id of each TSV it read, keyed by path as the guard
69
- // keys its own), `prior` (the installed table's `fitted_commit`, `stage`,
70
- // `cells`, `classifier`, `splits` and `window_start`, and the install's `package.json`
71
- // `version`) and the fitted `table`. The cockpit lays it out as what the
72
- // evidence favours; nothing routes by it and nothing commits it. It is called
73
- // in-process because a fit has no verdict for an exit status to carry, and the
74
- // `fit` CLI reads the TSVs only as committed. It never fails the run: an error
75
- // prints `metrics-refresh: preview: failed — <why>`, leaves the old file in
76
- // place and leaves the exit status as the other duties set it. That line stays
77
- // on stdout: the cockpit reads it off the receipts' `metrics` step, and
78
- // close-out's receipt keeps only stdout from a run that exits 0.
64
+ // FIT. After the cost guard wrote a guard, and only then, the Router's fit
65
+ // (`ticket-router.mjs`'s fitTable) runs in-process over the working-tree TSVs
66
+ // the guard just read and the guard just written, with the starting table
67
+ // (`router-table.json` beside the scripts) as its prior and no commit. It
68
+ // writes the Fit, `.fleet/router-fit.json`, through a temp file and a rename:
69
+ // `computed_at`, `guard_computed_at` (the guard's own `computed_at`),
70
+ // `guard` (the guard it used, as the router reads it: its `computed_at`,
71
+ // `tripped`, per-Cell `n` and `window_start`), `tsv_blobs` (the git blob id of
72
+ // each TSV it read, keyed by path as the guard keys its own), `prior` (the
73
+ // starting table's `fitted_commit`, `stage`, `cells`, `classifier`, `splits`
74
+ // and `window_start`, and the install's `package.json` `version`) and the
75
+ // fitted `table`. `ticket-router.mjs route` routes by that `table`, read
76
+ // beside the guard; nothing commits the file. The Fit is a pure function of
77
+ // those records: the TSVs at the recorded blob ids, the guard and the prior
78
+ // fit to the same table again. With no records it is the starting table's
79
+ // fit, as any other. It is called in-process because a fit has no verdict
80
+ // for an exit status to carry, and the `fit` CLI reads the TSVs only as
81
+ // committed. It never fails the run: an error prints `metrics-refresh: fit:
82
+ // failed — <why>`, leaves the old file in place, so the run routes by the
83
+ // last Fit that computed, and leaves the exit status as the other duties set
84
+ // it. That line stays on stdout: the cockpit reads it off the receipts'
85
+ // `metrics` step, and close-out's receipt keeps only stdout from a run that
86
+ // exits 0.
79
87
  //
80
88
  // One `metrics-refresh: <duty>: …` line per duty on stdout. Exit 0 when no
81
89
  // duty failed; 1 when one failed — named on stderr, and the duties after
82
90
  // it did not run (each is safe to run again); 2 on a usage error. The
83
- // Preview fit is not one of those duties: it never sets the exit status.
91
+ // Fit is not one of those duties: it never sets the exit status.
84
92
 
85
93
  import { spawnSync } from "node:child_process";
86
94
  import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
@@ -94,7 +102,7 @@ import { COLUMNS as MEMBER_COLUMNS, ENDINGS, isImplementer, parseTsv as parseMem
94
102
  import { blobId } from "./pr-cost.mjs";
95
103
  import { FEATURE_COLUMNS, parseFeatures } from "./pull-attribution.mjs";
96
104
  import { REPORT_STATUSES } from "./report-files.mjs";
97
- import { DEFAULT_TABLE, INSTALL_PACKAGE, fitTable, installVersion, readGuard, validateTable } from "./ticket-router.mjs";
105
+ import { DEFAULT_TABLE, FIT_FILE, INSTALL_PACKAGE, fitTable, installVersion, readGuard, validateTable } from "./ticket-router.mjs";
98
106
  import { parseTierOutcomes } from "./tier-outcomes.mjs";
99
107
 
100
108
  const NAME = "metrics-refresh";
@@ -105,7 +113,7 @@ const MEMBERS = join("docs", "metrics", "member-outcomes.tsv");
105
113
  const TIERS = join("docs", "metrics", "tier-outcomes.tsv");
106
114
  const CORPUS = [MEMBERS, TIERS, FEATURES];
107
115
  const GUARD = join(".fleet", "cost-guard.json");
108
- const PREVIEW = join(".fleet", "router-preview.json");
116
+ const FIT = join(".fleet", FIT_FILE);
109
117
  // pr-cost.mjs --guard: 0 no cell tripped, 3 a cell tripped, 4 no verdict yet —
110
118
  // all three are verdicts its readers consume; anything else is a failure.
111
119
  const GUARD_VERDICT_EXITS = new Set([0, 3, 4]);
@@ -276,19 +284,19 @@ function costGuard(repo) {
276
284
  return g;
277
285
  }
278
286
 
279
- // The Preview fit over `repo`'s working-tree TSVs and `written`, the guard file the
287
+ // The Fit over `repo`'s working-tree TSVs and `written`, the guard file the
280
288
  // guard duty just wrote (parsed), with the router table at `tablePath` as its
281
- // prior, written to `.fleet/router-preview.json` through a temp file and a
282
- // rename. Throws on anything it cannot read, fit or write, before the rename, so
283
- // the old file stays as it was.
284
- export function writePreview(repo, written, { tablePath = DEFAULT_TABLE, packagePath = INSTALL_PACKAGE, now = new Date() } = {}) {
289
+ // prior, written to `.fleet/router-fit.json` through a temp file and a rename.
290
+ // Throws on anything it cannot read, fit or write, before the rename, so the
291
+ // old file stays as it was.
292
+ export function writeFit(repo, written, { tablePath = DEFAULT_TABLE, packagePath = INSTALL_PACKAGE, now = new Date() } = {}) {
285
293
  const guard = readGuard(written);
286
294
  if (guard === null) throw new Error(`${GUARD} is not a guard the router reads`);
287
295
  let prior;
288
296
  try {
289
297
  prior = validateTable(JSON.parse(readFileSync(tablePath, "utf8")));
290
298
  } catch (e) {
291
- throw new Error(`cannot read the installed router table ${tablePath}: ${e.code ?? e.message}`);
299
+ throw new Error(`cannot read the starting router table ${tablePath}: ${e.code ?? e.message}`);
292
300
  }
293
301
  if (prior instanceof Error) throw new Error(`${tablePath}: ${prior.message}`);
294
302
  // Keyed by the path as the guard keys its own (pr-cost.mjs reads these, relative to the workspace).
@@ -302,9 +310,10 @@ export function writePreview(repo, written, { tablePath = DEFAULT_TABLE, package
302
310
  const verdicts = read(TIERS, parseTierOutcomes);
303
311
  const features = read(FEATURES, parseFeatures);
304
312
  const table = fitTable({ prior, features, members, verdicts, guard, commit: null });
305
- const preview = {
313
+ const record = {
306
314
  computed_at: now.toISOString(),
307
315
  guard_computed_at: written.computed_at,
316
+ guard: { computed_at: written.computed_at, tripped: guard.tripped, n: guard.n, window_start: guard.window_start },
308
317
  tsv_blobs: Object.fromEntries(Object.entries(tsvBlobs).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
309
318
  prior: {
310
319
  fitted_commit: prior.fitted_commit,
@@ -317,28 +326,28 @@ export function writePreview(repo, written, { tablePath = DEFAULT_TABLE, package
317
326
  },
318
327
  table,
319
328
  };
320
- const file = join(repo, PREVIEW);
321
- writeFileSync(`${file}.tmp`, `${JSON.stringify(preview, null, 2)}\n`);
329
+ const file = join(repo, FIT);
330
+ writeFileSync(`${file}.tmp`, `${JSON.stringify(record, null, 2)}\n`);
322
331
  renameSync(`${file}.tmp`, file);
323
- return preview;
332
+ return record;
324
333
  }
325
334
 
326
- // The Preview fit as the run calls it: only beside a guard the guard duty wrote, and
335
+ // The Fit as the run calls it: only beside a guard the guard duty wrote, and
327
336
  // never a failure of the run — its error is a line, and the exit stays as it was.
328
- function preview(repo, written) {
329
- if (written === null) return say(`preview: skipped, no guard written — ${PREVIEW} left as it is`);
337
+ function fit(repo, written) {
338
+ if (written === null) return say(`fit: skipped, no guard written — ${FIT} left as it is`);
330
339
  let p;
331
340
  try {
332
- p = writePreview(repo, written);
341
+ p = writeFit(repo, written);
333
342
  } catch (e) {
334
- return say(`preview: failed — ${e.message}`);
343
+ return say(`fit: failed — ${e.message}`);
335
344
  }
336
- say(`preview: fitted ${p.table.n_rows} Pull${p.table.n_rows === 1 ? "" : "s"}, stage ${p.table.stage}${p.table.burn_in ? ", in burn-in" : ""}; ${PREVIEW} computed ${p.computed_at}`);
345
+ say(`fit: fitted ${p.table.n_rows} Pull${p.table.n_rows === 1 ? "" : "s"}, stage ${p.table.stage}${p.table.burn_in ? ", in burn-in" : ""}; ${FIT} computed ${p.computed_at}`);
337
346
  }
338
347
 
339
348
  function main() {
340
349
  const die = makeDie(NAME);
341
- const F = defineFlags(die, { flags: { repo: "value" } });
350
+ const F = defineFlags(die, { flags: { repo: "value", "no-fit": "bool" } });
342
351
  F.sweep();
343
352
  F.stray();
344
353
  let repo = F.arg("repo") === null ? null : resolve(F.arg("repo"));
@@ -361,7 +370,7 @@ function main() {
361
370
  return;
362
371
  }
363
372
  }
364
- preview(repo, written);
373
+ if (!F.has("no-fit")) fit(repo, written);
365
374
  }
366
375
 
367
376
  if (isCLI(import.meta.url)) main();
@@ -16,6 +16,12 @@
16
16
  // routing by the objective's row set, and appends the Pull's
17
17
  // ticket-features row to the pending TSV (by default
18
18
  // `ticket-features.pending.tsv` beside `--guard`, in the run's `.fleet/`).
19
+ // With no `--table` it routes by the Fit, `router-fit.json` beside
20
+ // `--guard`, which metrics-refresh.mjs writes at phase 0. A Fit that is
21
+ // absent, unreadable, unparseable or fails validateTable routes by the
22
+ // starting table beside the script instead, and `REASON` names why:
23
+ // `fit-missing`, `fit-unreadable` or `fit-invalid`. A missing guard routes
24
+ // the default cell whatever the table, so it names no Fit there.
19
25
  // The paths its brief names are looked up under the working directory,
20
26
  // the checkout, for `named_lines`. Exit 0 on every data degradation — a
21
27
  // missing or unreadable issue, sizing or guard file degrades the line,
@@ -430,6 +436,27 @@ export function readGuard(raw) {
430
436
  return r.ok ? r.guard : null;
431
437
  }
432
438
 
439
+ /** The Fit's file name: metrics-refresh.mjs writes it beside the cost guard, and `route` reads it there. */
440
+ export const FIT_FILE = "router-fit.json";
441
+
442
+ /**
443
+ * The table the Fit beside `guardPath` holds, `{ table, fallback: null }`, or `{ table: null, fallback }` when
444
+ * there is none to route by: `fallback` is the Routing `REASON` that names why — `fit-missing` for no file,
445
+ * `fit-unreadable` for one that will not read or parse, `fit-invalid` for one whose `table` validateTable refuses.
446
+ */
447
+ export function readFitBeside(guardPath) {
448
+ let text;
449
+ try {
450
+ text = readFileSync(join(dirname(guardPath), FIT_FILE), "utf8");
451
+ } catch (e) {
452
+ return { table: null, fallback: e.code === "ENOENT" ? "fit-missing" : "fit-unreadable" };
453
+ }
454
+ let fit;
455
+ try { fit = JSON.parse(text); } catch { return { table: null, fallback: "fit-unreadable" }; }
456
+ const table = validateTable(fit?.table);
457
+ return table instanceof Error ? { table: null, fallback: "fit-invalid" } : { table, fallback: null };
458
+ }
459
+
433
460
  /** The sizing verdict on a live B Pull: `{ src, label, usd }`, or null when it is unusable. */
434
461
  function readSizing(raw, classifier) {
435
462
  if (raw === null || typeof raw !== "object" || raw.source !== classifier.b) return null;
@@ -456,15 +483,18 @@ export function sessionDate(session) {
456
483
  * it leaves out the cell the `cost` set routes the group to, whichever set
457
484
  * routes the Pull, so a Pull draws the same cell under both. A live B Pull
458
485
  * records its sizing verdict and routes as an A Pull does: a label names no
459
- * group of the tree.
486
+ * group of the tree. `fallback` is readFitBeside's REASON when `table` is the
487
+ * starting table standing in for a Fit, else null: it is the first thing that
488
+ * went wrong, except beside no guard, where the table routes nothing.
460
489
  * @returns {{ line: string, row: Record<string,string> }}
461
490
  */
462
491
  export function route({
463
492
  session, ticket, arm, implRow, chainHead = false, issue, sizing = null, guard, table, objective, now = Date.now(),
464
- root = process.cwd(), version = installVersion(),
493
+ root = process.cwd(), version = installVersion(), fallback = null,
465
494
  }) {
466
495
  let reason = null;
467
496
  const degrade = (r) => { reason ??= r; };
497
+ if (fallback !== null && guard !== null) degrade(fallback);
468
498
 
469
499
  const metrics = issueMetrics(issue, now);
470
500
  if (metrics === null) degrade("no-issue-json");
@@ -898,11 +928,15 @@ function main() {
898
928
  if (foreign) die(`--${foreign} does not apply to ${mode === "check" ? "--check" : mode}`);
899
929
  const need = (name) => F.arg(name) ?? die(`${mode === "check" ? "--check" : mode} needs --${name}`);
900
930
 
931
+ // `route` with no `--table` routes by the Fit beside `--guard`, else by the starting table.
932
+ const fit = mode === "route" && F.arg("table") === null && F.arg("guard") !== null ? readFitBeside(F.arg("guard")) : null;
901
933
  const tablePath = mode === "route" ? (F.arg("table") ?? DEFAULT_TABLE) : need("table");
902
- let table;
903
- try { table = JSON.parse(readFileSync(tablePath, "utf8")); } catch (e) { die(`cannot read the router table ${tablePath}: ${e.message}`); }
904
- const valid = validateTable(table);
905
- if (valid instanceof Error) die(`${tablePath}: ${valid.message}`);
934
+ let table = fit?.table ?? null;
935
+ if (table === null) {
936
+ try { table = JSON.parse(readFileSync(tablePath, "utf8")); } catch (e) { die(`cannot read the router table ${tablePath}: ${e.message}`); }
937
+ const valid = validateTable(table);
938
+ if (valid instanceof Error) die(`${tablePath}: ${valid.message}`);
939
+ }
906
940
 
907
941
  if (mode === "route") {
908
942
  const ticket = need("ticket");
@@ -938,6 +972,7 @@ function main() {
938
972
  const { line, row } = route({
939
973
  session, ticket: Number(ticket), arm, implRow: Number(implRowArg), chainHead: F.has("chain-head"),
940
974
  issue: readJson(issuePath), sizing: readJson(F.arg("sizing")), guard: readGuard(readJson(guardPath)), table, objective, root, version,
975
+ fallback: fit?.fallback ?? null,
941
976
  });
942
977
  const pending = F.arg("pending") ?? join(dirname(guardPath), "ticket-features.pending.tsv");
943
978
  // The header decision and the append are not atomic and take no lock. That is
@@ -104,7 +104,7 @@ issue number among the reasons — comes before that PR's WARNING and says why.
104
104
 
105
105
  **Drain the pending ticket-features rows and refresh the cost guard, after
106
106
  the member-outcomes scrape and every `tier-outcomes.mjs append`, before the
107
- metrics files are committed.** `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run metrics-refresh.mjs`
107
+ metrics files are committed.** `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run metrics-refresh.mjs --no-fit`
108
108
  moves `.fleet/ticket-features.pending.tsv` — the row the router script
109
109
  appended for each Pull at dispatch — into `docs/metrics/ticket-features.tsv`,
110
110
  deduped on `session`+`agent`, so this run's own rows are in the file that gets
@@ -112,10 +112,9 @@ committed; that file is a run artifact too and is committed with the other
112
112
  two. It then widens a `docs/metrics/member-outcomes.tsv` written before the
113
113
  newest columns, as at phase 0 — a file already at the current width is left
114
114
  as it is — and then runs `pr-cost.mjs --guard`, which rewrites
115
- `.fleet/cost-guard.json` from all three files. After a guard it wrote it writes
116
- the Preview fit, `.fleet/router-preview.json`, for the cockpit alone: it is not
117
- a metrics file and is never committed, and its `preview: failed — <why>` line
118
- leaves the exit as it was. Exit 0: every duty ran. The guard's
115
+ `.fleet/cost-guard.json` from all three files. `--no-fit` computes no Fit:
116
+ one Fit per run, at phase 0, so the rows this close-out commits route the
117
+ next run, and `.fleet/router-fit.json` is left as it is. Exit 0: every duty ran. The guard's
119
118
  own exit 3 (a cell tripped) and 4 (no verdict yet, baseline too thin) are
120
119
  verdicts the router and `fleet-tick.mjs` read, never failures; the script
121
120
  absorbs them. Exit 1 names the duty that failed on stderr and the duties after it