docs: land architecture grilling corpus (ADRs 0001–0025)#45
Merged
Conversation
Capture the from-scratch architecture grilling: a single-host, multi-process, event-sourced design. ADRs 0001-0006 (topology, Bus, canonical model, risk control loop, single-writer Core, broker reconciliation) plus 0007 (binding time: no hot-path dyn), 0008 (single-owner Kernel + stateless Policies over a StateView, emitting Decisions into a sink), and 0009 (spine-inverted, process-aligned crate topology). CONTEXT.md holds the ubiquitous language; the grilling summary tracks parked questions and the remaining branches (B strategy runtime, C Frontend/CLI). The 0009 topology is the decided target; the crates are not yet restructured. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Close grilling Branch B (strategy runtime & multi-topic-join). - ADR-0010: strategies are out-of-Core deterministic folds in Strategy Nodes (supersedes ADR-0001 co-location); capability-derived backtest fidelity (DetCtx/IoCtx), not a gate. - ADR-0011: trading mode = (data feed x execution backend); Simulated Broker as an adapter backend; each mode an isolated Environment (Backtest/Shadow/Paper/Live); Core + Strategy mode-agnostic. - ADR-0012: event-time-ordered fusion + latest-value view; per-Environment lateness bound L (L=0 live); ingestion-order logging for bit-exact session replay. - ADR-0013: one push framework; Signal = idempotent target + freshness + StrategyId; two-part registration; fault isolation. CONTEXT.md: sharpen Strategy/Strategy Node/Core/Signal; add Backtest and the Execution environments section. Spec: status, parked leaves, Extism. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Closes Branch (C) of the from-scratch architecture grilling — three-plane observability (Business State / Domain Events / Telemetry) on a push-spine + narrow query; off-thread split egress; req/reply over the Bus (resolves the parked req/resp leaf); operational-only control with halt-via-risk; frontend-core library + two scopes + persistent session; host-OS trust boundary for MVP. Updates CONTEXT.md (Business State, Domain Event, Telemetry, Emergency Halt) and the grilling spec. All architecture branches now closed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Close the Bus-contract parked-question cluster from the from-scratch architecture grilling. - ADR-0020: Bus trait — two delivery classes (LatestValue keyed store / Reliable stream) x two access patterns; Serialize universal bound (zero-copy/POD a backend capability); loan-guard receive + three-boundary copy-out; publish(&M) + opt-in loan-to-write; (namespace, type, role, instance-key) identity with typed Key structs. Refines ADR-0002. - ADR-0021: two-level routing (coarse backend shard + in-process demux). - ADR-0022: Reliable order-path graduated failure; drain-fast adapter capability; risk-trip vs channel-death halt split. Amends ADR-0006/0017. - docs/design/bus-backend-realization.md: per-backend mechanism reference. - CONTEXT.md: add Source, LatestValue, Reliable; clarify Symbol. - ADR-0002: refinement pointer; spec: mark cluster closed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Close the numeric-types parked question. Drop rust_decimal; Price/Quantity are fixed-point always-i128 on the wire (Price signed, Quantity unsigned magnitude + Side). Two-domain split (exact i128 / analytical f64, convert at the strategy boundary); precision is instrument metadata, raw-only wire; money ops are checked with widen-to-256 notional; layered float-determinism scope (refines ADR-0012). Couples to the symbology thread (precision/tick/lot are instrument metadata). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Symbology grilling thread (ADR-0025): InstrumentId is the self-identifying canonical identity (externally anchored ISIN/FIGI/OCC where it exists, venue-qualified fallback, never guess a collapse); Symbol demoted to the venue ticker; off-wire Instrument record keyed (InstrumentId, Source) is the single home for ADR-0023 precision; fixed-size self-identifying name on the wire; deterministic rule + curated mapping with a cross-Source price-plausibility monitor; logged resolution + lifecycle (immutable id + logged succession, corporate actions as Core inputs). It reopened ADR-0011 -> ADR-0024: an Environment binds one-or-more same-safety-class execution backends, so cross-broker risk is in-fold; shadow/ live/off is per-strategy targeting, not an in-Core tag. Glossary gains InstrumentId, Instrument, Account, Position; Symbol redefined. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (8)
✅ Files skipped from review due to trivial changes (5)
🚧 Files skipped from review as they are similar to previous changes (3)
📝 WalkthroughWalkthroughAdds ChangesOATH Architecture ADR Corpus
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related issues
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/adr/0002-backend-agnostic-bus-canonical-message-model.md`:
- Around line 22-24: Update the payload contract wording in the ADR section so
it matches ADR-0020: in the canonical Bus model, describe the shared requirement
as Serialize only, and move any fixed-layout/POD/zero-copy language out of the
universal contract or rephrase it as backend-specific discipline. Keep the
wording consistent with the nearby refinement note and the canonical message
model section so the Bus contract is no longer self-contradictory.
In `@docs/adr/0003-canonical-model-adapter-translation.md`:
- Around line 16-19: Update the numeric-type example in the ADR text so it
matches the settled numeric-types decision and does not mention conflicting
alternatives like i64 or bignum. Keep the sentence generic about swappable inner
numeric types, or reference the actual fixed-point i128/u128 model used
elsewhere so the documentation stays consistent with the numeric-types ADR.
In `@docs/adr/0009-crate-topology-spine-inverted-process-aligned.md`:
- Around line 23-59: The crate layout tree in this ADR is missing a language tag
on the fenced block, so update the fence around the layout listing to use a text
code block. Keep the content unchanged and apply the fix in the documentation
snippet that contains the crate tree so markdownlint recognizes the block as
intentionally plain text.
In `@docs/adr/0012-strategy-input-fusion-event-time-parity.md`:
- Around line 7-11: Clarify the latency guarantee in the strategy input fusion
ADR by updating the paragraph around the lateness bound L so it does not imply
zero buffering latency for all values of L. In the relevant text about
configurable per-Environment lateness and the live decision path, make it
explicit that no buffering latency applies only when L = 0 for latency-critical
Live, while L > 0 may introduce buffering; keep the references to ingestion
order and replay behavior intact.
In `@docs/adr/0017-frontend-control-plane-operational-only.md`:
- Around line 13-16: Clarify the Supervisor halt flow so the effectful trip and
the recorded “halt as-of seq N” fact are described as a durable, atomic boundary
rather than “then emits” semantics. Update the wording in the ADR section
referenced by the Supervisor/Event Log description to state that the halt action
is only considered committed once the log fact is durably recorded, or otherwise
make clear the replay claim does not rely on a crash-prone gap between trip and
append.
In `@docs/adr/0020-bus-trait-delivery-classes-access-patterns.md`:
- Around line 21-29: The bus-trait wording in the ADR conflates the general
`Serialize`-only message allowance with a boundary rule that sounds like it
requires `M: Copy` at every loan boundary. Update the “Receive is a loan guard”
and boundary explanation in the ADR to state that non-`Copy` payloads are still
valid on the public API, and that only the act of crossing retention, thread
hand-off, or `.await` requires copying out to an owned value when the payload is
copyable or otherwise materializing ownership before the loan is dropped. Refer
to the `Sample<M>` loan-guard description and the boundary rule paragraph so the
contract is consistent throughout.
In `@docs/adr/0024-environment-multi-broker-binding-shadow-targeting.md`:
- Around line 15-21: The ADR text is using Symbol in the cross-broker
risk/position semantics where InstrumentId should be used instead; update the
affected wording in the risk-fold and position-keying sections to consistently
reference InstrumentId instead of Symbol. Make the terminology change throughout
the relevant clauses in this document, including the statement about positions
being keyed by (Account, InstrumentId) and any mentions of global per-identifier
tracking or cross-asset budget rules, so the language aligns with ADR-0025.
In `@docs/superpowers/plans/2026-06-27-crate-topology-adr-0009.md`:
- Around line 1458-1475: The literal package-name output blocks in this ADR
should be marked as text rather than left as untagged code fences. Update the
expected-output snippets in the affected section, including the final
package-path block, by adding the text language tag so the markdownlint warning
is resolved and the intent is clear. Use the surrounding fenced blocks in the
document to locate the snippets and apply the same change consistently.
- Around line 1324-1351: The Mermaid dependency graph is missing the direct
ooth-model edges for the core and strategy host crates, so update the graph in
the topology ADR to match the dependency table. Add the omitted links involving
oath-core and oath-strategy-host, using the existing Mermaid node symbols such
as core, kernel, risk, exe, por, strathost, and model, and keep the surrounding
explanatory note consistent with the corrected graph.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 7f3fd1c9-20f9-4a3f-aa69-2fbe93fe32ac
📒 Files selected for processing (29)
CONTEXT.mddocs/adr/0001-single-host-multi-process-topology.mddocs/adr/0002-backend-agnostic-bus-canonical-message-model.mddocs/adr/0003-canonical-model-adapter-translation.mddocs/adr/0004-risk-as-continuous-control-loop.mddocs/adr/0005-single-writer-event-sourced-core.mddocs/adr/0006-broker-reconciliation-contract.mddocs/adr/0007-binding-time-runtime-pluggable-iff-cross-process.mddocs/adr/0008-single-owner-kernel-stateless-policies.mddocs/adr/0009-crate-topology-spine-inverted-process-aligned.mddocs/adr/0010-strategies-out-of-core-deterministic-folds.mddocs/adr/0011-execution-environments-mode-isolation.mddocs/adr/0012-strategy-input-fusion-event-time-parity.mddocs/adr/0013-strategy-runtime-push-signal-target-registration.mddocs/adr/0014-observability-three-planes-deterministic-boundary.mddocs/adr/0015-off-thread-split-egress-observable-outputs.mddocs/adr/0016-request-reply-over-bus-query-tiering.mddocs/adr/0017-frontend-control-plane-operational-only.mddocs/adr/0018-frontend-architecture-scopes-library-session.mddocs/adr/0019-frontend-trust-boundary-host-os-mvp.mddocs/adr/0020-bus-trait-delivery-classes-access-patterns.mddocs/adr/0021-two-level-routing-in-process-demux.mddocs/adr/0022-reliable-order-path-graduated-failure.mddocs/adr/0023-numeric-types-fixed-point-exact-analytical-split.mddocs/adr/0024-environment-multi-broker-binding-shadow-targeting.mddocs/adr/0025-symbology-instrument-id-reference-data.mddocs/design/bus-backend-realization.mddocs/superpowers/plans/2026-06-27-crate-topology-adr-0009.mddocs/superpowers/specs/2026-06-23-from-scratch-architecture-grilling.md
Address internal cross-ADR inconsistencies surfaced in review: - 0002: payload contract is `Serialize`-only; POD is backend-specific zero-copy discipline (ADR-0020), not the universal Bus contract. - 0003: drop stale `i64`/bignum numeric example; point at the settled fixed-point `i128`/`u128` model (ADR-0023). - 0012: clarify that the live path is buffering-free only when `L = 0`; `L > 0` buffers up to `L`. - 0017: record the "halt as-of seq N" fact before/with the effectful trip so the deterministic-replay claim survives a crash window. - 0020: loan boundary materializes to an owned payload; `Copy` POD is a backend fast-path discipline, not a public-API bound. - 0024: key risk/positions by `InstrumentId`, not `Symbol` (demoted to a venue ticker by ADR-0025), so cross-broker collapse holds. - 0009 + crate-topology plan: tag plain-text fences as `text`; add the missing `oath-model` edges for `oath-core`/`oath-strategy-host` so the Mermaid graph matches the dependency table. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #44
What
Lands the full from-scratch architecture grilling corpus on
main:docs/adr/) — topology, backend-agnostic Bus contract,event-sourced single-writer Core, strategy runtime, three-plane observability,
frontend, numeric types, multi-broker Environments (0024), symbology (0025).
CONTEXT.md— ubiquitous-language glossary (InstrumentId,Symbol,Instrument,Account,Position, …).docs/superpowers/specs/) with the parked-questions list.Why
mainhad none of the canonical ADRs, so README/CLAUDEdocs/adr/*links dangledand the first implementation step (
oath-model) had nothing to cite. This unblockssequence step 2.
Notes
mainwas merged in (ADR-0009 craterestructure, refactor: implement ADR-0009 crate topology #40) so this is a clean squash-merge.
just ciis green (enforced by the pre-push hook).🤖 Generated with Claude Code
Summary by CodeRabbit