Filed unassigned by the dev on #12900. Dedupe search run: one targeted search against the broken-sweep / spec-TSDoc family; positive control satisfied in the same session (#12900, #12722 and #12685 all came back), no existing card for these three mentions.
#12685 established, with a measured A/B pinned in run-summary.test.ts, that selected > 0 AND acted = 0 AND unmeasured = 0 cannot separate a healthy idempotent sweep from a dead gate. #12721 corrected sys_automation_run's field descriptions and content/docs/automation/flows.mdx; #12722 corrected automation/execution.zod.ts (the FlowRunSummarySchema block, ~:168, and the unmeasured block, ~:193) and integration/connector.zod.ts; #12900 corrected automation/flow-function.zod.ts. Each of those changes was fenced to the doc blocks its dispatch named, so three mentions in the same two files were left standing rather than fixed in passing.
The three mentions
1. packages/spec/src/automation/execution.zod.ts ~:57-61 — the unmeasuredEffect rationale, a doc block #12722 did not name (it corrected the two blocks further down the same file). Ships in .d.ts:
... when the action declares nothing about whether it reads or writes, 0 understates a write and 1 overstates a read. Both are worse than saying so — an understated 0 fires the broken-sweep alert on a healthy run until operators learn to ignore it, and an overstated 1 makes the alert never fire at all, which is the original bug back again.
"fires the broken-sweep alert" / "makes the alert never fire" is the alarm vocabulary #12721 replaced everywhere it corrected. Note the block is not merely stylistically off: "fires ... on a healthy run until operators learn to ignore it" is the exact muting failure #12685 names, stated here as if it were peculiar to an understated 0 — when after #12685 it is what the predicate does on every healthy idempotent sweep, declared effects or not. The sibling block ~40 lines below now says "a filter, not a verdict", so the same file disagrees with itself.
2. packages/spec/src/automation/execution.test.ts ~:210-211 — a test comment:
A connector-driven run: acted: 0 is INCOMPLETE, not zero, and the broken-sweep query has to be able to tell.
"has to be able to tell" is the claim #12685 disproved. The assertion under it is correct and should stay (it pins that unmeasured is carried distinctly from acted); only the comment's justification is wrong.
3. packages/spec/src/automation/flow-function.test.ts ~:192-194 — a test comment that mirrors, almost word for word, a source sentence #12900 reworded:
... and the failure is the quiet direction: the function registers, runs, and its writes are counted as none, keeping #4354's broken-sweep query silent on the one run that needed it.
After #12900 the source sentence it mirrors says "filter"; the comment still says "query ... silent".
A second, separate question the same reading raised
Worth stating because it is not the same defect and should not be swept in with a vocabulary pass. Two sentences describing a misspelled effect key state the consequence in a direction that reads backwards, in both the source and its mirroring test comment — packages/spec/src/automation/flow-function.zod.ts ~:144 and the history string ~:176, plus mention 3 above:
the function is registered, it runs, and its writes are counted as none, so #4354's broken-sweep filter stays silent on the one flow that needed it
Reading the mechanism forward: a lost effect: 'writes' declaration means the step reports no unmeasuredEffect, so the run reports unmeasured: 0 with acted: 0 and selected > 0 — which SATISFIES the three-clause filter. The run therefore enters the candidate set rather than escaping it, which is a false positive, not silence. That is also how the same file's @module block states it ("A function that writes anyway makes its run under-report — selected: 30, acted: 0 on a run that wrote 30 invoices, which reads exactly like the broken sweep #4354 exists to detect"). So either the two sentences are stating the direction backwards, or "the one flow that needed it" means something narrower that is not spelled out (for instance a flow whose only work is done inside the function, so selected stays 0 and the filter is quiet regardless of the declaration).
This was deliberately NOT resolved in #12900: that card's remit was the predicate-as-detector claim, and the vocabulary reword there leaves each sentence's own claim exactly as it was, whichever reading is correct. It needs someone who can settle the intended meaning rather than a mechanical pass.
Why it is worth a card
Same severity argument the parent cards were graded on: an operator wiring an alert to a documented predicate, watching it fire during normal operation, and muting it leaves a dead sweep unmonitored while looking monitored. Mention 1 ships in .d.ts and is what a platform author reads. Mentions 2 and 3 are comments, so they cost less directly — but they are the sentences the next author reads before touching these blocks, and a test comment that still asserts the disproved claim is how the claim comes back.
Related: #12900, #12722, #12721, #12685, #4354, #4347, #4396.
Filed unassigned by the dev on #12900. Dedupe search run: one targeted search against the broken-sweep / spec-TSDoc family; positive control satisfied in the same session (#12900, #12722 and #12685 all came back), no existing card for these three mentions.
#12685 established, with a measured A/B pinned in
run-summary.test.ts, thatselected > 0 AND acted = 0 AND unmeasured = 0cannot separate a healthy idempotent sweep from a dead gate. #12721 correctedsys_automation_run's field descriptions andcontent/docs/automation/flows.mdx; #12722 correctedautomation/execution.zod.ts(theFlowRunSummarySchemablock, ~:168, and theunmeasuredblock, ~:193) andintegration/connector.zod.ts; #12900 correctedautomation/flow-function.zod.ts. Each of those changes was fenced to the doc blocks its dispatch named, so three mentions in the same two files were left standing rather than fixed in passing.The three mentions
1.
packages/spec/src/automation/execution.zod.ts~:57-61 — theunmeasuredEffectrationale, a doc block #12722 did not name (it corrected the two blocks further down the same file). Ships in.d.ts:"fires the broken-sweep alert" / "makes the alert never fire" is the alarm vocabulary #12721 replaced everywhere it corrected. Note the block is not merely stylistically off: "fires ... on a healthy run until operators learn to ignore it" is the exact muting failure #12685 names, stated here as if it were peculiar to an understated
0— when after #12685 it is what the predicate does on every healthy idempotent sweep, declared effects or not. The sibling block ~40 lines below now says "a filter, not a verdict", so the same file disagrees with itself.2.
packages/spec/src/automation/execution.test.ts~:210-211 — a test comment:"has to be able to tell" is the claim #12685 disproved. The assertion under it is correct and should stay (it pins that
unmeasuredis carried distinctly fromacted); only the comment's justification is wrong.3.
packages/spec/src/automation/flow-function.test.ts~:192-194 — a test comment that mirrors, almost word for word, a source sentence #12900 reworded:After #12900 the source sentence it mirrors says "filter"; the comment still says "query ... silent".
A second, separate question the same reading raised
Worth stating because it is not the same defect and should not be swept in with a vocabulary pass. Two sentences describing a misspelled
effectkey state the consequence in a direction that reads backwards, in both the source and its mirroring test comment —packages/spec/src/automation/flow-function.zod.ts~:144 and thehistorystring ~:176, plus mention 3 above:Reading the mechanism forward: a lost
effect: 'writes'declaration means the step reports nounmeasuredEffect, so the run reportsunmeasured: 0withacted: 0andselected > 0— which SATISFIES the three-clause filter. The run therefore enters the candidate set rather than escaping it, which is a false positive, not silence. That is also how the same file's@moduleblock states it ("A function that writes anyway makes its run under-report —selected: 30, acted: 0on a run that wrote 30 invoices, which reads exactly like the broken sweep #4354 exists to detect"). So either the two sentences are stating the direction backwards, or "the one flow that needed it" means something narrower that is not spelled out (for instance a flow whose only work is done inside the function, soselectedstays 0 and the filter is quiet regardless of the declaration).This was deliberately NOT resolved in #12900: that card's remit was the predicate-as-detector claim, and the vocabulary reword there leaves each sentence's own claim exactly as it was, whichever reading is correct. It needs someone who can settle the intended meaning rather than a mechanical pass.
Why it is worth a card
Same severity argument the parent cards were graded on: an operator wiring an alert to a documented predicate, watching it fire during normal operation, and muting it leaves a dead sweep unmonitored while looking monitored. Mention 1 ships in
.d.tsand is what a platform author reads. Mentions 2 and 3 are comments, so they cost less directly — but they are the sentences the next author reads before touching these blocks, and a test comment that still asserts the disproved claim is how the claim comes back.Related: #12900, #12722, #12721, #12685, #4354, #4347, #4396.