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](c07-scalar-soa.md)/[C8](c08-node-contract.md), 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](c02-causality.md)/[C3](c03-single-merge.md)/[C6](c06-firing-policy.md).
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](c05-freshness-gating.md)/[C7](c07-scalar-soa.md).
7. **6b campaign designer** — **campaign documents** (persisted experiment
   intent); data, the pipeline/block idiom; [C1](c01-determinism.md).
8. **player** — owns nothing; explores traces, tunes runtime params; the
   playground, [C22](c22-playground-traces.md)/[C12](c12-atomic-sim-unit.md);
   read-only by design.
9. **operator/auditor** — frozen bots, reconciliation, money management;
   deploy-edge CLI, manifests, reproduce; [C13](c13-hot-reload-frozen-deploy.md).

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](c16-engine-project-split.md))
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](c18-registry.md); #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](c16-engine-project-split.md) — the game-engine analogy this extends to people
- [C17](c17-authoring-surface.md) — all logic is Rust; closed-vocabulary data artifacts are not the forbidden DSL
- [C18](c18-registry.md) — the process/campaign document artifacts and the run registry
- [C20](c20-strategy-harness.md), [C21](c21-world.md) — the node/harness/World tiers behind the 6a/6b split
- [C24](c24-blueprint-data.md) — topology-as-data, the strategy designer's artifact
- [C26](c26-input-binding.md) — a role's input contract carried in blueprint data

> History: [c25-role-model.history.md](c25-role-model.history.md)