Two customer-facing documentation pages state that before* hooks fire once for the batch. They have been false since #5574 / Addendum II.
Filed by the domain:spec execution seat, session session_01MkQhmuuJAVDjmeWNixwDDH, 2026-09-13T08:57Z, surfaced by the at-tier post-hoc review of PR #17249. ⛔ Pre-existing — not that PR's defect. ⛔ No domain:* or priority:* applied.
The two lines
content/docs/data-modeling/formulas.mdx:204 — says previous is "unbound in before* hooks, which fire once for the batch".content/docs/api/data-flow.mdx:311 — says "The after* events instead dispatch once per matched row", implying the before* events do not.
Both describe a dispatch model the engine stopped using. before* hooks dispatch per row, and previous is bound per row — which is the whole premise of the ruling (#16074) that PR #17249 wrote into the contract.
Why these two lines are worth a card
They are not internal comments. They are the pages an author reads before writing a hook, and they teach the opposite of what the engine does on the one axis that decides how the hook must be written. An author who believes before* fires once for the batch will write a loop, or will not write the per-row guard the contract now expects, and nothing will tell them otherwise until the behaviour surprises them in production.
The sibling contract text was just corrected upstream; leaving these two pages behind means the protocol says one thing and the docs another, on the same release.
Provenance
Flagged as finding F5 by the director seat's review, carried forward as "docs lane", and never filed — a semantic issue search found no existing card (⚠️ the REST search endpoint returned total: None even on a control query in this session, so "no card found" rests on the semantic search alone and is not a proven zero). Check for a duplicate before starting.
The repair
Correct both sentences to the per-row dispatch model, and check the surrounding paragraphs rather than only the two quoted lines — a sentence that survived one retirement usually has neighbours that did too.
Generated by Claude Code
Two customer-facing documentation pages state that
before*hooks fire once for the batch. They have been false since #5574 / Addendum II.Filed by the
domain:specexecution seat, sessionsession_01MkQhmuuJAVDjmeWNixwDDH, 2026-09-13T08:57Z, surfaced by the at-tier post-hoc review of PR #17249. ⛔ Pre-existing — not that PR's defect. ⛔ Nodomain:*orpriority:*applied.The two lines
content/docs/data-modeling/formulas.mdx:204— sayspreviousis "unbound inbefore*hooks, which fire once for the batch".content/docs/api/data-flow.mdx:311— says "Theafter*events instead dispatch once per matched row", implying thebefore*events do not.Both describe a dispatch model the engine stopped using.
before*hooks dispatch per row, andpreviousis bound per row — which is the whole premise of the ruling (#16074) that PR #17249 wrote into the contract.Why these two lines are worth a card
They are not internal comments. They are the pages an author reads before writing a hook, and they teach the opposite of what the engine does on the one axis that decides how the hook must be written. An author who believes
before*fires once for the batch will write a loop, or will not write the per-row guard the contract now expects, and nothing will tell them otherwise until the behaviour surprises them in production.The sibling contract text was just corrected upstream; leaving these two pages behind means the protocol says one thing and the docs another, on the same release.
Provenance
Flagged as finding F5 by the director seat's review, carried forward as "docs lane", and never filed — a semantic issue search found no existing card (⚠️ the REST search endpoint returned
total: Noneeven on a control query in this session, so "no card found" rests on the semantic search alone and is not a proven zero). Check for a duplicate before starting.The repair
Correct both sentences to the per-row dispatch model, and check the surrounding paragraphs rather than only the two quoted lines — a sentence that survived one retirement usually has neighbours that did too.
Generated by Claude Code