@feigi/fleet-ctl 3.153.1 → 3.154.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.
@@ -90,7 +90,7 @@ It cannot ask the user anything and cannot wait on CI — rebasing, watching che
90
90
  - **Say read-only.** No `fleet-review-*` definition's frontmatter restricts tool access — a `.agent.md` prompt saying "report only" is instruction, not enforcement — so an agent hand-dispatched here, named or general-purpose, has write tools it must not use: one committed and pushed during a report-only dispatch. No commits, no pushes, no worktree edits.
91
91
  - **Cut TWO trees, not one — a shared snapshot is not enough.** Mutation probing is a *write*, so a mutating specialist and read-only specialists cannot share a copy: the readers then observe the mutant exactly as if it were real code. Give them `snap-ro`, pristine and **never written**, and one private copy **per mutating specialist**. Keep every one out of the worktree. What one shared snapshot did is in run-team's `references/reviewers.md` (**What a shared snapshot did to its readers**). Reverting a probe does not help — it leaves a window where every concurrent reader sees a lie, and serializing does not close it because readers are concurrent with the *mutator*.
92
92
  - **Do not trust the obvious contamination check.** `diff -rq` and `md5` against the mutating tree both returned *clean* — because the probe had been reverted between the two reads. A clean diff against a live tree is not evidence in either direction; only `snap-ro` and the object store settle it.
93
- - **`git archive` carries tracked files only.** No installed dependencies, no gitignored runner or config. Provision in the same step — run the Install step in the copy (read it off the worktree or main checkout, `derive-testcmd.sh <worktree or main checkout> install`; pointed at the copy it refuses, since a copy holds no Recipe cache), from the copy's root, before anyone measures in it — or specialists silently have no runnable suite and reason from source instead of measuring. That failure is invisible: you get confident prose where you asked for a measurement. Never `cp -R` an installed tree, and never symlink or clone its ignored paths into a copy: an install can record absolute paths back into the tree it ran in, so the copy runs that tree's source and a mutation made in the copy never runs.
93
+ - **`git archive` carries tracked files only.** No installed dependencies, no gitignored runner or config. Provision in the same step — run the Install step in the copy (read it off the worktree or main checkout, `derive-testcmd.sh <worktree or main checkout> install --at origin/main`; pointed at the copy it refuses, since a copy holds no Recipe cache), from the copy's root, before anyone measures in it — or specialists silently have no runnable suite and reason from source instead of measuring. That failure is invisible: you get confident prose where you asked for a measurement. Never `cp -R` an installed tree, and never symlink or clone its ignored paths into a copy: an install can record absolute paths back into the tree it ran in, so the copy runs that tree's source and a mutation made in the copy never runs.
94
94
  - **Initialize the copy before anyone measures in it — a bare `git archive` tree cannot validly run every suite.** It is not a git repository, so anything that asks git about the checkout breaks: `derive_workspace_id` shells out to `git rev-parse`, falls back to the directory basename and the hook tests fail on the *name* — naming the dir after the repo makes those pass **by coincidence, not correctness** — while every sweep that asks git what ships declines instead of running, which is the silent half. `git init && git add -A -f && git commit` in the extracted copy is what makes a count mean what it looks like; the review's snapshot agent does exactly that, verifies it by comparing the new commit's tree hash against the reviewed commit's, and then runs the Install step in it, and a hand-cut tree needs the same before you read a count off it. **Every agent you send to work in its own copy of the snapshot makes that copy the same way:** copy the tracked files only (`git -C <snapshot> archive HEAD | tar -x -C <copy>`, or a `git clone` of the snapshot repository), `git init`, `git add -A -f` and commit, then run the Install step in the copy before measuring anything in it — never `cp -R` the snapshot. Suites that need the real worktree for some *other* reason — the stack below — still do.
95
95
  - **Give specialists a stack-free test command, not the worktree's runner, and their own scratch dir** — `<scratch>/pr<N>/fleet-review-<key>/`, resolved to an absolute path that you write into that specialist's prompt; a specialist never derives its own. Specialists inherit no environment, and one falling back to the default config runs a `globalSetup` that brings the shared compose stack up and tears it down, recreating the DB mid-run for every sibling. **The snapshot does not cover this** — the compose project name comes from the environment, not the working directory, so three agents on three copies still collide. But `./agent-test` does not fix it either: it exports **one** `TEST_COMPOSE_PROJECT`/port triple per *worktree* (`ab-<issue>`), so N concurrent specialists sharing it tear down each other's postgres mid-run. So tell specialists the repo's test command directly — the Test entrypoint, read off the Recipe cache the way step 3 reads it (`derive-testcmd.sh <worktree or main checkout> test` prints it; the snapshot carries no `.fleet/` cache, so pointing it at the snapshot refuses) — when it brings up no shared stack, and the repo's own stack-free config when it does; never name a config the repo does not have, which sends every specialist into a missing-file error that reads as a broken tree rather than a bad instruction. Keep `./agent-test` for your own verification. **Hand that command with its reading rule: `tests 0` is a failed run, not a pass.** A command is not self-checking: a path glob or filter that matches nothing can exit 0 having run nothing. Measured with `node --test` over a glob matching no file: bash passes the pattern through literally, node globs it itself and finds no files, and you get `ℹ tests 0` / exit 0 — and `# tests 0` to a pipe on older node, so a rule that greps only for `ℹ` finds nothing in a CI log and cannot tell a zero-test run from a full one. Do not count on the shell to catch it: zsh errors (`no matches found`, exit 1) and bash does not, so the guard has to be the reading rule. **And zero is not the only no-work count.** **0 passes with no failures** is everything skipped, and a count **materially below the full suite** is a partial copy of the tree — which is the *documented* behavior, since the prompt tells specialists to run their probe work inside their own copy of the snapshot and nothing anchors an expected count for them. `review-core.mjs` classifies the first itself, in `suiteVerdictOf`; the second it structurally cannot, because that function is kept pure and so never learns how many tests the tree has. Handing the rule over with the command is the only guard the partial-copy case has. Carry the rule, not the command: wherever a repo has a stack, N concurrent specialists sharing one runner collide, and the escape is whatever that repo's stack-free config is.
96
96
  - **Completion is not delivery — but you can reach a specialist, so never wait idle.** A specialist you dispatched reports when it settles; if a report is missing, `hub send` it by name and ask for the report. Judge delivery by whether a report came out. **Do not settle a dimension you hold no report for**: ask the specialist, then the controller by name; only when neither answers, rule and name that dimension **unrun** — a killed specialist never reports, so waiting on one is unbounded. Never ship "dispatched, never delivered" as settled; a ruling citing a report you do not hold gets verified from source, never applied on trust.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.153.1",
