CORE_CONTRACTS.md¶
Status: DRAFT v0.1
Purpose: semantic contracts for the canonical quantitative platform
Rule: these contracts describe meaning before implementation details.
1. General contract rules¶
Every canonical domain entity must define, where applicable:
- identity;
- version;
- source/provenance;
- time semantics;
- deterministic parameters;
- validation invariants;
- serialization boundary;
- failure semantics.
No entity may silently infer critical semantics from a filename, column name, UI field, or runtime default.
2. DatasetIdentity¶
Represents one logically identifiable market dataset.
Required concepts:
dataset_idvenuemarket_typeinstrumentdata_kindschema_versiontime_coverageprovenancemanifest_identity
Invariants:
- identity must not depend on local mount path;
- logical dataset identity and physical storage location are separate;
- the same logical dataset may move across storage roots without becoming a different dataset.
3. PartitionIdentity¶
Represents one reproducible partition of a DatasetIdentity.
Required concepts:
dataset_idpartition_idpartition_keytime_starttime_endrow_countcontent_hashschema_versionstorage_reference
Invariants:
- content identity must be stable across physical relocation;
- partition boundaries must be explicit;
- overlapping partitions are either forbidden or explicitly modeled.
4. MarketEvent¶
Common semantic envelope for time-ordered market information.
Possible event families:
- Trade
- L1Quote
- L2Snapshot
- L2Update
- L3OrderEvent
- SessionEvent
- VenueStatusEvent
Required concepts:
event_timeobservation_timewhen distinctinstrumentvenuesequencewhen available- source/provenance
Invariants:
- source timestamps must preserve their original precision;
- missing sequence/order identifiers must remain missing rather than fabricated.
5. Trade¶
Represents a canonical trade event.
Required concepts:
- event time;
- price;
- quantity;
- aggressor side when derivable/canonical;
- trade identifier when provided;
- sequence when provided;
- source provenance.
No synthetic receive timestamp is introduced unless it is genuinely observed.
6. L1Quote¶
Represents top-of-book state or update.
Required concepts:
- best bid price;
- best bid quantity;
- best ask price;
- best ask quantity;
- event time;
- update/sequence identity when available.
Derived values such as spread, mid, microprice and top-of-book imbalance are Features, not raw L1 fields unless explicitly supplied by the source.
7. L2Update / L2Snapshot¶
Represents aggregated book state by price level.
Required concepts:
- side;
- price level;
- aggregate quantity;
- event/update time;
- snapshot/update semantics;
- sequence/reconstruction metadata when available.
Invariants:
- snapshot and incremental update semantics are never conflated;
- reconstruction validity must be checkable;
- add/cancel/replenishment features are only claimed when the source semantics support them.
Normalized v1 contract:
L2BookEventV1is the cross-venue canonical event for aggregated L2 data.- One event is either
event_type=snapshotorevent_type=delta. - Historical archives and live websocket ingestion use the same logical event;
they differ only by
acquisition_mode(historical_archive,live_websocket, orrest_snapshot). bidsandasksare ordered sequences ofL2LevelChangeV1.L2LevelChangeV1hasside,price,size,actionand optionalorder_count.action=deleteis represented only assize="0";action=upsertrequires a strictly positive aggregate size.native_sequence,native_prev_sequence,native_update_id,continuity_token,source_depth_limit,provider_tsandreceive_tsare evidence/reconstruction metadata, not derived features.order_countis allowed only when the venue supplies aggregate count at that price level. It is not an order identifier and does not make the event L3.- L2 adapters must reject or leave out-of-scope venue feeds whose semantics are order-level/MBO rather than aggregate-price-level L2.
8. L3OrderEvent¶
Represents order-level book activity when provided by the venue/feed.
Possible actions:
- add;
- modify;
- cancel;
- execute;
- replace.
Required concepts depend on feed but may include:
- order identifier;
- side;
- price;
- quantity;
- queue-relevant ordering;
- event time;
- sequence.
Invariants:
- L3 features must not be reconstructed from L2 and labeled as native L3.
9. CandleDefinition¶
A reproducible definition of a candle representation.
Required concepts:
source_datasetintervalalignmentinterval_semanticstimestamp_labelprice_sourcevolume_semanticsempty_interval_policylate_event_policypartial_policy
Recommended interval semantics:
A CandleDefinition is part of identity.
10. Candle¶
Represents one interval produced by a CandleDefinition.
PARTIAL is a mutable incremental runtime representation and is not sealed.
CLOSED is immutable after closure. A reusable series of CLOSED candles may
be materialized as a canonical derived dataset with catalog, partition and
lineage semantics. Candle is a representation, not merely a Feature.
Required concepts:
start_timeend_timestate:PARTIALorCLOSEDopenhighlowclosevolume- source/provenance
Optional canonical aggregates may include:
- trade count;
- VWAP.
Feature values derived at candle grain are not required to be embedded in the Candle object itself.
Temporal invariant:
- final values for a
CLOSEDcandle cannot be treated as available before candle close plus any processing delay defined by the provider.
10.1 FootprintDefinition / Footprint¶
A footprint is a Representation-owned price-level aggregation of canonical trades. It is not a FeatureDefinition and does not contain imbalance thresholds, labels, strategy semantics or FeatureArtifact materialization.
FootprintDefinition v1 is governed by
ADR-0027.
Required definition concepts:
- source contract
trades@1/trade-v1; - fixed positive duration;
- UTC Unix-epoch alignment;
- half-open bucket support
[bucket_start,bucket_end); - positive exact-decimal
tick_size; - zero-origin exact integer tick grid;
- sparse level policy;
- explicit aggression evidence requirement;
- finalized historical-only lifecycle for v1.
Required finalized Footprint concepts:
- definition identity;
- bucket support interval;
- integer
level_index; - canonical price
level_index * tick_size; - exact buy/sell volume sums by aggressor side;
- concrete source venue/instrument binding;
- authoritative source coverage/finality/provenance evidence.
Invariants:
- source price is valid only when
price / tick_sizeis an exact integer; - no rounding, snapping, epsilon tolerance or inferred side is allowed;
aggressor_side == "unknown"fails closed for the affected bucket;- missing grid levels remain absent and are never synthesized as zero rows;
- complete zero-trade bucket support produces no level rows and is distinct from missing source support;
- finalized Footprints require complete authoritative source support and are immutable for a fixed definition and source revision/content evidence.
11. FeatureDefinition¶
Canonical definition of a derived observable.
Required concepts:
- deterministic
feature_definition_id - governed canonical
feature_key - explicit
semantic_version - declared typed semantic-parameter schema
- canonical normalized semantic parameters
- exactly one versioned
InputContract - declarative support/reference semantics
- input maturity and availability/finality semantics
- initialization/history semantics when output-affecting
- minimal
OutputContract
Provider families may include:
- Trades
- L1
- Footprint
- L2
- L3
- Technical
- Context
- Custom
Invariants:
- feature identity changes when semantic meaning, identity-bearing parameters, input contract, support, availability/finality, initialization/history or output-equivalence semantics change;
- feature identity does not depend on registry order, implementation build/SHA/backend, cache/materialization strategy, concrete dataset, venue, instrument, time range, physical locator, execution provenance or concrete representation grain unless that grain/duration is intrinsic feature semantics;
- temporal availability and finality are explicit and distinguish causal floors from nullable observed runtime evidence;
- undefined/insufficient support is a non-observation outcome, not a canonical null/NaN/zero sentinel value.
FeatureDefinition identifies one semantic observable, such as delta@1 or
vwap@1, and is distinct from a bundle or materialization. Valid examples
include trade -> candle, price_level -> candle, L1_update -> candle,
trade -> trade and candle -> candle.
FeatureDefinition v1 is governed by ADR-0026.
12. FeatureSetDefinition¶
Defines a versioned bundle containing one or more FeatureDefinition
identities and stable materialization parameters. The existing canonical
feature_set_definitions catalog is retained as this identity foundation.
Feature-set identity does not replace per-feature identity.
13. FeatureArtifact¶
Represents computed feature values.
Required concepts:
feature_definition_identitysource_dataset_identity- source partition identities;
- computation window;
- output grain;
- code/implementation identity;
- materialization/cache mode;
- content identity where persisted.
Lifecycle:
EPHEMERALCACHEABLEMATERIALIZED
14. HypothesisSpec¶
Represents a research hypothesis composed from Features.
Examples of semantics:
- conjunction/disjunction of conditions;
- regime constraints;
- threshold/percentile conditions;
- temporal context;
- feature interactions.
Invariants:
- strategy-specific compound logic belongs here or in StrategySpec, not in primitive FeatureDefinition;
- hypothesis semantics must be declarative enough to fingerprint and reproduce.
15. EventSpec¶
Defines how a hypothesis becomes discrete research events.
Required concepts may include:
- trigger condition;
- deduplication/cooldown;
- event timestamp;
- direction/context;
- minimum data/warmup requirements.
16. Event¶
Represents one detected occurrence.
Required concepts:
event_idevent_timeevent_spec_identityinstrument- relevant feature snapshot/provenance
- direction/context where applicable
An Event is not automatically a Signal.
17. OutcomeSpec¶
Defines what future/path information should be measured after an observation or Event.
Examples:
- multi-horizon return;
- MFE/MAE;
- barrier hits;
- time-to-event;
- path drawdown;
- realized volatility;
- cost-aware simulated outcome.
Invariants:
- horizon and temporal alignment are explicit;
- future information is never fed back into features or decision inputs.
OutcomeSpec/Outcome v1 is governed by ADR-0038.
18. Outcome¶
Represents the realized result of an OutcomeSpec for an Event/observation.
Required concepts:
- source event/observation identity;
- outcome-spec identity;
- measurement window;
- realized values;
- censoring/incomplete-path state where applicable.
Outcome is descriptive, not automatically a training label.
CENSORED_END_OF_DATA requires explicit end-of-data/completeness evidence,
never bare iterator/collection exhaustion; see
ADR-0038.
19. LabelDefinition¶
Defines how Outcomes or policy simulations become learning targets.
Families:
- outcome-derived;
- policy-derived.
Required concepts:
- source outcome/policy semantics;
- transformation;
- class/value schema;
- timing;
- censoring policy;
- implementation identity.
Policy-derived labels must include the StrategySpec / ExecutionSpec assumptions used in their creation.
20. ValidationSpec¶
Defines the evaluation schedule.
Required concepts may include:
- warmup;
- train;
- validation;
- test;
- lockbox;
- rolling/expanding mode;
- purge;
- embargo;
- fold alignment;
- minimum sample/event requirements.
Different domains may use different procedures while sharing these temporal primitives.
21. StrategySpec¶
Defines a stateful trading strategy independent from market replay/live source.
Possible components:
- EntryPolicy
- ExitPolicy
- PositionPolicy
- SizingPolicy
- RiskPolicy
- SessionPolicy
- SignalCombinationPolicy
- ExecutionPolicy
A StrategySpec is not reducible to one event trigger.
EntryPolicy/ExitPolicy reference signals only by signal_key: the actual
rule/threshold logic that decides what a signal key means (comparison
operators, indicator thresholds, stop-loss/take-profit levels) is
deliberately outside this contract's ownership. execution_policy is the
intended extension point for that logic (ADR-0051): it is typed as the
generic IdentityBackedPolicy interface (identity: str,
stable_dict() -> Mapping[str, Any]) specifically so a consumer's own
rule/threshold payload participates in strategy_identity — two strategies
differing only in thresholds are guaranteed different identities — without
the platform ever needing to interpret what those thresholds mean. No other
StrategySpec component is a supported carrier for this; a consumer should not
encode rule/threshold content into, for example, policy_key strings on
EntryPolicy/ExitPolicy, which are plain governed keys, not
identity-bearing payloads.
EntryPolicy.direction is a single Direction (LONG or SHORT; FLAT is
rejected) — one StrategySpec always enters in exactly one pre-configured
direction and cannot express "go long or short depending on signal" or
reverse directly in a single decision. A two-sided strategy is expressed as
two single-direction StrategySpecs run side by side (ADR-0052), not a
single two-sided spec. This is intentional, not a gap to work around
silently: each spec in the pair gets its own strategy_identity and
independent G04 session/cooldown state, and H03's existing execution
conflict model already resolves the (signal-design-error) case where both
specs' entries fire in the same decision instant.
22. DecisionIntent¶
Canonical learner-agnostic strategy output.
Required concepts:
decision_timeinstrument- desired exposure or target position;
- direction where applicable;
- size/risk budget;
- confidence where applicable;
- urgency where applicable;
- policy/strategy provenance.
Invariants:
- every input used to produce the DecisionIntent must have been available by
decision_time; - DecisionIntent contains desired trading intent, not venue-specific fill results.
23. ExecutionSpec¶
Defines how DecisionIntent is translated into orders/fills.
Possible concepts:
- order type policy;
- price policy;
- fee schedule;
- slippage model;
- latency model;
- partial-fill model;
- cancel/replace rules;
- participation constraints;
- venue-specific execution constraints.
Execution semantics must be shared between historical replay and live adapters as far as the real venue allows.
translate_intent (H01-H03) has no position/ledger state and is stateless
per call: it does not know whether the caller already holds a
DecisionIntent's target_position, and it does not become a no-op when
one is already held. Replaying a persistent entry signal (one that stays
true across many ticks) admits a new full-size order on every call, not just
the first — this is intentional, not a defect (ADR-0053). Gating repeated
entries (e.g. tracking whether the current entry condition has already been
acted on) is the caller's responsibility until H04 (portfolio/ledger, issue
144) is integrated with this seam.¶
24. Order¶
Represents one executable order state.
Required concepts may include:
- order identity;
- instrument;
- side;
- type;
- quantity;
- limit/stop price where applicable;
- submission time;
- state;
- execution provenance.
25. Fill¶
Represents one realized fill.
Required concepts:
- order identity;
- fill time;
- price;
- quantity;
- fees;
- liquidity role when available;
- venue/source identity.
26. Position¶
Represents current instrument exposure.
Required concepts:
- quantity;
- average basis;
- realized/unrealized state;
- timestamps;
- strategy/run provenance.
27. Portfolio / Ledger¶
Canonical accounting state.
Responsibilities:
- cash/equity;
- positions;
- fills;
- realized/unrealized PnL;
- exposure;
- fees;
- reconciliation.
Ledger semantics must be deterministic under historical replay.
Materialized representation replay is permitted only through a declared FINAL artifact identity with exact source/output support and causal availability evidence. A CLOSED bar becomes consumable no earlier than its bucket end. Tick-level and bar-level replay are comparable only under an explicit common bar-close profile; neither may silently substitute for the other. See ADR-0059.
28. Study¶
A research program grouping related trials.
Example:
BTCUSDT absorption-family study on trade/footprint features.
Study identity must not depend on run order.
29. Trial¶
One parameterized hypothesis/model/strategy evaluation within a Study.
Required concepts:
- complete parameterization;
- input identities;
- validation spec;
- result metrics;
- run/artifact references.
30. Run¶
One concrete execution of a reproducible Trial or operational job.
Required concepts:
- run identity;
- trial/study linkage where applicable;
- code identity;
- environment identity where applicable;
- status;
- timestamps;
- metrics;
- artifacts;
- failure metadata.
A single logical run must not acquire separate incompatible identities in different subsystems.
Independent replay attempts may execute in parallel only when each attempt
preserves one complete stateful replay and a declared RunIdentity. Temporal
sharding of a replay is not a Run optimization: it changes the state universe.
Workers must record failed/aborted attempts rather than omitting them from
trial accounting. See ADR-0058.
31. ArtifactIdentity¶
Represents persisted outputs such as:
- feature partitions;
- model files;
- prediction files;
- event tables;
- traces;
- backtest outputs;
- plots/reports.
Identity must include the semantic inputs needed to prove reproducibility.
32. Job¶
Represents long-running asynchronous work.
The durable J03 contract is ADR-0062.
job_id is a deterministic fingerprint of an immutable admitted operation; it
is not a runtime UUID, path, worker identity, attempt count, or an Experiment
RunIdentity. Re-admission of the same immutable request returns the existing
Job, while a conflicting record fails closed.
Required concepts:
job_id- operation type
- immutable admitted request and declared input identities
- handler/implementation identity and effect-safety declaration
- durable lifecycle:
ADMITTED,QUEUED,RUNNING,CANCELLATION_REQUESTED,RECOVERY_REQUIRED,SUCCEEDED,FAILED, orCANCELLED - attempt identity
(job_id, attempt_no)and bounded attempt evidence - cancellation acknowledgement/effect evidence
- immutable result/artifact and domain-reference identities
- explicit terminal reason code and bounded diagnostic/evidence reference
Only SUCCEEDED, FAILED, and CANCELLED are terminal. A process restart
never treats RUNNING as liveness evidence and never silently redispatches it:
the Job becomes RECOVERY_REQUIRED until an explicit, effect-safe recovery
decision. Automatic retry is prohibited. Job lifecycle storage is distinct from
I02 Experiment persistence; a Job may reference RunIdentity values but does
not replace their ownership.
33. Shared temporal invariants¶
At minimum:
feature_available_time <= decision_time
signal_available_time <= decision_time
decision_time <= order_submit_time
order_submit_time <= fill_time
For any derived value, the platform must be able to explain which source events were consumed and when the result became available.
34. PressurePolicyDefinition¶
Operational pressure policy is deterministic policy over explicit evidence, not
capacity observation. PressurePolicyDefinition v1 is governed by
ADR-0028.
Required concepts:
- immutable/versioned policy definition;
- deterministic content-derived policy identity;
- explicit UTC
as_ofevaluation instant; - fresh K04 capacity evidence;
- optional caller-supplied write-rate evidence when time-to-full participates;
NORMAL,PRESSURE,CRITICALandEXHAUSTEDstates;- explicit unavailable decisions for missing, stale, future-dated or malformed required evidence;
- deterministic decision evidence and identity;
- pressure restrictions as upper bounds only.
Invariants:
- K05 does not observe filesystems, collect telemetry history, mutate storage, schedule work or authorize deletion;
- the evaluator does not read an implicit host clock;
available_bytesis consumed as reported by K04 and is not recomputed;- zero write rate means unbounded time-to-full, not a finite sentinel;
- equality enters the more severe threshold state;
delete_authorizedis false for every successful K05 decision.
35. Contract evolution¶
Breaking semantic changes require:
- version increment;
- migration/adoption plan where persisted artifacts exist;
- ADR if the change affects architecture or domain meaning;
- updated semantic tests.
Silent reinterpretation of an existing version is forbidden.