fix(service-automation): the broken-sweep predicate is a first FILTER, not the detector

[os-litant]

Fixes#12685

Documentation-contract fix. No counter, no schema, no engine behaviour changes — the run summary is correct and untouched, and hotcrm's flow-run-summary.test.ts pin (both shapes trip the run-level predicate) moves nothing, because the counts it reads are unchanged.

The wrong claim

sys_automation_run.acted_count advertised selected_count > 0 AND acted_count = 0 AND unmeasured_count = 0 as the broken-sweep signal, unqualified. The card's measured A/B shows it cannot separate a healthy idempotent sweep from a dead gate — both fire — and "over N consecutive runs" does not rescue it, because the healthy steady state is persistent rather than transient.

Reproduced here on the platform's own engine (run-summary.test.ts), on one graph pair whose two shapes differ only in where the gate sits relative to the lookup:

run	totals	the run-level filter	the lookup behind the gate	gate skips
healthy steady state — every stalled deal already nudged	selected 6, acted 0	matches	runs: 3, selected: 3	3
dead gate — gate in front of the lookup, never opens	selected 3, acted 0	matches	runs: 0	3
wrong gate — lookup runs, finds nothing, gate closes anyway	selected 3, acted 0	matches	runs: 3, selected: 0	3
genuinely idle — nothing stalled	selected 0, acted 0	quiet	—	0

What changed

• acted_count states the predicate as the first filter, says in one sentence why it is not a verdict, and names the discriminator: a healthy skip is accounted for by a read this run performed (the lookup the gate depends on shows runs > 0 and selected > 0 in summary_json.nodes[]), while a dead gate skips just as often with nothing behind it (runs: 0, or selected: 0).
• skipped_count points at the same fold — gates[] names which edge closed and how often, nodes[] says whether the lookup behind it found anything. Its existing "names the gate as the suspect" line now says what convicts or clears it.
• unmeasured_count keeps its own point (why the third clause exists) and calls the query a filter rather than an alert.
• The block comment over the four columns records the measurement so the next reader does not re-derive it.
• content/docs/automation/flows.mdx carries the same correction for the operator wiring the alert: the measured table above, why consecutiveness does not help, how to read the fold, and the two authoring shapes that decide how good a sweep's signal can be (exclude already-handled records in the query where it can be expressed; otherwise make the "already handled?" check a real lookup node so the run records the evidence). It also states the limit plainly — a gate deciding on a field the run already read leaves no second read to account for its skips, and there the summary cannot separate a correct decision from a stuck one.

The discriminating data was already shipped; nothing new is measured, and no detector is implemented in platform code — the platform documents the rule and ships the data, as before.

The test is a pin on the sentence, not a new predicate

run-summary.test.ts gains an engine-driven pair asserting that both shapes match the run-level filter and that the per-node fold separates them. The rule lives in a local test helper, deliberately: it makes the shipped description executable in the repo that ships it, without giving the platform a detector it does not have. The existing fake data engine learned one more answer (what an idempotency lookup finds) rather than a second double being added beside it.

Verification

Union derived from the actual changed set with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (4 paths; the script reads the merge base itself). Exit codes captured before any pipe; the verdict lines below are the gates' own.

• pnpm --filter @objectstack/service-automation test — 91 files, 1091 tests passed.
• pnpm --filter @objectstack/service-automation exec vitest run src/run-summary.test.ts — 40 passed.
• Reverse verification: flipping the dead-gate discriminator assertion to its opposite turns exactly that one test red (1 failed | 39 passed), restored from HEAD with git diff HEAD empty afterwards. The healthy/dead pair is mutually falsifying — a helper stuck at either verdict fails one half.
• pnpm --filter @objectstack/service-automation exec tsc --noEmit — 3 errors, the frozen ledger count, all pre-existing TS2341 in nested-region-parity.test.ts; the shrink-only ratchet does not move. --listFiles confirms both edited files are in that program, so the reading covers them.
• node scripts/check-type-check-coverage.mjs — OK — 65/78 workspace packages type-checked (plus the root), 13 in the DEBT ledger, 1 exempt.
• pnpm lint (repo-wide eslint . --no-inline-config) — green, whole repo, no narrowing claimed.
• Derived gates, all green: check:changeset-gate-self-tests, check:objectui-changeset, check:pm-half-states, check-adr-0087-registration, check-changeset-no-major, check-empty-changeset, release-rehearsal-clone --self-test, check:nul-bytes, check:doc-anchors, check:doc-authoring, check:docs-single-h1, check:docs-redirects, check:docs-audit-scope, check-doc-frontmatter, check-doc-route-spelling, check-docs-section-name, check-section-landing-index, check:role-word, check:published-readme-links, check:react-page-adapter-contract, check:doc-formula-expressions, check:doc-security-posture, spec check:docs / check:empty-state / check:liveness / check:strictness-ledger / check:variant-docs / check:skill-examples, check:engine-double-contract, check:where-matcher, check:query-options-erasure, check:objectql-double-limit, check:cross-package-test-inputs, check-ci-filter-parity, check-comment-mask-adoption, check:page-declaration-shape, check:slot-lookup, check:published-files, check:test-source-alias, check:type-source-resolution, check-plugin-teardown-shape, docs-audit/check-affected-docs, docs-audit/check-drift-comment.
• check:skill-examples first refused with packages/client-react/dist holds no .d.ts — NOT MEASURED, not red. Built @objectstack/client-react and re-ran: 260 prose examples type-check across 3 surfaces. The four marked blocks on this page are outside the edited region.
• node scripts/pm/check-half-states.mjs — exit 3, PREREQUISITE NOT MET (no valid GitHub credential in this container). NOT MEASURED, and unrelated to this diff: it sweeps the issue board, not the tree.

Ratchet family re-run on the pushed head 48940d54c (tree identical to the verified 67c01af5f, proven by an empty git diff between them).

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, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• 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 — 5 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 4af6c4419d7669a56940ec8e7adbb133829fcbde → packageMentionDocs.

Which tree this was computed on

This run read content/docs from cde974a392c300a282ffced0b2d61aede2b13113 — the merge of head 48940d54c74c39da9bf796416b7651a2a1f8bb08 into base 4af6c4419d7669a56940ec8e7adbb133829fcbde, 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 cde974a392c300a282ffced0b2d61aede2b13113 && git checkout cde974a392c300a282ffced0b2d61aede2b13113
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4af6c4419d7669a56940ec8e7adbb133829fcbde 48940d54c74c39da9bf796416b7651a2a1f8bb08 && git checkout -B drift-repro 4af6c4419d7669a56940ec8e7adbb133829fcbde && git merge --no-ff 48940d54c74c39da9bf796416b7651a2a1f8bb08
node scripts/docs-audit/affected-docs.mjs --json 4af6c4419d7669a56940ec8e7adbb133829fcbde

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