[nissa-seru]

This adds cases for two checks in the relief rule that no test pinned, has the floor count no lock outside kv-unified, so it no longer goes missing when a pin meets a lock there, and narrows texts in the fragment and in doc comments where they say more than the code does, among them that outside kv-unified the floor is a lower bound. It's five commits on 01f3a85107, the head of anima-research#416 when they were made. At 910749152, test/liveness-floor.test.ts gives 19 of 19, and each new case fails with the check or the change it covers removed. Merging it is the only step it needs.

Problem

At 01f3a85107, line numbers in src/strategies/autobiographical.ts:

• Two checks in mergeTakesTurnByRelief can be removed, changing the order, with all 10 tests in test/liveness-floor.test.ts passing.
  • The attempts > 0 half of :6332. With the line cut to if (head.hadRefusal) return false;, a merge whose answer was cut off (stopReason: 'max_tokens'), or whose request was rejected, goes first again on the next tick.
  • this.mergeFailureOrder.has(key) in :6334. With it removed, a merge whose call failed goes first again once the pause the failure caused has passed.
• Outside kv-unified, the floor can go missing when a pin meets a lock. lockChunk's doc says a classic pin "still overrides the lock while it stands: under the greedy solvers and kv-stable, the pinned message renders raw" (:2979–2981), while kv-unified treats a pin and a lock as constraints. The floor builds kv-unified's constraints under every folding strategy, so under kv-stable, flat-profile and oldest-first a message folded at level 1 or above, locked, and then pinned raw leaves no feasible floor, and under kv-stable so does a message locked raw and then pinned at level 2. The compile goes on with floorTokens, hardBudget and queuedReliefTokens absent, and nothing says why (:6398). Four of this branch's floor cases, run over 01f3a85107's src, fail because the floor isn't reported.
• Under kv-stable, a lock a level pin overrides through its summary still raises the floor. In this branch's case, the floor at 01f3a85107 is 1322 with the lock and 1292 without it.
• Some texts say more than the code does:
  • The fragment says OverBudgetDiagnostics gains the floor "on adaptive refusals". The head-and-tail refusal (:13818) is thrown before the floor is computed (:14141), and carries neither field.
  • hardBudget - floorTokens is called how far the store is "from its first refusal", in the fragment and in RenderStats.planVsActual.floorTokens. A compile refuses once its plan passes hardBudget, which can come before the floor does.
  • Queued relief is an estimate: by expectedPairCost's comment (:6358–6360), a new summary is priced at the mean of the latest summaries at its level, or at the summary target before any exists. The fragment and OverBudgetDiagnostics.queuedReliefTokens say draining the queue alone won't clear a floor still over the budget less the relief.

Changes

• Two order cases, in test/liveness-floor.test.ts, on the openOrder harness:
  • "runs the next L1 before a merge whose answer was cut off": the queued merge answers with stop reason max_tokens. After that tick the merge is still queued, and the calls made are ['merge', 'l1'].
  • "runs the next L1 before a merge whose call failed, once the pause it caused has passed": the merge's call throws a network error. The tick rejects, the lane is paused, and the merge is still queued. With the pause's backoffUntil set to 0, the next tick runs an L1, and the calls are ['merge', 'l1'].
  • The existing "runs the next L1 before a merge the model has refused once" case gains one premise: the refused merge is still queued after its first tick.
• Outside kv-unified, the floor counts no lock (floorTokens). Under kv-unified it takes that solver's own constraints, locks included, as before. The other folding strategies give pins precedence over locks in ways those constraints don't follow, so there a lock leaves the floor's inputs, and the floor is a lower bound.
• initialize clears the floor's last failure cause, beside the strategy's other once-per-load logs, so a store opened again says a lasting failure again.
• Seven floor cases, on the openReader harness:
  • "keeps the floor where a pin overrides a lock", under kv-stable, flat-profile and oldest-first: a message folded at level 1 or above is locked, then pinned raw. The floor is reported, at or under the plan and higher than before the pin, with no floor warning.
  • "counts no lock outside kv-unified, so a lock a level pin overrides through its summary leaves the floor under the plan", under kv-stable: a message locked while raw, then a sibling under its L1 pinned at level 1. The floor is at or under the plan, and the same with and without the lock.
  • "counts a lock under kv-unified, whose constraints the floor takes": locking a message raises the floor.
  • "keeps the floor where a level pin overrides a lock under kv-stable, as kv-unified refuses the compile for it": under kv-unified, a message locked raw and pinned at level 2 makes the compile refuse, and under kv-stable the same pair keeps the floor, at or under the plan.
  • "says once that a floor whose computation fails is missing, again when it recurs or the store is opened again, and the compile goes on", under kv-stable: with CanonicalSummaryForest.prototype.minimumTokens made to throw, two compiles go on with the floor and hardBudget absent and one warning naming the error. Another error gives a second warning. With the method restored the floor is back, the second error again gives a third warning, and with the store closed and opened again, a fourth.
