@feigi/fleet-ctl 3.125.1 → 3.126.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.125.1",
3
+ "version": "3.126.0",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -819,6 +819,35 @@ export function readGuardFile(stateDir) {
819
819
  return readCostGuard(join(stateDir, "cost-guard.json"));
820
820
  }
821
821
 
822
+ // The Preview fit metrics-refresh.mjs writes beside the guard,
823
+ // `.fleet/router-preview.json`: `{ status: "ok", preview }`, `{ status: "missing" }`
824
+ // or `{ status: "unreadable", why }`. Its `table` is read through `validateTable`,
825
+ // as the installed one is, and its `n_rows`, which `validateTable` does not check
826
+ // and the tab prints, must be a count; `computed_at` and `guard_computed_at` must
827
+ // be strings, and `tsv_blobs` and `prior` objects, their values checked where the
828
+ // tab reads them.
829
+ export function readPreviewFile(stateDir) {
830
+ let text;
831
+ try {
832
+ text = readFileSync(join(stateDir, "router-preview.json"), "utf8");
833
+ } catch (e) {
834
+ return e.code === "ENOENT" ? { status: "missing" } : { status: "unreadable", why: e.code ?? e.message };
835
+ }
836
+ let p;
837
+ try { p = JSON.parse(text); } catch { return { status: "unreadable", why: "not JSON" }; }
838
+ if (!isJsonObject(p)) return { status: "unreadable", why: "not a JSON object" };
839
+ for (const key of ["computed_at", "guard_computed_at"]) {
840
+ if (typeof p[key] !== "string") return { status: "unreadable", why: `\`${key}\` is not a string` };
841
+ }
842
+ for (const key of ["tsv_blobs", "prior"]) {
843
+ if (!isJsonObject(p[key])) return { status: "unreadable", why: `\`${key}\` is not an object` };
844
+ }
845
+ const table = validateTable(p.table);
846
+ if (table instanceof Error) return { status: "unreadable", why: table.message };
847
+ if (!Number.isInteger(table.n_rows) || table.n_rows < 0) return { status: "unreadable", why: "router table: `n_rows` is not a count" };
848
+ return { status: "ok", preview: { computed_at: p.computed_at, guard_computed_at: p.guard_computed_at, tsv_blobs: p.tsv_blobs, prior: p.prior, table } };
849
+ }
850
+
822
851
  // A receipt's `metrics` step, `{ status, at, output }`, or null: no receipt, one
823
852
  // that will not read, or one with no such step. Both receipts, `phase0.json` and
824
853
  // `closeout.json`, carry `steps: { <name>: { status, at, output } }` and nothing
@@ -1211,6 +1240,7 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, stateDir
1211
1240
  // no workspace, so it reads none of the workspace's records and spawns no `omp`
1212
1241
  // either (a guard that reads as missing, no receipts, the read carried as it was).
1213
1242
  const guard = stateDir === null ? { status: "missing" } : readGuardFile(stateDir);
1243
+ const preview = stateDir === null ? { status: "missing" } : readPreviewFile(stateDir);
1214
1244
  const receipts = stateDir === null
1215
1245
  ? { phase0: null, closeout: null }
1216
1246
  : { phase0: readMetricsStep(join(stateDir, RECEIPT)), closeout: readMetricsStep(join(stateDir, CLOSEOUT_RECEIPT)) };
@@ -1220,6 +1250,6 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, stateDir
1220
1250
  const modelRoles = stateDir === null ? heldRead(prev?.modelRoles) : await carryModelRoles(prev?.modelRoles, now);
1221
1251
  return { ledger, issues, prs, merged, closed, closedIssues, ci, prev, repo, repoUrl, workspace, port, spend, beat, ticked, acted, controller, stallOwner: stallOwnerOf, poolOk,
1222
1252
  roles, labelMapError,
1223
- poolCapped, prsCapped, guard, receipts, agents, modelRoles, install, objective, implementers: [...implementers.values()], routerTable,
1253
+ poolCapped, prsCapped, guard, preview, receipts, agents, modelRoles, install, objective, implementers: [...implementers.values()], routerTable,
1224
1254
  now, interval };
1225
1255
  }
@@ -455,25 +455,29 @@ function ceEntry(e) {
455
455
  }
456
456
 
457
457
  // One side's heading on the policy rows: its title, source line, the check it
458
- // could not make, its burn-in or no-guard heading, its shared dispatch and its
459
- // model-name line, where each is set.
458
+ // could not make, its burn-in or no-guard heading, its trust labels, its shared
459
+ // dispatch and its model-name line, where each is set.
460
460
  function cePolicySide(s) {
461
461
  const box = el("div", "ce-side");
462
462
  box.append(el("div", "ce-verdict", s.title), el("div", "ce-source", s.source.text));
463
463
  if (s.source.check) box.append(el("div", "ce-note", s.source.check));
464
464
  if (s.heading) box.append(el("div", "ce-note", s.heading));
465
+ for (const label of s.labels || []) box.append(el("div", "ce-note ce-amber", label));
465
466
  if (s.dispatch) box.append(el("div", "ce-note", "dispatch: " + s.dispatch));
466
467
  if (s.modelLine) box.append(el("div", "ce-note ce-amber", s.modelLine));
467
468
  return box;
468
469
  }
