Defines an effective-dated record model, query shapes, indexing, correction rules, retention, and observability for systems that must answer what was valid at a business instant.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Represent business validity with non-overlapping half-open intervals [valid_from, valid_to), keep system audit timestamps separately, and make current-state queries an explicit optimized path rather than a hidden convention.
Scope
- Valid-time records, corrections, current and as-of queries, interval integrity, indexes, retention, and operations.
- One-dimensional valid time with optional audit timestamps.
- Performance profiles for point-in-time and bounded history queries.
Outside this block
- Full bitemporal reconstruction unless system-time history is explicitly added.
- Event sourcing or storing every operational event.
Contract
- For one entity and logical attribute set, validity intervals do not overlap.
- Intervals are half-open;
valid_tois null only for the current open interval. - All stored instants are UTC and API boundaries identify timezone assumptions for local business dates.
- A scheduled future value may coexist with the current value but not overlap it.
- Corrections preserve audit evidence and distinguish
recorded_atfromvalid_from. - Queries must name current, as-of, or history intent; no unbounded history endpoint is implicit.
Implementation guidance
- Use an exclusion constraint or transactionally enforced overlap check where the database supports it.
- Index current lookups separately from as-of lookups and include the entity partition key first.
- Partition only after measured volume and maintenance requirements justify it.
- Build a repair command that reports overlapping or inverted intervals before changing data.
Failure handling and safeguards
- Reject inverted or overlapping intervals with a domain error that identifies the conflicting interval.
- Concurrent changes for the same entity serialize or retry against a version guard.
- Retention removes history only under an approved policy and never rewrites surviving validity boundaries to hide gaps.
Verification and operations
- Measure p50/p95/p99 for current and as-of query classes, rows scanned, overlap rejections, open intervals per entity, and partition maintenance time.
- Continuously check interval invariants on new writes and sample historical data for drift.
- Test daylight-saving boundaries at API conversion edges even though storage remains UTC.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.