Authority model¶
Distributed systems accumulate contradictory statements about themselves. The defence is not more documentation; it is deciding in advance which component is allowed to be right about what, and then writing everything else as a consumer of that decision.
Who owns which fact¶
| Class of fact | Authority | Consumers must | Documented at |
|---|---|---|---|
| Trading runtime primitives — instruments, bars, orders, positions, portfolio accounting, the backtest engine | Upstream NautilusTrader at the pinned version | Reference upstream, never redefine | NautilusTrader boundary |
| What market data exists, its coverage and its retention | ONIX backend data plane | Query it; never infer coverage from a chart | Data plane |
| Durable bar history and derived resolutions | ONIX backend catalog and aggregation | Treat a client-side series as a cache, never a record | Catalog, aggregation |
| Which venues are integrated, and at what capability | ONIX backend venue profiles and registries | Read the capability matrix, not the UI | Venues, venue matrix |
| Instrument identity and symbol normalisation | ONIX backend | Use backend identifiers end to end | Instrument identity |
| What a strategy is, and what a backtest did | ONIX backend trading subsystem | Present results; never recompute them client-side | Backtesting |
| Execution permissions and risk boundaries | ONIX backend | Never imply capability the backend does not expose | Execution runtime |
| Screener feature values and their trustworthiness | ONIX backend screener engine | Render absence as absence, never as zero | Screener engine |
| The request/response contract | ONIX backend schema set | Pin it explicitly and fail loudly on mismatch | Gateway and schemas |
| Web product behaviour and presentation | ONIX frontend | — | Product |
| Native client behaviour | ONIX macOS and iOS repositories | — | Native clients |
| What an agent may do | The MCP surface that exposes the operation | Assume denial by default | MCP safety and scope |
| What is deployed | The tracked production record, and — when observed — the live host | Distinguish record from observation | Runtime and deployment |
The tie-break rules¶
When two sources conflict, resolve in this order.
- Executable locks beat prose. A pin file, a lockfile, a schema manifest or a content hash outranks any sentence in a README, including sentences in this documentation.
- The owning component beats a consumer. A client's belief about a market fact never overrides the backend's.
- Observed state beats recorded intent. A live observation outranks a manifest that says what should be running. When there is no observation, say so — do not promote intent.
- Upstream beats local prose about upstream. If this site and upstream NautilusTrader documentation disagree about upstream behaviour, upstream is right and this site has a bug.
- Newer pin beats older pin, but only after revalidation. A later commit is not automatically authoritative for a claim written against an earlier one. The claim must be re-read at the newer pin.
Rule 3 is the reason Production record exists as a distinct status token. The
repository's tracked record pins a specific backend release, a specific frontend
release, an activation set and an ingestion manifest version. None of that was
observed on a live host during this documentation pass, so it is reported as a
record, not as reality.
Rule 5 is the reason the macOS client's claims about frontend parity are marked
Unverified: the client records an older frontend pin than the one documented
here, and revalidation has not happened.
How this documentation implements the model¶
Each page declares an owner in its metadata, drawn from a closed set:
documentation integrator, frontend/product, backend/platform, or native clients
and MCP. That owner appears in the status strip on every page.
The practical rule for authors is short: a page may define only what its owner owns. Everything else is a link. A product page describing the chart does not define what a bar is; it links to aggregation. A native page describing the macOS client does not define the contract; it links to gateway and schemas.
This is why the site has fewer, longer pages than the documentation set it replaced. Duplicated definitions were the main source of drift, so they were removed rather than kept in sync.
Related reading¶
- System boundaries — the same structure expressed as seams.
- Design principles — why these rules and not others.
- Documentation standards — how the rules are enforced at build time.
Evidence and source pins for this page
Verified. Current behaviour, confirmed in source at the pinned commit.
Verified on against the following immutable sources:
backend@efa38e04:docs/handoff/contract-manifest.jsonfrontend@99f49dae:scripts/engine-pin.mjsbackend@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.