Found while writing the #179 regression, which failed for this reason rather than for the reason it was testing.
iris_execute builds at most ONE hint, first-writer-wins. execute_redirect_hint (a static steer based on the code text) is applied before enrich_abort runs, and enrich_abort then only fills the slot if resp.get("hint").is_none(). So whenever the code happens to mention %Dictionary — or any other redirect trigger — the runtime error's own explanation is dropped.
Real envelope, from the #179 work:
error: ERROR: <UNDEFINED> 9 RunUser+5^... ID
source_line_number: 3
source_line: "write ID"
hint: "Introspect classes with typed tools, not %Dictionary SQL: docs_introspect(...)"
The hint is true and it is about something else. The caller had a runtime abort on a specific line, and the one free-text field went to a generic steer they did not ask about. Note the structured fields survive — source_line, source_line_number, signal are all correct — so an agent reading fields is fine and an agent reading hint (most of them) is not.
Order is the whole bug: a %Dictionary mention is a property of the code, so it is knowable before execution and gets there first, while the abort explanation can only be built after. The more specific hint loses to the more generic one because the generic one is cheaper to compute.
Suggested shape
Carry more than one. Either an ordered hints array with the abort explanation first, or concatenate with the abort explanation leading. If only one may be returned, the abort-specific hint should win: the caller is looking at a failure, and "line 3, write ID, is what failed" acts on that failure while the redirect acts on a style preference.
Worth checking the same shape elsewhere — this is a first-writer-wins single slot, and every producer that writes it earlier than another is silently higher priority whether or not anyone chose that. Sibling-path pattern, as in #177/#178.
Not urgent. Filed with the evidence so it is not rediscovered from scratch.
Found while writing the #179 regression, which failed for this reason rather than for the reason it was testing.
iris_executebuilds at most ONEhint, first-writer-wins.execute_redirect_hint(a static steer based on the code text) is applied beforeenrich_abortruns, andenrich_abortthen only fills the slotif resp.get("hint").is_none(). So whenever the code happens to mention%Dictionary— or any other redirect trigger — the runtime error's own explanation is dropped.Real envelope, from the #179 work:
The hint is true and it is about something else. The caller had a runtime abort on a specific line, and the one free-text field went to a generic steer they did not ask about. Note the structured fields survive —
source_line,source_line_number,signalare all correct — so an agent reading fields is fine and an agent readinghint(most of them) is not.Order is the whole bug: a
%Dictionarymention is a property of the code, so it is knowable before execution and gets there first, while the abort explanation can only be built after. The more specific hint loses to the more generic one because the generic one is cheaper to compute.Suggested shape
Carry more than one. Either an ordered
hintsarray with the abort explanation first, or concatenate with the abort explanation leading. If only one may be returned, the abort-specific hint should win: the caller is looking at a failure, and "line 3,write ID, is what failed" acts on that failure while the redirect acts on a style preference.Worth checking the same shape elsewhere — this is a first-writer-wins single slot, and every producer that writes it earlier than another is silently higher priority whether or not anyone chose that. Sibling-path pattern, as in #177/#178.
Not urgent. Filed with the evidence so it is not rediscovered from scratch.