docs: C21/C22 — the World is the product; playground is a trace explorer

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) <noreply@anthropic.com>

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.

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.

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).