docs(spec): state the broken-sweep predicate as the first filter, not the detector

[os-trump]

Fixes#12722

TSDoc text only — no behaviour, no schema, no accept-set change. The diff filtered to non-comment changed lines is empty.

What was wrong

#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: both match, on every run, so "over N consecutive runs" does not rescue it either. #12721 corrected sys_automation_run's field descriptions and content/docs/automation/flows.mdx; its dispatch fenced packages/spec out, which left the identical unqualified claim standing in shipped TSDoc.

Three doc blocks in two files stated the three-clause query as the detector:

file	block	said
automation/execution.zod.ts	FlowRunSummarySchema	"... over consecutive runs is the broken-sweep signal"
automation/execution.zod.ts	the unmeasured field	"the broken-sweep query is ..."
integration/connector.zod.ts	effect-declaration rationale	"the broken-sweep alert is ..."

These ship in .d.ts, so a consumer reading the type got the sentence #12685 measurably disproved — and the schema doc is what a platform author actually reads.

What changed

Each block now states the predicate as the FIRST FILTER, not a verdict, and points at the per-node fold (nodes[] / gates[]) as the discriminator: a healthy skip is accounted for by a read the run performed (runs > 0 and selected > 0 in nodes[]), while a dead gate skips just as often with nothing behind it (runs: 0, or selected: 0).

The wording mirrors what #12721 landed, read from the tree (sys-automation-run.object.ts field descriptions and flows.mdx) rather than from the card's paraphrase — the whole point being that the two surfaces agree.

The unmeasured clause's own point survives, and is now explicit where it used to be implied: a run with uncountable effects has an INCOMPLETE acted count, not a zero one.

Pin check

The card asked whether these doc blocks are treated as pinned text before writing. Evidence, not a verdict:

• No pinned text. Each of the three sentences occurs exactly once in the repo — in its own source file. No test, gate or JSON artifact quotes them, so there was no pin to move, and nothing was rewritten to match new output.
• check:api-surface records names and kinds, not doc text ("FlowRunSummarySchema (const)"), so a doc-block edit cannot move it. Confirmed green regardless.
• The liveness ledger cites no path in either file. Its line-anchored evidence entries point into consumer source (engine.ts:1292 and similar), so no anchor drifted and none was repointed. check:liveness green.
• No generated artifact moved.check:generated reports all 14 up to date after the reword. These are mid-file, schema-attached blocks; only a file's @module block becomes a reference-page intro, and neither edit touched one. No .describe() string carried the claim, so gen:docs had nothing to regenerate.

Verification

Run on 0c746010 — this branch's head after merging origin/main. The union was re-run on that commit, not on an earlier tree.

• pnpm --filter @objectstack/spec check:generated — "All 14 generated artifacts are up to date" (covers check:docs, check:api-surface, check:authorable-surface, check:liveness, check:strictness-ledger, check:skill-refs).
• pnpm --filter @objectstack/spec typecheck — tsc --noEmit plus check:scripts-typecheck and check:test-typecheck, clean.
• vitest run src/automation/execution.test.ts src/integration/connector*.test.ts — 5 files, 125 tests passed.
• Gate families re-derived from the actual diff with scripts/pm/dispatch-gates.mjs (the dispatch's list was short by several): check:empty-state, check:variant-docs, check:doc-authoring, check:spec-parsed-alias, check:nul-bytes, check:comment-mask-adoption, check:doc-formula-expressions, check:cross-package-test-inputs, check:ci-filter-parity, check:merge-driver, check:published-files, check:type-source-resolution, check:test-source-alias, check:page-declaration-shape, check:slot-lookup, check:plugin-teardown-shape, plus the changeset family (check:empty-changeset, check:changeset-no-major, check:adr-0087-registration, check:objectui-changeset, check:changeset-gate-self-tests, check:pm-half-states, release-rehearsal-clone --self-test) — all green.

Declared narrowing: the test run was scoped to the five files covering the two edited sources rather than the full spec suite. The diff is comment-only and no test quotes the edited text, so no other suite can read it; CI runs the farm regardless.

Out of scope

packages/spec/src/automation/flow-function.zod.ts carries the same unqualified predicate on FlowFunctionEffectSchema ("the broken-sweep query"). It sits outside this card's declared file surface, so it is filed as #12900 and left standing here rather than corrected in passing — that surface additionally feeds a generated reference page and so needs gen:schema && gen:docs, which this PR deliberately does not run. #12900 remains open.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them. ⚠️1 changed file(s) yielded no anchor (packages/spec/src/integration/connector.zod.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/src/integration/connector.zod.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 126 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 20821802855ea03d637a6a828be8e9ea12a652b5 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 695cd2373ac0f0a08e44fb5396d2f516636a1684 — the merge of head 0c746010a9e183934a349be89d820ce2f411925c into base 20821802855ea03d637a6a828be8e9ea12a652b5, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 695cd2373ac0f0a08e44fb5396d2f516636a1684 && git checkout 695cd2373ac0f0a08e44fb5396d2f516636a1684
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 20821802855ea03d637a6a828be8e9ea12a652b5 0c746010a9e183934a349be89d820ce2f411925c && git checkout -B drift-repro 20821802855ea03d637a6a828be8e9ea12a652b5 && git merge --no-ff 0c746010a9e183934a349be89d820ce2f411925c
node scripts/docs-audit/affected-docs.mjs --json 20821802855ea03d637a6a828be8e9ea12a652b5

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.