feat(brain): surface cost_unit aggregation in event_counts

[ohdearquant]

Summary

• Closes the ADR-103 Amendment 1 read-side gap: PR feat(runtime): emit resource.cost_unit per ADR-103 Amendment 1 #927 has stamped payload.resource.cost_unit on every successful verb dispatch's audit event since it merged, but brain.event_counts (ADR-103 Stage 1, Read surface: windowed event counts (per-actor, per-kind) + section co-usage aggregates #724 Ask A) never read or surfaced it.
• Extends brain.event_counts to sum payload.resource.cost_unit into two new response fields, total_cost_unit and cost_unit_by_verb, following the same aggregate-in-handler / omit-when-empty style already used by counts_by_kind / counts_by_actor / counts_by_work_class.
• This is additive per ADR-103 Amendment 1: no existing field or behavior changes. Events with no resource.cost_unit (pre-feat(runtime): emit resource.cost_unit per ADR-103 Amendment 1 #927 events, or errored/denied dispatches, per Amendment 1's "absence has exactly two meanings" rule) simply do not contribute to either sum.
• Updates the verb's help description, its internal doc comment, and the event_counts sections of docs/guide/api-reference.md and AGENTS.md's brain-pack verb table.

Closes #955

Downstream

Flagging for the lambda gate read: #931 (measured per-verb weights table) is the consumer waiting on this read path to validate/calibrate cost_unit weights against real dispatch volume.

Test plan

• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets -- -D warnings
• cargo test -p khive-pack-brain (235 tests, including 5 new/updated event_counts cost_unit tests: sum + per-verb split, absence handling, window filtering, saturating overflow)
• cargo test -p khive-runtime (907 tests)
• RUSTDOCFLAGS="-D warnings" cargo doc --no-deps -p khive-pack-brain

🤖 Generated with Claude Code

[ohdearquant]

APPROVE-WITH-FIXES

Findings: 0 Blocker, 0 High, 0 Medium, 1 Low

[Low] Update the stale work_class producer comment

Evidence: crates/khive-pack-brain/src/handlers.rs:2320 calls
payload.resource.work_class a not-yet-emitted shape, and
crates/khive-pack-brain/src/handlers.rs:2322 says that no producer writes it.
That is no longer true: crates/khive-runtime/src/cost_unit.rs:158 constructs
the successful-dispatch resource object with work_class, and
crates/khive-runtime/src/pack.rs:1379 persists it on successful audit rows.
The same PR correctly documents the live shape in
docs/guide/api-reference.md:693.

Why this matters: this helper documents the only two input shapes for
counts_by_work_class; saying the audit-row path is hypothetical contradicts
the runtime contract and would mislead the next maintainer extending the
event reader.

Suggested fix: revise the helper documentation to say that audit rows already
use payload.resource.work_class, while retaining the documented phase-payload
precedence.

Looks Right

• The new reader uses only payload.resource.cost_unit via Value::as_i64
  (crates/khive-pack-brain/src/handlers.rs:2336), matching the runtime's
  successful-dispatch i64 resource payload (crates/khive-runtime/src/cost_unit.rs:172).
• Aggregation is additive: existing kind, actor, verb, profile, and work-class
  increments remain unchanged, while the new totals are accumulated separately
  (crates/khive-pack-brain/src/handlers.rs:811) and inserted only when at
  least one event carries a cost unit (crates/khive-pack-brain/src/handlers.rs:856).
  Missing values therefore do not create zero-valued totals or verb entries.
• Both totals use saturating i64 addition (crates/khive-pack-brain/src/handlers.rs:832),
  consistent with the writer's overflow clamp.
• The existing half-open window filter and 50,000-event page remain the sole
  input to every aggregate (crates/khive-pack-brain/src/handlers.rs:783;
  crates/khive-pack-brain/src/handlers.rs:717). The handler help and API
  reference honestly say that cost sums cover only the fetched page when
  truncated=true (crates/khive-pack-brain/src/handlers.rs:82;
  docs/guide/api-reference.md:699).
• EventStore-backed tests cover absence including a pre-feat(runtime): emit resource.cost_unit per ADR-103 Amendment 1 #927 audit row
  (crates/khive-pack-brain/src/tests.rs:6557), total/per-verb aggregation
  (crates/khive-pack-brain/src/tests.rs:6615), window exclusion
  (crates/khive-pack-brain/src/tests.rs:6715), and saturation
  (crates/khive-pack-brain/src/tests.rs:6762).
• PR feat(brain): surface cost_unit aggregation in event_counts #958 closes brain.event_counts: surface cost_unit aggregation (ADR-103 Amendment 1 read side) #955, and brain.event_counts: surface cost_unit aggregation (ADR-103 Amendment 1 read side) #955 exists as an open tracking issue with an
  accurate description of the unimplemented read-side aggregation.

Commands Run

• git diff --check origin/main...HEAD: passed.
• cargo test -p khive-pack-brain (from crates/, with
  CARGO_TARGET_DIR=$HOME/.cache/shared-cargo-target/khive): executed after
  waiting on the shared Cargo lock. Its built test executable subsequently
  completed successfully: 222 passed, 0 failed, including all five
  cost_unit tests. The terminal bridge did not preserve Cargo's final
  wrapper exit transcript.
• cargo test -p khive-runtime: not yet run; queued behind the same shared
  lock.
• cargo clippy --workspace --all-targets -- -D warnings: not yet run for
  this checkout; queued behind the same shared lock.
• RUSTDOCFLAGS=-D warnings cargo doc --no-deps -p khive-pack-brain: not yet
  run; queued behind the same shared lock.

What I Did Not Check

• I did not claim passing results for the three queued gates or an exit status
  the terminal bridge did not expose. They need a narrow follow-up once the
  shared Cargo queue clears.

Re-Review Guidance

• Narrow follow-up: correct the stale helper comment and rerun the four listed
  gates from crates/ using the shared target cache. No broader design review
  is needed.

Domain utility: SKIPPED — no applicable lore-domain connector was available;
the accepted ADR and runtime writer contract supplied the required standards.

[ohdearquant]

Codex static review: APPROVE at b66fbf6 (0 blocking findings).

[oceanwaves630]

Reviewed against the posted review artifacts and CI rollup. Approved.