ADR-0021 — CandleDefinition v1 semantic contract¶
Status: ACCEPTED
Date: 2026-08-29
Context¶
ADR-0005 makes candles first-class derived representations and ADR-0017
requires a reproducible CandleDefinition with mutable PARTIAL and
immutable CLOSED states. The platform now needs a precise contract before a
historical candle runtime is implemented. The definition must remain separate
from consumer selectors, canonical source dataset identity and physical
materialization details, while allowing historical and future incremental/live
construction to converge.
Decision¶
Adopt the normative contract in CandleDefinition v1 Contract, with these central decisions:
- A definition identity is a SHA-256 of canonical UTF-8 JSON containing only versioned semantic source, duration, alignment, boundary, aggregation, empty-bucket, lifecycle, late-event, availability, numerical and output schema parameters. Venue, instrument, query interval, dataset identity, catalog identifiers, paths and runtime identifiers are excluded.
- V1 consumes deterministic
trades@1/trade-v1events, uses positive integer nanosecond durations, UTC Unix-epoch alignment, and half-open buckets labelled bybucket_start. - OHLCV and trade count use deterministic source order and exact decimal arithmetic; binary float and implicit rounding are forbidden.
- Fully covered zero-trade buckets are omitted, not filled or treated as coverage gaps.
- Query intervals select full aligned buckets whose intervals intersect the
query; required bucket support is tracked separately from the consumer
interval and returned records. Review remediation changes selection from
bucket_startfiltering to bucket intersection so Consumer API coverage projects over every requested interval, including non-aligned intervals. PARTIALis mutable and unsealed.CLOSEDrequires source finalization, complete support and stable source revision/content evidence, and is immutable. Corrections require a revised source and rebuilt result, never silent in-place mutation.- Historical data without observed receive/finalization time does not receive
a fabricated timestamp. The
causal_floorfor final closed values isbucket_end;observed_available_atis nullable/unknown unless evidenced and is never implied to equal the causal floor. - On-demand and materialized CLOSED results are equivalent only when their definition, source revision/evidence, support/coverage and canonical records are equivalent; physical placement is not semantic identity.
The closed-record schema is schemas/candle-v1.json. State and provenance
remain in an envelope/materialization metadata, not in the row. The canonical
five-minute definition payload, serialization and hash are protected by
fixtures/candle-definition-v1/golden-5m.json and its focused contract test.
Consequences¶
- Two independent implementations have a deterministic target for the first historical candle slice.
- A later runtime can support incremental/live construction without weakening closed-result immutability or temporal availability rules.
- Empty-bucket and non-aligned-query behavior are explicit, including required source support beyond a non-aligned query end when a selected bucket needs it.
- Candle v1 remains only the first representation slice; it does not redefine the future Representation system.
- The existing DataGateway, frozen
trade-v1, catalog and producer contracts remain unchanged.
Review outcome¶
The independent semantic review gate has passed and this ADR is ACCEPTED.
Acceptance freezes the CandleDefinition v1 contract but does not itself
authorize Candle runtime implementation; runtime work still requires an
explicit bounded scope.