3
+ "version": "3.154.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": {
@@ -14,8 +14,8 @@
14
14
  #
15
15
  # The ONE reader of the cache — reused, not reimplemented, by claim-ticket.sh
16
16
  # (the Install step it runs and the Test entrypoint it bakes into the runner)
17
- # and by review-core.mjs's snapshot agent (the Test entrypoint handed to the
18
- # specialists). Two independent readers is what drifts.
17
+ # and by review-core.mjs's snapshot agent (the Install step it runs in the
18
+ # snapshot). Two independent readers is what drifts.
19
19
  #
20
20
  # THE CACHE is `<workspace>/.fleet/recipe.json`, where <workspace> is the
21
21
  # directory git-env.mjs's resolveWorkspace() names for the repository: the
@@ -114,7 +114,7 @@ export LC_ALL=C
114
114
  # `$repo` — and the cache it then reads is another repository's Recipe,
115
115
  # reported as this one's. Both consumers act on that string: claim-ticket.sh
116
116
  # runs it in a fresh worktree and bakes it into the runner, and review-core.mjs's
117
- # snapshot agent hands it to every specialist.
117
+ # snapshot agent runs it in the snapshot.
118
118
  #
119
119
  # GIT_WORK_TREE is unset alongside it: the vacuous-suite probe's `check-ignore`
120
120
  # reads the ignore rules of whatever work tree git is pointed at, so an ambient
@@ -416,9 +416,9 @@ fi
416
416
  # `;`, `&`, or a newline lets a real shell read the caller's "$@" as an
417
417
  # unrelated top-level command instead of args reaching the Test entrypoint, and
418
418
  # one containing a `#`-led word swallows everything after it, "$@" included, as
419
- # a comment. review-core.mjs's snapshot agent appends no arguments but embeds
420
- # the string in `{ cd <dir> && <cmd>; }`, where the same endings and `#` word
421
- # break the wrapper as a syntax error — measured on both. A trailing
419
+ # a comment. review-core.mjs's shared test run hands the string to
420
+ # suite-slot.mjs single-quoted and appends no arguments, so neither hazard
421
+ # reaches it there. A trailing
422
422
  # newline is checked here too: the frame above lets a value keep one
423
423
  # where an unframed `$(…)` capture always dropped it silently, so a value
424
424
  # that used to read as `true;` now reads as `true;\n` and would otherwise
@@ -62,7 +62,7 @@
62
62
  // router and `fleet-tick.mjs` consume, not failures; any other non-zero exit is.
63
63
  //
64
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
65
+ // (`ticket-router.mjs`'s fitTree) runs in-process over the working-tree TSVs
66
66
  // the guard just read and the guard just written, with the starting table
67
67
  // (`router-table.json` beside the scripts) as its prior and no commit. It
68
68
  // writes the Fit, `.fleet/router-fit.json`, through a temp file and a rename:
@@ -71,18 +71,31 @@
71
71
  // `tripped`, per-Cell `n` and `window_start`), `tsv_blobs` (the git blob id of
72
72
  // each TSV it read, keyed by path as the guard keys its own), `prior` (the
73
73
  // starting table's `fitted_commit`, `cells`, `classifier`, `splits` and
74
- // `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. It never fails the run: an error prints
81
- // `metrics-refresh: fit: failed — <why>`, leaves the old file in place, so the
82
- // run routes by the last Fit that computed, and leaves the exit status as the
83
- // other duties set it. That line stays on stdout: the cockpit reads it off the receipts'
84
- // `metrics` step, and close-out's receipt keeps only stdout from a run that
85
- // exits 0.
74
+ // `window_start`, and the install's `package.json` `version`), the
75
+ // fitted `table` and `gate`, the split gate's record: a digest of the Cells
76
+ // and Pulls it searched (`records`), the Pulls it scored and those it left
77
+ // out for want of a recorded assignment probability, the best split it found
78
+ // with its figures, `passed`, the inputs of the split that passed both its
79
+ // tests, and `stands`, those of the split that stands. `ticket-router.mjs
80
+ // route` routes by that `table`, read beside the guard; nothing commits the
81
+ // file. A split stands in the `table` once it has passed at two consecutive
82
+ // Fits on the same input or inputs, and is gone at the first Fit it fails;
83
+ // the next Fit reads the previous one's `gate` from the file this one
84
+ // replaces, which is all it carries forward. The Fit is a pure function of
85
+ // the records, the guard, the prior and that `gate`: the TSVs at the recorded
86
+ // blob ids, the guard and the prior fit to the same table again. So a Fit
87
+ // whose `records` are the previous one's is no look at the gate: it keeps
88
+ // that one's `passed` and `stands`, and a phase 0 run again over records that
89
+ // have not changed neither advances a split's count nor resets it. With no
90
+ // records it is the starting table's fit, as any other. It is called
91
+ // in-process because a fit has no verdict for an exit status to carry. It
92
+ // never fails the run: an error prints `metrics-refresh: fit: failed — <why>`,
93
+ // leaves the old file in place, so the run routes by the last Fit that
94
+ // computed, and leaves the exit status as the other duties set it. A Fit that
95
+ // failed is no look at the gate either: the old file's `gate` is still what
96
+ // the next Fit reads, so its count neither advances nor resets. That line
97
+ // stays on stdout: the cockpit reads it off the receipts' `metrics` step, and
98
+ // close-out's receipt keeps only stdout from a run that exits 0.
86
99
  //
87
100
  // One `metrics-refresh: <duty>: …` line per duty on stdout. Exit 0 when no
88
101
  // duty failed; 1 when one failed — named on stderr, and the duties after
@@ -101,7 +114,7 @@ import { COLUMNS as MEMBER_COLUMNS, ENDINGS, isImplementer, parseTsv as parseMem
101
114
  import { blobId } from "./pr-cost.mjs";
102
115
  import { FEATURE_COLUMNS, parseFeatures } from "./pull-attribution.mjs";
103
116
  import { REPORT_STATUSES } from "./report-files.mjs";
104
- import { DEFAULT_TABLE, FIT_FILE, INSTALL_PACKAGE, fitTable, installVersion, readGuard, validateTable } from "./ticket-router.mjs";
117
+ import { DEFAULT_TABLE, FIT_FILE, INSTALL_PACKAGE, fitTree, installVersion, readGuard, validateTable } from "./ticket-router.mjs";
105
118
  import { parseTierOutcomes } from "./tier-outcomes.mjs";
106
119
 
107
120
  const NAME = "metrics-refresh";
@@ -283,11 +296,30 @@ function costGuard(repo) {
283
296
  return g;
284
297
  }
285
298
 
299
+ // What the last Fit that computed recorded of the split gate (its `gate`), or null where there is no such Fit to read:
300
+ // no file, one that will not parse, or one written before the gate. Any other failure to read the file throws, as a
301
+ // Fit that cannot read what it replaces cannot write it either.
302
+ function previousGate(repo) {
303
+ let text;
304
+ try {
305
+ text = readFileSync(join(repo, FIT), "utf8");
306
+ } catch (e) {
307
+ if (e.code === "ENOENT") return null;
308
+ throw e;
309
+ }
310
+ try {
311
+ return JSON.parse(text)?.gate ?? null;
312
+ } catch {
313
+ return null;
314
+ }
315
+ }
316
+
286
317
  // The Fit over `repo`'s working-tree TSVs and `written`, the guard file the
287
318
  // guard duty just wrote (parsed), with the router table at `tablePath` as its
288
319
  // prior, written to `.fleet/router-fit.json` through a temp file and a rename.
289
320
  // Throws on anything it cannot read, fit or write, before the rename, so the
290
- // old file stays as it was.
321
+ // old file stays as it was: a Fit that throws is no look at the split gate,
322
+ // and the next one reads the gate the old file holds.
291
323
  export function writeFit(repo, written, { tablePath = DEFAULT_TABLE, packagePath = INSTALL_PACKAGE, now = new Date() } = {}) {
292
324
  const guard = readGuard(written);
293
325
  if (guard === null) throw new Error(`${GUARD} is not a guard the router reads`);
@@ -298,6 +330,7 @@ export function writeFit(repo, written, { tablePath = DEFAULT_TABLE, packagePath
298
330
  throw new Error(`cannot read the starting router table ${tablePath}: ${e.code ?? e.message}`);
299
331
  }
300
332
  if (prior instanceof Error) throw new Error(`${tablePath}: ${prior.message}`);
333
+ const previous = previousGate(repo);
301
334
  // Keyed by the path as the guard keys its own (pr-cost.mjs reads these, relative to the workspace).
302
335
  const tsvBlobs = {};
303
336
  const read = (rel, parse) => {
@@ -308,7 +341,10 @@ export function writeFit(repo, written, { tablePath = DEFAULT_TABLE, packagePath
308
341
  const members = read(MEMBERS, parseMemberTsv);
309
342
  const verdicts = read(TIERS, parseTierOutcomes);
310
343
  const features = read(FEATURES, parseFeatures);
311
- const table = fitTable({ prior, features, members, verdicts, guard, commit: null });
344
+ const { table, gate } = fitTree({ prior, features, members, verdicts, guard, commit: null, previous });
345
+ // The tree the gate grew is the one `route` will read it through.
346
+ const valid = validateTable(table);
347
+ if (valid instanceof Error) throw valid;
312
348
  const record = {
313
349
  computed_at: now.toISOString(),
314
350
  guard_computed_at: written.computed_at,
@@ -323,6 +359,7 @@ export function writeFit(repo, written, { tablePath = DEFAULT_TABLE, packagePath
323
359
  window_start: prior.window_start,
324
360
  },
325
361
  table,
362
+ gate,
326
363
  };
327
364
  const file = join(repo, FIT);
328
365
  writeFileSync(`${file}.tmp`, `${JSON.stringify(record, null, 2)}\n`);
@@ -145,8 +145,8 @@ export const TRIP_POINTS = 15;
145
145
 
146
146
  const round2 = (x) => (Number.isFinite(x) ? Number(x.toFixed(2)) : null);
147
147
 
148
- // Deterministic, so a re-run reads the same range.
149
- function mulberry32(seed) {
148
+ // Deterministic, so a re-run reads the same range; the split gate's shuffles and folds draw from it too.
149
+ export function mulberry32(seed) {
150
150
  let a = seed >>> 0;
151
151
  return () => {
152
152
  a = (a + 0x6d2b79f5) >>> 0;
@@ -451,7 +451,7 @@ function stretchesOf(pulls) {
451
451
 
452
452
  /**
453
453
  * One unit per ticket-features row dated on or after `windowStart` (every dated
454
- * row when null), in file order: `{ pull, cell, stratum, stretch, generation, status,
454
+ * row when null), in file order: `{ pull, cell, stretch, generation, status,
455
455
  * merged, pr, ruling, pendingPr, noRuling, noRulingPrs, claims, falseClaims, rows, spend, workS }`,
456
456
  * `generation` null exactly when the Pull is excluded. `noRulingPrs` are the
457
457
  * Pull's own implementer PRs that are merged and that no Pull holds a Ruling
@@ -459,13 +459,13 @@ function stretchesOf(pulls) {
459
459
  * Ruling, or when PR state is unknown. `spend` is null when a
460
460
  * booked `cost` is blank, and `workS`, its work time in seconds, when a booked
461
461
  * `work_s` of a row naming no parent is. `prs` is `gh pr list`'s
462
- * `{ number, state }` rows, or null when PR state is unknown (the fit). `stratum`
463
- * maps a features row to its stratum. `stretch` names the Pull's stretch among
464
- * the windowed Pulls (`stretchesOf`), excluded Pulls included. Throws `AttributionError` on a features
462
+ * `{ number, state }` rows, or null when PR state is unknown (the fit).
463
+ * `stretch` names the Pull's stretch among the windowed Pulls
464
+ * (`stretchesOf`), excluded Pulls included. Throws `AttributionError` on a features
465
465
  * row it cannot date or a booked `cost` or `work_s` it cannot read, and
466
466
  * `RulingError` as `rulingFor` does.
467
467
  */
468
- export function attribute({ features, members, tiers, prs = null, windowStart = null, stratum = () => null }) {
468
+ export function attribute({ features, members, tiers, prs = null, windowStart = null }) {
469
469
  const pulls = datedRows(features);
470
470
  const omp = ompRows(members);
471
471
  // Implementer rows to their Pull, and a PR-named member's key to its PR.
@@ -570,7 +570,7 @@ export function attribute({ features, members, tiers, prs = null, windowStart =
570
570
  else if (blank || (r && !r.carried)) status = "unpriced";
571
571
  else if (untimed) status = "untimed";
572
572
  return {
573
- pull, cell: pull.chosen_cell, stratum: stratum(pull), stretch: stretch.get(pull), generation, status, merged, pr: r?.pr ?? null, ruling: r?.ruling ?? null,
573
+ pull, cell: pull.chosen_cell, stretch: stretch.get(pull), generation, status, merged, pr: r?.pr ?? null, ruling: r?.ruling ?? null,
574
574
  noRuling: noRulingPrs.length > 0, noRulingPrs, pendingPr, claims, falseClaims, rows: booked, spend: blank ? null : spend, workS: untimed ? null : workS,
575
575
  };
576
576
  });
@@ -1,7 +1,7 @@
1
1
  // review-core.mjs — the review body for PR review.
2
2
  //
3
3
  // This file holds every host-independent declaration PR review needs: the
4
- // JSON schemas, `usableDiff`, `usableMessages`, `messagesNote`, `refuterMessagesNote`, `readRules`, `resolveTestCmd`,
4
+ // JSON schemas, `usableDiff`, `usableMessages`, `messagesNote`, `refuterMessagesNote`, `readRules`,
5
5
  // `decodeArgs`, `selectDimensions`, `resolveDimensions`, `snapshotMissing`,
6
6
  // `installReason`/`installFinding`, `suiteVerdictOf`/`unrunCrashed`,
7
7
  // `sharedRunNote`, `copyRule`,
@@ -134,8 +134,6 @@ export const SNAPSHOT_SCHEMA = {
134
134
  messagesPath: { type: "string" },
135
135
  refHead: { type: "string" },
136
136
  prHead: { type: "string" },
137
- testCmd: { type: "string" },
138
- testCmdError: { type: "string" },
139
137
  // The Recipe's `uncovered` as derive-testcmd.sh printed it: the merge-gating
140
138
  // CI steps neither the Test entrypoint nor the Check step runs, one line of JSON, `[]` for none.
141
139
  // `uncoveredError` carries the reader's refusal instead when it could not
@@ -410,23 +408,6 @@ re-billed as cache-read each time. Measured over one run, 88 unpiped whole-file
410
408
  reads carried 434 KB.`;
411
409
  }
412
410
 
413
- // The step a missing Test entrypoint is derived by, named in the refusal so the
414
- // caller — a controller or a reviewer — knows what to run rather than what went
415
- // wrong. derive-testcmd.sh's refusals about the cache name the same
416
- // step; its exit-3 refusals name an environment fault instead, which the caller
417
- // fixes rather than deriving. This one covers the case where the snapshot agent
418
- // reported no reason at all.
419
- const DERIVATION_STEP =
420
- "run the Recipe derivation step (run-team phase 0, before the first claim) to derive, prove and write the Recipe cache";
421
-
422
- export function resolveTestCmd(explicit, snap) {
423
- if (explicit) return explicit;
424
- if (snap && snap.testCmd) return snap.testCmd;
425
- throw new Error(
426
- `review-pr: no test command for this repository — ${(snap && snap.testCmdError) || `the snapshot agent read no Recipe cache; ${DERIVATION_STEP}`}. Pass args.testCmd to override.`,
427
- );
428
- }
429
-
430
411
  // The review's one run goes through the suite-slot wrapper, by the Resolver,
431
412
  // so it counts against the host-wide bound on concurrent full runs. The
432
413
  // command is one word to the wrapper — it hands the string to `sh -c` itself —
@@ -1104,6 +1085,15 @@ async function reviewRun(host, args, run) {
1104
1085
  // into it: an absent `pr` is owed "required", not a complaint about digits.
1105
1086
  if (!isDigits(pr)) throw new Error(`review-pr: args.pr must be a PR number, got ${JSON.stringify(pr)}`);
1106
1087
 
1088
+ // Nothing in the review derives a test command: every caller reads the Test
1089
+ // entrypoint off the Recipe cache and passes it. Refused here, beside the
1090
+ // other argument refusals, so a review that could never run its suite costs
1091
+ // no snapshot.
1092
+ const testCmd = A.testCmd;
1093
+ if (typeof testCmd !== "string" || testCmd.trim() === "") {
1094
+ throw new Error(`review-pr: args.testCmd is required — the Test entrypoint the shared run executes, got ${JSON.stringify(testCmd)}`);
1095
+ }
1096
+
1107
1097
  // Resolved only now: the default spawns git, so a missing or malformed `pr`
1108
1098
  // is refused on its own terms before anything is resolved or spawned.
1109
1099
  const scratch = A.scratch === undefined ? standaloneScratchRoot() : A.scratch;
@@ -1154,7 +1144,7 @@ async function reviewRun(host, args, run) {
1154
1144
  ( cd "$SNAP" && git init -q && git add -A -f && git -c user.name=fleet -c user.email=fleet@invalid commit -q --no-verify -m "review snapshot of $SHA" ) || echo SNAPSHOT_INIT_FAILED
1155
1145
  SNAPTREE=$(git -C "$SNAP" rev-parse 'HEAD^{tree}' 2>/dev/null); SRCTREE=$(git -C ${worktree} rev-parse 'HEAD^{tree}')
1156
1146
  { [ -d "$SNAP/.git" ] && [ -n "$SNAPTREE" ] && [ "$SNAPTREE" = "$SRCTREE" ]; } && echo SNAPSHOT_TREE_MATCH || echo SNAPSHOT_TREE_MISMATCH="snapshot $SNAPTREE vs commit $SRCTREE"
1157
- INSTALL=$(~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh ${worktree} install) && echo SNAPSHOT_INSTALL_STEP="$INSTALL" || { INSTALL=; echo SNAPSHOT_INSTALL_UNREAD; }
1147
+ INSTALL=$(~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh ${worktree} install --at origin/main) && echo SNAPSHOT_INSTALL_STEP="$INSTALL" || { INSTALL=; echo SNAPSHOT_INSTALL_UNREAD; }
1158
1148
  [ -z "$INSTALL" ] || { ( cd "$SNAP" && env -u CI sh -c "$INSTALL" ) >"$RUN/install.log" 2>&1; echo SNAPSHOT_INSTALL_EXIT=$?; }
1159
1149
  if [ -d "$SNAP/.git" ] && git -C "$SNAP" status --porcelain --untracked-files=all >"$RUN/status.txt"; then head -n 20 "$RUN/status.txt" | sed 's/^/SNAPSHOT_UNTRACKED=/'; echo SNAPSHOT_UNTRACKED_COUNT=$(wc -l <"$RUN/status.txt" | tr -d ' '); else echo SNAPSHOT_STATUS_FAILED; fi
1160
1150
 
@@ -1273,17 +1263,7 @@ a match nor a mismatch. Do not judge whether the diff is usable, and do not
1273
1263
  withhold one field because another failed: report what you got and let the
1274
1264
  caller decide.
1275
1265
 
1276
- Then read this repository's Test entrypoint out of its Recipe cache:
1277
-
1278
- ~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh ${worktree} test
1279
-
1280
- Report \`testCmd\` = its stdout ONLY if it exited 0. If it exited non-zero,
1281
- report \`testCmdError\` = its stderr and omit \`testCmd\`. Never derive or
1282
- guess a command yourself: a refusal about the cache names the step that
1283
- derives it; an exit-3 refusal names an environment fault, and the caller fixes
1284
- that instead of deriving.
1285
-
1286
- Then read, out of the same cache, the merge-gating CI steps that neither the
1266
+ Then read, out of the Recipe cache, the merge-gating CI steps that neither the
1287
1267
  Test entrypoint nor the Check step runs:
1288
1268
 
1289
1269
  ~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh ${worktree} uncovered
@@ -1334,8 +1314,7 @@ replaces uncovered.`,
1334
1314
  log(`snapshot ${snap.head} at ${snap.path} — head ref ${snap.refHead || "(absent): head check SKIPPED"} — PR head ${snap.prHead ?? "(absent)"}`);
1335
1315
  log(environmentNote(snap));
1336
1316
 
1337
- const testCmd = resolveTestCmd(A.testCmd, snap);
1338
- log(`testCmd ${A.testCmd ? "(caller override)" : "(derived)"} ${testCmd}`);
1317
+ log(`testCmd ${testCmd}`);
1339
1318
  // An Install step that failed or never ran leaves a snapshot that cannot
1340
1319
  // measure the tree: the shared run is skipped, the suite verdict is not
1341
1320
  // usable through `testRunReason`, and a non-zero exit is filed as a finding.
@@ -0,0 +1,382 @@
1
+ // The split gate: whether a group of tickets should be split on what is known of a ticket at dispatch.
2
+ //
3
+ // `searchSplits` takes one group's counted Pulls, each with the inputs its ticket held at dispatch, the Cell it ran,
4
+ // what it cost and the probability the router assigned it that Cell, and answers with the best way to cut the group
5
+ // and whether the cut has earned a place. `standing` says whether it stands yet.
6
+ //
7
+ // THE SEARCH. A numeric input is cut at its 25th, 50th and 75th percentile, a `values` input on each of its values
8
+ // (the Pulls holding it against the other Pulls that hold some value) and a `presence` input on whether it is above
9
+ // zero. A Pull that lacks an input has no side of a cut on it: a blank is the input's missing value, never a value of
10
+ // its own, so no cut asks whether the input was recorded. A cut whose smaller side holds fewer than twice the
11
+ // minimum Pulls is dropped, and so is one that cuts its input as an earlier cut does. A partition is one cut, or two
12
+ // cuts on two different inputs: depth two, the most the search reaches. A Pull lacking an input of the partition is
13
+ // outside it, and the gate scores it as keeping the group's one-Cell choice. In the tree, one lacking the first cut's
14
+ // input routes by the group's own row, and one holding it but lacking the second's by the row of its side of the
15
+ // first cut, which no leaf of the partition scores.
16
+ //
17
+ // THE GAIN. Each side of a partition (a leaf, for two cuts) takes the cheapest Cell it can: one with the minimum
18
+ // merged PRs there that is not under the quality floor against the default Cell, the default Cell itself needing
19
+ // the minimum merged PRs there too. The gain of a partition is the $ per merged PR of the group's one-Cell choice
20
+ // less the $ per merged PR of the leaves' choices, each leaf weighted by its share of the group's Pulls. A partition
21
+ // that moves no leaf off the one-Cell choice gains exactly zero.
22
+ //
23
+ // THE GATE. The best partition by gain splits only if it passes both tests:
24
+ // - the shuffled null: the same search, run on outcomes shuffled against the inputs inside each set of Pulls with
25
+ // the same assignment probability, reaches the real gain in at most 5% of the shuffles;
26
+ // - the off-policy bound: a doubly robust estimate of the one-Cell choice's value less the leaves' value, each
27
+ // Pull weighted by the probability the router assigned its own Cell, has a one-sided 95% lower bound above zero.
28
+ // The outcome model is a leaf-by-Cell mean fitted on the other folds of a five-fold split, so no Pull is
29
+ // predicted by itself.
30
+ // Everything is a function of the Pulls and the seed: the same record and seed give the same answer.
31
+ //
32
+ // THE FIGURES ARE PLAIN. A leaf's figure for a Cell is the Cell's own $ per merged PR over the leaf's Pulls, and the
33
+ // floor is the integer cross-product over their claims, not the time-matched comparison the table's rows are judged
34
+ // by. The gate asks whether an input changes which Cell wins; the bound weighs each Pull by the probability its Cell
35
+ // was drawn with, which is what keeps a change in the draw from reading as an input's effect. The rows of a split
36
+ // that stands are judged by the time-matched comparison, as every row is.
37
+
38
+ import { TRIP_POINTS, mulberry32 } from "./pull-attribution.mjs";
39
+
40
+ /** The shuffles the null runs: with 99, at most 4 reaching the real gain is the 5% test. */
41
+ export const NULL_SHUFFLES = 99;
42
+
43
+ const ALPHA = 0.05;
44
+ const Z95 = 1.644854; // one-sided 95%
45
+ const EPS = 1e-12;
46
+ const FOLDS = 5;
47
+ const PERCENTILES = Object.freeze([0.25, 0.5, 0.75]);
48
+ // What a leaf's tally holds for one Cell, in this order: Pulls, merged PRs, $, claims, false claims.
49
+ const STRIDE = 5;
50
+ // The most leaves a partition has: two cuts, two sides each.
51
+ const MOST_LEAVES = 4;
52
+
53
+ // The value `q` of the way along `sorted`, between the two Pulls it falls between.
54
+ function quantile(sorted, q) {
55
+ const k = (sorted.length - 1) * q;
56
+ const f = Math.floor(k);
57
+ const c = Math.min(f + 1, sorted.length - 1);
58
+ return sorted[f] + (sorted[c] - sorted[f]) * (k - f);
59
+ }
60
+
61
+ // Fisher-Yates over the first `length` entries of `list`, in place.
62
+ function shuffle(list, length, rand) {
63
+ for (let i = length - 1; i > 0; i--) {
64
+ const j = Math.floor(rand() * (i + 1));
65
+ const t = list[i];
66
+ list[i] = list[j];
67
+ list[j] = t;
68
+ }
69
+ }
70
+
71
+ /**
72
+ * The cuts of the group's inputs that the search keeps, in search order: each `{ input, cut, side, below, above }`,
73
+ * `side` a Pull's side of the cut, 1 above it (or holding the value), 0 the other side, -1 for a Pull lacking the
74
+ * input, `below` and `above` the Pulls on each side. A percentile is floored: an input is a count, so a Pull is above
75
+ * the percentile exactly when it is above the whole number under it, which is the cut a table can name.
76
+ */
77
+ function cutsOf(pulls, inputs, minN) {
78
+ const cuts = [];
79
+ for (const { name, cuts: how, values } of inputs) {
80
+ const held = pulls.map((p) => p.inputs[name] ?? null);
81
+ const present = held.filter((v) => v !== null);
82
+ if (present.length === 0) continue;
83
+ let thresholds = values;
84
+ if (how === "presence") thresholds = [0];
85
+ else if (how === "percentiles") {
86
+ const sorted = Float64Array.from(present).sort();
87
+ thresholds = PERCENTILES.map((q) => Math.floor(quantile(sorted, q)));
88
+ }
89
+ const kept = new Set();
90
+ for (const cut of thresholds) {
91
+ const side = Int8Array.from(held, (v) => (v === null ? -1 : (how === "values" ? v === cut : v > cut) ? 1 : 0));
92
+ const above = side.reduce((n, s) => n + (s === 1 ? 1 : 0), 0);
93
+ const below = present.length - above;
94
+ if (Math.min(above, below) < 2 * minN) continue;
95
+ const key = Buffer.from(side.buffer, side.byteOffset, side.length).toString("latin1");
96
+ if (kept.has(key)) continue;
97
+ kept.add(key);
98
+ cuts.push({ input: name, cut, side, below, above });
99
+ }
100
+ }
101
+ return cuts;
102
+ }
103
+
104
+ /** Every partition of one cut, then of every pair of cuts on two different inputs, with `gid` each Pull's leaf (-1: outside). */
105
+ function partitionsOf(cuts, n) {
106
+ const parts = cuts.map((c, i) => ({ cuts: [i], gid: c.side, leaves: 2 }));
107
+ for (let i = 0; i < cuts.length; i++) {
108
+ for (let j = i + 1; j < cuts.length; j++) {
109
+ if (cuts[i].input === cuts[j].input) continue;
110
+ const gid = new Int8Array(n);
111
+ const a = cuts[i].side;
112
+ const b = cuts[j].side;
113
+ for (let r = 0; r < n; r++) gid[r] = a[r] < 0 || b[r] < 0 ? -1 : a[r] * 2 + b[r];
114
+ parts.push({ cuts: [i, j], gid, leaves: MOST_LEAVES });
115
+ }
116
+ }
117
+ return parts;
118
+ }
119
+
120
+ // Each Cell's tally in each leaf of a partition, from Pulls `o` (parallel columns), into `s`: `s[(leaf * C + cell) * STRIDE + k]`.
121
+ function tallyInto(s, gid, leaves, C, o) {
122
+ s.fill(0, 0, leaves * C * STRIDE);
123
+ const { cell, merged, usd, claims, failed } = o;
124
+ for (let i = 0; i < gid.length; i++) {
125
+ const g = gid[i];
126
+ if (g < 0) continue;
127
+ const at = (g * C + cell[i]) * STRIDE;
128
+ s[at] += 1;
129
+ s[at + 1] += merged[i];
130
+ s[at + 2] += usd[i];
131
+ s[at + 3] += claims[i];
132
+ s[at + 4] += failed[i];
133
+ }
134
+ }
135
+
136
+ // Whether the Cell tallied at `at` is under the quality floor against the default Cell tallied at `base`: its fail rate
137
+ // TRIP_POINTS or more points above, compared in integers so a gap of exactly the margin reads as one.
138
+ function underFloor(s, at, base) {
139
+ const [claims, failed, baseClaims, baseFailed] = [s[at + 3], s[at + 4], s[base + 3], s[base + 4]];
140
+ return claims > 0 && baseClaims > 0 && (failed * baseClaims - baseFailed * claims) * 100 >= TRIP_POINTS * claims * baseClaims;
141
+ }
142
+
143
+ // The Cell leaf `g` takes: the cheapest per merged PR of those the leaf can judge, the default Cell (index 0) first and
144
+ // winning a tie. With too few merged PRs on the default Cell there is nothing to hold the floor against, so no Cell is
145
+ // judged and the leaf keeps `fallback`.
146
+ function pick(s, g, C, minN, fallback) {
147
+ const at0 = g * C * STRIDE;
148
+ if (s[at0 + 1] < minN) return fallback;
149
+ let best = 0;
150
+ let cheapest = s[at0 + 2] / s[at0 + 1];
151
+ for (let c = 1; c < C; c++) {
152
+ const at = at0 + c * STRIDE;
153
+ if (s[at + 1] < minN || underFloor(s, at, at0)) continue;
154
+ const v = s[at + 2] / s[at + 1];
155
+ if (v < cheapest) {
156
+ cheapest = v;
157
+ best = c;
158
+ }
159
+ }
160
+ return best;
161
+ }
162
+
163
+ // The $ per merged PR of Cell `c` in leaf `g`, or the leaf's own over every Cell where `c` merged none.
164
+ function valueOf(s, g, c, C) {
165
+ const at = (g * C + c) * STRIDE;
166
+ if (s[at + 1] > 0) return s[at + 2] / s[at + 1];
167
+ let usd = 0;
168
+ let merged = 0;
169
+ for (let k = 0; k < C; k++) {
170
+ usd += s[(g * C + k) * STRIDE + 2];
171
+ merged += s[(g * C + k) * STRIDE + 1];
172
+ }
173
+ return merged > 0 ? usd / merged : 0;
174
+ }
175
+
176
+ // What a partition gains over every leaf taking Cell `base`: each leaf's share of the group's `n` Pulls times the
177
+ // $ per merged PR it saves.
178
+ function gainOf(s, leaves, C, n, minN, base) {
179
+ let gain = 0;
180
+ for (let g = 0; g < leaves; g++) {
181
+ let pulls = 0;
182
+ for (let c = 0; c < C; c++) pulls += s[(g * C + c) * STRIDE];
183
+ if (pulls === 0) continue;
184
+ const chosen = pick(s, g, C, minN, base);
185
+ if (chosen !== base) gain += (pulls / n) * (valueOf(s, g, base, C) - valueOf(s, g, chosen, C));
186
+ }
187
+ return gain;
188
+ }
189
+
190
+ /**
191
+ * How many of `shuffles` shuffles of the outcomes reach `gain` in some partition, counting only up to one past
192
+ * `allowed`, where the answer is settled. A shuffle permutes the outcomes (Cell, $, merged, claims, false claims) among
193
+ * the Pulls of each set in `sets`, the rows of Pulls with the same probability, against inputs that stay where they are.
194
+ */
195
+ function shuffledReach({ parts, sets, o, C, minN, base, gain, shuffles, allowed, rand }) {
196
+ const n = o.cell.length;
197
+ const s = new Float64Array(MOST_LEAVES * C * STRIDE);
198
+ const list = new Int32Array(n);
199
+ const perm = new Int32Array(n);
200
+ const shuf = { cell: new Int32Array(n), merged: new Float64Array(n), usd: new Float64Array(n), claims: new Float64Array(n), failed: new Float64Array(n) };
201
+ let reached = 0;
202
+ for (let b = 0; b < shuffles && reached <= allowed; b++) {
203
+ for (const set of sets) {
204
+ list.set(set);
205
+ shuffle(list, set.length, rand);
206
+ for (let i = 0; i < set.length; i++) perm[set[i]] = list[i];
207
+ }
208
+ for (let i = 0; i < n; i++) {
209
+ const j = perm[i];
210
+ shuf.cell[i] = o.cell[j];
211
+ shuf.merged[i] = o.merged[j];
212
+ shuf.usd[i] = o.usd[j];
213
+ shuf.claims[i] = o.claims[j];
214
+ shuf.failed[i] = o.failed[j];
215
+ }
216
+ for (const part of parts) {
217
+ tallyInto(s, part.gid, part.leaves, C, shuf);
218
+ if (gainOf(s, part.leaves, C, n, minN, base) >= gain - EPS) {
219
+ reached++;
220
+ break;
221
+ }
222
+ }
223
+ }
224
+ return reached;
225
+ }
226
+
227
+ /**
228
+ * The one-sided 95% lower bound of the one-Cell choice's value less the leaves' value, per Pull, by the doubly robust
229
+ * estimate. `picks` is each leaf's Cell; `z` a Pull's outcome; `fold` its fold; `o.prob` the probability its own Cell was
230
+ * assigned with. A Pull outside the partition, or in a leaf that keeps `base`, adds nothing, but counts in the mean.
231
+ */
232
+ function lowerBound({ gid, leaves }, picks, base, o, z, fold, C) {
233
+ const n = o.cell.length;
234
+ // The sums of $ by fold, leaf and Cell, and their totals, so a Pull's model is the mean of the other folds.
235
+ const inFold = new Float64Array(FOLDS * leaves * C);
236
+ const sumFold = new Float64Array(FOLDS * leaves * C);
237
+ const inLeaf = new Float64Array(leaves * C);
238
+ const sumLeaf = new Float64Array(leaves * C);
239
+ const inCellFold = new Float64Array(FOLDS * C);
240
+ const sumCellFold = new Float64Array(FOLDS * C);
241
+ const inCell = new Float64Array(C);
242
+ const sumCell = new Float64Array(C);
243
+ for (let i = 0; i < n; i++) {
244
+ const f = fold[i];
245
+ const c = o.cell[i];
246
+ inCellFold[f * C + c] += 1;
247
+ sumCellFold[f * C + c] += z[i];
248
+ inCell[c] += 1;
249
+ sumCell[c] += z[i];
250
+ if (gid[i] < 0) continue;
251
+ const at = (f * leaves + gid[i]) * C + c;
252
+ inFold[at] += 1;
253
+ sumFold[at] += z[i];
254
+ inLeaf[gid[i] * C + c] += 1;
255
+ sumLeaf[gid[i] * C + c] += z[i];
256
+ }
257
+ // The leaf's mean for the Cell over the other folds, else the Cell's over them, else nothing known.
258
+ const model = (i, g, c) => {
259
+ const f = fold[i];
260
+ const left = inLeaf[g * C + c] - inFold[(f * leaves + g) * C + c];
261
+ if (left > 0) return (sumLeaf[g * C + c] - sumFold[(f * leaves + g) * C + c]) / left;
262
+ const rest = inCell[c] - inCellFold[f * C + c];
263
+ return rest > 0 ? (sumCell[c] - sumCellFold[f * C + c]) / rest : 0;
264
+ };
265
+ let total = 0;
266
+ let squares = 0;
267
+ for (let i = 0; i < n; i++) {
268
+ const g = gid[i];
269
+ if (g < 0 || picks[g] === base) continue;
270
+ const chosen = picks[g];
271
+ const own = o.cell[i];
272
+ const [mBase, mChosen] = [model(i, g, base), model(i, g, chosen)];
273
+ const d = (mBase + (own === base ? (z[i] - mBase) / o.prob[i] : 0)) - (mChosen + (own === chosen ? (z[i] - mChosen) / o.prob[i] : 0));
274
+ total += d;
275
+ squares += d * d;
276
+ }
277
+ const mean = total / n;
278
+ const variance = Math.max(0, (squares - n * mean * mean) / (n - 1));
279
+ return mean - Z95 * Math.sqrt(variance / n);
280
+ }
281
+
282
+ /**
283
+ * Search `pulls`, one group's counted Pulls, for the best split and judge it. `pulls` are
284
+ * `{ cell, usd, merged, claims, failed, prob, inputs }`: the Cell the Pull ran (one of `cells`), the $ it cost, whether
285
+ * its PR merged (0 or 1), its claims and false claims, the probability (0..1] it was assigned its Cell, and its ticket's
286
+ * inputs by name, a number, a string or null where the ticket lacks it. `cells` names the Cells to choose among, the
287
+ * default Cell first; `inputs` the inputs to search, each `{ name, cuts }` with `cuts` `percentiles`, `presence` or
288
+ * `values` (then listing the values); `minN` the merged PRs a Cell needs in a leaf to be chosen there.
289
+ *
290
+ * @returns {{
291
+ * scored: number, base: string|null, cuts: { input: string, cut: number|string, below: number, above: number }[],
292
+ * best: null | {
293
+ * inputs: string[], cuts: { input: string, cut: number|string }[], key: string, gain: number, picks: string[],
294
+ * exceeded: number, passesNull: boolean, lowerBound: number, passesBound: boolean, passes: boolean,
295
+ * },
296
+ * }} `base` is the Cell the group's one-Cell choice names. `best` is null where no partition moves a leaf off it.
297
+ * `exceeded` counts the shuffles whose best gain reached `best.gain`, stopping once there are too many for the null to
298
+ * pass; with `shuffles` 0 none is run and `passesNull` is false, which leaves the bound and the gain. `picks` names each leaf's Cell: leaf 0 is the side at or below the cut, 1 the side above it; for two cuts leaf
299
+ * `2a + b` is side `a` of the first and side `b` of the second.
300
+ */
301
+ export function searchSplits({ pulls, cells, inputs, minN, shuffles = NULL_SHUFFLES, seed = 1 }) {
302
+ const n = pulls.length;
303
+ const C = cells.length;
304
+ const out = { scored: n, base: null, cuts: [], best: null };
305
+ if (C === 0) return out;
306
+ const index = new Map(cells.map((c, i) => [c, i]));
307
+ const o = {
308
+ cell: new Int32Array(n), merged: new Float64Array(n), usd: new Float64Array(n),
309
+ claims: new Float64Array(n), failed: new Float64Array(n), prob: new Float64Array(n),
310
+ };
311
+ pulls.forEach((p, i) => {
312
+ const c = index.get(p.cell);
313
+ if (c === undefined) throw new RangeError(`Pull ${i} ran ${p.cell}, which is not one of the Cells searched`);
314
+ [o.cell[i], o.merged[i], o.usd[i], o.claims[i], o.failed[i], o.prob[i]] = [c, p.merged, p.usd, p.claims, p.failed, p.prob];
315
+ });
316
+
317
+ const cuts = cutsOf(pulls, inputs, minN);
318
+ const parts = partitionsOf(cuts, n);
319
+ const s = new Float64Array(MOST_LEAVES * C * STRIDE);
320
+ const whole = new Int8Array(n);
321
+ tallyInto(s, whole, 1, C, o);
322
+ const base = pick(s, 0, C, minN, 0);
323
+ const ratio = s[base * STRIDE + 1] > 0 ? s[base * STRIDE + 2] / s[base * STRIDE + 1] : 0;
324
+ out.base = cells[base];
325
+ out.cuts = cuts.map(({ input, cut, below, above }) => ({ input, cut, below, above }));
326
+
327
+ let top = -1;
328
+ let gain = 0;
329
+ for (let q = 0; q < parts.length; q++) {
330
+ tallyInto(s, parts[q].gid, parts[q].leaves, C, o);
331
+ const g = gainOf(s, parts[q].leaves, C, n, minN, base);
332
+ if (g > gain) [top, gain] = [q, g];
333
+ }
334
+ if (gain <= EPS) return out;
335
+ const best = parts[top];
336
+
337
+ const strata = new Map();
338
+ for (let i = 0; i < n; i++) (strata.get(o.prob[i]) ?? strata.set(o.prob[i], []).get(o.prob[i])).push(i);
339
+ const allowed = Math.floor(ALPHA * (shuffles + 1)) - 1;
340
+ const exceeded = shuffledReach({
341
+ parts, sets: [...strata.values()].map((l) => Int32Array.from(l)), o, C, minN, base, gain, shuffles, allowed, rand: mulberry32(seed),
342
+ });
343
+ const passesNull = exceeded <= allowed;
344
+
345
+ // The bound's outcome is a Pull's $ less the one-Cell choice's $ per merged PR for each PR that merged, so a Pull that
346
+ // never merged counts for what it cost. With every Pull merged that is the $ shifted, which the estimate ignores.
347
+ const z = Float64Array.from(o.usd, (u, i) => u - ratio * o.merged[i]);
348
+ const fold = new Int8Array(n);
349
+ const order = Int32Array.from({ length: n }, (_, i) => i);
350
+ shuffle(order, n, mulberry32(seed ^ 0x5bd1e995));
351
+ for (let k = 0; k < n; k++) fold[order[k]] = k % FOLDS;
352
+ tallyInto(s, best.gid, best.leaves, C, o);
353
+ const picks = Array.from({ length: best.leaves }, (_, g) => pick(s, g, C, minN, base));
354
+ const bound = lowerBound(best, picks, base, o, z, fold, C);
355
+
356
+ const used = best.cuts.map((i) => cuts[i]);
357
+ out.best = {
358
+ inputs: used.map((c) => c.input),
359
+ cuts: used.map(({ input, cut }) => ({ input, cut })),
360
+ key: used.map((c) => c.input).join("+"),
361
+ gain,
362
+ picks: picks.map((c) => cells[c]),
363
+ exceeded,
364
+ passesNull,
365
+ lowerBound: bound,
366
+ passesBound: bound > 0,
367
+ passes: passesNull && bound > 0,
368
+ };
369
+ return out;
370
+ }
371
+
372
+ /**
373
+ * Where a candidate stands. `best` is `searchSplits`'s answer and `previous` the keys that passed at the last Fit that
374
+ * computed. `passed` is the keys that pass now, to be kept for the next Fit, and `stands` those that also passed then,
375
+ * on the same input or inputs, whatever their cuts: a split that fails at a Fit is in neither, so it merges back, and
376
+ * one that passes on other inputs than before starts its count again.
377
+ * @returns {{ passed: string[], stands: string[] }}
378
+ */
379
+ export function standing({ best, previous }) {
380
+ const passed = best !== null && best.passes ? [best.key] : [];
381
+ return { passed, stands: passed.filter((key) => previous.includes(key)) };
382
+ }
@@ -51,6 +51,7 @@
51
51
  // the guard are files the caller wrote, a fitted commit is fetched by the
52
52
  // caller, and the install reads ask the local `omp`.
53
53
 
54
+ import { createHash } from "node:crypto";
54
55
  import { readFileSync, readdirSync, appendFileSync, mkdirSync, statSync, realpathSync } from "node:fs";
55
56
  import { spawnSync } from "node:child_process";
56
57
  import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
@@ -65,6 +66,7 @@ import { parseTsv as parseMemberTsv } from "./member-outcomes.mjs";
65
66
  import {
66
67
  AttributionError, FEATURE_COLUMNS, OPTIONAL_COLUMNS, TRIP_POINTS, attribute, compareCells, generations, parseFeatures, tally,
67
68
  } from "./pull-attribution.mjs";
69
+ import { searchSplits, standing } from "./split-gate.mjs";
68
70
  import { RulingError, parseTierOutcomes } from "./tier-outcomes.mjs";
69
71
  import { LINE_REF, briefPaths, briefText } from "./ticket-text.mjs";
70
72
  import { catalogEntry, implementerCell, readOmpConfigValue, readOmpModelCatalog, resolveRole } from "./tier-roles.mjs";
@@ -666,21 +668,24 @@ const round4 = (x) => Math.round(x * 1e4) / 1e4;
666
668
 
667
669
  /**
668
670
  * The fit's Pulls: pull-attribution.mjs's units over the window — booked as
669
- * routed, each to its own row's cell and group, `stratum` the walk from a
670
- * features row to its group — restricted to rows the free classifier routed
671
- * plus exploration rows: a row a live B classifier routed is the A/B's test
672
- * set, not the fit's. The fit sees no PR state, so a Pull with
671
+ * routed, each to its own row's cell — restricted to rows the free classifier
672
+ * routed plus exploration rows: a row a live B classifier routed is the A/B's
673
+ * test set, not the fit's. The fit sees no PR state, so a Pull with
673
674
  * a Ruling is merged. A fit reads everything in the commit it is given: no row
674
675
  * is cut by date, because `--check` re-reads that same commit rather than
675
676
  * re-cutting the working tree's files. `order` ranks each cell's generations
676
677
  * over every Pull in the window, the restriction aside, so the fit names the
677
- * same newest generation the guard does.
678
+ * same newest generation the guard does. No unit is in a group yet: `book`
679
+ * puts each where a tree walks its features row.
678
680
  */
679
- function fitPulls({ features, members, verdicts, window, stratum }) {
680
- const all = attribute({ features, members, tiers: verdicts, windowStart: window || null, stratum });
681
+ function fitPulls({ features, members, verdicts, window }) {
682
+ const all = attribute({ features, members, tiers: verdicts, windowStart: window || null });
681
683
  return { units: all.filter((u) => u.pull.exploration_draw !== "" || u.pull.sizing_src === "rule"), order: generations(all) };
682
684
  }
683
685
 
686
+ /** `units`, each booked to the group `table`'s tree walks its features row to (stratumOf). */
687
+ const book = (units, table) => units.map((u) => ({ ...u, stratum: stratumOf(table, u.pull) }));
688
+
684
689
  // Per node of the tree, per cell, its newest generation's figures: `n` counted
685
690
  // Pulls, `merged`, $ per merged PR, minutes of work time per merged PR, false
686
691
  // claims over claims, fix rounds per merged PR, `by_hand` (the counted merged Pulls whose
@@ -881,8 +886,8 @@ function judgeSpeedRow(pulls, cells, tripped, costCell) {
881
886
  }
882
887
 
883
888
  /**
884
- * The re-fit table, over the tree `prior.splits` holds: the fit makes no split
885
- * and takes none away. `guard` is `{ tripped, n, window_start }` (readGuard's
889
+ * The re-fit table, over the tree `prior.splits` holds: this makes no split
890
+ * and takes none away (fitTree grows the tree). `guard` is `{ tripped, n, window_start }` (readGuard's
886
891
  * shape); `commit` is the sha of the commit the inputs were read from, or null
887
892
  * for the empty corpus before any fit. `rows` and `reasons` hold one set per
888
893
  * objective, and each a row or record for every node. `reasons.cost` holds
@@ -899,8 +904,13 @@ function judgeSpeedRow(pulls, cells, tripped, costCell) {
899
904
  */
900
905
  export function fitTable({ prior, features, members, verdicts, guard, commit = null }) {
901
906
  const window = guard.window_start ?? prior.window_start ?? null;
907
+ return tableOver({ prior, ...fitPulls({ features, members, verdicts, window }), guard, commit, window });
908
+ }
909
+
910
+ // The table over the tree `prior.splits` holds, from the fit's Pulls (fitPulls') booked to its groups.
911
+ function tableOver({ prior, units: unbooked, order, guard, commit, window }) {
902
912
  const nodes = treeNodes(prior.splits);
903
- const { units, order } = fitPulls({ features, members, verdicts, window, stratum: (row) => stratumOf(prior, row) });
913
+ const units = book(unbooked, prior);
904
914
  const { estimates, pulls } = estimate(units, order, nodes);
905
915
  const tripped = new Set(guard.tripped);
906
916
 
@@ -934,6 +944,114 @@ export function fitTable({ prior, features, members, verdicts, guard, commit = n
934
944
  };
935
945
  }
936
946
 
947
+ // ---------------------------------------------------------------------------
948
+ // the split gate — which tree the fit grows
949
+ // ---------------------------------------------------------------------------
950
+
951
+ // The inputs the split search reads, in the order it searches them, and how each is cut: a count at its percentiles,
952
+ // `kind` on each of its values, `parent` on whether the ticket names one. They are the inputs a split may read.
953
+ const SEARCHED = Object.freeze([
954
+ ...Object.keys(INPUTS).filter((name) => INPUTS[name] === "number" && name !== "parent").map((name) => ({ name, cuts: "percentiles" })),
955
+ { name: "kind", cuts: "values", values: [...KINDS] },
956
+ { name: "parent", cuts: "presence" },
957
+ ]);
958
+
959
+ const PROBABILITY = /^(?:1|([1-9][0-9]*)\/([1-9][0-9]*))$/;
960
+
961
+ /**
962
+ * The probability a features row's Cell was assigned with, or null where the row records none, as one written before
963
+ * the column existed does: it is left out of the gate, never read as certain. Throws `AttributionError` on a value that
964
+ * is no probability.
965
+ */
966
+ function probabilityOf(row) {
967
+ const text = row.assignment_prob ?? "";
968
+ if (text === "") return null;
969
+ const m = PROBABILITY.exec(text);
970
+ const p = m === null ? NaN : m[1] === undefined ? 1 : Number(m[1]) / Number(m[2]);
971
+ if (!(p > 0 && p <= 1)) throw new AttributionError(`ticket #${row.ticket}: a ticket-features row's assignment_prob is '${text}', expected blank or a probability`);
972
+ return p;
973
+ }
974
+
975
+ // A seed that is a function of which Pulls were scored: a Fit reproduces from its records, and draws other shuffles once they grow.
976
+ function seedOf(ids) {
977
+ let h = 2166136261;
978
+ for (const id of ids) {
979
+ for (let i = 0; i < id.length; i++) h = Math.imul(h ^ id.charCodeAt(i), 16777619);
980
+ h = Math.imul(h ^ 0xff, 16777619);
981
+ }
982
+ return h >>> 0;
983
+ }
984
+
985
+ /** The tree a standing split makes: its first cut at the root, its second, if it has one, at each child of the root. */
986
+ function treeOf(cuts) {
987
+ const splits = { "*": { ...cuts[0] } };
988
+ if (cuts.length > 1) for (const node of childrenOf("*", cuts[0])) splits[node] = { ...cuts[1] };
989
+ return splits;
990
+ }
991
+
992
+ /**
993
+ * The tree the fit grows, and what the gate found. The group searched is every counted Pull of the table's Cells the
994
+ * guard has not tripped, that records the probability its Cell was assigned with (the rest are `left_out`): the gate
995
+ * weighs each Pull by it. `previous` is the `gate` record of the last Fit that computed, or null. The tree is the root
996
+ * and, when the best split passes both tests and passed on the same input or inputs at the last Fit too, that split;
997
+ * the starting table's own tree is not read. `gate.records` is a digest of the Cells and Pulls searched: a Fit whose
998
+ * digest is the last Fit's searched what that Fit searched and finds what it found, so it is no look at the gate — it
999
+ * keeps that Fit's `passed` and `stands`, and a first pass cannot stand on the same records twice. `gate.passed`,
1000
+ * `gate.stands` and `gate.records` are what the next Fit reads.
1001
+ */
1002
+ function growTree({ prior, units, order, tripped, previous }) {
1003
+ const cells = prior.cells.includes(POLICY_CELL) ? [POLICY_CELL, ...prior.cells.filter((c) => c !== POLICY_CELL && !tripped.has(c))] : [];
1004
+ const pulls = [];
1005
+ let leftOut = 0;
1006
+ for (const { pulls: counted } of tally(units, order).filter((t) => cells.includes(t.cell))) {
1007
+ for (const u of counted) {
1008
+ const prob = probabilityOf(u.pull);
1009
+ if (prob === null) {
1010
+ leftOut++;
1011
+ continue;
1012
+ }
1013
+ pulls.push({
1014
+ cell: u.cell, usd: u.spend, merged: u.merged ? 1 : 0, claims: u.claims, failed: u.falseClaims, prob,
1015
+ inputs: Object.fromEntries(SEARCHED.map(({ name }) => [name, inputOf(name, u.pull)])), id: `${u.pull.session}\0${u.pull.agent}`,
1016
+ });
1017
+ }
1018
+ }
1019
+ const found = searchSplits({ pulls, cells, inputs: SEARCHED, minN: MIN_N, seed: seedOf(pulls.map((p) => p.id)) });
1020
+ const records = createHash("sha256").update(JSON.stringify({ cells, pulls })).digest("hex");
1021
+ const kept = Array.isArray(previous?.passed) ? previous.passed : [];
1022
+ const { passed, stands } = previous?.records === records
1023
+ ? { passed: kept, stands: (Array.isArray(previous.stands) ? previous.stands : []).filter((key) => key === found.best?.key) }
1024
+ : standing({ best: found.best, previous: kept });
1025
+ const best = found.best;
1026
+ const gate = {
1027
+ records,
1028
+ scored: found.scored,
1029
+ left_out: leftOut,
1030
+ best: best === null ? null : {
1031
+ inputs: best.inputs, cuts: best.cuts, gain: round4(best.gain), exceeded: best.exceeded, passes_null: best.passesNull,
1032
+ lower_bound: round4(best.lowerBound), passes_bound: best.passesBound,
1033
+ },
1034
+ passed,
1035
+ stands,
1036
+ };
1037
+ return { gate, splits: stands.length > 0 ? treeOf(best.cuts) : {} };
1038
+ }
1039
+
1040
+ /**
1041
+ * The Fit: the table fitted over the tree the split gate grows, and the gate's record. `previous` is the `gate` record
1042
+ * of the last Fit that computed, or null where there is none; the rest is fitTable's. A split stands in the table
1043
+ * once it has passed the gate at two consecutive Fits on the same input or inputs, over other records each time — a
1044
+ * Fit over the records the last one searched is no look, and keeps what that one found — and is gone from it at the
1045
+ * first Fit it fails; that Fit's `gate` is the whole of what the next one reads of this.
1046
+ * @returns {{ table: object, gate: { records: string, scored: number, left_out: number, best: object|null, passed: string[], stands: string[] } }}
1047
+ */
1048
+ export function fitTree({ prior, features, members, verdicts, guard, commit = null, previous = null }) {
1049
+ const window = guard.window_start ?? prior.window_start ?? null;
1050
+ const fitted = fitPulls({ features, members, verdicts, window });
1051
+ const { gate, splits } = growTree({ prior, ...fitted, tripped: new Set(guard.tripped), previous });
1052
+ return { table: tableOver({ prior: { ...prior, splits }, ...fitted, guard, commit, window }), gate };
1053
+ }
1054
+
937
1055
  // ---------------------------------------------------------------------------
938
1056
  // the commit a fit reads
939
1057
  // ---------------------------------------------------------------------------
@@ -251,11 +251,21 @@ After a guard it wrote, the script computes the Fit — the router's table fitte
251
251
  over the three metrics files and that guard, with the starting table beside the
252
252
  scripts as its prior — and writes it to `.fleet/router-fit.json`, which every
253
253
  Pull of this run routes by. Nothing commits it. One Fit per run: close-out
254
- computes none, so each close-out's rows route the next run. A
254
+ computes none, so each close-out's rows route the next run. The Fit also grows
255
+ the tree of groups: it searches the dispatch-time inputs of the Pulls that
256
+ recorded an assignment probability for a split, and a split joins the tree only
257
+ after it has passed the shuffled null and the off-policy bound at two
258
+ consecutive Fits on the same input or inputs, and leaves it at the first Fit
259
+ it fails. What passed, what stands and a digest of the Pulls the gate searched
260
+ are kept in the Fit file for the next Fit to read, which is the only state a
261
+ Fit carries: a Fit over the same Pulls as the last one — phase 0 run again
262
+ before a close-out added any — finds what that one found, so it is no look at
263
+ the gate and keeps what that one kept. A
255
264
  `metrics-refresh: fit: failed — <why>` line leaves the previous file as it
256
265
  was and the exit at 0, so it never stops the run: the run routes by the last
257
- Fit that computed, else by the starting table. A skipped guard skips the Fit
258
- too, and both files are left as they are.
266
+ Fit that computed, else by the starting table, and a Fit that failed is no look
267
+ at the gate — it neither advances a split's count nor resets it. A skipped
268
+ guard skips the Fit too, and both files are left as they are.
259
269
 
260
270
  ## Launch the cockpit
261
271
 
@@ -484,7 +494,7 @@ code in the claim tree.
484
494
  **Derive the Recipe — the Recipe derivation step — before the fold-in below
485
495
  and before the first claim.** Every claim runs this repository's Install
486
496
  step and bakes its Test entrypoint into the member's runner, and every
487
- review reads the Test entrypoint, all out of the **Recipe cache**
497
+ review runs the Install step, all out of the **Recipe cache**
488
498
  (`.fleet/recipe.json` beside the common git dir); no script infers either
489
499
  command. Check it first: `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh .
490
500
  install --at origin/main`, `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh . check
@@ -522,7 +532,7 @@ stall, below.
522
532
  **Where `checkCmd` comes from:** the repository's Check step, out of the same Recipe cache — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run derive-testcmd.sh . check` prints it. Pass it to the fix-applier beside `testCmd`; the review does not run it. Neither member runs the two by hand: `recipe-check.mjs` runs the Check step it reads off that cache, then the `testCmd` it is handed, on the member's staged tree, and writes the record `ledger.mjs settle --from-report` requires of an implementer's and a fix-applier's report.
523
533
 
524
534
  **Mid-run, a cache that stops running is re-derived once, then the run
525
- stalls.** A claim or a review that refuses because the Recipe cache is
535
+ stalls.** A claim that refuses because the Recipe cache is
526
536
  invalid — a command that no longer runs, or an Install step that changed
527
537
  the tree — is a mid-run trigger: dispatch `derive-recipe` again
528
538
  exactly as above, then retry what refused. So is the `NEED derive-recipe`
@@ -131,7 +131,7 @@ that ran clean has nothing in those three either.
131
131
 
132
132
  ## A failed review is a failure event, not a clean review
133
133
 
134
- The review throws on missing `args.pr`/`args.worktree` and on a snapshot agent
134
+ The review throws on missing `args.pr`/`args.worktree`/`args.testCmd` and on a snapshot agent
135
135
  that returned no tree, and a failure surfaces mid-loop, where "react, never
136
136
  block" makes it easy to log and carry on — leaving a PR that *reads* as
137
137
  reviewed and is not.