Design principles¶
These are the rules the current system was built to, stated as rules rather than as aspirations. Each one exists because its absence caused a specific, expensive failure in an earlier generation of the platform.
1. One authority per class of fact¶
Every fact has exactly one owner, and every other component is a consumer. There is no negotiated truth and no reconciliation layer.
The rule sounds obvious and is routinely broken in trading systems, usually by a client that starts caching aggressively, then starts filling gaps, then quietly becomes a second source of history that disagrees with the first. ONIX forbids that: a client cache is a cache, and a gap is reported rather than invented.
The full ownership table is on the authority model page.
2. Contracts are pinned by content, not by convention¶
Components do not agree to "the latest API". The frontend carries an executable pin that names the exact backend release it accepts, together with the schema set and its hash. A mismatch is a build failure.
The consequence is that a version skew becomes a loud, early, local error instead of a quiet, late, distributed one. It also makes documentation checkable: a claim about client behaviour is only meaningful relative to the contract it was pinned to, and that pin is recorded on every page of this site.
3. Reference upstream before inventing¶
NautilusTrader is a mature trading runtime. Where it already defines something — an instrument, a bar, an order lifecycle, a portfolio calculation — ONIX uses it rather than writing a parallel implementation with subtly different semantics.
Extensions are allowed, but they must be deliberate, scoped and labelled. An extension that exists only because nobody checked upstream first is a defect. This principle is strong enough that it has its own contributor page: upstream reference discipline.
4. Absence is a value¶
A screener feature that cannot be trusted is reported as absent, with a reason. It is never reported as zero, and never silently omitted. A coverage gap is reported as a gap rather than interpolated away.
This principle extends to the documentation. Where evidence was unavailable at
the pinned commits, pages carry the Unverified badge and record the open
question. A documentation set with no unverified claims is either trivial or
lying.
5. Determinism where determinism is affordable¶
Backtests, builds and artifacts are content-addressed and reproducible wherever that is achievable at reasonable cost. Two runs over identical inputs are expected to produce identical outputs, and a divergence is treated as a bug rather than as noise.
This documentation site holds itself to the same standard: the production build is run twice and the outputs are compared before anything is published.
6. Safety boundaries are explicit and default to refusal¶
Anything that can move money, mutate live state or reach outside the system is enumerated, bounded and default-denied. This applies most visibly to the MCP surfaces, where an agent's available operations are a closed list rather than an open capability.
The documentation consequence is a hard editorial rule: this site does not claim real-money execution, and does not describe a capability as available when what exists is a bounded, private, or test-stage version of it.
7. Retire rather than rewrite¶
When a subsystem is wrong in its foundations, it is removed rather than patched into plausibility. The earlier TypeScript trading and data engine was retired whole, along with its compile and isolation gate and its venue-adapter prototype.
Documentation follows suit: retired material is not quietly deleted, because a
reader who remembers it needs to be told it is gone. It is marked Retired, its
old URL redirects to the page that explains the replacement, and the redirect is
part of a generated contract so it cannot be lost.
8. Private by default, published by decision¶
ONIX is a private system. Operational runbooks, alerting, incident history, security internals and private topology are not published because publishing them has costs and no reader benefit.
But the fact of withholding is published: the list of what is quarantined and why is public even though the content is not. Silent omission and declared omission are very different things, and only the second is compatible with trustworthy documentation.
What these principles cost¶
Stating the trade-offs honestly:
- Single authority makes some client interactions slower than a locally-computed approximation would be.
- Content-pinned contracts make coordinated releases heavier.
- Referencing upstream means inheriting upstream's constraints and release pace.
- Reporting absence produces user-visible gaps that a less careful system would paper over.
- Determinism costs build time and engineering attention.
- Default-deny safety means capability arrives slowly.
These were accepted deliberately. A trading platform that is fast and wrong is worth less than one that is slower and correct about what it knows.
Related reading¶
Evidence and source pins for this page
Verified. Current behaviour, confirmed in source at the pinned commit.
Verified on against the following immutable sources:
frontend@99f49dae:scripts/engine-pin.mjsbackend@efa38e04:docs/handoff/contract-manifest.jsonbackend@efa38e04:feature-state/rc3-data-plane-frozen-current-production.yaml
Status tokens are defined on the documentation and status model page. Every pin on this site is listed under versions and source pins.