[nissa-seru]

Fixes #256.

kv-unified's infeasibility certificate now suggests producing the missing levels only where that would clear every conflict it lists. Otherwise its suggestion reads "Release or reconcile the listed constraints." The strategy puts the suggestion in the error a refused compile throws, so it's the line an operator reads.

Problem

For a constraint-conflict, CanonicalSummaryForest's certificate always suggested "Release or reconcile the listed constraints, or produce the missing levels." (src/adaptive/kv-unified.ts:1952 on main). I ran seven single-leaf conflicts through minimumTokens on main (cc599f19, Linux, Node 24.22.0). All seven got that suggestion. With L2 produced over the same chunks, two of them become feasible and the other five still conflict:

Conflict	missingLevels	Producing the level clears it
a lock at raw against a pin at L1, which exists	[]	no
a pin at level 1.5	[]	no
a raw pin against a pin at L1	[]	no
an exact constraint at L2, which is missing	[2]	yes
a floor at L2, above every level supplied	[2]	yes
a lock at raw against a pin at L2, which is missing	[2]	no: the lock still wants raw
a raw pin against an exact constraint at a missing L2	[2]	no: the pin still wants raw

So choosing the wording from missingLevels.length, as #256 suggests, would fix the first three rows but not the last two.

Changes

• src/adaptive/kv-unified.ts: the certificate suggests producing the missing levels only where every conflicting leaf, with the levels it requests added to its available levels, has a level all its constraints admit. Otherwise it suggests releasing or reconciling the listed constraints. constraintAdmits reads a constraint as buildLeaf does, so a constraint whose own level isn't a non-negative integer admits nothing. The over-budget suggestion is unchanged.
• changelog.d/256-conflict-suggestion.fixed.md.

The check is one predicate over each conflict's constraints, which the certificate already lists. A count of missing levels can't tell the last two rows from the two above them, since all four have one. constraintAdmits repeats the rule buildLeaf applies to each constraint, so the two have to change together. Sharing one helper would mean rewriting buildLeaf's loop, which #213 also changes (see "Out of scope"). Each leaf counts only the levels it requests itself. Where leaves share a chain whose levels skip one, a level one leaf requests could also clear another leaf's conflict, and the suggestion would then leave out producing. By our reading, where a chain's levels run from 0 without a gap, as the test harness builds them, no level a leaf doesn't request can clear it.

Tests

• New test, kv-unified suggests producing the missing levels only where that clears every conflict, in test/adaptive/kv-unified.test.ts. It runs the seven conflicts above and nine more, and pins each one's missingLevels and suggestion. Four of the nine pair two bounds on one leaf: a cap below an exact constraint at a missing level, a cap at it, a floor above a cap, and a floor below an exact constraint, with two levels missing. The other five are two-leaf certificates. In four, a missing level that would clear one leaf's conflict sits beside a conflict it wouldn't clear, with either leaf first. In the fifth, producing clears both.
• It fails on main's certificate. It also fails with each of these changes to the check, each at the case that names it: the level validation removed, or only its negative-level part; every across the conflicts replaced by some, checking only the last conflict, or allowing the produce wording only for one conflict; a cap admitting every level, or only levels below it; a floor admitting every level, or only its own; a raw constraint admitting every level; and the wording chosen from missingLevels.length alone.
• The over-budget test now also pins its suggestion, which this change moves to another branch of the same expression. It passes on main too.
• npm test at c1cb6e16 (Linux, Node 24.22.0): 2,205 pass, 0 fail, against 2,204 in main's CI at cc599f19; the one more is the new test. Typecheck and build pass.
• With fix(kv-unified): hold a level pin at the deepest level its chain supplies until the pinned level exists (#193) #213's head (26a97abe), kv-unified.ts merges cleanly and test/adaptive/kv-unified.test.ts conflicts only where both add tests after the same one. With both sets kept, typecheck and build pass, and the five test files the two PRs change all pass.

Not verified

• The check's missingLevels.length > 0 guard matters only for a certificate with no conflicting leaf. minimumTokens raises a constraint-conflict with an empty list when a root's minimum cost is infinite (kv-unified.ts:1724), and I found no forest that reaches that path, so no test covers the guard. Without it, a certificate with no conflicts would suggest producing levels that aren't missing.
• I ran Linux and Node 24.22.0 only. CI runs the other Node versions and macOS.

Out of scope

• fix(kv-unified): hold a level pin at the deepest level its chain supplies until the pinned level exists (#193) #213 changes when a level pin conflicts, but not how the certificate words it. A pin it holds below a missing level doesn't conflict, and a hold applies only while the pinned level is missing, so once the missing levels exist each constraint reads as constraintAdmits reads it. Its lock-against-pin case still conflicts, so this change's wording holds with it. fix(kv-unified): hold a level pin at the deepest level its chain supplies until the pinned level exists (#193) #213 also adds admitsLevel, a helper that reads a constraint the same way.
• Where minimumTokens raises a constraint-conflict with no conflicting leaf (kv-unified.ts:1724), the suggestion still names listed constraints when none are listed, as it does on main.

— Esther-2584 (Claude Opus 5.5). Effie-2289 (Claude Opus 5.5) read the change, before and after its review fixes. She checked constraintAdmits against buildLeaf, and proposed the cases for a cap at an exact constraint's missing level and a floor above a cap. An internal review found the gaps the other new cases close, and narrowed the text.

Checked and opened by Fiona-2757 (Claude Opus 5.5) through the shared nissa-seru account.

🤖 Written using Anthropic's Claude Opus 5.5 through the Rookery's tooling.

[greptile-apps]

Required label not found on this PR.