docs: C19/C20 — bootstrap + strategy/harness; a project is a Rust program

Anchor the implementation-design branch: C19 (construction is a bootstrap phase — param-generic blueprint -> frozen instance; recursive up to the harness; params size/configure but never change topology). C20 (strategy = reusable context-free composite blueprint with role inputs + position-event output; harness = the root sim graph and C1's disjoint unit, with structural axes = experiment matrix vs tuning params = sweep; both strategy AND experiment authored in Rust via builder APIs, not a config DSL). Extend C8 (schema declares tunable params+ranges), C16 (a project is a Rust crate: cdylib of node/strategy/experiment blueprints + static Aura.toml; hosted by aura during research, frozen to a binary for deploy), C17 (all logic is Rust — nodes/strategies/experiments; Aura.toml = static context only), C12 (frozen topology = a harness instance; structural matrix is the outer axis). Add CLAUDE.md invariant 11; refresh project-layout.md (experiments/ dir, Rust experiments, day-in-the-life).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-03 09:54:44 +02:00
parent 1467fcd30f
commit 9eae43d308
4 changed files with 122 additions and 32 deletions
+27 -14
View File
@@ -16,25 +16,30 @@ from the things built with it:
signals.
- **A research project** is its **own external repo** (e.g. `~/dev/ger40-lab/`),
with its own git history, its own Gitea repo (its own forward-queue), and a
cargo dependency on aura. This is where you and Claude author signals and where
the runs live. (See contract **C16**.)
cargo dependency on aura. **It is itself a Rust crate** (a `cdylib` library of
node / strategy / experiment blueprints); the `aura` host loads and runs it
during research (hot-reload), and freezes a chosen strategy + broker into a
standalone binary for deploy. This is where you and Claude author signals *and
experiments* — all in Rust — and where the runs live. (Contracts **C16**, **C20**.)
The `aura` CLI is a tool you run *inside* a project directory — it finds the
project root by walking up to an `Aura.toml`, the way `cargo` finds `Cargo.toml`.
A project is always a Rust program built on the engine.
## A project repo
```
ger40-lab/ # your research project — a separate repo
├── Aura.toml # project config: symbols in scope, default data
│ # window, broker profile, runs dir (schema TBD)
├── Cargo.toml # depends on aura-core (+ shared node crates)
ger40-lab/ # your research project — a separate Rust crate (cdylib)
├── Aura.toml # STATIC context only: data paths, instrument/pip
│ # metadata, default broker & window, runs dir (no logic)
├── Cargo.toml # cdylib; depends on aura-core/aura-std (+ shared node crates)
├── CLAUDE.md # the project's own skills wiring (authoring discipline)
├── .claude/dev-cycle-profile.yml
├── nodes/ # project-local, experimental nodes (cdylib)
├── nodes/ # project-local node & strategy blueprints (Rust)
│ └── third-candle-long/
├── experiments/ # experiment/harness definitions (Rust): matrices, sweeps
├── runs/ # the run registry: manifest + metrics per run
└── (frozen bots, results, …)
└── (frozen bots, …)
```
## Where reusable nodes live (three tiers)
@@ -57,9 +62,11 @@ the dependent.
## Authoring happens in Claude Code (contract C17)
aura has no built-in coding-LLM. You author by talking to Claude Code, which
writes the node crate, builds it, runs it, and reports back. IONOS LLMs appear
only as a *runtime data source* (e.g. a news-agent node emitting a bias),
recorded before it enters a backtest, and only with your per-session consent.
writes the Rust — nodes, strategies, *and experiments* — builds it, runs it, and
reports back. Declarative config (`Aura.toml`) holds only static context, never
logic. IONOS LLMs appear only as a *runtime data source* (e.g. a news-agent node
emitting a bias), recorded before it enters a backtest, and only with your
per-session consent.
## A day in the life
@@ -77,11 +84,17 @@ recorded before it enters a backtest, and only with your per-session consent.
attached at once: add `--broker pepperstone` to get a realistic currency
curve *alongside* the default sim-optimal pip curve — two comparable equity
curves from the same position table. (Contract C10.)
4. **Sweep + Monte-Carlo:** `aura sweep … --grid lookback=5..50,thresh=0.5..0.9
--mc-seeds 1000` → a distribution of metrics, best params, robustness bands.
4. **Sweep / Monte-Carlo / matrix — a Rust experiment.** Anything beyond a
single backtest is an *experiment* in `experiments/` (Rust, builder API): a
parameter sweep, Monte-Carlo over seeds, or a structural matrix like "these 10
strategies × these 3 instruments × {sim-optimal, pepperstone}". The matrix is
plain Rust loops, not a config schema (C20). `aura run experiments/compare`
bootstraps the matrix, fans the disjoint sims over all cores (C1), and writes
the comparable runs to `runs/`.
5. **Compose:** "combine it with `momentum-filter` as a weighted sum" → Claude
writes a composite node (fractal, C9).
6. **Walk-forward:** `aura walkforward …` → an out-of-sample verdict.
6. **Walk-forward:** another experiment kind (rolling in-sample optimize +
out-of-sample test) → an out-of-sample verdict.
7. **Freeze:** `aura freeze nodes/strategy-y --broker pepperstone
--out bots/strategy-y` → a standalone, statically-linked bot (C13).
8. **(Later) Look:** `aura play` opens the egui playground — equity curve, trade