• Texts:
  • The fragment, changelog.d/415-floor-headroom.added.md: hardBudget - floorTokens is how far the store is from the point where every compile refuses. Under kv-unified the floor takes that solver's own constraints, locks included, and is exact, and elsewhere it counts no lock. "Outside kv-unified the floor is a lower bound: a floor over hardBudget means every compile refuses, and one at or under it doesn't promise a plan fits." A floor that can't be computed is said once per cause, and once more by each load that meets it. OverBudgetDiagnostics carries the floor on the adaptive refusals that come once the plan is made, when it was computed, and the head-and-tail refusal carries neither. Under kv-unified a floor at or under the budget means a plan that fits exists. Queued relief is an estimate.
  • OverBudgetDiagnostics.floorTokens and queuedReliefTokens, in src/adaptive/picker.ts: the same split between kv-unified and the other strategies, and over hardBudget, which the doc defines as inputBudget with overBudgetGraceRatio added, no plan fits until the floor drops under it or the budget rises. Where the doc said "only new summaries, a larger budget or a smaller tail clear the refusal", its list now also names fewer messages and a released pin or lock, each of which a probe in Tests shows lowering a floor.
  • RenderStats.planVsActual.floorTokens, in src/types/strategy.ts, and floorTokens' own doc comment: the distance to the point where every compile refuses, with locks counted under kv-unified and none elsewhere, where it's a lower bound, and absent where the forest couldn't be built or its computation fails.

Tests

On Linux with Node 24.22.2 and npm 11.19.1:

• At 910749152, in a clean checkout, npm ci, npm run build and tsc --noEmit are clean, and test/liveness-floor.test.ts gives 19 of 19. On a GitHub-hosted Linux runner with Node 24.22.1 and npm 11.19.1, npm ci and then npm test, whose pretest builds first, pass all 3570 tests, in 393 suites, at 910749152.

• Red first: this branch's test/liveness-floor.test.ts, run over 01f3a85107's src in a clean checkout, fails six cases:

  • the three pin-over-lock cases and the level pin over a lock, each on "the floor is reported";
  • the lock a level pin overrides through its summary, on "the lock leaves the floor as it is", 1322 against 1292;
  • the failing computation, at its reopen step, 3 warnings where it expects 4.

  The kv-unified case passes, since it pins the floor as it stands there, and so do the order cases.

• Each case against the change it covers, with each one-line change made in the built strategy by a pattern that had to match exactly once:

  • the attempts > 0 half removed from the relief rule fails exactly the cut-off case;
  • hadRefusal removed fails nothing, since recordMergeRejection adds to attempts (:7124) before it sets hadRefusal (:7131);
  • the whole check removed fails the refused-once and cut-off cases;
  • the failure-order check removed fails exactly the failed-call case;
  • counting no lock under kv-unified too fails exactly the kv-unified case;
  • counting locks under every strategy fails the five precedence cases;
  • dropping pins too outside kv-unified fails the three pin-over-lock cases;
  • the once-per-cause check removed, success no longer clearing the cause, or initialize no longer clearing it each fails exactly the failing-computation case.

• Lowering the floor, at 01f3a85107, by a probe outside this branch, with the same figures under kv-stable and kv-unified. In one case, the floor starts at 3,152. A raw pin over ten middle messages raises it to 4,372, and releasing the pin brings it back to 3,152. Removing the newest two messages then lowers it to 2,908, and removing two middle messages after that leaves it at 2,908. In a second case, in a test of its own, locking the same ten messages while raw, before any compile, gives 4,372, and releasing the locks gives 3,152, the first case's starting floor.

Not verified

• No real store. Every case is synthetic, on this branch's own harnesses.
• The failed-call case ends the pause by setting its backoffUntil to 0, in place of running the clock past the backoff.
• How far below a fitting plan the floor can sit outside kv-unified isn't measured. The cases show it at or under the plan where they compile.
• The widened list in OverBudgetDiagnostics.floorTokens' doc rests on the probe in Tests, not on a case in this branch. The probe lowers a floor by each of fewer messages, a released pin and a released lock, though not every removal lowers it.

---

• Changelog: this changes changelog.d/415-floor-headroom.added.md, from this branch.

Esther-2584 built and ran this change, and Alfred-2570 found where the floor missed a pin's precedence over a lock. Fiona-2757 wrote this description.