feat(scoring): Issue #261 PR-A — multi_class_aggregate_shares_suspected annotate (CIK-collision detector)

[dackclup]

Summary

Closes the observability half of issue #261 — GOOG/GOOGL multi-class shares overcount where both tickers store Alphabet's 12.12B total shares (companyfacts aggregate-only filer), producing $4.6T market_cap per ticker vs real ~$1.05T per class.

Per methodology-scientist Mode B verdict 2026-05-26 (NEEDS-MORE-CALIBRATION):

• PR-A (this PR) — annotate-only multi_class_aggregate_shares_suspected (CIK-collision detector)
• PR-B (next PR) — reverse-allowlist per-class XBRL extraction (structural fix). Gated on the edgar-debugger probe that confirmed per-class dimensional contexts are XBRL-available.

Detector

New compute/scoring/multi_class_shares.py exports a pure universe-level function:

detect_multi_class_aggregate_shares_suspected(
    cik_by_ticker: dict[str, str | None],
    market_cap_by_ticker: dict[str, float | None],
) -> set[str]

Trigger (methodology-scientist Mode B):

1. Ticker's CIK collides with ≥ 1 other ticker in the universe (CIK-collision signature of a multi-class filer)
2. Ticker's market_cap > MARKET_CAP_FLOOR_RATIO × universe-median(market_cap) (MARKET_CAP_FLOOR_RATIO = 0.10)

Annotate-only per portable-annotate-before-veto; composite rank unchanged.

Schema bump

0.10.4-phase4.5e → 0.10.5-phase4.5e (PATCH; one additive Metadata field). Triple lockstep:

• compute/output/schemas.py — Metadata.multi_class_aggregate_shares_suspected_count: int | None
• frontend/lib/types.ts — TypeScript mirror
• frontend/lib/schema-snapshot.json — regenerated

Wiring in compute/main.py

• Pre-loop: build cik_by_ticker + market_cap_by_ticker dicts (universe-level scan needs full data upfront)
• Inside loop: emit multi_class_aggregate_shares_suspected to valuation_warnings when ticker in flagged set; increment counter
• Post-loop: wire counter to Metadata(...)

Tests (1196 → 1216 passing, +13 new + 1 updated)

tests/test_scoring/test_multi_class_shares.py:

1. MARKET_CAP_FLOOR_RATIO constant pin
2. Empty universe → empty set
3. No-collision universe → empty set
4. Canonical GOOG/GOOGL case → both fire
5. Collision below floor (micro-class artifact) → empty set
6. Partial above-floor → only above-floor sibling fires
7. None CIK → excluded from collision detection
8. None market_cap → excluded from firing set
9. All-None market_caps → empty set (no divide-by-zero)
10. Three-way collision → all fire
11. Threshold strict-inequality boundary (at-floor excluded by >)
12. Hypothesis property: firing set ⊆ collision set (regression guard)

tests/test_config.py::test_schema_version_is_phase4_5e updated 0.10.4 → 0.10.5-phase4.5e.

Edgar-debugger findings (live probe, 2026-05-26)

Filing inspected: Alphabet 10-K accession 0001652044-26-000018, FY2025.

VERDICT: PER-CLASS-AVAILABLE-IN-XBRL ✅

Per-class share counts ARE present as dimensional facts on us-gaap:CommonStockSharesOutstanding at the balance-sheet date:

StatementClassOfStockAxis member	Shares	Maps to
us-gaap:CommonClassAMember	5.822B	GOOGL
us-gaap:CommonClassBMember	0.837B	(founders, not traded)
goog:CapitalClassCMember	5.429B	GOOG

Per-class sum = 12.088B ≈ aggregate (perfect reconcile per Damodaran 2019 Ch. 16 Σ MC_class = MC_total identity).

CRITICAL gotcha for PR-B: GOOG Class C uses the filer-specific namespace goog:CapitalClassCMember, NOT the standard us-gaap:CommonClassCMember. An allowlist keyed on the standard namespace would silently return zero rows for GOOG. PR-B's allowlist will need:

MULTI_CLASS_SHARE_PER_CLASS_ALLOWLIST = {
    "GOOGL": "us-gaap:CommonClassAMember",   # standard
    "GOOG":  "goog:CapitalClassCMember",      # filer-namespace — gotcha
}

Behavior impact

ZERO behavior change for 496 non-colliding S&P 500 tickers — composite / risk_flags / fair_price / top5 rotation unchanged. The 6 multi-class tickers (GOOG / GOOGL / NWS / NWSA / FOX / FOXA) gain the new annotate in valuation_warnings; composite rank unaffected.

Expected Metadata fingerprint post first cron:

• multi_class_aggregate_shares_suspected_count ≈ 6

Verification ladder

• ruff check . — All checks passed
• python -m compute.output.schema_check — clean (triple in sync)
• pytest tests/ -m "not network" — 1216 passed, 7 skipped (ipca/qlib not installed), 24 deselected (@network)
• Vercel preview (auto-deploys post-push)
• CI: full lint+test+schema+frontend gauntlet

Deferred follow-ups (not in this PR)

• PR-B — reverse-allowlist per-class XBRL extraction (structural fix). Code shape proposed by edgar-debugger; allowlist must use filer-namespace goog: member for GOOG.
• Combined-MC reconcile invariant as Rule-18 diagnostic (|Σ MC_per_class − MC_aggregate| / MC_aggregate < 0.05) — methodology-scientist Mode B Q3 suggestion.
• Q3 2026-08-19 quarterly audit: walk the multi_class_aggregate_shares_suspected_count history; decide whether to retire after ≥ 2 crons of clean reconcile + recalibrate the 10% floor.

Lockstep

• PHASE_STATUS_INFLIGHT.md entry appended per PR docs(workflow): adopt PHASE_STATUS_INFLIGHT.md side-file (structural fix for parallel-PR collision) #237 side-file convention
• No CLAUDE.md / AGENTS.md substance change required — annotate doesn't introduce new invariant; pattern covered in existing §Gotchas
• Schema triple in sync (snapshot regenerated)

Test plan

• CI: Python lint+test should pass (513+ test files; this PR adds 1 new test file)
• CI: Frontend build should pass (single additive Metadata field; no consumer migration)
• Verify on Vercel preview: /stock/GOOG and /stock/GOOGL should now show multi_class_aggregate_shares_suspected in valuation_warnings on the next cron-feat(phase-2): SEC EDGAR fundamentals + per-stock detail pages #4

https://claude.ai/code/session_01JwntEE4PNAXSMkZxRA9BB4

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
quantrank	Ready	Preview, Comment	May 26, 2026 1:26am