claude
9eb6d6b4f6
Slice 8, closing the #319 retirement's prose and bench debt. Bench argv rides exec (fixed_cost single-run probe, campaign surfaces, and the seed helper that still called the retired sweep at runtime — caught by the bench run itself); all five fingerprints unchanged against the committed baselines, confirming record-line parity through the retirement. Live docs (README, authoring guide, project layout, glossary) describe only exec + campaign documents + graph introspect --params; three glossary entries explicitly mark their verb retired. Ledger amendments per the C29 discipline — C25's executor-verb-set re-settled (exec + the --override residue), C14's dual grammar reduced to the one dispatch, C24's document-built runs/families + gated-intake route list (lockstep with the code comment), C12's override clause and identity anchor repointed to the runner-layer hash computation, C18/C22/C27/C01 mention rewrites — superseded sentences moved verbatim to the history sidecars (c25's created). Stale dual-grammar doc comment on is_blueprint_file rewritten. refs #319
5.9 KiB
C25 — The role model: nine authoring roles, cut by artifact + surface + iteration cost
Guarantee. aura's user-facing design is organized by roles, cut by the artifact a role owns, the surface/language it works in, and the iteration cost it tolerates — never by org chart. One trader — or an LLM actor, which is the whole point of the authoring design — must be able to fill every role; the separation separates surfaces with different iteration costs and failure modes, not people, and switching roles is a visible act. The nine roles (ratified 2026-07-03, #188):
- system programmer — the engine; Rust, this repo; all invariants.
- extension dev — native nodes + analysis blocks; Rust in project/shared
crates; C7/C8, determinism in
eval. - toolchain dev — playground/viewer/skills pipeline; vendor-side; authoring ergonomics.
- data curator — recorded streams, sidecars, derived/news recordings; CLI + recording edge; C2/C3/C6.
- methodology designer — validation/eval process documents ("the game rules"); closed data vocabulary; anti-false-discovery.
- 6a strategy designer — blueprint topologies; data (op-script/blueprint JSON, the graph idiom); C5/C7.
- 6b campaign designer — campaign documents (persisted experiment intent); data, the pipeline/block idiom; C1.
- player — owns nothing; explores traces, tunes runtime params; the playground, C22/C12; read-only by design.
- operator/auditor — frozen bots, reconciliation, money management; deploy-edge CLI, manifests, reproduce; C13.
The 6a/6b split follows invariant 12's tier boundary (node/harness vs World); the interface between them is the id machinery (content id = byte-exact, identity id = topological). The param gradient runs 6a defines topology + open params, 6b spans spaces over them, 7 moves inside those spaces live. A role is recognizable when four things exist: a named artifact type it owns, a surface addressed to it, an entry path, and its invariants enforced at its boundary.
Text-first / headless-first is an invariant, not a taste (owner-ratified 2026-07-03: editors must never be the only way; LLM operability demands it): every artifact class has a canonical, complete, text-serialized form; every operation is executable headless via CLI/API; visual surfaces are stateless projections that read/write the same canonical form and add no semantics — read-only projections (viewers) rank far above write editors. The Blockly litmus test is the acceptance criterion for every artifact vocabulary, editor or no editor: a block palette must be generatable from the vocabulary — every block with typed slots, every valid composition snappable, every invalid one not.
Control surfaces are projections (#295, ratified 2026-07-20). The text-first invariant fixes the control-surface layering: the text artifact vocabulary (blueprints, process/campaign documents, registry records) is the canonical layer, and every control surface — the one-shot CLI's executor verbs, any future long-running host, any MCP face, a World program — is a projection/executor over those artifacts, never a second home for intent.
Forbids. An artifact class whose only authoring path is a visual editor or a Rust compile cycle when the role's iteration cost demands data (the role-6b lesson: a tiny campaign change must never cost a compile); stringly-typed fields, implicit inter-block coupling, or "arbitrary JSON here" holes in a role's vocabulary (they fail the litmus test); collapsing the 6a/6b idioms into one surface (dataflow boxes-and-wires vs sequential pipeline blocks are different languages).
Why. The game-engine analogy that seeded aura (C16) extends to its people: engines separate system programmers, toolchain devs, asset creators, level designers, and players because their artifacts, tools, and iteration loops differ — a design that forces one role's technique on another (Rust for campaign tweaks, an editor as the only entry) mis-prices iteration exactly where research throughput lives.
Current state
Roles 5 and 6b have their artifacts — process and campaign documents (C18; #189). Roles 4, 7, and 8 remain technically present but faceless: no addressed verb families yet. Role homes in the project layout and docs-by-role are open (#192).
Document-first completion is the resolved direction on the control-surface
amendment (owner-minuted 2026-07-21 on #295), delivered by #300. The executor
surface is settled again, one reduction further (#319, 2026-07-25): a single
exec <target> verb runs both document classes — a campaign (file or content
id) and a signal blueprint (single run) — over the document verbs
validate/introspect/register/show/runs (show #300's read-back addition); the
one argv residue is --override NODE.PARAM=VALUE, a per-execution bound-param
reopen threading through both exec legs. A typed-protocol host or MCP face
remains demand-driven and unbuilt.
See also
- C16 — the game-engine analogy this extends to people
- C17 — all logic is Rust; closed-vocabulary data artifacts are not the forbidden DSL
- C18 — the process/campaign document artifacts and the run registry
- C20, C21 — the node/harness/World tiers behind the 6a/6b split
- C24 — topology-as-data, the strategy designer's artifact
- C26 — a role's input contract carried in blueprint data
History: c25-role-model.history.md