docs(ci): re-derive the CLI whole-fit bound on the refreshed shard-timings dataset

[objectstack-fleet]

Fixes #21758
Clause-②: no

This PR covers triage's direction 5982304306, steps 2 to 4. Step 1 (option A, the re-measure) is the refresh that already landed as f2aa0c9fad. The only thing left open is the seat's reading on the next hourly full run after this lands.

The diff is one comment block in scripts/partition-test-shards.mjs. No code changed. FILE_SHARDED_PACKAGES is unchanged (still empty), and so are test-shard-timings.json, ci.yml and every timeout.

Step 2: the docblock is corrected

The FILE_SHARDED_PACKAGES docblock argued that the CLI "fits whole until ~1852s". It reached that by solving the bound against a 733.33 s entry. That entry was the CLI's two slice windows summed within one run (run 36380128221, the only sample that refresh had). It was not a whole-suite window. Once the CLI ran whole, its windows read 1659.03 s and 1667.97 s, which is 2.26 to 2.27 times that entry. The conclusion held, because both readings are under ~1852 s, but the figure behind it was wrong.

The block now records that, and it re-derives the bound on the dataset that measured the CLI whole.

Step 3: option B is not indicated (the arithmetic)

Dataset. scripts/test-shard-timings.json at origin/main 01e0f71a, blob 12c2460c00. That blob is identical to f2aa0c9fad, the #21826 refresh.

• It was measured from run 37262126122: 72 packages, 9781.33 s in total.
• @objectstack/cli reads 1702.69 s and is now the heaviest item.
• @objectstack/dogfood, the only --exclude in ci.yml, is not in the dataset.

The rule used is the partitioner's own, not a paraphrase. meetsBound (pins 2 and 3) requires both of these:

• the heaviest bin is at most MAX_SHARD_OVER_MEAN (1.3) times the mean;
• no single item is heavier than 1.3 times the mean.

When the CLI is the heaviest item and sits alone in a bin, both halves reduce to C ≤ (1.3/6)(R + C), where C is the CLI's weight and R is everything else.

Numbers.

• R = 8078.64 s.
• Mean = 9781.33 / 6 = 1630.22 s.
• Bound = 1.3 × 1630.22 = 2119.29 s.
• CLI/mean = 1702.69 / 1630.22 = 1.044, inside 1.3.
• Solving for C: C_max = 1.3 × 8078.64 / 4.7 ≈ 2234.5 s. That is 1.31 times the CLI's dataset entry, and 1.27 times its worst reading since the refresh (1753.66 s, run 37415122516).

CLI weight	max/mean	heaviest item
whole, as in the dataset (1702.69 s)	1.044	1703 s (cli)
sliced at 2	1.002	1135 s (spec)
whole at its worst since (1753.66 s)	1.070	1754 s (cli)

Slicing at 2 would lower the maximum, but the bound already holds at n = 1. Pin 3c's own derivation refuses a { '@objectstack/cli': 2 } entry on this dataset ("at 1 the split already meets 1.3x (max/mean 1.04x, heaviest item 1703s against a 1630s mean). Retire the entry"). So option B is not taken.

Because FILE_SHARDED_PACKAGES did not change, the Test Core matrix and the required-check names (Test Core (N/6) and the aggregate Test Core) do not change either.

The 6 bins the landed dataset produces (full list, as the hourly run splits it)

shard	predicted	share of mean	items	contents
1/6	1702.69 s	1.044	1	cli
2/6	1614.77 s	0.991	12	spec, service-messaging, plugin-audit, mcp, …
3/6	1615.33 s	0.991	15	metadata-protocol, service-analytics, verify, cloud-connection, …
4/6	1615.40 s	0.991	15	objectql, service-automation, client, lint, …
5/6	1616.73 s	0.992	15	rest, plugin-auth, plugin-approvals, driver-turso, …
6/6	1616.41 s	0.992	14	runtime, plugin-security, driver-sql, plugin-sharing, …

The partitioner's own self-test prints the same bins: bins 1703/1615/1615/1615/1617/1616s.

Step 4: second samples (reported here, not written into the dataset)

Source. Each reading is a turbo execution window for a task that actually ran (a cache MISS). It comes from the report-test-timings merged table that the aggregate Test Core job echoes into its log, read with the GitHub MCP get_job_logs read tool.

• The test-core-run-summary-* artifacts and the raw job-log REST endpoint are both unreadable from this container: gh api …/actions/jobs/112121376726/logs refuses the redirect to productionresultssa16.blob.core.windows.net.
• The merged table lists only the 10 slowest packages per run.

Each ratio is the reading divided by the landed dataset value.

package (dataset)	37421524959 schedule @ 76fec88	37415122516 push @ 3c7785d	37419396793 push @ 76fec88	37416453417 schedule @ 3c7785d
plugin-auth (364.98 s)	393.33 s, 1.08×	387.53 s, 1.06×	231.44 s, 0.63×	cache replay, NOT MEASURED
metadata-protocol (566.45 s)	372.89 s, 0.66×	549.06 s, 0.97×	not in the top-10 (cutoff 150.51 s), NOT MEASURED	cache replay, NOT MEASURED
cli (1702.69 s)	1723.05 s, 1.01×	1753.66 s, 1.03×	1721.19 s, 1.01×	1033.74 s, 0.61×

