Per-channel run report: make the composition audit a command (#628)

[WilfordGrimley]

Closes #628.

docs/reports/2026-07-29-pipeline-coverage-composition-audit.md is a per-channel table across vote channels, Stage C extractors and skip reasons, assembled by hand against production one channel at a time. It found three channels down, one for a reason nobody had recorded. This makes that table a command: manage.py channel_report.

The roster is derived from code

cardpicker/channel_roster.py reads the tree with ast — no imports, no Django, no hand-written list. Same technique and same reasoning as docs_lint.py's calculator/skip-reason tethers: "a second hand-maintained list would just move the stale list from the doc into the check." The scan is recursive (rglob, minus tests/, including migrations/), so PR #588's management-commands hole stays closed.

Derived: vote channels from actual cast sites, the Stage C manifest from image_evidence.py's own extractor_versions[...] stores (the same facts check_extractor_manifest_sync.py tethers), abstention channels from CardScanLog writers, and skip reasons from *_SKIP_REASON declarations.

Chips are counted BY TAG, not by identity

The single most important requirement. local-fallback-v1 derives as seven channels, not one — the audit found border chips healthy while frame-style and bleed-edge sat at zero under that same anonymous_id, and an identity-level count reports the identity as fine while two thirds of it is dead.

Getting this right needed intra-function constant tracing: both cast_border_attribute_vote and cast_frame_style_vote reach Tag.objects.filter(name=tag_name) through a local bound from BORDER_COLOR_TO_TAG / FRAME_STYLE_TO_TAG. Without it both collapse into the bleed channel — the exact merge this instrument exists to prevent. There is a test for that.

Identity-scoped abstentions deliberately do not count as evidence for a tag-grained channel: CardScanLog has no tag column, so letting border abstentions rescue the frame channel would reinstate the same merge.

Five outcomes, one failure

Positive vote / negative vote / abstention by named reason / value written / nothing at all. Only the last gates.

• A negative vote (is_no_match, is_unknown, polarity=NOT_APPLICABLE) is a conclusion, not an absence.
• Abstentions are reported by reason — "500 × no-evidence" and "500 × artist-mismatch" are different findings.
• Stage C success is a populated field, never a manifest key. All eleven extractors report 100% key presence while bleed_diff_mm is NULL on 97.9% of rows. "" does not count as a written value, since compute_card_evidence writes it for "ran, found nothing".
• Routers that write CardScanLog only (stage-d-slow-path-v1) say so in their row instead of showing zeros that read as failure.

No consensus outcome is read. Machine votes cast are the measure; a report keyed on resolutions would show ~100% failure on a healthy pipeline.

Zero gates unless declared

ZeroDeclaration rejects an empty, token, or unsigned reason at construction — the declaration table cannot be used as a silencer. A declared-silent channel that starts producing is flagged too.

ZERO_DECLARATIONS ships empty on purpose. The audit's real zeros are meant to show up red on the first run rather than be silenced in the same change that built the meter.

Four states, and reachability

NEVER-WIRED / WIRED-NEVER-RUN / RAN / RAN-AND-PURGED, from a module-qualified static call graph plus the ledger. The graph independently reproduces the audit's hand-built findings, and there are tests asserting each:

• the per-channel CMD column, channel by channel;
• art-edge-continuity-v1 reachable from no management command — the same shape as extract_card_evidence, whose only non-test callers are a docstring and a comment;
• the headline that the pooled runner reaches no vote channel — run_image_evidence_cohort reaches exactly one channel, evidence-transfer-v1, which writes no votes.

Limits are stated in the doc rather than hidden: dynamic dispatch is not modelled, so "reachable" is the weak claim and NEVER-WIRED is the strong one.

Generalises build_reconciliation_report, does not duplicate it

The Stage C side calls it once per derived extractor key and inherits its doctrine — "queries the rows directly rather than a separately-maintained counter, so the report can never drift from what was actually persisted" — including its deliberate run_id asymmetry.

Three exit codes

Following soak_gate_report: 0 PASS, 1 FAIL, 2 INSUFFICIENT-DATA when the roster itself cannot be derived. An empty derivation is a hard finding — an instrument that measures nothing must never report all clear.

Verification

35 tests in cardpicker/tests/test_channel_report.py, including the three demonstrations the brief asked for: a silent channel flagged and gating, a fully-producing roster passing, and a mutated derivation whose empty roster is itself the finding (asserted both at the API and through the command's exit code 2).

docs_lint.py --strict clean. No migration. No production write — validated against fixtures only.

Documented in docs/features/stage-e-operations.md (living published doc, per the owner rule), not a dated report.

🤖 Generated with Claude Code

https://claude.ai/code/session_013NhYmT1PxCcyemA16dFDxN