fix: explain why an element reference stopped resolving - #84
Merged
Conversation
Closes #16. Element references are reissued by every inspection, so a reference from an earlier call silently stops working — including the common case where a narrow --context summary returns eight controls after a --context full returned two hundred. The agent got a bare ELEMENT_NOT_FOUND with nothing to distinguish 'this expired, re-inspect' from 'this never existed', which is the difference between recovering and retrying a dead reference. Failures now name the cause: expired, unknown, or detached. Region lookups do the same. Region references keep their existing lifetime on purpose. They stay resolvable across inspections because the documented outline-then-scope workflow depends on it, but the map holding them was never cleared and kept strong references to detached nodes for the lifetime of the page. It is now bounded at 256, oldest first. P1 documents the asymmetry rather than leaving it as folklore, and the runtime suite asserts each failure mode plus the cross-inspection region workflow.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #16.
The problem
snapshot()reissues element references on every call, so a reference from an earlier inspection silently stops resolving. The common case is nasty: run--context full(200+ controls), then--context summary(8 controls), and every reference from the first call is now dead. The agent received:Nothing there distinguishes "this expired, re-inspect" from "this never existed" — which is exactly the difference between recovering and retrying a dead reference forever.
The fix
Failures name the cause:
expiredunknowndetachedBoth
ELEMENT_NOT_FOUNDandREGION_NOT_FOUNDcarry it. Host error-code mapping is unchanged (it matches on the prefix), so this is additive on the wire.The asymmetry is deliberate
I kept element and region lifetimes different, and documented why rather than "fixing" it:
@eNis latest-inspection-only. That is already what the skill teaches, and making references durable would mean holding every control on every page.@rNstays resolvable across inspections, because the documented outline-then-scope workflow depends on it — take@r4from an outline, then scope repeatedtext/actionscalls to it. An existing test covers that workflow; changing it would have broken a shipped contract.What was wrong with regions is that the map was never cleared, holding strong references to detached nodes for the lifetime of the page. It is now bounded at 256, oldest-first — a leak fix, not a semantic change.
Verification
Ran the runtime suite locally (this one I can run — it is Node-only): stale reference reports
expired, unknown reference reportsunknown, a fresh reference still resolves, and the cross-inspection region workflow still works. The pruning numbers are unchanged (48,428 → 895 bytes), so the headline metric did not regress.P1 gains a Reference lifetime section so this is documented behaviour rather than folklore.