`Sweeper::reclaimable()`'s carve-out is wider than the resume it protects — a legacy record failed at a structure-only position is immortal

[TBarregren]

This was generated by AI during triage.

Split out of the analysis on #25, which deliberately declined to widen itself to cover this.

The finding

Sweeper::reclaimable() and Dispatcher::is_resumable() ask different questions about the same record, and the sweep's carve-out is strictly wider than the resume it exists to protect.

• The sweep spares a record when is_pre_adaptation_stall() is true.
• The Dispatcher re-drives one only when is_pre_adaptation_stall() && adapted_budgets() !== null && has_free_slot().

adapted_budgets() is null whenever stalled_budget() returns null — which it does for a structure-only position and for the artifact's sealed index, since neither spends a shrinkable bound. So a legacy (pre-0.6.0) record failed at one of those positions is spared by the sweep forever and re-driven by nobody. It is immortal residue.

This predates the work on #25. It is the same root cause — one predicate serving two callers whose needs differ — which is why it surfaced while analysing that ticket rather than on its own.

What is_pre_adaptation_stall()'s own docblock says

"This is the one definition of that record shape, because two callers must agree about it exactly: the Dispatcher re-drives it, and the TTL sweep spares it while reclaiming every other failed record. A disagreement would have the sweep delete the very container the resume is for."

The docblock anticipates disagreement in one direction — the sweep deleting what the resume needs — and guards against it. The other direction is unguarded, and is the one that actually happens: the sweep sparing what the resume will never come for.

What has to be decided

Whether the sweep should spare a record it can establish is resumable, rather than one merely shaped like a pre-adaptation stall. That is the obvious answer and it is not obviously safe, because the two callers evaluate at different moments: has_free_slot() is a live condition, so a record that is not resumable right now may be minutes later, and a sweep reading is_resumable() verbatim would reclaim a record purely because the slot happened to be busy.

So the fix is probably not "make the sweep call is_resumable()" but "give the resume condition a time-invariant half that both callers can share, with the live half left to the Dispatcher alone". Whoever picks this up should establish that split rather than assume it.

Scope note

The record class involved is exactly the one ADR-0015's penultimate Consequences bullet describes as a back-compatibility cluster that must retire as one piece. Anything done here must leave that cluster reachable — this is a correction to how one predicate is consumed, not a step towards retiring it early.

Blocked by

Nothing technically. Sequence it after #25's follow-up lands, which removes one class of record from the leak (a legacy record that throws) and would otherwise be re-solved here.

[TBarregren]

This was generated by AI during triage.

Analysis this was split out of: #25, section 6.

[TBarregren]

This was generated by AI during triage.

Closed by decision — the carve-out is being deleted rather than narrowed (#52)

Triaged 2026-08-21. The finding is correct; it was verified against the code before this decision was taken. It is closed because the record class it protects is going away entirely, which makes narrowing the carve-out work spent on a path that is itself being removed.

What the verification established

The mechanism is exactly as described: Sweeper::reclaimable() spares on is_pre_adaptation_stall() alone, while Dispatcher::is_resumable() additionally requires adapted_budgets() !== null && has_free_slot(), and stalled_budget() returns null for a structure-only position and for the sealed index. Those records are spared forever and re-driven by nobody.

Three things the ticket left open:

• Both halves are reachable, not only the index half. Structure-only tables shipped in 0.2.0, in the coordinated Add GET /environment: read-only site & runtime facts (PHP/DB versions, resolved defines) for the kntnt-wp-skills cutover #15/Extraction: support structure-only (schema, no rows) tables — carry every table's structure but only some tables' data #16/Add GET /extractions: list the caller's own non-terminal jobs (stranded-job recovery for the cutover health check) #17 trio — well before the 0.6.0 adaptation. A 0.5.1-or-earlier record can therefore carry a non-empty structure_only list and stall on it, so that half is not vacuous.
• The stated sequencing blocker is clear. Record what an opaque failure actually was — a failed job's error is null and the poll reports a fallback sentence #25's follow-up landed in 0.7.0: with_thrown_failure() writes error as null, so a throw fails the first test in is_pre_adaptation_stall() and is reclaimed like any other failure. That class of record is already out of the leak.
• The current release cannot feed the leak. budget_keys_present defaults to true and job creation never overrides it; the property's own docblock states it is true for every object this release constructs and false only where from_array() rebuilt a 0.5.1-or-earlier write. The leak is fed exclusively by records an unsupported release left behind.

Why it is closed rather than fixed

This project carries no backwards compatibility below 1.0, and the plugin will carry no mechanism for cleaning up what an older release left on disk.

The ticket's own proposal — give the resume condition a time-invariant half both callers can share — is sound, and the split turned out to be tractable: adapted_budgets()'s only external input is Artifact_Builder::budgets(), a pure function of the job and the Config seam, and Sweeper already holds Config. It would have worked. It is simply the wrong target now.

The carve-out is not being narrowed. It is being removed with the rest of the cluster ADR-0015 enumerates: #52.

With no carve-out there is no immortal record, so this defect cannot exist. And the removal disposes of the residue as a side effect: a legacy record left on a live site falls under the ordinary TTL and lifetime windows and is reclaimed by the next sweep that reaches it — no migration, no cleanup path, nothing to remember to run.

The scope note about ADR-0015's cluster still binds, and #52 honours it in the only way that remains: the cluster retires as one piece, all of it, rather than one member ahead of the others.