Aura/CLAUDE.md

aura — project rules

aura is a "game engine for traders": a Rust framework and a playground to author trading nodes, backtest them deterministically and massively in parallel, compose them fractally, validate them (sweep / Monte-Carlo / walk-forward), and freeze a validated strategy into a standalone bot with a broker connection.

This file is the project sittenkodex. It imports the universal discipline from ~/dev/skills/templates/CLAUDE.md.fragment and adds aura's domain invariants. The full architecture lives in the design ledger (docs/design/), not here. Per-cycle specs (docs/specs/) and plans (docs/plans/) are ephemeral working artifacts, kept git-tracked — committed while their cycle is live and removed (git rm) at cycle close, valid only for the cycle that produces them. Durable rationale is lifted to the ledger; a spec/plan is never treated as a live API reference (its code snippets drift the moment the code moves). The canonical record of past cycles is the ledger plus the git history.

Roles

I am the orchestrator, not the implementer. The skills-plugin agents are my workers: I plan, design, decide, and integrate; they implement, refactor, test, and diagnose. Trivial mechanical edits I may do directly; anything needing broad reading or judgement goes to an agent. Agent reports describe intent, not outcome — I verify the diff and the test output myself before committing.

Commit discipline and main-branch sanctity

• Only the orchestrator commits. No skill agent runs git commit; agents leave their output as unstaged working-tree changes for me to inspect and shape into commits.
• main HEAD is sacrosanct — with one narrow /boss exception. As a rule, no git reset/git revert on main: it moves forward only via my commits, and pushed or user-ratified history is never rewound (a bad landing there is fixed forward with git revert, never reset). Wrong agent output is discarded with git checkout -- <paths>/git stash. The exception: under /boss, the orchestrator MAY git reset --hard to wind back its own autonomous, unpushed commits made this run — those above the session anchor (main HEAD at the run's start) — when it has run a line of work into a genuine dead end. Never below the anchor; never a pushed commit; the discarded attempt is hard-dropped (its trace survives in the run's reference issue). This is the /boss rollback sandbox, not a licence to rewrite history.
• When a commit closes a Gitea issue, reference it in the body: closes #N (or refs #N for non-final work).

Design rationale ≠ implementation effort

Design choices are justified by substance — semantics, structural fit, what the design permits vs forbids, compositional clarity, future-proofing. Implementation effort ("approach A touches 250 sites, B touches 1") is an observation about the current code, not a rationale. Effort is at most a named tiebreaker after substantive reasons tie.

Bug fixes — TDD, always

Bug fixes are RED-first and autonomous: the failing test exists in the working tree before any fix. The debug skill is mandatory for any observable misbehaviour (failing test, panic, wrong output).

Domain invariants (load-bearing — never silently violate)

These are the contracts the whole design rests on. A change that breaks one is a design decision, not a refactor, and belongs in the ledger.