Seat 1's pre-refresh executed readings (5982793172), divided by the new values:

• plugin-auth: 297.82 / 417.15 / 320.88 s, which is 0.82× / 1.14× / 0.88×;
• metadata-protocol: 511.20 / 426.17 s, which is 0.90× / 0.75×.

Every sample for both packages is under 1.5× against the landed dataset. The highest are plugin-auth at 1.14× and metadata-protocol at 0.97×.

Early reading toward the acceptance (not the seat's post-landing reading)

This PR changes no code, so the partition on main is already the one above. Two post-refresh hourly full runs exist:

• Shard 1/6 (cli alone): measured/predicted is 0.61× in 37416453417 and 1.01× in 37421524959.
• Shards 2 to 6: NOT MEASURED here. A shard's ratio needs every package window on it. Those windows are only in the run-summary artifacts, which this container cannot reach, and the merged table names 10 packages. In 37421524959 all ten listed packages read between 0.66× and 1.21×.

Acceptance notes (noted, not filed)

• Shard 1/6 wall time. Shard 1 is the whole CLI alone. Its job took 31m37s (37421524959), 34m39s (37415122516), 32m09s (37419396793) and 20m42s (37416453417). The current timeout is a temporary 45 minutes, and its written revert condition returns it to 30. This PR changes no timeout (fenced), and the 1.3× ratio bound holds. Handed on: ci: Test Core compares each shard's measured duration with its predicted weight — warning at 1.3x, red at 70% of the timeout (maintainer-directed, drift alarm) #16465 and the owner of that revert condition.
• ci.yml comments are now stale (ci.yml is ci: Test Core compares each shard's measured duration with its predicted weight — warning at 1.3x, red at 70% of the timeout (maintainer-directed, drift alarm) #16465's to edit, so they were not touched here):
  • the drift-step block still cites the CLI as "458.15s recorded, 1231.52s measured";
  • "WHY SIX" names @objectstack/spec as the heaviest indivisible suite, but on this dataset the CLI is.
  • Handed on: ci: Test Core compares each shard's measured duration with its predicted weight — warning at 1.3x, red at 70% of the timeout (maintainer-directed, drift alarm) #16465.
• The refreshed dataset is again a single run. Its provenance.runs is ["37262126122"]. The CLI alone on shard 1 read 1033.74 s and 1723.05 s one hour apart. Handed on: the refresh lane's next weekly run.
• spec's cost on the new partition is unknown. spec moved from a bin of its own into a 12-package bin. The weights are contended wall clock (ci.yml "WHY SIX"), and spec was a cache replay in all four post-refresh runs read here. Its window under the new placement is NOT MEASURED. If shard 2 drifts, look there first.

Verification (head cb3f093c)

• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 30 commands from the merge base 01e0f71ad, the same 30 the dispatch named.
  • All 30 exited 0, with each exit code written to disk.
  • --ran reconciliation: ✓ dispatch-gates --ran: 30 derived famil(ies) accounted for — 30 run, 0 NOT-MEASURED (a DERIVED zero …).
  • node scripts/partition-test-shards.mjs --self-test: self-test OK (72 measured packages -> 72 shard items, 6 shards, max/mean 1.04x …, floor 1703s, bins 1703/1615/1615/1615/1617/1616s, file-level slices: none), where the elided part states the 1.3x bound.
  • pnpm check:pm-dispatch-gates: ✓ dispatch-gates self-test: 1976 cases pass.
  • pnpm check:nul-bytes: OK (scanned 10322 text file(s) … no raw ASCII control bytes).
• Extra runs, for rosters under scripts/: node scripts/check-published-list-mirrors.mjs and node scripts/measure-test-shard-timings.mjs --self-test both exit 0.
• No *.test.* file names this script (zero hits; the control grep for scripts/ over the same pathspec has 383 hits).
• eslint, narrowed to this one file:
  • eslint --no-inline-config --format json scripts/partition-test-shards.mjs gives 1 file, 0 errors, 0 warnings.
  • The file is in the population of eslint.config.mjs's **/*.{…,mjs,…} object; --print-config shows 2 rules and parserOptions {ecmaVersion, sourceType}.
  • The config enables no type-aware linting (no parserOptions.project or projectService anywhere), so a comment edit in one file cannot change any other file's result. The full pnpm lint run is CI's.
• No changeset: root scripts/ only, private, nothing publishes, so skip-changeset.

The holder of this card ran out of session tokens. This PR continues the existing branch claude/issue-21758-shard-fit-after-refresh as a takeover (Release:/Claim: 6010756437), by domain:devx seat 2, session session_01VF48aw8RPG6wzDnMgp6rtw.

---

Generated by Claude Code