mostlyright.finance.transcripts.pit

Point-in-time alignment + leakage wiring for earnings facts.

Two safety primitives keep earnings facts faithful in research:

align_event_date(event_date, ticker) : Calendar-date-only coercion (a datetime is rejected, the same guard kalshi_nhigh applies and the TypeScript twin’s coerceContractDate mirrors) followed by an HQ-timezone re-projection of the call instant to the issuer’s HQ-local calendar date, a ±1-UTC-day correction of the kind dailyExtremes performs. A call that airs at 03:00 UTC on Jul 1 is still the evening of Jun 30 in Los Angeles, and the settlement/contract date must be the HQ-local date, not the UTC date.

knowledge_time_for(transcript_available_at) + assert_earnings_no_leakage : The point-in-time invariant: knowledge_time is transcript availability (post-call), not event_date. A research read standing at an as_of before the transcript posted must not see the mention, because a mention spoken on the call is not knowable until the transcript is published. These reuse mostlyright.core.assert_no_leakage() and KnowledgeView rather than reimplementing them; this module supplies only the earnings-specific knowledge_time derivation and a thin wrapper.

If knowledge_time were set to event_date (the call date) instead of transcript availability, a research read could see a mention before the call aired. That is the leak this module exists to forbid.

Module Attributes

Attribute	Description
LIVE_STREAM_SOURCE	The live delivery-channel source id.
PROVISIONAL_RESOLUTION_STATUS	The provisional resolution status carried by a live counted fact delta.
AUTHORITATIVE_SOURCE	The single authoritative post-call delivery-channel source id, and the only valid research / settlement delivery channel.

Functions

Function	Description
align_event_date(event_date, ticker, *[, …])	Coerce + hq-tz-correct an earnings event_date to the issuer-local date.
assert_earnings_no_leakage(df, as_of)	Raise LeakageError if any fact row leaks past as_of.
assert_not_backtest_source(df)	Raise if a DataFrame carrying provisional/live rows feeds a research read.
assert_settlement_source(df)	Raise if a DataFrame carrying provisional/live rows feeds settlement.
knowledge_time_for(transcript_available_at)	Return the tz-aware UTC knowledge_time for a transcript availability.
live_knowledge_time(published_at, *[, spoken_at])	Return the tz-aware UTC live knowledge_time = published_at.
live_knowledge_view(df, as_of)	Return a KnowledgeView over the authoritative rows only.

mostlyright.finance.transcripts.pit.AUTHORITATIVE_SOURCE

The single authoritative post-call delivery-channel source id, and the only valid research / settlement delivery channel. This is the delivery-channel id, which is what a live/provisional row carries in its source column (earnings.hosted.stream); an authoritative post-call frame’s per-row source overlay is the shared identity "earnings_call" (see EarningsAdapter). The guards below work by rejecting the provisional earnings.hosted.stream / provisional rows, never by an equality check against this constant, so the label appears only in error text and its mismatch with "earnings_call" carries no leakage risk.

mostlyright.finance.transcripts.pit.LIVE_STREAM_SOURCE

The live delivery-channel source id. Rows tagged this way are provisional live deltas, excluded from every research and settlement read.

mostlyright.finance.transcripts.pit.PROVISIONAL_RESOLUTION_STATUS

The provisional resolution status carried by a live counted fact delta.

mostlyright.finance.transcripts.pit.align_event_date(event_date, ticker, , call_instant=None)

Coerce + hq-tz-correct an earnings event_date to the issuer-local date.

• Parameters:
  • event_date (date) – The calendar date the call airs / the market settles for. Must be a datetime.date with no time component — a datetime is rejected (the time component would break the date-equality settlement match, mirroring kalshi_nhigh).
  • ticker (str) – The issuer ticker; its IANA HQ timezone is looked up in TICKER_HQ_TIMEZONE.
  • call_instant (str | None) – Optional ISO-8601 UTC instant of the call. When given, the event date is re-projected to the HQ-local calendar date of that instant, a ±1-UTC-day correction, so a call that straddles a UTC day boundary lands on the correct local date. The re-projected hq-local date must be within ±1 calendar day of the supplied event_date; a larger divergence raises ValueError (it signals a mis-paired (event_date, call_instant) at the call site rather than a legitimate UTC-boundary shift). When omitted, event_date is returned unchanged (after coercion).
