STZ: market_cap = None on 2026-05-14 cron — shares_outstanding missing from XBRL fact extraction

[dackclup]

Symptom

frontend/public/data/stocks/STZ.json (Constellation Brands, Consumer Staples, rank 308) has market_cap: null on the 2026-05-14 cron.

{
  "ticker": "STZ",
  "current_price": 151.18,
  "market_cap": null,
  "has_history": true,
  "raw_metrics": {
    "shares_outstanding": null,
    ...
  },
  "data_quality": {
    "missing_metrics": ["eps_basic", "eps_diluted", "shares_outstanding", "research_and_development"],
    "latest_period_end": "2026-02-28",
    "latest_filed_date": "2026-04-22",
    "filing_lag_days": 28
  },
  "risk_flags": []
}

Surfaced by the stock-detail-auditor subagent's Step 2 deterministic prefilter (SCHEMA category — market_cap ≤ 0 or None) on its dry-run during PR #175.

Root cause hypothesis

XBRL fact extraction (compute/ingest/fundamentals.py) failed to pull 4 per-share / count metrics from STZ's 10-Q filed 2026-04-22 (covering period ending 2026-02-28):

• eps_basic
• eps_diluted
• shares_outstanding
• research_and_development

With shares_outstanding: None, market_cap = current_price × shares_outstanding cannot be computed → null flows to output JSON → frontend /stock/STZ page renders a partial detail.

Related to #10 (shares_outstanding wrong for ~12 tickers), but STZ is a different failure mode — not "wrong value" but "no value at all". Possibly the XBRL fact name STZ uses for shares-outstanding differs from the _FUNDAMENTALS_REQUIRED_ATTRS manifest.

Why data_quality_input_corruption did NOT fire

risk_flags: [] — the Step 7.5 sanity guard in scoring did not flag this, even though data_quality.missing_metrics lists 4 missing fields. The current data_quality_input_corruption threshold appears to require both wrong-value AND mcap drift; missing-value paths are not caught.

This is issue #18 territory (composite scoring doesn't yet respect the data-quality flag) plus a sub-issue: the flag itself isn't being emitted on the "all None" failure mode.

Proposed investigation order

1. Pull STZ's 10-Q XBRL directly via edgartools and check the fact names for shares-outstanding (dei:EntityCommonStockSharesOutstanding vs us-gaap:CommonStockSharesOutstanding vs share-class–scoped variants — Constellation Brands has Class A / Class B share classes).
2. If fact name differs, extend the manifest in compute/ingest/fundamentals.py (and bump _FUNDAMENTALS_REQUIRED_ATTRS drift-detector test).
3. Add fallback: if XBRL doesn't yield shares_outstanding, scrape from 10-Q cover-page text (the SEC requires a count there).
4. Tighten data_quality_input_corruption to fire on "all None across critical metrics" paths so this is visible without an auditor pass.

Reproduction

python3 -c "
import json
d = json.load(open('frontend/public/data/stocks/STZ.json'))
print('market_cap:', d.get('market_cap'))
print('shares_outstanding:', (d.get('raw_metrics') or {}).get('shares_outstanding'))
print('missing_metrics:', d.get('data_quality',{}).get('missing_metrics'))
"

Tickers to cross-check (audit candidates)

Run the stock-detail-auditor Step 2 prefilter across the full universe — STZ is the only SCHEMA market_cap: null on this cron, but the dual-share-class hypothesis (Class A + Class B) might affect: BRK.B (already special-cased?), GOOG / GOOGL, FOX / FOXA, NWS / NWSA, DISH-class tickers if any. Worth confirming none silently degraded.

Out of scope for this issue

• Fair-price ensemble extreme estimates on growth-heavy stocks (separate issue — see follow-up filed in same audit)
• extended_top5 Rule 16 invariant (passed on this cron)

Owner

Unassigned. Pickup ladder: edgar-debugger for fact-name debug → patch in compute/ingest/fundamentals.py + tests/test_ingest/.

[dackclup]

Root cause investigation (2026-05-21, via live SEC EDGAR probe)

Probed STZ (CIK 0000016918) against three SEC API endpoints to nail down why shares_outstanding came back None despite the rest of the balance sheet extracting cleanly.

Finding 1: companyfacts aggregate API has NO common-share-count facts for STZ

curl https://data.sec.gov/api/xbrl/companyfacts/CIK0000016918.json

STZ exposes 1 dei namespace concept — EntityPublicFloat (USD). The expected share-count concepts are all absent:

us-gaap: 71 share-keyword concepts found, but NONE of:
  - us-gaap:CommonStockSharesOutstanding
  - us-gaap:CommonStockSharesIssued
  - us-gaap:WeightedAverageNumberOfDilutedSharesOutstanding
  - us-gaap:WeightedAverageNumberOfSharesOutstandingBasic
