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.

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 is a decoupled downstream layer; 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 → position-management (the RiskExecutor composite, per symbol; the Veto an optional documented pre-trade-gate seam) turns bias + a protective stop into a managed position, in R. 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 — the research loop is pure feed-forward: flat-1R, gross R → net R via the composable cost-model graph (C10), no Sizer, no equity feedback, no z⁻¹ register. Money is a live/deploy-edge concern: currency P&L, fixed-fractional sizing, and compounding are post-hoc money-management transforms of the net-R sequence at the deploy/account layer, and the live broker is an I/O adapter at the recording/deploy edge (C11/C13), never part of the strategy. The broker-independent position-event table (event_ts, action[buy/sell/close], position_id, instrument_id, volume) survives as the decoupled, derived deploy/reconciliation audit artifact — 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).
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 native nodes live in the project's attached node crate; cross-project-reusable nodes in shared crates; universal blocks in aura-std (shipped here). Reuse is cargo-native. 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 a directory anchored by a static Aura.toml — data-only by default (blueprints + research documents over the std vocabulary, no build step), hosted by aura during research and frozen to a standalone binary for deploy. Native node logic lives in node crates: separate cdylib crates referenced via Aura.toml [nodes], scaffolded/attached by a dedicated verb (the visible role-2 switch); the hot-reload unit is the referenced node-crate cdylib. (#241 amendment, 2026-07-12 — re-opened deliberately by the role model's diagnosis.)
10. Authoring surface — all logic is Rust. Node, strategy, and harness logic is 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). Clarification (2026-07-03, #188/C25): a closed-vocabulary data artifact — an op-script, a blueprint, a process or campaign document — is NOT the forbidden DSL: what failed historically (RustAst) was an open, logic-bearing language; closed, typed vocabularies as serialized data (Blockly-litmus-clean, at most the total P1 construct tier) are the proven pattern, and experiment intent lives in them (C20/C25). Genuinely new logic escalates to a new Rust block (role 2), never to a freetext hole in an artifact. 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.
13. Self-description: every surface explains itself. Every closed- vocabulary entry the binary exposes (nodes, metrics, tap slots, folds, blocks) carries a one-line meaning, enforced at its entry seam — compile/unit for engine-shipped entries, load for native node crates, register for the content-addressed store (documents: an optional gated description). The gate is deterministic string shape (doc_gate), never content judgement: the engine never evaluates description text (no freetext logic hole, invariant 10), descriptions never influence execution, determinism (C1), or identity ids, and registered artifacts are never retroactively invalidated. (C29)

HTML surfaces

Every HTML surface — runtime-rendered (chart/graph viewer) or ad-hoc generated (demo/report pages) — embeds crates/aura-cli/assets/aura.css as its style source; the palette tokens and shared components live only there. New components extend that file; never fork the palette. Pages stay self-contained: all assets inlined, no external requests. Design record: issue #209.

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
• Bench — cargo run --release -p aura-bench -- run (cycle close; report-only — see crates/aura-bench/README.md)
• 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