From e2dcc7471d5accc6ba6b43f64464c1e6f12c82ec Mon Sep 17 00:00:00 2001 From: Brummel Date: Wed, 3 Jun 2026 10:47:16 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20C21/C22=20=E2=80=94=20the=20World=20is?= =?UTF-8?q?=20the=20product;=20playground=20is=20a=20trace=20explorer?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Anchor the world/playground bundle. C21 (the World: harnesses are dynamically constructible first-class objects; orchestrating families of them via the C12 axes is aura's differentiator, not the single backtest which is commodity; registry is the World's memory). C22 (the World is a program -> nothing displayable until it runs; the only durable displayable substance is the recorded trace; sinks (C8) are the recording mechanism into the registry (C18); the playground plays ANY harness and is a trace explorer / execution viewer, never a scene editor; observability is explicit/selective; samples ship with sinks). Sharpen C20 (open node vs closed harness; a harness is NOT a node, it is the closure that runs / the root scope; harnesses do not nest as nodes — the World orchestrates them as objects). Correct C14 (playground is core, not 'freely deferrable'). Foundation positioning (World = product, single-harness engine = substrate). CLAUDE.md invariant 12; project-layout day-in-the-life. Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 12 ++++++ docs/design/INDEX.md | 85 +++++++++++++++++++++++++++++++++++++----- docs/project-layout.md | 14 ++++++- 3 files changed, 99 insertions(+), 12 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e00d5b7..7c760b7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -110,3 +110,15 @@ design decision, not a refactor, and belongs in the ledger. 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. +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. diff --git a/docs/design/INDEX.md b/docs/design/INDEX.md index 554588e..c6ea9a0 100644 --- a/docs/design/INDEX.md +++ b/docs/design/INDEX.md @@ -35,6 +35,12 @@ inverts it — engine in Rust, strategies in Rust — but keeps RustAst's *conce RustAst is a conceptual reference, not a dependency. The one reused component is `data-server` (the first data source). +What sets aura apart is **not** the single backtest — every quant system does +that — but the **World**: the meta-level where harnesses are dynamically +constructed and *families* of them orchestrated and explored (walk-forward, +sweeps, Monte-Carlo, comparison). The deterministic single-harness engine is the +*substrate*; the World is the *product* (C20–C22). + --- ## Contracts @@ -242,9 +248,9 @@ for human exploration. Visualization is only a downstream consumer node on the streams. **Forbids.** Any UI/pixel knowledge inside the engine. **Why.** The LLM drives programmatically, the human visually; a headless core -serves both and makes the visual face freely deferrable. (Visual face leaning -egui-native, in-process zero-copy from the SoA columns — deferred decision, see -Open threads.) +serves both. The visual face is the **playground** (C22) — egui-native, +in-process zero-copy from the SoA columns; it is staged after the runnable +substrate but is core to aura's identity, not optional. ### C15 — Resampling-as-node; sessions/calendars **Guarantee.** A resampler is a node (finer stream → coarser bar stream), @@ -349,10 +355,17 @@ swept *within* a fixed structure (Fork A). The same strategy blueprint is reused across backtest, sweep, visual workspaces, and the frozen live bot — each a different harness. **Both strategy and harness/experiment are authored in Rust** via builder APIs (C17); the experiment matrix is ordinary Rust control flow -(loops/conditionals), not a config schema. +(loops/conditionals), not a config schema. Ontologically, a node (incl. a +strategy composite) is an **open** fragment — free input roles + ≤1 output +(C8/C9) — that does not run alone; a **harness is the closed root graph**: a +strategy with its input roles bound to sources and its output terminated in +broker/sink nodes, under a clock. A harness is therefore **not a node** (no free +inputs, no output; it does not fit `eval`) — it is the *closure that runs*, C1's +disjoint unit / the root scope. Harnesses do not nest as nodes; the World (C21) +orchestrates them as objects. **Forbids.** Embedding data sources / brokers / sinks inside a strategy; a -declarative experiment mini-DSL (logic is Rust — C17); treating the harness as -anything but a (root) graph. +declarative experiment mini-DSL (logic is Rust — C17); modelling the harness as +a node (it is the closed root scope, not an open composable node). **Why.** Reusability needs the strategy to be a context-free blueprint that many harnesses embed. Modelling the harness as a root graph keeps it within the one Node/graph abstraction (C9) and makes "10 strategies in one environment" and @@ -361,12 +374,61 @@ authoring (not config) preserves full programmatic power — conditional/adaptiv matrices, generated axes, custom wiring — and avoids re-introducing the DSL trap C17 rejects. +### C21 — The World: the meta-level is the product +**Guarantee.** Above the harness sits the **World** — the project's program / +"game" (C16: a Rust crate). Within it, **harnesses are dynamically constructible, +first-class objects**: meta-programs (walk-forward, sweep, optimize, +Monte-Carlo — C12's axes) construct harness instances at runtime via the +bootstrap (C19), run them disjointly in parallel (C1), aggregate / compare their +results, and discard the transient instances. A walk-forward rolls windows → +bootstraps a harness per window → stitches out-of-sample equity + parameter +stability into one meta-result. Orchestrating *families* of harnesses is +**first-class**, not a headless afterthought; the run registry (C18) is the +World's memory. +**Forbids.** Relegating multi-harness orchestration (walk-forward / sweep / +comparison) to second-class headless-only status; treating the single backtest +as the product. +**Why.** What happens *within* one harness — backtest a strategy → equity — is +commodity; every quant system covers it. aura exists for the meta-level: a +programmable space where harnesses are dynamically built and families of them +orchestrated and explored. The deterministic single-harness engine (C1–C20) is +the **substrate**; the World is the **product**. + +### C22 — The playground is a trace explorer; sinks are the recording mechanism +**Guarantee.** The World is a *program*: nothing is displayable until it runs, +and its harnesses are transient machinery (built, run, discarded — C21). The only +durable, displayable substance is the **recorded trace**, captured by **sinks** — +pure consumer nodes (C8) that persist a stream (equity, position events, a node's +output) into the run registry (C18). **Displayable = exactly what a sink +recorded**; with no sink, only input params + summary metrics remain. The +**playground** is therefore an **execution viewer / trace explorer**, and it +plays *any* harness (it is the harness *player*, not a harness, never bound to a +default one): before a run it shows the program *structure* (graph-as-data, C9) + +param knobs; during a run, live sink streams; after a run, recorded traces + +metrics from the registry — including meta-views (stitched walk-forward, sweep +surfaces, multi-strategy / instrument comparison). Observability is **explicit +and selective** — you instrument what you want to see; the choice of sinks is +part of the experiment. The engine ships sample harnesses *with* sinks so a +newcomer sees a populated trace immediately; a fresh project is empty until +built, run, and instrumented. +**Forbids.** A scene-editor model that assumes a persistent populated world; +constructing or wiring topology in the UI (topology is Rust + hot-reload, +C9/C17 — the UI reflects the live graph-as-data and tunes runtime params via +sliders, C12); retaining un-sinked data; binding the playground to a single / +default harness. +**Why.** A program has no scene-at-rest to inspect; what persists is what it +records. Making sinks the one recording-and-observability mechanism keeps "what +can I see?" answerable by "what did I instrument?", and keeps the engine +UI-agnostic (C14). Live param tuning (runtime values, no topology change — +C12 / C19 Fork A) gives the interactive feel without a wiring DSL. + --- ## Open architectural threads not yet resolved -- **Visual playground form** — leaning egui-native; deferred. The headless core - (C14) makes deferring it free. +- **Playground & World UI surface** — the playground is core (C22), egui-native; + open is the concrete UI of the meta-views (walk-forward, sweep surfaces, + comparison) and the run/replay clock controls. - **Parameter-space search strategies** (Bayesian/genetic) — pluggable policies atop the atomic sim unit (C12), not yet designed. - **`aura new` scaffolder, the experiment-builder API, and `Aura.toml`'s @@ -379,5 +441,8 @@ C17 rejects. land first follows the walking-skeleton's needs. - **`strategies/` split** — a later split, *inside a project*, of top-level strategies from reusable building blocks in `nodes/`; not a day-1 cut. -- **Sequencing** — engine + CLI face first; walking-skeleton milestone before - hot-reload, sweep, sessions, the run registry, and the visual playground. +- **Sequencing** — the runnable single-harness *substrate* comes first (walking + skeleton: a closed harness that runs deterministically and records via a sink); + the World/meta layer (C21) and the playground trace-explorer (C22) are the + differentiating layers that follow — you orchestrate and visualize a thing that + must first run once. diff --git a/docs/project-layout.md b/docs/project-layout.md index 6697be8..452529e 100644 --- a/docs/project-layout.md +++ b/docs/project-layout.md @@ -97,8 +97,18 @@ per-session consent. 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 - overlays on the chart, sweep heatmaps. For *looking*, not authoring (C14). +8. **Explore — `aura play`.** The playground plays *any* harness and shows what + your **sinks** recorded (C22): live equity/signal streams while a run + executes, and recorded traces + meta-views afterwards — stitched walk-forward + equity, sweep surfaces, multi-strategy comparison. It is a trace explorer, not + a scene editor (the World is a *program*; only sink-recorded data is visible — + no sink, nothing to see). Topology you grow in Rust (hot-reload); runtime + params you tune with sliders (C12). + +The real value is not step 3 (one backtest — every quant system does that) but +the **World**: steps 4/6 dynamically construct and orchestrate *families* of +harnesses, and the playground explores those families. The single-harness engine +is the substrate; the World is the product (C20–C22). CLI command names and `Aura.toml` are illustrative; the concrete surface is designed with the relevant milestone (see the open threads in the design ledger).