Skip to content

Observation records and archive snapshots

fast_vollib.observations stores immutable evidence with explicit event, availability and recording times. It imports no financial payload classes. All timestamps are UTC-aware; interval events and coverage have ordered endpoints. Availability is a caller statement. It is never inferred from an event timestamp. Recording may precede availability when the caller's policy permits that ordering.

An ObservationRecord has a stable record_id, kind, entities, payload_schema, stamp, optional coverage and a verified payload_digest. Construction copies dictionaries and lists into immutable canonical trees. Accepted leaves are strings, integers, booleans, finite floats, finite Decimals, UTC instants and None. Arbitrary objects, arrays, callables and reserved $ mapping keys are refused. Canonicalization is versioned as observation.canonical/1; JSON encodes Decimals and instants with explicit tags.

ObservationStamp includes source, optional source record ID, version, revision ancestor, world, timing note and mapping version. Synthetic sources require a non-actual world. Source IDs use (source, source_record_id, version, world_id) for idempotency; otherwise the caller's record ID is the identity. Repeated identical deliveries deduplicate. Conflicting content under either identity raises ObservationConflictError.

Available-time selection

from fast_vollib.observations import select_as_of

snapshot = select_as_of(records, knowledge_cutoff=cutoff, world_id="actual")

The named policy is available_time/1 (available_time is its input alias). Selection filters world and availability, then resolves full replacement revisions. selected_records contains the current admissible versions. records additionally retains eligible revision ancestors so serialized snapshots can independently validate lineage. Both are deterministic tuples owned by the snapshot. The digest binds records, cutoff, world and policy. A later revision never mutates an older snapshot.

Revision chains must preserve source, source identity, entities, kind and payload schema. Versions increase and availability cannot move backwards along the chain. Missing ancestors, forks, cycles and codec changes raise RevisionError. Delta merges require a separate codec policy and are refused by this replacement route. A snapshot validates the archive's supplied world before selection; malformed future chains are refused even when the current cutoff precedes them.

Generic selection retains notices and forecasts about future events. Economic reducers separately exclude executions after their valuation time. An archive availability query reconstructs declared knowable information; it does not prove what a local system had ingested. Local ingestion replay needs recording-time evidence and a corresponding policy.

Serialization

observations.serialization.dumps / loads round-trip individual records. record_to_dict / record_from_dict and snapshot_to_dict / snapshot_from_dict provide strict versioned data records. Unknown fields, versions, duplicate JSON keys, invalid tags and digest mismatches are refused. No executable objects or pickle are accepted.