claude
8688a60ded
The single-file ledger had grown to 2968 lines / ~42k tokens, mixing current design law with accreted history: 59 cycle-stamped realization blocks, 18 [HISTORY] passages, 22 supersession markers, and the C10 / C22 / C24 reframe sagas layered several supersessions deep. A code-grounding audit (31 agents, adversarially verified) confirmed 11 defects stated as current truth: stale crate homes from the C28 #288 roster split (cost nodes, PositionManagement, PositionEvent, Session), the renamed InputSpec->PortSpec, the pre-#241 project model in C16 and the open-threads section, a stale HarnessKind retirement deferral in C24, and three C28-internal inconsistencies. New shape, per the ailang precedent: - INDEX.md stays the sole addressable entry point: foundation, external components, a C-id-keyed contract map (one line per contract), and only the genuinely open architectural threads. - contracts/cNN-<slug>.md carries each contract's current truth only: Guarantee / Forbids / Why with ratified refinements integrated, plus a code-anchored Current state. All confirmed defects are fixed here; crate anchors were re-verified against the tree. - contracts/cNN-<slug>.history.md (18 sidecars) and INDEX.history.md preserve every superseded block verbatim, stamps and issue refs intact, under a frozen-record banner. Nothing was deleted: superseded design intent remains an addressable working-tree artifact, off the per-cycle audit walk. - Ledger discipline is now stated in INDEX.md: live files are edited in place at cycle close, superseded text moves verbatim to the sidecar, and a supersession marker in a live file is itself an audit finding. Every contract file was verified against its old text by an independent zero-loss pass (statement-by-statement) plus a code-accuracy spot check; C-ids and contract titles are unchanged, so existing C-id citations in code, tests, and issues resolve as before.
91 lines
5.7 KiB
Markdown
91 lines
5.7 KiB
Markdown
# 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 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](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
|