fix(ingest): extend shares_outstanding fallback to catch implausibly-low primary extraction (#246 ERIE)

[dackclup]

Summary

Closes #246. ERIE's raw_metrics.shares_outstanding = 2542 (real ~57M) because SEC companyfacts aggregate API filters out dimensional facts. ERIE files Class A (~54.9M) only with a dei: share-class dimension and Class B (~2,541) without — so the aggregate returns Class B only.

PR #182 STZ fallback _fetch_shares_from_per_filing_xbrl already exists, BUT its trigger was strict shares is None (Issue #176 STZ signature). ERIE's non-None 2,542 slipped past → fallback never fired → ERIE shipped with wrong data + ranks at #69 despite veto.

This PR extends the trigger to also fire when shares < MIN_PLAUSIBLE_SHARE_COUNT (100_000) — the S&P 500 index-floor sanity gate (30× safer than any plausible legitimate value).

Production code changes (~12 net LOC)

• compute/config.py — new MIN_PLAUSIBLE_SHARE_COUNT: int = 100_000 constant with rationale docstring (S&P 500 index-floor mcap $15B + extreme single-share-price $500 implies ≥ 30M minimum; 100K is 30× safer)
• compute/ingest/fundamentals.py:774-803 — trigger extended from shares is None to shares is None OR shares < MIN_PLAUSIBLE_SHARE_COUNT. Existing revenue > 0 + total_assets > 0 gates preserved. Logger updated to surface primary=<None|count> for operator visibility (distinguishes STZ-signature None case from ERIE-signature too-low case without re-running a probe)
• PHASE_STATUS_INFLIGHT.md — in-flight entry per §Conventions (PR docs(workflow): adopt PHASE_STATUS_INFLIGHT.md side-file (structural fix for parallel-PR collision) #237 convention)

Tests

Test-engineer spawn in flight — 12 cases incoming on a follow-up commit:

• 6 boundary/branch (ERIE shape · STZ backward-compat · 99K/100K/100001 boundaries)
• 2 gate preservation (revenue/assets zero invariants)
• 1 logging discipline (caplog distinguishes None vs too-low)
• 1 Hypothesis property
• 1 config constant pin
• 1 @network ERIE drift-detector (mirrors STZ/AAPL/WMT @network pins)

Side-effect coverage

Ticker	Extracted	Status
ERIE	2,542 (< 100K)	✅ fixed — fallback fires → recovers ~57M
BRK-B	1,643,118 (> 100K)	not covered — existing DQ veto stays; Class A → B 1500:1 conversion is separate methodology call
V (Visa)	469M (> 100K)	not covered — handled by #248 PR2a/PR2b per methodology verdict
FOXA / NWS / NWSA	all > 100K	not covered — included in #248 PR2b regression fixture

Backward-compat note

ERIE's risk_flags = ['data_quality_input_corruption'] will stop firing post-fix (shares becomes plausible → TBVPS gate doesn't trigger). No existing test pins ERIE's veto state (verified via grep -r ERIE tests/ — zero hits). ERIE's rank shifts based on now-valid valuation; expected behavior.

Schema / docs

• Schema bump: none — fix is in ingest layer; no new field. Stays at 0.10.2-phase4.5e.
• CLAUDE.md / AGENTS.md substance: no change — focused bug fix; existing §Gotchas entry for issue STZ: market_cap = None on 2026-05-14 cron — shares_outstanding missing from XBRL fact extraction #176 + fix(ingest): per-filing XBRL fallback recovers STZ-style dimensional shares_outstanding (closes #176) #182 already covers the failure class. PHASE_STATUS_INFLIGHT.md side-file satisfies the "ship with every PR" lockstep rule.

Verification

• ruff check compute/config.py compute/ingest/fundamentals.py — clean
• python -c "from compute.config import MIN_PLAUSIBLE_SHARE_COUNT" — imports OK
• pytest tests/test_ingest/test_fundamentals.py -m "not network" -x -q — pending test-engineer commit
• Test count delta — pending
• @network ERIE drift-detector — runs in CI with EDGAR_USER_AGENT

Sibling issues filed in same audit batch (2026-05-25)

• NVR — data_quality_input_corruption in valuation_warnings but absent from risk_flags (scoring layer gap) #247 NVR scoring-layer DQ gap → methodology-scientist Mode B owns
• V (Visa) — shares_outstanding=469M (real ~1.85B, ~4× off) — no veto despite obvious mcap understatement #248 V/Visa cross-source escalation → PR2a + PR2b split per methodology verdict
• Rebaseline compute-rankings.yml timeout-minutes vs 5-loop cold-cache reality (OR adopt off-cycle pre-cache) #249 Rebaseline compute-rankings.yml timeout (durable fix for 2026-05-25 P1)

Test plan

• CI green (ruff + offline pytest + frontend tsc + frontend build)
• Test-engineer follow-up commit adds 12 cases (boundary + property + @network)
• Mon 22:00 UTC cron-feat(phase-2): SEC EDGAR fundamentals + per-stock detail pages #4 produces fresh ERIE.json with shares_outstanding ≈ 57M + market_cap > $10B + empty risk_flags
• defense-layer-auditor post-cron Section A-J verifies no regression

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 25, 2026 8:23am