Keep an auditable ledger

A forecast is a dated belief about a frozen question, supported by a record of what was known and how the estimate changed. Preserve each revision rather than overwriting the latest probability.

Supercast’s core Ledger owns one validated question version. Its public API exposes records for reading and accepts new forecasts or resolutions through validation. The SQLite adapter persists the same lifecycle as immutable events and replays the rules when loading them.

Revision fields

A forecast records its ID, as-of time, evidence cutoff, probability, predecessor ID, change type, method, rationale, assumptions, next review trigger, and evidence references. The initial forecast has no predecessor and uses initial. Later revisions name the current forecast ID.

Forecast times must increase strictly, cutoffs cannot regress, and no forecast can be submitted at or after the frozen deadline. A review_unchanged record must preserve the probability. Corrections append a new record and keep the old erroneous estimate visible.

The ledger does not require a probability to move after every review. New evidence can confirm a prior judgment or provide no diagnostic information. The rationale explains the assessment; small cosmetic changes do not make an agent more responsive.

Evidence timing

An evidence reference contains an ID, origin ID, locator, claim, publication time, and optional observation time. Both known times must respect the forecast’s evidence cutoff. A later article about an earlier event was not necessarily available at the earlier time.

The timestamp fields are caller assertions. The database also records local commit time, but historical imports remain possible. A credible prospective evaluation needs additional controls that freeze the cohort and enforce contemporaneous recording.

The source locator may refer to a supplied file rather than a URL. The library does not fetch it, prove its authenticity, or execute any instructions found inside it. The consuming application should treat source content as evidence data.

Resolution lifecycle

An adjudication must occur at or after resolve_after, name a declared source, and include a rationale. Outcomes are yes, no, unresolved, or void with a reason.

An unresolved adjudication may be followed by a later one. Yes, no, and void are terminal. Once adjudication begins, the ledger rejects additional forecasts. A delayed source release is handled as unresolved rather than quietly treating the absence as “no.”

Safe retries

Durable writes use the request ID as an idempotency key. After a lost response, resend the same decoded command and ID. The stored receipt returns without another event. Reusing the ID for a different command is a conflict.

Reading the current ledger before proposing a revision is not enough to prevent a race; another writer can append in between. The adapter rechecks the predecessor under the SQLite write transaction. If your revision is stale, read the new history and reconsider the update instead of merely replacing its predecessor string.