Fixture truth and score truth are separate
A competition can be active while StumpScope has no supported score connection for one or all of its matches. The league directory answers a calendar question: is the real tournament scheduled, live or complete? The match desk answers a separate data question: can the server retrieve and identify the official or licensed record for this fixture? Combining the two would create false coverage. A season window proves that games exist, but it does not provide innings totals or player figures. The schedule therefore allows a “schedule-status” state without promising automatic coverage. The live desk uses an “official-score” state only when a fixture has an official live URL or a configured score provider. This separation also protects future matches. A confirmed date can appear before the source publishes a scorecard, while an unconfirmed time remains TBC and cannot drive a guessed countdown.
How a fixture becomes source-ready
Source readiness begins with identity. The server checks the provider, match identifier, teams and scheduled time rather than choosing the first page that contains similar names. Some adapters can extract an identifier from a known official match URL. Others match a provider’s fixture list by normalized home and away team names and a narrow time window. Name normalization handles controlled variations, such as Saint versus St or a current team brand versus a known previous label, but it cannot authorize a different matchup. Date checks reduce the risk of attaching an older result between the same teams. A mapped match still needs a valid response with the expected structure. If the provider returns no confirmed innings score, the adapter can state that the score is pending. It must not infer a total from a headline, social-media post or another website’s snippet.
What an adapter normalizes
Each source publishes a different shape. One may count legal balls, another may expose overs, and a third may nest batter and bowler lines inside innings. The adapter converts those fields into a stable StumpScope contract: fixture identity, live or complete status, result summary, innings number, batting team, runs, wickets, legal balls, batter figures, bowler figures, recent overs, commentary when supplied, last event time and source provenance. The conversion does not create missing values. A batter line needs runs and balls from the source. A bowling card needs the delivered balls, conceded runs and wickets required for that view. Commentary can appear only when the connected record provides it under terms that permit use. The public interface can then render different competitions without teaching the browser every provider’s private field names.
Caching, polling and duplicate requests
The official-source layer uses an eight-second cache. Requests for the same match inside that window can reuse the recent normalized response, and in-flight deduplication prevents several page visitors from starting identical upstream calls at once. The fixture match page runs its own refresh loop every ten seconds. Those intervals serve different jobs: server caching controls source load, while browser polling controls how often a reader asks StumpScope for the current state. An update may therefore appear after a short delay even when both systems work. The site should call that a refresh interval, not “instant” or “real time” without qualification. Cache headers for public pages also balance freshness with resilience. A score timestamp tells the reader when the source snapshot was fetched or when the last event occurred; the clock should not imply a newer ball than the data contains.
Atomic snapshots and the backup file
Successful live-desk responses are stored on disk as JSON. The store writes to a process-specific temporary file, copies the existing valid file to a backup, and then renames the temporary file into place. Rename-based replacement prevents readers from seeing a half-written JSON document if the process stops during a write. The primary snapshot has strict structural checks when it loads. If that file is missing or invalid, the store tries the backup. If neither can be read, it returns no snapshot rather than manufacturing a default score. File permissions restrict the saved snapshot on the local system, though production security still depends on the host, service account and storage configuration. Runtime snapshot churn is operational data, so a changed automatic desk file should not be treated as an intentional source-code edit without checking why it changed.
What readers see during a source failure
A provider can time out, change its response or become unavailable during a match. The source-score endpoint first attempts a current fetch. If that call fails and the match publication store has an earlier confirmed snapshot, the server returns that stored record with a stale flag. The page can keep the last score and show that the update is delayed. It does not add the next delivery, calculate an assumed target from a tweet or switch to an unreviewed competitor feed. If no prior snapshot exists, the endpoint returns an error state rather than a number. The automatic live desk follows the same principle across its match window. A stale snapshot is useful because it preserves known facts, but the timestamp and status must make its age visible. Readers should use the named official match centre when they need the organizer’s current ruling during a StumpScope outage.
Full scorecard, summary and pending states
StumpScope has three honest levels of match detail. A full scorecard contains enough source data for innings, batter and bowler tables. A result summary contains a confirmed winner or result and team totals but lacks the player lines needed for a complete card. A pending state means the fixture is source-ready but the provider has not published a usable score. The interface should label each state. Empty cells must not look like zero runs, and a result summary must not be marketed as ball-by-ball coverage. Completed source snapshots are saved in the match-publication ledger so the final page does not vanish when the source moves the game out of its live window. The match report can identify a top batter or leading bowler only from the stored player statistics. Missing toss, partnership or dismissal data stays missing.
Stable match pages and the 48-hour publication rule
A confirmed fixture can receive a stable match page 48 hours before play under the current publication rule. The rule calculates a publish time from a confirmed start. A fixture with TBC timing remains a draft because a thin page with a false countdown would mislead readers. Once published, the URL remains the same through upcoming, in-progress and completed states. That continuity helps a supporter bookmark one page and allows the stored result to replace the live panel without creating a second canonical route. The page’s lifecycle does not guarantee indexability. Local and unfinished production environments remain noindex, and individual routes still need useful content, reliable data, metadata agreement and human approval. Scheduled publication is an editorial workflow state, while Google indexing is a separate external process with no guarantee.
Corrections, provenance and visible dates
Every normalized score carries a source object with a publisher or provider, official URL where available, fetch time and source mode. Fixture records also keep the schedule source and confirmation date. A later confirmed provider update can replace an earlier snapshot. That is normal in cricket because scorers can correct a boundary, dismissal, innings total or player attribution after review. StumpScope’s corrections policy provides the public route for material editorial errors, while timestamps explain when time-sensitive material was checked. A correction should change the inaccurate field and, where useful, record what changed. It should not refresh every article date for appearance. Source notes belong in the reference rail or methodology, not as decorative trust badges that imply affiliation. The organizer or licensed data owner remains authoritative for an official score.
Current limits and the production gate
The current implementation supports several adapters and archive modes, but support is not equivalent to blanket permission for every league or field. Each connection needs a terms, licensing, reliability and mapping review before production use. A technically reachable endpoint can still impose contractual limits. Images, logos, player portraits and written commentary require separate rights checks from numerical score facts. Production launch also needs durable storage, backup and restore tests, secrets management, rate-limit review, monitoring and access controls. The local server and passing tests prove only the behavior exercised in that worktree. They do not prove a public deployment, domain ownership or 24-hour operations. StumpScope’s safest promise is narrow: it will show confirmed data from a supported connection, preserve the last reliable state during a temporary failure and label the information it cannot supply.