The dependency direction runs from validated probability values, through mathematical functions, to workflow records. The core has no network, filesystem, model-provider, or async-runtime dependency. The workspace's separate supercast-agent crate depends on the core and owns JSON transport and SQLite persistence.
The detailed mdBooks in books/handbook and books/reference explain these layers. The reference operation pages are generated from the runtime schema and executed examples; scripts/docs.py --check verifies both content and rendered links.
probability owns the numerical value types. bayes, aggregate, decompose, score, reference, and decision operate on them. calibration and evaluation consume frozen observations. workflow holds question contracts, evidence, revisions, adjudications, and elicitation records.
- Construct a
Questionwith frozen outcome rules and a source hierarchy. Rehearse boundary cases outside the library; nonempty text alone does not prove resolvability. - Assemble an attributable
ReferenceClass. Report unresolved members and transfer concerns. Choose an empirical or explicitly smoothed prior. - Record supporting and contrary pathways. Use conditional scenarios and inspect sensitivity before adding complexity.
- Gather evidence with source-origin IDs and publication cutoffs. Seed
UpdateSessionwith origins already incorporated into the prior. Apply likelihoods conditional on earlier evidence. - For a real panel, retain respondent metadata and private initial estimates. Use the same declared aggregation rule across rounds. Model draws are not independent human respondents.
- Append the forecast to
Ledgerwith its assumptions and next review trigger. A trigger is metadata, not a scheduled task. - Resolve against the frozen rules. Unavailable observations produce unresolved status, not a negative outcome.
- Select equivalent-time snapshots or a prespecified time grid. Average within question before comparing across questions. Validate chronological and cluster separation, compare a baseline, and inspect calibration.
Keep external input structures separate from domain values. Parse numbers into Probability::new; validate a complete record before appending. Never deserialize untrusted bytes directly into private probability fields. Represent infinite log loss explicitly if the transport cannot encode infinity.
The SQLite adapter commits events and retry receipts atomically under an immediate transaction. It indexes each question version's sequence and validates through the core ledger, which rejects duplicate forecast IDs and invalid predecessors. One connection-local validated history supports incremental mutations; SQLite data-version changes invalidate it under the write lock. Reads, cold starts and cache misses still fully replay. See cache invariants and measurements. SQL triggers reject updates and deletes to existing events and receipts. The in-memory ledger remains free of storage dependencies. Neither layer makes a tamper-evidence claim against an actor with direct database access.
A retrieval adapter should preserve provenance and access time; a URL shared by several outlets is not necessarily the true origin. The update session deliberately rejects any reuse of an origin. Distinct observations from one continuing source need distinct observation-origin IDs, with explicitly conditional likelihoods.
For categorical or continuous agent workflows, the scoring layer is available, but the current ledger stores binary forecasts. Add a versioned forecast-distribution enum and matching resolution type before extending that boundary.
All calculations use IEEE 754 f64. Extremely small probabilities can underflow and extreme logits can saturate to 0 or 1; they are not arbitrary-precision outputs. Counts above 2^53 lose unit precision when converted to f64. Mixture and categorical sum tolerances are 1e-12. Accepted categorical sum roundoff is normalized; scalar probability inputs are never clipped.
Functions return errors for invalid inputs. A few internal expect/unwrap calls construct values whose bounds follow directly from validated inputs. No unsafe code is permitted.
ReferenceClass validates the declared counts and fields, not case overlap or sampling quality. validate_holdout enforces supplied question, cluster, and time metadata, not hidden pretraining contamination. compare returns descriptive paired means without inferential uncertainty. Equal weighting is an application choice, not proof of exchangeability.
Useful extensions are native bindings or an MCP wrapper, richer distribution and survival models, retrieval/model adapters, and a prospective evaluation harness. Transport schemas, durable event storage, declared-cutoff evaluation, cluster-resampled uncertainty, and calibration grid selection with a separate holdout are implemented. See release scope. Add each further capability with its own data contracts and independent validation cases. Avoid interpreting additional numerical sophistication as demonstrated predictive skill.