• Return type: date
• Returns: The HQ-local calendar datetime.date.
• Raises:
  • TypeError – event_date is a datetime (or any non-date).
  • KeyError – ticker is not in TICKER_HQ_TIMEZONE.
  • ValueError – call_instant is naive, or the re-projected hq-local date diverges from event_date by more than one calendar day.

mostlyright.finance.transcripts.pit.assert_earnings_no_leakage(df, as_of)

Raise LeakageError if any fact row leaks past as_of.

Thin wrapper over mostlyright.core.assert_no_leakage(). The df must carry a tz-aware UTC knowledge_time column holding transcript availability (post-call), so a research read standing at as_of cannot see a mention before the transcript posted. as_of is a mostlyright.core.TimePoint.

• Return type: None
• Parameters: df (DataFrame)

mostlyright.finance.transcripts.pit.assert_not_backtest_source(df)

Raise if a DataFrame carrying provisional/live rows feeds a research read.

A research read cannot include source="earnings.hosted.stream" or resolution_status="provisional" rows: they are the live feed, not research history. Pair this with live_knowledge_view(), which excludes them from as_of(), so a provisional row can neither be handed in whole nor survive a knowledge-time filter.

• Return type: None
• Parameters: df (DataFrame)

mostlyright.finance.transcripts.pit.assert_settlement_source(df)

Raise if a DataFrame carrying provisional/live rows feeds settlement.

A market can never settle on a provisional live count: only an authoritative post-call earnings.hosted row, final and settled, is a valid settlement/resolution source. Filtering the research read alone is not enough, so the settlement path carries its own guard. Call this at the markets earnings/ resolver’s settlement evaluation so a provisional row cannot resolve a market.

• Return type: None
• Parameters: df (DataFrame)

mostlyright.finance.transcripts.pit.knowledge_time_for(transcript_available_at)

Return the tz-aware UTC knowledge_time for a transcript availability.

knowledge_time is transcript availability (post-call), not event_date. This is the single place the earnings point-in-time invariant is computed: the timestamp from which a research read may know the facts from a call.

• Raises: ValueError – transcript_available_at is naive (no timezone). A naive knowledge_time would silently mis-order against the tz-aware as_of cutoff the leakage check uses.
• Return type: Timestamp
• Parameters: transcript_available_at (str | Timestamp | datetime)

mostlyright.finance.transcripts.pit.live_knowledge_time(published_at, , spoken_at=None)

Return the tz-aware UTC live knowledge_time = published_at.

For a live row, the moment it became knowable is the STT-finalization / publish wallclock (published_at), not the aired spoken_at (event_time) and not post-call transcript availability. A row’s mention is knowable the instant the STT segment is finalized and published to the stream.

• Parameters:
  • published_at (str | Timestamp | datetime) – The STT-finalization / publish wallclock (tz-aware).
  • spoken_at (str | Timestamp | datetime | None) – The aired event time (tz-aware). When given, the function asserts published_at >= spoken_at — a publish that predates the aired instant is impossible and signals a mis-paired row.
• Return type: Timestamp
• Returns: published_at normalized to tz-aware UTC.
• Raises: ValueError – published_at is naive, or published_at < spoken_at.

mostlyright.finance.transcripts.pit.live_knowledge_view(df, as_of)

Return a KnowledgeView over the authoritative rows only.

Excludes provisional/live rows (source="earnings.hosted.stream" or resolution_status="provisional") before constructing the view, so a research as_of() read over a mixed frame returns only authoritative post-call earnings.hosted rows with knowledge_time <= as_of. Reuses mostlyright.core.KnowledgeView rather than reimplementing filtering; this wrapper supplies only the provisional-row exclusion.

• Parameters:
  • df (DataFrame) – A mixed frame carrying a tz-aware UTC knowledge_time column.
  • as_of – The as-of cutoff (mostlyright.core.TimePoint).
• Returns: A KnowledgeView whose dataframe() excludes provisional rows.