mostlyright.core.schemas.earnings_fact

Earnings-fact schema (schema.finance.fact.v1).

One row per (ticker, call_id, term, occurrence) mention counted from an earnings call. Kalshi and Polymarket resolve the same fact rows through different filters, so the schema carries every taxonomy dimension either venue keys on; a row that loses one of them cannot be settled.

This module defines:

validate_kalshi_counted_occurrence : The fail-closed Kalshi-count rule. A Kalshi-counted occurrence must carry role_source in {transcript_structural, transcript_self_id, roster_match} and speaker_role in {company_executive, operator_ir}. Un-anchorable occurrences are excluded from the Kalshi count (accepting recall loss to avoid mis-settlement) but retained for the Polymarket any-speaker count. ColumnSpec (core/schema.py) supports no regex or cross-field rule, so the check is a module-level function, as with validate_satellite_station.

validate_ticker : Ticker-identity check; raises EarningsFactCorruptError for a malformed ticker.

EarningsFactSchema : The full schema.finance.fact.v1 shape contract.

delivery vs source. delivery (enum {live, hosted}, default "live") records the delivery channel only; it is not source identity. The per-row source overlay column is the source identity the validator checks. The live speech-to-text path and the hosted feed produce rows from the same public call audio, so they share one source identity ("earnings_call"), as satellite rows share noaa_goes.

Streaming fields. resolution_status carries the extra "provisional" value for live early-signal fact deltas, and the is_final / spoken_at markers are optional, so a batch (post-call) row is unchanged. is_final denotes speech-to-text segment finality only — a counted fact delta can be is_final=True and still resolution_status="provisional". Settlement and research authority is gated on resolution_status and source, never on is_final; validate_kalshi_counted_occurrence applies identically to live and batch rows.

Module Attributes

Attribute	Description
`DELIVERY_VALUES`	Delivery-channel lineage.
`ROLE_SOURCE_VALUES`	role_source — the provenance of the speaker-role attribution; exactly four values.
`SPEAKER_ROLE_VALUES`	Speaker role of the occurrence.
`COUNTING_MODE_VALUES`	Counting mode.
`SEGMENT_VALUES`	Call segment of the occurrence.
`WINDOW_SCOPE_VALUES`	Time-window scope a market resolves over.
`MATCH_RULE_VALUES`	Term match rule.
`COMPOUND_TYPE_VALUES`	Compound-type axis.
`KALSHI_AUTOCOUNT_COMPOUND_TYPES`	Venue auto-count membership over `COMPOUND_TYPE_VALUES`.
`RESOLUTION_STATUS_VALUES`	Resolution status.
`KALSHI_COUNTABLE_ROLE_SOURCES`	Fail-closed membership sets.

Functions

Function	Description
`validate_kalshi_counted_occurrence`(…[, strict])	Fail-closed Kalshi-count rule.
`validate_kalshi_counted_rows`(rows, *[, strict])	Cross-field guard: a stored `kalshi_counted=True` must be derivable.
`validate_ticker`(ticker)	Validate an earnings-fact row’s ticker identity.

Classes

Class	Description
`EarningsFactSchema`()	`schema.finance.fact.v1` — one row per counted mention occurrence.

mostlyright.core.schemas.earnings_fact.COMPOUND_TYPE_VALUES : tuple[str, …]

Compound-type axis. A separate per-occurrence axis from MATCH_RULE_VALUES — do not carry these values in the match-rule enum. A hyphenated compound counts for the bare term on both venues; a closed (unhyphenated) compound (wildfire for fire) diverges: Kalshi does not count it, Polymarket treats it as a candidate only. An affix derivation (joyful for joy) counts for neither venue.

mostlyright.core.schemas.earnings_fact.COUNTING_MODE_VALUES : tuple[str, …]

Counting mode. mention_count is the integer primary tally; the boolean form is derived as count >= 1 (boolean markets are boolean_ge1 with threshold_n == 1).

mostlyright.core.schemas.earnings_fact.DELIVERY_VALUES : tuple[str, …]

Delivery-channel lineage. Informational only; not source identity. Mirrors SATELLITE_DELIVERY_VALUES.

class mostlyright.core.schemas.earnings_fact.EarningsFactSchema

Bases: Schema

schema.finance.fact.v1 — one row per counted mention occurrence.

Carries the six taxonomy dimensions (term match rule, counting mode, speaker scope, window scope, time, tie-break/resolution) plus the role_source provenance and the derived kalshi_counted flag, so the same fact rows resolve correctly under each venue’s wording.

mention_count is the primary integer tally; the boolean (“said at least once”) is derived as mention_count >= 1. Storing only a bool cannot settle Polymarket “say X 5+ times” threshold brackets.