469
470
 
470
- // One side's cell of a row: the Cell it routes to and why, its own dispatch where
471
- // it differs from the side's, and each candidate's n, verdict and interval.
471
+ // One side's cell of a row: the Cell it routes to and why, where it differs
472
+ // from routes now, its own dispatch where it differs from the side's, and each
473
+ // candidate's n, verdict and interval. A side with nothing to show leaves it empty.
472
474
  function cePolicyCell(s, href) {
473
475
  const box = el("div", "ce-polcell");
476
+ if (s.empty) return box;
474
477
  if (s.unread || s.follows) { box.append(el("span", "ce-dim", s.unread || s.follows)); return box; }
475
478
  const hd = el("div", "ce-hd");
476
479
  hd.append(el("span", "ce-cell", s.cell));
480
+ if (s.differs) hd.append(el("span", "ce-amber", s.differs));
477
481
  const reason = el("a", "ce-dim", s.reason);
478
482
  reason.href = href;
479
483
  hd.append(reason);
@@ -481,7 +485,7 @@ function cePolicyCell(s, href) {
481
485
  box.append(hd);
482
486
  if (s.dispatch) box.append(el("div", "ce-note", "dispatch: " + s.dispatch));
483
487
  for (const c of s.candidates) {
484
- const line = el("div", "ce-cand", `${c.cell} · n ${c.n ?? "not checked"} · ${c.verdict} · ${c.interval}`);
488
+ const line = el("div", "ce-cand", `${c.cell} · n ${c.n ?? "not checked"}${c.nMark || ""} · ${c.verdict} · ${c.interval}`);
485
489
  if (c.model && c.model.text) line.append(el("span", "ce-amber", " · " + c.model.text));
486
490
  box.append(line);
487
491
  }
@@ -863,6 +863,7 @@ export function computeBoard(inputs) {
863
863
  // computeCellEvidence reads an input left out as nothing read.
864
864
  cellEvidence: computeCellEvidence({
865
865
  guard: inputs.guard,
866
+ preview: inputs.preview,
866
867
  receipts: inputs.receipts,
867
868
  agents: inputs.agents,
868
869
  modelRoles: inputs.modelRoles,
@@ -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) into the model the page lays out.
4
+ // read, the Preview 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
@@ -10,12 +10,15 @@
10
10
  // What this holds is the guard section — what the cost guard holds each
11
11
  // implementer Cell to, from the guard file and nothing recomputed, with this
12
12
  // run's Pulls booked to each Cell off the board's cards — "Declared, not
13
- // measured", and the policy rows' routes-now side: for each Objective × Stratum
14
- // row, the Cell the installed router table plus the workspace's guard route to,
15
- // why, and how a Pull on that row is dispatched (ticket-router.mjs's
16
- // rowDispatch, the function `route` itself calls). Figures show only from a
17
- // guard `readCostGuard` (fleet-tick.mjs, the reader the tick judges the file by)
18
- // accepts; `guard` here is that reader's own answer, `{ status: "ok", guard }` or
13
+ // measured", and the policy rows: for each Objective × Stratum row, on the
14
+ // routes-now side the Cell the installed router table plus the workspace's guard
15
+ // route to, why, and how a Pull on that row is dispatched (ticket-router.mjs's
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
+ // Figures show only from a guard `readCostGuard` (fleet-tick.mjs, the reader
20
+ // the tick judges the file by) accepts; `guard` here is that reader's own
21
+ // answer, `{ status: "ok", guard }` or
19
22
  // `{ status: "missing" | "unreadable" }`.
20
23
  //
21
24
  // A figure the guard file lacks reads "not checked", never 0: the file written
@@ -23,6 +26,7 @@
23
26
  // and `untimed` per Cell, and each count the file does not carry is named as not
24
27
  // checked where its figure would show.
25
28
 
29
+ import { isDeepStrictEqual } from "node:util";
26
30
  import { CELL, OBJECTIVES, POLICY_CELL, STRATA } from "./ledger-grammar.mjs";
27
31
  import { MIN_N, readGuard, rowDispatch } from "./ticket-router.mjs";
28
32
  import { implementerCell, modelsEqual, parseModelRoute, resolveRole } from "./tier-roles.mjs";
@@ -451,15 +455,21 @@ function routesSource(table, install, repoUrl) {
451
455
  return { same, owner: named === null ? "another repository" : named.name, runs, text: [runs, fitted, installed].join(" · "), check };
452
456
  }
453
457
 
454
- // The Cells short of `MIN_N` merged PRs at the fit, in the table's order, as one
455
- // past-tense phrase: the counts are what the fit saw.
456
- function shortWords(table) {
458
+ // The Cells short of `MIN_N` merged PRs in the table's `guard.n`, in the table's
459
+ // order, as one phrase: past tense for an installed table, whose counts are what
460
+ // its fit saw ("had"), present for the Preview fit, whose counts are the
461
+ // workspace's own now ("has", "have").
462
+ function shortWords(table, tense = "past") {
457
463
  const short = table.cells.filter((c) => (table.guard.n[c] ?? 0) < MIN_N).map((c) => [c, table.guard.n[c] ?? 0]);
458
464
  if (short.length === 0) return null;
459
465
  const each = short.length === 1 ? "it needs" : "each needs";
466
+ const one = tense === "past" ? "had" : "has";
460
467
  const counts = new Set(short.map(([, n]) => n));
461
- if (counts.size === 1) return `${list(short.map(([c]) => c))} had ${short[0][1]} of the ${MIN_N} merged PRs ${each}`;
462
- return `${list(short.map(([c, n]) => `${c} had ${n}`))} of the ${MIN_N} merged PRs ${each}`;
468
+ if (counts.size === 1) {
469
+ const verb = tense === "past" ? "had" : short.length === 1 ? "has" : "have";
470
+ return `${list(short.map(([c]) => c))} ${verb} ${short[0][1]} of the ${MIN_N} merged PRs ${each}`;
471
+ }
472
+ return `${list(short.map(([c, n]) => `${c} ${one} ${n}`))} of the ${MIN_N} merged PRs ${each}`;
463
473
  }
464
474
 
465
475
  // The side's burn-in or no-guard heading, or null while neither holds. Past tense
@@ -510,10 +520,11 @@ function intervalWords(range, objective) {
510
520
  return `95% interval [${one(range[0])}, ${one(range[1])}]`;
511
521
  }
512
522
 
513
- // One row of the installed table under the guard: the Cell it routes to and why,
514
- // its dispatch, and each candidate's n (null where the table carries no count),
523
+ // One row of a table under the guard — the installed table for routes now, the
524
+ // Preview fit's for evidence favours: the Cell it routes to and why, its
525
+ // dispatch, and each candidate's n (null where the table carries no count),
515
526
  // verdict and interval.
516
- function routesEntry(table, guard, modelRoles, objective, stratum) {
527
+ function rowEntry(table, guard, modelRoles, objective, stratum) {
517
528
  const rd = rowDispatch({ table, guard, objective, stratum });
518
529
  const row = table.rows[objective][stratum];
519
530
  const record = isRecord(table.reasons?.[objective]?.[stratum]) ? table.reasons[objective][stratum] : null;
@@ -537,7 +548,8 @@ function routesEntry(table, guard, modelRoles, objective, stratum) {
537
548
 
538
549
  // The routes-now side of the policy rows: its heading words and every row the
539
550
  // installed table holds, `rows[objective][stratum]` — `*` and each Stratum with a
540
- // row of its own. `rows` is null when no table could be read.
551
+ // row of its own. `rows` is null when no table could be read, and each of its
552
+ // rows then reads `unread`.
541
553
  function routesNow({ table, guard, modelRoles, install, repoUrl }) {
542
554
  const source = routesSource(table, install, repoUrl);
543
555
  const foot = source.same ? [] : [{ mark: "¹", text: "this repository's runs reach routing only through its cost guard, which can hold a Cell back but never picks one" }];
@@ -545,10 +557,104 @@ function routesNow({ table, guard, modelRoles, install, repoUrl }) {
545
557
  title: "routes now",
546
558
  source: { text: source.text + (foot.length ? " ¹" : ""), check: source.check },
547
559
  heading: routesHeading(table, guard, source),
560
+ labels: [],
548
561
  footnotes: foot,
549
562
  rows: table === null ? null : Object.fromEntries(OBJECTIVES.map((o) => [o,
550
- Object.fromEntries(["*", ...STRATA].filter((s) => Object.hasOwn(table.rows[o], s)).map((s) => [s, routesEntry(table, guard, modelRoles, o, s)])),
563
+ Object.fromEntries(["*", ...STRATA].filter((s) => Object.hasOwn(table.rows[o], s)).map((s) => [s, rowEntry(table, guard, modelRoles, o, s)])),
551
564
  ])),
565
+ unread: "router table not read",
566
+ };
567
+ }
568
+
569
+ // ---------------------------------------------------------------------------
570
+ // Policy rows: what the evidence favours — the Preview fit, `.fleet/router-preview.json`.
571
+ // ---------------------------------------------------------------------------
572
+
573
+ const FAVOURS = "evidence favours";
574
+
575
+ // The evidence-favours side with no Preview fit to lay out: its heading says
576
+ // why, and its column is empty — nothing is unknown there, there is nothing to show.
577
+ const noFit = (heading) => ({
578
+ title: FAVOURS, source: { text: "Preview fit", check: null }, heading, labels: [], footnotes: [], rows: null, unread: null,
579
+ });
580
+
581
+ // The Preview fit's heading labels, against `raw`, the guard on disk, `routed`,
582
+ // readGuard's answer for it, `table`, the installed one, and `records`, whether
583
+ // the fit read the guard's files: fitted beside another guard, on other records,
584
+ // or against another prior. The prior is
585
+ // compared only on what the fit takes from it — `stage`, `cells`, `classifier`,
586
+ // and `window_start` when the guard gives none — so a release that changes only
587
+ // what the fit recomputes, or `fitted_commit` and `version`, raises nothing: the
588
+ // next phase 0's refit would come out the same.
589
+ function previewLabels(p, raw, routed, table, records) {
590
+ const labels = [];
591
+ if (p.guard_computed_at !== raw.computed_at) labels.push(`fitted beside the guard of ${when(p.guard_computed_at)}, not this one`);
592
+ if (records === null) labels.push("fitted on the guard's records: not checked: this guard predates the blob ids it needs");
593
+ else if (!records) labels.push("fitted on other records than the guard's");
594
+ if (table === null) {
595
+ labels.push("fitted against the installed table: not checked: no router table read");
596
+ return labels;
597
+ }
598
+ const read = ["stage", "cells", "classifier", ...(routed.window_start === null ? ["window_start"] : [])];
599
+ const prior = isRecord(p.prior) ? p.prior : {};
600
+ if (read.some((k) => !isDeepStrictEqual(prior[k], table[k]))) {
601
+ const version = prior.version === "0.0.0" ? "linked checkout" : (typeof prior.version === "string" ? prior.version : "no version");
602
+ const fitted = typeof prior.fitted_commit === "string" && prior.fitted_commit !== "" ? `fitted at ${prior.fitted_commit.slice(0, 7)}` : "never fitted";
603
+ labels.push(`fitted against ${version} · ${fitted}; the next phase 0 refits`);
604
+ }
605
+ return labels;
606
+ }
607
+
608
+ // The Cells whose newest generation's merged n the guard and the fit count
609
+ // differently although both read the same files, `records` true: the guard
610
+ // counts merges by GitHub's state, the fit by Rulings. Files the guard names no
611
+ // blob ids for, or other files, compare nothing.
612
+ function nDiffers(p, raw, records) {
613
+ if (records !== true) return [];
614
+ const fit = isRecord(p.table.estimates?.["*"]) ? p.table.estimates["*"] : {};
615
+ return raw.cells.filter((e) => {
616
+ const f = fit[e.cell];
617
+ return isRecord(f) && f.generation === e.generation && count(f.merged) !== null && count(f.merged) !== e.n;
618
+ }).map((e) => e.cell);
619
+ }
620
+
621
+ // The evidence-favours side: the Preview fit's table laid out row by row under
622
+ // the workspace's guard, as routes now lays out the installed one, each row's
623
+ // Cell marked where it differs from the Cell routes now gives that row. `preview`
624
+ // is gather's read, `{ status: "ok", preview } | { status: "missing" } | {
625
+ // status: "unreadable", why }`; `guard` readCostGuard's answer and `routed`
626
+ // readGuard's for the same file, null when the router reads none; `mark` the
627
+ // footnote mark its n footnote takes.
628
+ function evidenceFavours({ preview, guard, routed, table, modelRoles, mark }) {
629
+ if (routed === null) return noFit("no Preview fit: it is written only beside a cost guard");
630
+ if (preview?.status === "unreadable") return noFit(`no Preview fit read: ${preview.why}`);
631
+ if (preview?.status !== "ok") return noFit("no Preview fit yet: the next phase 0 writes one");
632
+ const p = preview.preview;
633
+ const fit = p.table;
634
+ const raw = guard.guard;
635
+ // Whether the fit read the guard's files: null when the guard names no blob
636
+ // ids to compare, else whether the two name the same ones.
637
+ const records = isRecord(raw.tsv_blobs) ? isDeepStrictEqual(p.tsv_blobs, raw.tsv_blobs) : null;
638
+ const differ = nDiffers(p, raw, records);
639
+ const entry = (o, s) => {
640
+ const e = rowEntry(fit, routed, modelRoles, o, s);
641
+ const now = table === null ? null : rowDispatch({ table, guard: routed, objective: o, stratum: s }).policy;
642
+ return {
643
+ ...e,
644
+ differs: now !== null && now !== e.cell ? "≠ routes now" : null,
645
+ candidates: e.candidates.map((c) => ({ ...c, nMark: s === "*" && differ.includes(c.cell) ? mark : null })),
646
+ };
647
+ };
648
+ return {
649
+ title: FAVOURS,
650
+ source: { text: ["Preview fit", "this repository's runs", `computed ${when(p.computed_at)}`, plural(fit.n_rows, "Pull")].join(" · "), check: null },
651
+ heading: fit.burn_in ? `stage ${fit.stage}: ${shortWords(fit, "present") ?? "every Cell has its merged PRs"}` : null,
652
+ labels: previewLabels(p, raw, routed, table, records),
653
+ 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` }],
654
+ rows: Object.fromEntries(OBJECTIVES.map((o) => [o,
655
+ Object.fromEntries(["*", ...STRATA].filter((s) => Object.hasOwn(fit.rows[o], s)).map((s) => [s, entry(o, s)])),
656
+ ])),
657
+ unread: null,
552
658
  };
553
659
  }
554
660
 
@@ -557,7 +663,10 @@ function routesNow({ table, guard, modelRoles, install, repoUrl }) {
557
663
  // showing theirs on the row), its one model-name line when every candidate it
558
664
  // names differs, a Stratum no side has a row for collapsed to one line, and the
559
665
  // Objective of the live run marked. Every row, collapsed or not, has an anchor
560
- // the `#cells/row/<objective>/<stratum>` link lands on.
666
+ // the `#cells/row/<objective>/<stratum>` link lands on. A side with no rows reads
667
+ // its `unread` on every row, and keeps a Stratum from collapsing, since its rows
668
+ // are not known; one whose `unread` is null has nothing to show, its cells are
669
+ // empty, and the Strata collapse on the sides that have rows.
561
670
  export function policyRowsView({ sides, objective = null }) {
562
671
  const entries = (s) => (s.rows === null ? [] : OBJECTIVES.flatMap((o) => Object.values(s.rows[o])));
563
672
  const shared = sides.map((s) => {
@@ -574,21 +683,27 @@ export function policyRowsView({ sides, objective = null }) {
574
683
  dispatch: e.dispatch === shared[i] ? null : e.dispatch,
575
684
  candidates: e.candidates.map((c) => (c.model !== null && modelLine[i] !== null ? { ...c, model: { ...c.model, text: null } } : c)),
576
685
  });
686
+ // How many sides have rows, and whether a Stratum none of them has a row for
687
+ // may collapse: never while a side's rows are unknown.
688
+ const read = sides.filter((s) => s.rows !== null).length;
689
+ const collapsible = read > 0 && sides.every((s) => s.rows !== null || !s.unread);
690
+ const cellOf = (s, e, i) => {
691
+ if (s.rows === null) return s.unread ? { unread: s.unread } : { empty: true };
692
+ if (e === null) return { follows: "no row of its own: follows *" };
693
+ return show(e, i);
694
+ };
577
695
  return {
578
- sides: sides.map((s, i) => ({ title: s.title, source: s.source, heading: s.heading, dispatch: shared[i], modelLine: modelLine[i], footnotes: s.footnotes })),
696
+ sides: sides.map((s, i) => ({ title: s.title, source: s.source, heading: s.heading, labels: s.labels ?? [], dispatch: shared[i], modelLine: modelLine[i], footnotes: s.footnotes })),
579
697
  objectives: OBJECTIVES.map((o) => ({
580
698
  objective: o,
581
699
  live: o === objective,
582
700
  lines: ["*", ...STRATA].map((stratum) => {
583
701
  const line = { stratum, anchor: `cells-row-${o}-${stratum}`, href: `#cells/row/${o}/${stratum}` };
584
702
  const own = sides.map((s) => s.rows?.[o]?.[stratum] ?? null);
585
- if (stratum !== "*" && sides.every((s) => s.rows !== null) && own.every((e) => e === null)) {
586
- return { ...line, collapsed: `${stratum}: ${sides.length > 1 ? "no row on either side" : "no row"}, follows *` };
703
+ if (stratum !== "*" && collapsible && own.every((e) => e === null)) {
704
+ return { ...line, collapsed: `${stratum}: ${read > 1 ? "no row on either side" : "no row"}, follows *` };
587
705
  }
588
- return {
589
- ...line,
590
- sides: sides.map((s, i) => (s.rows === null ? { unread: "router table not read" } : own[i] === null ? { follows: "no row of its own: follows *" } : show(own[i], i))),
591
- };
706
+ return { ...line, sides: sides.map((s, i) => cellOf(s, own[i], i)) };
592
707
  }),
593
708
  })),
594
709
  };
@@ -635,15 +750,20 @@ function declaredSection(agents, modelRoles) {
635
750
  * `{ issue, cell, mark, targets: [{ cell, generation }] }` (compute-board.mjs's
636
751
  * cellLine). `table` is the installed router table `validateTable` accepted or
637
752
  * null, `install` the install's `{ name, version, repository, error }`
638
- * (`repository` its url), `repoUrl` the workspace's, and `objective` the live
639
- * run's Objective or null between runs. An input left out reads as nothing
753
+ * (`repository` its url), `repoUrl` the workspace's, `objective` the live
754
+ * run's Objective or null between runs, and `preview` the Preview fit as gather
755
+ * read `.fleet/router-preview.json`: `{ status: "ok", preview: { computed_at,
756
+ * guard_computed_at, tsv_blobs, prior, table } }`, `{ status: "missing" }` or
757
+ * `{ status: "unreadable", why }`. An input left out reads as nothing
640
758
  * read: a missing guard, no receipt, no definitions, no `modelRoles` read, no
641
- * Pull, no table, no install, no Objective.
759
+ * Pull, no table, no install, no Objective, no Preview fit.
642
760
  */
643
- export function computeCellEvidence({ guard, receipts, agents, modelRoles = null, pulls = [], table = null, install = null, repoUrl = null, objective = null }) {
761
+ export function computeCellEvidence({ guard, receipts, agents, modelRoles = null, pulls = [], table = null, install = null, repoUrl = null, objective = null, preview = null }) {
644
762
  const routed = guard?.status === "ok" ? readGuard(guard.guard) : null;
763
+ const routes = routesNow({ table, guard: routed, modelRoles, install, repoUrl });
764
+ const favours = evidenceFavours({ preview, guard, routed, table, modelRoles, mark: superscript(routes.footnotes.length + 1) });
645
765
  return {
646
- policy: policyRowsView({ sides: [routesNow({ table, guard: routed, modelRoles, install, repoUrl })], objective }),
766
+ policy: policyRowsView({ sides: [routes, favours], objective }),
647
767
  guard: guardSection(guard, receipts, modelRoles, pulls),
648
768
  declared: declaredSection(agents, modelRoles),
649
769
  };
@@ -1,7 +1,8 @@
1
1
  #!/usr/bin/env node
2
- // The run's three metrics duties that keep the router's inputs current: move the
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
- // corpus written before its latest columns, then refresh the cost guard over it.
4
+ // corpus written before its latest columns, refresh the cost guard over it, then
5
+ // write the Preview fit beside that guard.
5
6
  //
6
7
  // metrics-refresh.mjs [--repo <dir>]
7
8
  //
@@ -55,9 +56,26 @@
55
56
  // (no verdict yet — the baseline cell has too few merged PRs) are verdicts the
56
57
  // router and `fleet-tick.mjs` consume, not failures; any other non-zero exit is.
57
58
  //
59
+ // PREVIEW FIT. After the cost guard wrote a guard, and only then, the Router's
60
+ // fit (`ticket-router.mjs`'s fitTable) runs in-process over the working-tree
61
+ // TSVs the guard just read and the guard just written, with the installed
62
+ // router table (`router-table.json` beside the scripts) as its prior and no
63
+ // commit. It writes `.fleet/router-preview.json` through a temp file and a
64
+ // rename: `computed_at`, `guard_computed_at` (the guard's own `computed_at`),
65
+ // `tsv_blobs` (the git blob id of each TSV it read, keyed by path as the guard
66
+ // keys its own), `prior` (the installed table's `fitted_commit`, `stage`,
67
+ // `cells`, `classifier` and `window_start`, and the install's `package.json`
68
+ // `version`) and the fitted `table`. The cockpit lays it out as what the
69
+ // evidence favours; nothing routes by it and nothing commits it. It is called
70
+ // in-process because a fit has no verdict for an exit status to carry, and the
71
+ // `fit` CLI reads the TSVs only as committed. It never fails the run: an error
72
+ // prints `metrics-refresh: preview: failed — <why>`, leaves the old file in
73
+ // place and leaves the exit status as the other duties set it.
74
+ //
58
75
  // One `metrics-refresh: <duty>: …` line per duty on stdout. Exit 0 when no
59
76
  // duty failed; 1 when one failed — named on stderr, and the duties after
60
- // it did not run (each is safe to run again); 2 on a usage error.
77
+ // it did not run (each is safe to run again); 2 on a usage error. The
78
+ // Preview fit is not one of those duties: it never sets the exit status.
61
79
 
62
80
  import { spawnSync } from "node:child_process";
63
81
  import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
@@ -67,17 +85,24 @@ import { makeDie, defineFlags } from "./arg.mjs";
67
85
  import { gitEnv } from "./git-env.mjs";
68
86
  import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
69
87
  import { isCLI } from "./is-cli.mjs";
70
- import { COLUMNS as MEMBER_COLUMNS, ENDINGS, isImplementer } from "./member-outcomes.mjs";
88
+ import { COLUMNS as MEMBER_COLUMNS, ENDINGS, isImplementer, parseTsv as parseMemberTsv } from "./member-outcomes.mjs";
89
+ import { blobId } from "./pr-cost.mjs";
71
90
  import { FEATURE_COLUMNS, parseFeatures } from "./pull-attribution.mjs";
72
91
  import { REPORT_STATUSES } from "./report-files.mjs";
92
+ import { DEFAULT_TABLE, fitTable, readGuard, validateTable } from "./ticket-router.mjs";
93
+ import { parseTierOutcomes } from "./tier-outcomes.mjs";
73
94
 
74
95
  const NAME = "metrics-refresh";
75
96
  const PR_COST = fileURLToPath(new URL("./pr-cost.mjs", import.meta.url));
76
97
  const PENDING = join(".fleet", "ticket-features.pending.tsv");
77
98
  const FEATURES = join("docs", "metrics", "ticket-features.tsv");
78
99
  const MEMBERS = join("docs", "metrics", "member-outcomes.tsv");
79
- const CORPUS = [MEMBERS, join("docs", "metrics", "tier-outcomes.tsv"), FEATURES];
100
+ const TIERS = join("docs", "metrics", "tier-outcomes.tsv");
101
+ const CORPUS = [MEMBERS, TIERS, FEATURES];
80
102
  const GUARD = join(".fleet", "cost-guard.json");
103
+ const PREVIEW = join(".fleet", "router-preview.json");
104
+ // The install's own package.json, whose `version` names the prior.
105
+ const PACKAGE = fileURLToPath(new URL("../package.json", import.meta.url));
81
106
  // pr-cost.mjs --guard: 0 no cell tripped, 3 a cell tripped, 4 no verdict yet —
82
107
  // all three are verdicts its readers consume; anything else is a failure.
83
108
  const GUARD_VERDICT_EXITS = new Set([0, 3, 4]);
@@ -228,9 +253,13 @@ function drain(repo) {
228
253
  say(`drain: ${added.length} row${added.length === 1 ? "" : "s"} from ${PENDING} into ${FEATURES} (${incoming.length - added.length} already there)`);
229
254
  }
230
255
 
256
+ // The guard file it wrote, parsed, or null when it skipped and wrote none.
231
257
  function costGuard(repo) {
232
258
  const missing = CORPUS.filter((f) => !existsSync(join(repo, f)));
233
- if (missing.length) return say(`cost guard: skipped, ${missing.join(", ")} not found — no corpus to guard yet; ${GUARD} left as it is`);
259
+ if (missing.length) {
260
+ say(`cost guard: skipped, ${missing.join(", ")} not found — no corpus to guard yet; ${GUARD} left as it is`);
261
+ return null;
262
+ }
234
263
  const out = join(repo, GUARD);
235
264
  const r = spawnSync(process.execPath, [PR_COST, "--guard", "--out", out], {
236
265
  cwd: repo, encoding: "utf8", env: gitEnv(), maxBuffer: MAX_BUFFER,
@@ -241,6 +270,77 @@ function costGuard(repo) {
241
270
  const g = JSON.parse(readFileSync(out, "utf8"));
242
271
  const tripped = g.tripped.map((t) => (typeof t === "string" ? t : t?.cell));
243
272
  say(`cost guard: verdict ${g.verdict}${tripped.length ? ` (tripped: ${tripped.join(", ")})` : ""}, pr-cost.mjs exit ${r.status}; ${GUARD} computed ${g.computed_at}`);
273
+ return g;
274
+ }
275
+
276
+ // The install's `package.json` `version`, or null when it names none or cannot be read:
277
+ // the prior is named by it, and the fit does not need it.
278
+ function installVersion(path) {
279
+ try {
280
+ const v = JSON.parse(readFileSync(path, "utf8"))?.version;
281
+ return typeof v === "string" ? v : null;
282
+ } catch {
283
+ return null;
284
+ }
285
+ }
286
+
287
+ // The Preview fit over `repo`'s working-tree TSVs and `written`, the guard file the
288
+ // guard duty just wrote (parsed), with the router table at `tablePath` as its
289
+ // prior, written to `.fleet/router-preview.json` through a temp file and a
290
+ // rename. Throws on anything it cannot read, fit or write, before the rename, so
291
+ // the old file stays as it was.
292
+ export function writePreview(repo, written, { tablePath = DEFAULT_TABLE, packagePath = PACKAGE, now = new Date() } = {}) {
293
+ const guard = readGuard(written);
294
+ if (guard === null) throw new Error(`${GUARD} is not a guard the router reads`);
295
+ let prior;
296
+ try {
297
+ prior = validateTable(JSON.parse(readFileSync(tablePath, "utf8")));
298
+ } catch (e) {
299
+ throw new Error(`cannot read the installed router table ${tablePath}: ${e.code ?? e.message}`);
300
+ }
301
+ if (prior instanceof Error) throw new Error(`${tablePath}: ${prior.message}`);
302
+ // Keyed by the path as the guard keys its own (pr-cost.mjs reads these, relative to the workspace).
303
+ const tsvBlobs = {};
304
+ const read = (rel, parse) => {
305
+ const bytes = readFileSync(join(repo, rel));
306
+ tsvBlobs[rel] = blobId(bytes);
307
+ try { return parse(bytes.toString("utf8")); } catch (e) { throw new Error(`${rel}: ${e.message}`); }
308
+ };
309
+ const members = read(MEMBERS, parseMemberTsv);
310
+ const verdicts = read(TIERS, parseTierOutcomes);
311
+ const features = read(FEATURES, parseFeatures);
312
+ const table = fitTable({ prior, features, members, verdicts, guard, commit: null });
313
+ const preview = {
314
+ computed_at: now.toISOString(),
315
+ guard_computed_at: written.computed_at,
316
+ tsv_blobs: Object.fromEntries(Object.entries(tsvBlobs).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
317
+ prior: {
318
+ fitted_commit: prior.fitted_commit,
319
+ version: installVersion(packagePath),
320
+ stage: prior.stage,
321
+ cells: prior.cells,
322
+ classifier: prior.classifier,
323
+ window_start: prior.window_start,
324
+ },
325
+ table,
326
+ };
327
+ const file = join(repo, PREVIEW);
328
+ writeFileSync(`${file}.tmp`, `${JSON.stringify(preview, null, 2)}\n`);
329
+ renameSync(`${file}.tmp`, file);
330
+ return preview;
331
+ }
332
+
333
+ // The Preview fit as the run calls it: only beside a guard the guard duty wrote, and
334
+ // never a failure of the run — its error is a line, and the exit stays as it was.
335
+ function preview(repo, written) {
336
+ if (written === null) return say(`preview: skipped, no guard written — ${PREVIEW} left as it is`);
337
+ let p;
338
+ try {
339
+ p = writePreview(repo, written);
340
+ } catch (e) {
341
+ return say(`preview: failed — ${e.message}`);
342
+ }
343
+ 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}`);
244
344
  }
245
345
 
246
346
  function main() {
@@ -257,15 +357,18 @@ function main() {
257
357
  die(`${e.message} — pass --repo <dir>`);
258
358
  }
259
359
  }
360
+ let written = null;
260
361
  for (const [name, duty] of [["drain", drain], ["member-outcomes", widenMemberOutcomes], ["cost guard", costGuard]]) {
261
362
  try {
262
- duty(repo);
363
+ const out = duty(repo);
364
+ if (duty === costGuard) written = out;
263
365
  } catch (e) {
264
366
  process.stderr.write(`${NAME}: ${name} failed: ${e.message}\n`);
265
367
  process.exitCode = 1;
266
368
  return;
267
369
  }
268
370
  }
371
+ preview(repo, written);
269
372
  }
270
373
 
271
374
  if (isCLI(import.meta.url)) main();
@@ -109,7 +109,10 @@ committed; that file is a run artifact too and is committed with the other
109
109
  two. It then widens a `docs/metrics/member-outcomes.tsv` written before the
110
110
  newest columns, as at phase 0 — a file already at the current width is left
111
111
  as it is — and then runs `pr-cost.mjs --guard`, which rewrites
112
- `.fleet/cost-guard.json` from all three files. Exit 0: every duty ran. The guard's
112
+ `.fleet/cost-guard.json` from all three files. After a guard it wrote it writes
113
+ the Preview fit, `.fleet/router-preview.json`, for the cockpit alone: it is not
114
+ a metrics file and is never committed, and its `preview: failed — <why>` line
115
+ leaves the exit as it was. Exit 0: every duty ran. The guard's
113
116
  own exit 3 (a cell tripped) and 4 (no verdict yet, baseline too thin) are
114
117
  verdicts the router and `fleet-tick.mjs` read, never failures; the script
115
118
  absorbs them. Exit 1 names the duty that failed on stderr and the duties after it
@@ -235,6 +235,10 @@ and the guard the script also widens a `docs/metrics/member-outcomes.tsv`
235
235
  written before the newest columns: each row gains them, `ending` reads
236
236
  `unknown` on an implementer's row, and nothing else changes. Without that,
237
237
  phase 0, the close-out scrape and `tier-outcomes.mjs append` refuse the file.
238
+ After a guard it wrote, the script writes the Preview fit,
239
+ `.fleet/router-preview.json`, which only the cockpit reads: nothing routes by
240
+ it and nothing commits it, and a `metrics-refresh: preview: failed — <why>`
241
+ line leaves the exit at 0, so it never stops the run.
238
242
 
239
243
  ## Launch the cockpit
240
244