1. Determinism. A backtest is a deterministic, synchronous, non-concurrent event loop that reaches a unique state after each input tick. Same input → same run, reproducibly. Two backtests are fully disjoint → concurrently executable without locking. Parallelism is across sims, never within one.
2. Causality / no look-ahead. A node sees only the past. Look-ahead is made structurally impossible (read-only input windows that end at the cursor; resamplers emit a bar only once it is complete), not merely discouraged.
3. One merge, at ingestion only. Heterogeneous timestamped sources are k-way-merged into a single chronological cycle stream at the ingestion boundary. There is no merge / as-of join inside the graph.
4. The four scalar base types, streamed as SoA. Only i64, f64, bool, timestamp are streamed, as columnar Structure-of-Arrays. Composite streams (e.g. OHLCV) are bundles of base columns. Non-scalars (String, Records, tables, calendars) exist as metadata beside the hot path, never in it.
5. Acyclic dataflow. The graph is a DAG; the only feedback path is an explicit delay/state node (the RTL "register"). The "cycle" of the research workflow is not a dataflow cycle.
6. Record-then-replay determinism boundary. Anything non-deterministic, external, or slow (LLM news agents, web sources) is materialized into a recorded, timestamped stream before it enters the engine. The sim never makes a live external call mid-replay. (See ~/.claude/CLAUDE.md for the IONOS consent rule: external LLM calls happen at the recording/live-source edge, with explicit per-session consent, never inside a backtest.)
7. Strategy output is a directional bias stream; risk-based execution and realistic brokers are decoupled downstream layers; signal quality is measured in R. The DAG expresses one state at t (C8: ≤1 record per eval), so a strategy's primary, backtestable output is a signed, bounded bias f64 ∈ [-1,+1] per cycle — direction (sign) + conviction (magnitude, optional), unsized (not an equity curve, not a position, not a size). Sizing leaves the strategy: a decoupled risk-based execution layer bias → stop-rule → Sizer → Veto → position-management (the RiskExecutor composite, per symbol, nested in a Broker/Account composite) turns bias + a protective stop into a sized intent. The stop defines the risk unit R (1R = the loss if stopped). Signal quality is measured in R (R-multiples / expectancy), the account- and instrument-agnostic yardstick — Stage 1: flat-1R sizing, feed-forward, no equity feedback, the primary research loop. Currency P&L is Stage 2 (deploy viability): fixed-fractional sizing reads equity (compounding) → realistic brokers apply real frictions → currency equity, entered only after E[R] > 0. The single feedback (equity → Sizer) is cut by a z⁻¹ register on the fill edge (mark-to-market stays a same-cycle price read), encapsulated in the executor composite; flat-1R vs compounding is a structural axis (C11). The broker-independent position-event table (event_ts, action[buy/sell/close], position_id, instrument_id, volume) remains the decoupled, derived Stage-2 audit layer — the first difference of the book (deal = target − book − in_flight), a computed table (not a per-eval output, since one decision instant may yield >1 event) — feeding realistic brokers. Brokers/executors are ordinary downstream nodes, never part of the strategy; account mode (netting/hedging) is a composition constraint.
8. Deploy artifacts are frozen. Hot-reload (cdylib) is an authoring-loop tool only. The live bot is a statically-linked, versioned, frozen artifact — never hot-swapped (audit trail: this bot = this commit).
9. Engine / project separation. This repo is the reusable engine. Research projects are separate external repos that depend on it. Project-specific signals live in a project's nodes/; cross-project-reusable nodes in shared crates; universal blocks in aura-std (shipped here). Reuse is cargo-native; the hot-reload unit is always the project-side cdylib. No user/project signals in this repo (only examples/ fixtures for the engine's own tests); no multi-project manager or node registry inside aura. A project is always a Rust crate (a cdylib library of node / strategy / experiment blueprints + a static Aura.toml), hosted by aura during research and frozen to a standalone binary for deploy.
10. Authoring surface — all logic is Rust. Nodes, strategies, and experiments/harnesses are authored in native Rust via Claude Code + the skills pipeline, using builder APIs. Declarative config (Aura.toml) carries only static project context, never logic — no experiment/strategy DSL (the RustAst trap). aura ships no embedded coding-LLM; IONOS LLMs are used only as a runtime data source (news bias), with per-session consent, never in the code path.
11. Construction is a bootstrap phase. Blueprints (param-generic graph-as- data from a Rust builder) are bootstrapped into frozen instances (buffers sized, topology fixed) by binding params + data + seed. Params configure and size nodes but never change topology (a topology change is a different blueprint). The harness — sources + strategy + broker node(s) + sinks — is the root sim graph, itself bootstrapped, and is C1's disjoint unit; its structural axes form the experiment matrix, its tuning params the sweep. The bootstrap is a compilation to a flat, type-erased FlatGraph, wired by raw index (composites inline — a composite is an authoring-level node, not a runtime object; names survive only as non-load-bearing debug symbols, as today). The flat graph is the target of behaviour-preserving optimisation, C1 the correctness invariant — intra-graph (CSE/DCE) and across a sweep family (sweep-invariant sub-graph computed once, shared via C11/C12). See C9/C19/C23.
12. The World is the product; the playground is a trace explorer. Three ontological tiers: a node is an open, composable fragment (at most one output, C8); a harness is the closed root graph that runs (sources + strategy + brokers + sinks + clock — C1's disjoint unit / root scope), not a node; the World is the program that dynamically constructs and orchestrates families of harnesses (walk-forward / sweep / MC / comparison) — aura's differentiator, not the single backtest. The World is a program: nothing is displayable until it runs, and what is displayable is exactly what a sink (C8) records into the registry (C18). The playground plays any harness and is an execution viewer / trace explorer (structure before, live streams during, recorded traces after) — never a scene editor; topology is grown in Rust + hot-reload, runtime params are UI-tunable.

Skills plugin: project facts

The few facts the skills plugin needs that genuinely vary per project. Everything else is a fixed convention (see ~/dev/skills/docs/conventions.md).

• Code roots — crates
• Build — cargo build --workspace
• Test — cargo test --workspace
• Lint — cargo clippy --workspace --all-targets -- -D warnings
• Doc build — cargo doc --workspace --no-deps 2>&1
• Design ledger — docs/design/INDEX.md
• Glossary — docs/glossary.md
• Issue tracker — Gitea, repo Brummel/Aura:
  • browsable URL: http://192.168.178.103:3000/Brummel/Aura/issues
  • list open issues: tea issues ls --repo Brummel/Aura --state open