feat(drain)!: bound the advisory payload by a per-rule cap and a token budget

[wenzowski]

Closes CLOUD-82.

CLOUD-79 landed the drain's delivery half; this is its emission half. The
renderer had no ceiling — a rule firing on two hundred identities inside one
changed scope spent two hundred lines of the agent's context, and nothing
asserted a bound on the payload at all. cycle is now three named stages
(select → cap → clamp), because the cap is a decision about a set: a renderer
that emitted as it walked could not know an eleventh identity for the same rule
was still coming.

Two bounds, and the store can tell them apart

Bound	What it is a statement about	Journalled as
[drain] cardinality_cap (default 10)	the rule — a check firing on eleven distinct identities in one changed scope is a rule-health signal, not a to-do list	over-cardinality-cap, the counter CLOUD-78's sampled review reads
[drain] token_budget (default 1024)	this boundary — the finding is unchanged, the payload just had no room	drain-suppressed, reconsidered next drain

A rule over the cap contributes one rule R: K+ findings line and no entries. A
clamped payload closes with budget: N findings withheld. The estimate is
budget::estimate_tokens, the same one [budget] gates instruction files with,
rather than a second estimator that could disagree about what a token is.

Both keys sit on the existing [drain] table and inherit its unlayered
treatment: they bound the engine's own output, so there is no raise-only reading
for a local file to weaken. 0 is the honest bottom of each range, not a
disabled feature.

Salience is independent of the count, structurally

Lines are ordered by tier, then rule, then fingerprint. The occurrence count is
deliberately not a sort key — that is CLOUD-80's no-escalation law made
structural rather than remembered, and it is what
a_rising_count_never_moves_a_finding_ahead_of_a_stronger_tier pins.

The group re-raise

Renders old->new against what this session's last drain actually said
(WakeState::counts), because the store carries no count anchor and the honest
anchor for "worth saying again" is what the agent was last told. Only emitted
identities are remembered, so a capped rule anchors nothing and cannot make the
next drain's re-raise silent. A count that fell renders plainly: a ratchet is not
a re-raise, because re-raising on incremental fixing punishes the fix.

One identity's occurrences are a count by construction, so a 500→501 re-raise is
one line with one in-scope pointer — 501 pointers is unreachable, not merely
avoided.

§7

Renderer unit tests in src/drain.rs, end-to-end over the compiled binary in
tests/advisory_drain.rs (not tests/cli.rs, which the Ready block named
before that file was under concurrent edit):

• (a) budget: the rendered payload is at or under the configured budget, and the
  same assertion over the unclamped set fails — so the fixture is shown to
  actually overflow;
• (b) K+1 identities in one rule render exactly one summary line and no entries;
  E2E, two caps in batten.toml produce two payloads, so the key is live;
• (c) a 500→501 fixture emits 500->501 and one in-scope pointer;
• (d) two renders of one snapshot are byte-identical whatever the input order;
• (e) a rising count reorders nothing and leaves the record's tier untouched.

Plus: a zero budget says nothing rather than one thing; the capped and the
clamped sets are disjoint, so no identity is journalled under two reasons.

Notes

• Marked !: DrainConfig/WakeState gain fields and cycle/drained change
  arity. batten.toml is unchanged for anyone who declared no new key.
• Operator diagnostics (volume, per-reason suppression counts) go to the verbose
  batten: rung, never into the agent payload. Routing them into systemMessage
  proper rides CLOUD-44's per-host emitter shims, which the Ready block states
  does not block this.
• fuzz/Cargo.lock catches up to v0.0.70, which the release commit left behind.

---

Generated by Claude Code

[linear-code]

CLOUD-82 Keep advisory drain output pointer-only under a token budget

Why
The advisory drain must emit pointer-only information and stay within a test-asserted token budget. Operator diagnostics should go through a zero-token channel for the agent.

Acceptance

• Drain output is pointer-only
• Drain output stays within a test-backed token budget
• Operator diagnostics are emitted through systemMessage or equivalent zero-token operator channel

---

Refinement from the identity decision (CLOUD-123) — this issue owns the cardinality cap:

• Per-rule cardinality cap + summary-line-on-overflow live here (previously ownerless): if one rule exceeds K distinct identities in a drain, emit rule R: K+ findings as one pointer-only summary line, never K entries.
• A group re-raise (count increase on a multiset identity) emits identity + old→new count + pointers only for instances inside current changed-scope hunks, capped by this budget — never the full instance list (a 500→501 re-raise must not emit 501 pointers).
• Duplicate-occurrence counts never escalate a severity tier or shorten a repeat interval (CLOUD-80's no-escalation law).
• Per-rule suppression-rate counter feeds rule-health telemetry (Tricorder's probation model) via CLOUD-78's sampled review.

---

Refinement — Ready (the drain's emission contract: pointers, caps, and a test-asserted token budget)

Refinement gate: Definition of Ready & Done. This body carries only specializations.

• Source of truth (§1). The drain renderer in crates/batten plus one budget key in the batten.toml config types — the budget is config, defined once in the loader's schema; the renderer is the only place emission shape is decided.
• Computable predicate (§2). Not expressible as a batten.toml rule — the rule model scans files, and this bounds the engine's own output — so it grows the drain capability. Every acceptance criterion is a test predicate: the rendered payload's token estimate stays at or under the configured budget; a rule exceeding K distinct identities renders one rule R: K+ findings summary line; a group re-raise emits identity, old→new count and only in-scope pointers. Gated by §7 under mise run test (hk gate + CI).
• Effect (§3). No new command and no declared-effect change; rendering is a pure function of the store snapshot.
• Output & exit (§5). Pointer-only (identity hash, path:line, counts), byte-stable and salient-first under the budget; a 500→501 re-raise never emits the instance list. Operator diagnostics (volume, timing, per-rule suppression rates) go to the host's zero-token operator channel — systemMessage on the claude-code emitter — never into the agent payload.
• Commit / bump (§6). feat → minor.
• Test obligation (§7). (a) a budget test: the token estimate of the rendered payload is at or under the configured budget, and the test fails when it is over; (b) K+1 identities in one rule render exactly one summary line; (c) a re-raise fixture emits old→new count and only pointers inside current changed-scope hunks; (d) two renders of one snapshot are byte-identical; (e) a duplicate-count increase leaves tier and repeat interval unchanged. Renderer unit tests plus E2E over the compiled binary (tests/cli.rs) for the emitted bytes.
• Blockers (§8). blockedBy CLOUD-79 (this is the emission half of that drain — there is no payload to bound until it exists); relatedTo CLOUD-44 — the zero-token operator channel rides the per-host emitter shims, but budget and pointer discipline are asserted over the rendered payload with no host attached, so CLOUD-44 does not block. Refinable now; implement after CLOUD-79 lands.

Review in Linear

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[wenzowski]

/fast-forward