columns: `ClassVar`[`list`[`ColumnSpec`]]

schema_id: `ClassVar`[`str`]

mostlyright.core.schemas.earnings_fact.KALSHI_AUTOCOUNT_COMPOUND_TYPES : frozenset[str]

Venue auto-count membership over COMPOUND_TYPE_VALUES. Both venues auto-count standalone, open, and hyphenated compounds. closed never auto-counts: it is raised for human review when it could flip a Polymarket outcome (fact_builder), and it is excluded from the Kalshi count entirely. affix_derivation is in neither set and counts for no venue.

mostlyright.core.schemas.earnings_fact.KALSHI_COUNTABLE_ROLE_SOURCES : frozenset[str]

Fail-closed membership sets. A Kalshi-counted occurrence must satisfy both. Anything outside them is excluded from the Kalshi count and retained for Polymarket’s any-speaker count.

mostlyright.core.schemas.earnings_fact.MATCH_RULE_VALUES : tuple[str, …]

Term match rule. Kalshi accepts exact, plural, and possessive forms, but not verb-tense inflections.

mostlyright.core.schemas.earnings_fact.RESOLUTION_STATUS_VALUES : tuple[str, …]

Resolution status. "provisional" marks a live early-signal fact delta, which is not a settlement or research source; authority is gated on this column plus source, never on is_final.

mostlyright.core.schemas.earnings_fact.ROLE_SOURCE_VALUES : tuple[str, …]

role_source — the provenance of the speaker-role attribution; exactly four values. Acoustic diarization is advisory only (it mis-clusters analyst Q&A as executive speech); only the three transcript-anchored sources are Kalshi-countable.

mostlyright.core.schemas.earnings_fact.SEGMENT_VALUES : tuple[str, …]

Call segment of the occurrence.

mostlyright.core.schemas.earnings_fact.SPEAKER_ROLE_VALUES : tuple[str, …]

Speaker role of the occurrence. Drives the speaker-scope divergence between Kalshi (company representatives, including the operator) and Polymarket (any speaker).

mostlyright.core.schemas.earnings_fact.WINDOW_SCOPE_VALUES : tuple[str, …]

Time-window scope a market resolves over.

mostlyright.core.schemas.earnings_fact.validate_kalshi_counted_occurrence(role_source, speaker_role, , strict=False)

Fail-closed Kalshi-count rule.

Returns True only when the occurrence is anchorable for the Kalshi count: role_source in KALSHI_COUNTABLE_ROLE_SOURCES and speaker_role in KALSHI_COUNTABLE_SPEAKER_ROLES. Every other (role_source, speaker_role) pair returns False — un-anchorable occurrences are excluded from the Kalshi count (accepting recall loss to avoid mis-settlement) but stay countable under Polymarket’s any-speaker rule.

This is the boolean a fact row’s kalshi_counted column is derived from. Live (resolution_status="provisional") and batch occurrences are filtered identically; is_final (speech-to-text finality) never gates this rule.

When strict=True and the occurrence is un-anchorable, raises KalshiCountRuleViolationError (carrying the offending fields) — used at a write-site asserting an occurrence is Kalshi-counted.

Return type: bool
Parameters:
- role_source (str)
- speaker_role (str)
- strict (bool)

mostlyright.core.schemas.earnings_fact.validate_kalshi_counted_rows(rows, , strict=True)

Cross-field guard: a stored kalshi_counted=True must be derivable.

The schema validator checks kalshi_counted only as a bool dtype — it cannot see that a stored True is consistent with the row’s role_source / speaker_role. Settlement authority would then trust the boolean as-is, letting a row assert kalshi_counted=True while role_source="diarization_advisory" or the speaker is an analyst.

This post-validation check re-derives the flag from validate_kalshi_counted_occurrence() and confirms it matches the stored value on every row. A row claiming kalshi_counted=True whose (role_source, speaker_role) is un-anchorable raises KalshiCountRuleViolationError (fail-closed) when strict; a row that under-counts (stored False while the pair is anchorable) is a contract bug too and raises EarningsFactCorruptError.

Returns the number of rows checked. It is a module-level function because ColumnSpec has no cross-field rule.

Return type: int
Parameters:
- rows (Iterable [Mapping [str , object ] ])
- strict (bool)

mostlyright.core.schemas.earnings_fact.validate_ticker(ticker)

Validate an earnings-fact row’s ticker identity.

Returns the ticker unchanged when valid (so call sites can use it inline). Raises EarningsFactCorruptError for a non-string or an empty string. The accepted ticker shape is deliberately permissive (issuers such as BRK.B carry a dot); the only rule enforced here is non-empty string.

Return type: str
Parameters: ticker (str)