Aura/docs/design/contracts/c25-role-model.md

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

1. system programmer — the engine; Rust, this repo; all invariants.
2. extension dev — native nodes + analysis blocks; Rust in project/shared crates; C7/C8, determinism in eval.
3. toolchain dev — playground/viewer/skills pipeline; vendor-side; authoring ergonomics.
4. data curator — recorded streams, sidecars, derived/news recordings; CLI + recording edge; C2/C3/C6.
5. methodology designer — validation/eval process documents ("the game rules"); closed data vocabulary; anti-false-discovery.
6. 6a strategy designer — blueprint topologies; data (op-script/blueprint JSON, the graph idiom); C5/C7.
7. 6b campaign designer — campaign documents (persisted experiment intent); data, the pipeline/block idiom; C1.
8. player — owns nothing; explores traces, tunes runtime params; the playground, C22/C12; read-only by design.
9. 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 verb set is settled: run, the four thin per-verb generators, and the document verbs validate/introspect/register/show/run/runs — show being #300's read-back addition. The verbs' per-verb identity is re-ratified (#300 F8 — reduction, not grammar collapse). 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