dei: 0 share-keyword concepts found (no dei:EntityCommonStockSharesOutstanding)

The 71 concepts that DO appear are all derivative — CommonStockSharesAuthorized (the legal max, not outstanding), share-based-compensation tags, TreasuryStock*, PreferredStock*, etc.

Finding 2: companyconcept API confirms the absence at the concept level

curl https://data.sec.gov/api/xbrl/companyconcept/CIK0000016918/dei/EntityCommonStockSharesOutstanding.json
# → HTTP 404 Not Found

curl https://data.sec.gov/api/xbrl/companyconcept/CIK0000016918/us-gaap/CommonStockSharesOutstanding.json
# → HTTP 404 Not Found

Not a temporary lag — the facts have never been published at the entity level.

Finding 3: per-filing XBRL DOES have the facts, but they're dimensional

Pulled the most-recent 10-Q (accession 0000016918-26-000005, filed 2026-01-08, reportDate 2025-11-30) and inspected the raw XBRL:

dei:EntityCommonStockSharesOutstanding   (2 rows, is_dimensioned=True)
  context c-2  → 173,384,625  (Class A)  CoverPage
  context c-3  →      26,197  (Class B)  CoverPage

us-gaap:CommonStockSharesIssued          (18 rows, is_dimensioned=True)
  Class A peg: ~212,698,298 across periods
  Class B peg: ~25,541-27,167 across periods

us-gaap:WeightedAverageNumberOfDilutedSharesOutstanding   (4 rows, all dimensioned)
us-gaap:WeightedAverageNumberOfSharesOutstandingBasic     (also dimensioned)
us-gaap:TreasuryStockCommonShares                         (treasury split by class)

STZ uses share-class dimensions (Class A common + Class B common) on every share-count fact. The SEC companyfacts aggregate API filters out dimensional facts — that's why our manifest extraction returns None despite the facts existing in the filing.

So the manifest extension proposed in this issue's step 2 doesn't help

_FUNDAMENTALS_REQUIRED_ATTRS in compute/ingest/fundamentals.py:59-77 already includes every plausible undimensioned share-count concept name. Adding more names won't help because the data isn't in the companyfacts API at all for filers like STZ.

Concrete fix path for a follow-up PR

The fix has to bypass the companyfacts aggregate and hit per-filing XBRL directly for the failing tickers:

# Pseudocode for the fallback path, scoped to tickers that match the
# share_count_extraction_missing signature (PR #181):
from edgar import Company
c = Company(ticker)
latest = c.get_filings(form='10-K').head(1)[0]  # or 10-Q for fresher
facts_df = latest.xbrl().facts.get_facts_by_concept(
    'dei:EntityCommonStockSharesOutstanding'
)
# Sum numeric_value across all dimensional contexts to get total
# common shares outstanding (Class A + Class B for STZ-like filers).
# Filter to the most recent period_end first.
shares = facts_df[
    facts_df.period_end == facts_df.period_end.max()
]['numeric_value'].sum()

Cost: 1 extra HTTP call per affected ticker per cron. Blast radius on the 2026-05-14 cron is 1 ticker (just STZ) — so the cost is negligible AS LONG AS the fallback only fires on the narrow share_count_extraction_missing signature shipped in PR #181.

Concerns to address in the follow-up PR:

1. Drift-detector manifest — edgartools per-filing XBRL extraction is a NEW API surface for this project (we don't use filing.xbrl().facts.get_facts_by_concept(...) anywhere yet). Needs a _PER_FILING_XBRL_REQUIRED_ATTRS manifest tuple asserted at module load, following the pattern in compute/scoring/form4_insider.py::_FORM4_REQUIRED_ATTRS.
2. Cache layer — per-filing XBRL fetches are slow (~5-10s each). Need a cache (similar to compute/cache/fundamentals/) keyed by (cik, accession_no). Long TTL — XBRL doesn't change after filing.
3. @network test — exercise the live SEC fallback on STZ to lock the fact-name + dimensional-aggregation behavior against edgartools API drift.
4. Performance audit — verify warm-cache cron doesn't exceed budget after the fallback adds 1-3 affected tickers' worth of extra HTTP. Off-cycle pre-cache the 1-3 tickers in the weekly cron's prologue.

Status

• Visibility gap closed by PR feat(defense): add share_count_extraction_missing annotate (closes #176) #181 (the share_count_extraction_missing annotate now fires when this happens; STZ will surface on the next cron with the flag in valuation_warnings).
• Root cause confirmed by this comment — the fix path is clear but non-trivial (new ingest API surface).
• Next step is a separate PR adding the per-filing XBRL fallback, scoped to tickers matching the PR-feat(defense): add share_count_extraction_missing annotate (closes #176) #181 signature.

Will close this issue when the per-filing fallback ships; PR #181 alone is sufficient for the visibility / surfacing concern.

---

Generated by Claude Code