@cynodia/axiom 0.6.0-alpha.1 → 0.6.2-alpha.1

package/README.md

@@ -12,7 +12,7 @@ releases. The documentation in `docs/` describes this exact version.
 ## Installation
 
 ```bash
-npm install @cynodia/axiom@alpha
+npm install @cynodia/axiom
 ```
 
 ## Canonical mental model

package/docs/ACTIONS_TRANSACTIONS.md

@@ -1,6 +1,6 @@
 # Actions and transactions
 
-Axiom 0.6.0-alpha.1. An action is behavior expressed as data, executed as a transaction.
+Axiom 0.6.2-alpha.1. An action is behavior expressed as data, executed as a transaction.
 
 ```ts
 {
@@ -40,6 +40,22 @@ result.diagnostics[0].details  // { preconditionIndex: 2, failureMode: 'insuffic
 
 `actionGuards(action)` returns the conditions however they were written.
 
+### Guards evaluate in order, and the first failure stops
+
+Declaration order is evaluation order. The first guard that does not hold refuses the
+invocation, and evaluation stops there: later guards are not evaluated, and exactly one
+`PRECONDITION_FAILED` is reported, naming that guard by position and by failure mode.
+
+This is the contract, not an implementation detail, and it has three consequences worth
+writing an action around:
+
+- **A guard may rely on the guards before it.** Ordering `required(x)` ahead of a guard that reads a field of `x` is how the second one is kept evaluable.
+- **A refusal names one cause.** Failures are not aggregated. An interface that wants to show every problem at once should express them as constraints, which are evaluated over the whole proposed state, rather than as guards.
+- **A guard that cannot be evaluated fails.** It refuses, exactly as an unevaluable constraint counts as violated — never passes.
+
+Aggregating guard failures would be a different feature with a different diagnostic shape,
+and is deliberately not this one.
+
 ## Lifecycle
 
 ```text

package/docs/AGENT_API.md

@@ -1,6 +1,6 @@
 # Agent API
 
-Axiom 0.6.0-alpha.1. The machine-facing interface. Agents query semantics and apply
+Axiom 0.6.2-alpha.1. The machine-facing interface. Agents query semantics and apply
 structural transformations; they never edit generated code.
 
 ```ts
@@ -121,7 +121,8 @@ reported.
 ```ts
 {
   formId, density,
-  submitActionId?,          // submitActionId, or the declared submit button's own action
+  submitActionId?,          // submitActionId, or the declared submit button's own action —
+                            // the same resolution execution, validation and presentation use
   submitButtonId?,          // set when the form declares its submit control
   sections: [{ nodeId, name?, headings: string[], inputIds }],
   ungroupedInputIds,        // controls belonging to no section

package/docs/AGENT_REFERENCE.md

@@ -1,6 +1,6 @@
 # Agent reference
 
-Axiom 0.6.0-alpha.1. Compressed operational contract. Read this plus the `.d.ts`
+Axiom 0.6.2-alpha.1. Compressed operational contract. Read this plus the `.d.ts`
 declarations before authoring or modifying an Axiom application.
 
 Formal guarantees: [`SEMANTIC_CONTRACT.md`](SEMANTIC_CONTRACT.md). Mistakes that compile:
@@ -408,13 +408,22 @@ not a constraint. Enforcement belongs to guards, constraints and transition cons
 
 ```ts
 const ir = compileToIR(graph);                  // throws GraphValidationError if invalid
-const html = compileToHtml(graph, { title?, appearance? });
+const html = compileToHtml(graph, { title?, appearance?, remote? });
 const css = createThemeStylesheet(ir.theme);
 
-const app = createAxiomRuntime({ ir, rootElement, host, nativeOperations?, inputValidation?, recordMutationValues? });
-app.start();
+const app = createAxiomRuntime({ ir, rootElement, host, remote?, nativeOperations?, inputValidation?, recordMutationValues? });
+await app.start();                              // render → restore → load authoritative state
 ```
 
+`start()` renders synchronously and then loads authoritative state when a gateway is
+configured; awaiting it means that has happened. **The gateway must be passed to
+`createAxiomRuntime`, before `start()`.** A failed load reports `AUTHORITY_UNREACHABLE` and
+leaves `authoritativeStateLoaded()` false — it never throws, and never looks like empty data.
+
+`compileToHtml` wires the browser-safe gateway into the generated page whenever the IR
+contains a remote action, so a server-authoritative application needs no client JavaScript
+of its own. `remote: { endpoint }` points it elsewhere; `remote: false` switches it off.
+
 `compileToIR` refuses an invalid graph. Pass `{ validate: false }` only for diagnostics.
 
 Hosts: `createBrowserHost()` for a page, `createMemoryHost()` for headless use. The runtime
@@ -431,7 +440,11 @@ reads nothing from globals.
 | `diagnostics()` / `clearDiagnostics()` | — | Running log. |
 | `getMutationLog()` | — | Every attempted mutation with source, path and `outcome`. |
 | `registerNativeOperation(id, fn)` | — | |
-| `start()` / `render()` | — | Rendering is a full re-render; focus and caret are restored by node id. |
+| `start()` / `render()` | — | `start()` is render → restore → synchronize, and returns a promise. Rendering is a full re-render; focus and caret are restored by node id. |
+| `invokeActionAsync(id, args?)` | yes | Awaits the outcome, an authority's answer included. |
+| `syncAuthoritativeState()` | — | Loads and applies the authoritative snapshot. Idempotent. |
+| `authoritativeStateLoaded()` | — | Whether a snapshot has been applied. Not the same question as "is this collection empty". |
+| `settled()` | — | Resolves when no remote invocation is outstanding — how to await an action a click or a form submit started. |
 
 ## Diagnostics
 
@@ -481,6 +494,12 @@ authoring an application that crosses the trust boundary.
 5. **CONCURRENCY** — two actions cannot both commit from incompatible snapshots.
 6. **PROTOCOL** — a client requests semantic actions, never mutation programs.
 7. **SERIALIZATION** — authoritative behavior is data. No closure, no arbitrary code.
+8. **BOOTSTRAP** — a remote client is given its gateway before it starts.
+9. **STARTUP** — `start()` renders, then synchronizes; a failed load is a diagnostic.
+10. **FORM SUBMIT** — a declared submit button invokes with its own arguments, clicked or submitted.
+11. **IDEMPOTENCY** — a generated request id is unique across runtime instances; records are scoped by principal.
+12. **CHANGES** — `changes` names every observable state whose value moved, and no others.
+13. **PORTABILITY** — `axiom.server.v1` is frozen and language-independent.
 
 ```ts
 { id: STATE_PRODUCTS, kind: 'state', authority: 'server' }                  // the authority owns it
@@ -506,23 +525,50 @@ graph.setPrincipalEntity(ENTITY_USER);
 ```
 
 `PRINCIPAL` is bound to a record keyed by the principal entity's field ids, and **only where
-an authority evaluates**. A rule that cannot be evaluated denies. `requiresConfirmation` is
-interaction, not authorization.
+an authority evaluates** — which is everywhere on the authority, not only in `authorization`:
+guards, operation values, postconditions and constraints alike. That is how a record says who
+caused it without a client being asked to claim an identity:
+
+```ts
+{ fieldId: F_ORDER_PLACED_BY, value: field(ref(PRINCIPAL), F_USER_ID) }
+```
+
+Reading it anywhere a client evaluates is `PRINCIPAL_REFERENCE_ON_CLIENT`. A rule that cannot
+be evaluated denies. An anonymous caller has no principal: attributes read from it are absent,
+so any rule naming one is false. `requiresConfirmation` is interaction, not authorization.
 
 ### Running one
 
-```ts
-const server = createAxiomServer({ ir: compileToServerIR(graph), persistence, host });
-await server.start();
-await serveOverHttp({ server, port: 3000 });
+One graph, one process — the generated page and the authority that answers it:
 
-const app = createAxiomRuntime({ ir, rootElement, host, remote: createRemoteGateway(transport) });
-await app.syncAuthoritativeState();
+```ts
+await serveAxiomApplication({
+  serverIR: compileToServerIR(graph),
+  page: compileToHtml(graph),
+  persistence: await createSqlitePersistence({ location: 'app.db' }),
+  authenticate: (credential) => resolveUser(credential),
+  port: 3000,
+});
 ```
 
+`GET /` is the page, `POST /axiom` the semantic endpoint. No route, controller, handler, SQL
+or client JavaScript is authored. **There is no published Axiom CLI.** The halves also run
+separately: `serveOverHttp({ server, port })` is the bare authority, and
+`createDirectTransport(server)` drives one in-process for tests.
+
 A remote invocation returns `{ ok: false, pending: true }` and its outcome arrives later,
 through the same action-outcome lifecycle a local refusal uses — so a `diagnostic` node
-presents a server refusal exactly as it presents a local one.
+presents a server refusal exactly as it presents a local one, and the control that started it
+renders `aria-busy` and refuses a second press until it settles.
+
+Portable artifacts, for a runtime written in another language:
+
+```
+@cynodia/axiom-server/conformance                     the fixture manifest
+@cynodia/axiom-server/conformance/<name>.json         one fixture, pure data
+@cynodia/axiom-server/schema/server-ir.v1.schema.json JSON Schema for the IR
+@cynodia/axiom-server/schema/protocol.v1.schema.json  JSON Schema for the protocol
+```
 
 Boundary diagnostics: `UNKNOWN_SERVER_ACTION` `ARGUMENT_TYPE_MISMATCH` `AUTHORIZATION_DENIED`
 `CONCURRENCY_CONFLICT` `MALFORMED_REQUEST` `AUTHORITY_UNREACHABLE`, plus `SERVER_STATE_WRITE`

package/docs/ANTI_PATTERNS.md

@@ -1,6 +1,6 @@
 # Anti-patterns
 
-Axiom 0.6.0-alpha.1. Each of these compiles. Each is wrong. Each is followed by the correct
+Axiom 0.6.2-alpha.1. Each of these compiles. Each is wrong. Each is followed by the correct
 alternative.
 
 ## 1. Field names as entity runtime keys

package/docs/AUTHORITY.md

@@ -1,6 +1,6 @@
 # Authority
 
-Axiom 0.6.0-alpha.1. How an application crosses the trust boundary.
+Axiom 0.6.2-alpha.1. How an application crosses the trust boundary.
 
 Until 0.5.x an Axiom application executed locally. 0.6 adds an **authority**: a generic
 runtime that owns state, decides mutations and persists them. The same semantic graph
@@ -26,6 +26,12 @@ describes both halves, so there is no backend to write.
 5. **CONCURRENCY** — two actions cannot both commit from incompatible snapshots.
 6. **PROTOCOL** — a client requests semantic actions, never mutation programs.
 7. **SERIALIZATION** — authoritative behavior is data. No closure, no arbitrary code.
+8. **REMOTE CLIENT BOOTSTRAP** — a client of a server-authoritative application is configured with a gateway *before* it starts. A generated page does this for itself; see [Running one](#running-one).
+9. **STARTUP** — `start()` renders synchronously, then loads authoritative state. See [Startup](#startup).
+10. **FORM SUBMIT** — a declared submit button invokes its action with exactly the arguments it declares, whether it is clicked or the form is submitted. See [UI](./UI.md#forms).
+11. **IDEMPOTENCY** — an automatically generated request id is unique across runtime instances, whatever the host's uuid provider does. See [Idempotency](#idempotency).
+12. **CHANGES** — `InvokeResponse.changes` names every observable state whose value moved, and no others. See [Observing authoritative state](#observing-authoritative-state).
+13. **PORTABILITY** — `axiom.server.v1` semantics are language-independent, defined normatively by this document, the [schemas](#machine-readable-contracts) and the [conformance fixtures](#conformance). See [Server IR v1](#server-ir-v1-is-frozen).
 
 ## Authority and persistence are different questions
 
@@ -44,7 +50,7 @@ persisted to local storage. Do not conflate them.
 ```
 
 - `authority` defaults to `'client'`, so **every 0.5.x graph is unchanged** and still runs with no server at all.
-- `serverOnly: true` excludes the state from the client IR entirely. It is not merely unwritable; it is absent.
+- `serverOnly: true` excludes the state from the client IR entirely. It is not merely unwritable; it is absent. What that does and does not hide is spelled out under [What `serverOnly` hides](#what-serveronly-hides).
 
 ## Where an action executes
 
@@ -109,6 +115,45 @@ client IR, so an authority that read one and not the other cannot silently skip
 
 Entity type declarations are shared: they are the schema, not the rules.
 
+### What `serverOnly` hides
+
+`serverOnly` is a statement about **values and behaviour**, not about the existence of a
+vocabulary. Stated exactly, so nothing has to be inferred from the word "absent":
+
+| | Hidden from the client? |
+| --- | --- |
+| The state's value | **yes** — not in the client IR, not in a snapshot, not in any `changes` map |
+| The state's id | **yes** — the state does not appear in the client IR at all |
+| The state's declared type, initial value, derivation, persistence | **yes**, with the state |
+| A constraint or transition rule that reads the state | **yes** — stripped, and enforced only on the authority |
+| An edge naming the state | **yes** |
+| The **entity type** the state holds | **no**, when a client-visible state or action also uses that type |
+| That entity's **field ids, names and types** | **no**, under the same condition |
+| The **values** a rule was judging when it refused | **yes** — see below |
+
+The exception is not an oversight: an entity type is a *schema*, shared by everything that
+stores instances of it, and a client that renders one legitimately needs its fields. Stripping
+the type would require proving no client-visible state or action reaches it, and a shared type
+makes that proof fail. **A client can therefore learn that an entity has a field, and never
+learn any value of it.** If the *shape* of a record is itself confidential, model it as a
+separate entity that no client-visible state or action references — then it is stripped with
+its state, and nothing is shared to keep.
+
+`validateGraph` enforces the boundary at authoring time with `SERVER_ONLY_STATE_OBSERVED`:
+anything a client evaluates that reads a `serverOnly` state is a validation error rather than
+a runtime surprise.
+
+**A diagnostic is the other way state could cross, and it does not.** A refusal is returned to
+the caller, and a locally-evaluated one carries the record it was judging — a transition rule's
+`previousValue` and `proposedValue`, for instance. An authority strips those: a diagnostic
+leaving an authority keeps its code, its authored message and its *structural* details — which
+rule, which record's identity, which guard by position — and carries **no state value**. The
+list is a whitelist (`DISCLOSABLE_DETAIL_KEYS`), so a detail added later is withheld until
+somebody decides it may cross, rather than disclosed until somebody notices.
+
+An authored `message` is returned verbatim, because a refusal that cannot say why is not a
+refusal a person can act on. Do not put a secret in one.
+
 ## Executing an action
 
 The authority runs **the same semantic engine** the client runs. Transaction boundaries,
@@ -153,11 +198,37 @@ graph.setPrincipalEntity(ENTITY_USER);
 ```
 
 - `PRINCIPAL` is bound to a record keyed by the **principal entity's field ids**, so a rule is written with the ordinary `field`/`ref` vocabulary. There is no separate policy language.
-- It is bound **only where an authority evaluates**. Reading it in a derivation or a UI expression is `PRINCIPAL_REFERENCE_ON_CLIENT`.
 - A rule that cannot be evaluated **denies**, exactly as an unevaluable constraint counts as violated.
 - No `authorization` means every caller may invoke the action. An application with server state and no authorization anywhere gets a warning.
 - `requiresConfirmation` is interaction, asked by the client. It is **not** an authorization mechanism and the authority never treats it as one.
 
+### Where `PRINCIPAL` resolves
+
+`PRINCIPAL` is not an authorization-only construct. It resolves **wherever an authority
+evaluates an expression**, which is load-bearing: it is how an authoritative record records
+who caused it without a client ever being asked to say so.
+
+| Scope | `PRINCIPAL` |
+| --- | --- |
+| An action's `authorization` | resolves |
+| A guard on a server action | resolves |
+| An operation's value expression, including inside `for-each` | resolves |
+| A postcondition of a server action | resolves |
+| A constraint or transition constraint evaluated on the authority | resolves |
+| A derivation, a UI expression, a client-evaluated guard | **prohibited** — `PRINCIPAL_REFERENCE_ON_CLIENT` |
+
+```ts
+// An order records its own author. The client passes no user id, so it cannot claim one.
+{ kind: 'insert', target: stateLocation(STATE_ORDERS), value: object(ENTITY_ORDER, [
+  { fieldId: F_ORDER_PRODUCT,   value: ref(PARAM_PRODUCT) },
+  { fieldId: F_ORDER_PLACED_BY, value: field(ref(PRINCIPAL), F_USER_ID) },
+]) }
+```
+
+- **Client validation.** `validateGraph` rejects a `PRINCIPAL` reference anywhere a client evaluates, and rejects an `authorization` on an action no authority executes. The rule is caught at authoring time, not discovered at run time.
+- **Anonymous callers.** When `authenticate` returns `null` there is no principal. `ref(PRINCIPAL)` resolves to nothing: `field(ref(PRINCIPAL), …)` is absent, `required(…)` over it is false, and an authorization rule comparing it to anything is false — so an anonymous caller is denied by any rule naming a principal attribute rather than passing by accident. An operation that writes an absent principal attribute into a `required` field refuses the transaction with `REQUIRED_FIELD_MISSING`; nothing half-attributed is ever committed.
+- **Never disclosed.** `PRINCIPAL` is not in the client IR, not in a snapshot and not in any answer. Observability reports the caller's **identity field only**.
+
 **Read authorization is not solved in 0.6.** Observability is per state
 (`serverOnly` or not), not per caller and not per record. An application whose users must
 see different rows of the same collection needs a mechanism this release does not provide.
@@ -212,24 +283,58 @@ A network retry must not run an action twice.
 ```
 
 The authority remembers recent request ids and answers a repeat from the record, marking it
-`replayed: true`. The client runtime generates one per invocation automatically. Exactly-once
-delivery is not assumed.
+`replayed: true`. Exactly-once delivery is not assumed.
+
+**Records are scoped by principal.** The key is the caller's identity together with the
+request id, not the request id alone. A request id is chosen by a client and is therefore not
+a secret: were it the whole key, a caller who guessed another caller's id would be handed
+that caller's answer. Anonymous callers share one scope, because there is nothing to tell
+them apart — an application that needs replay isolation between anonymous callers has to
+authenticate them.
+
+**Generated ids are unique across clients.** The client runtime generates one per invocation,
+combining a per-runtime session identity with the action, an ordinal and the host's uuid. The
+session identity matters: a deterministic host — a memory host, a conformance host, a test
+double — hands every runtime it constructs the same uuid sequence, and without something
+above the host two clients would generate the same key for their first invocation and the
+second would be answered as a replay of the first.
+
+A client writing its own `requestId` is choosing its own retry identity and must make it
+unique per intended transaction.
 
 ## The protocol
 
 Transport-independent by construction. One endpoint, semantic requests:
 
 ```ts
-{ kind: 'snapshot', protocol: 'axiom.protocol.v1', credential? }
+{ kind: 'snapshot', protocol: 'axiom.protocol.v1', credential?, sinceRevision? }
 { kind: 'invoke',   protocol: 'axiom.protocol.v1', actionId, arguments?, credential?, requestId? }
 ```
 
 ```ts
 { kind: 'result',   ok, diagnostics, changes, revision, requestId?, replayed? }
-{ kind: 'snapshot', snapshot: { revision, states } }
+{ kind: 'snapshot', snapshot: { revision, states, partial? } }
 { kind: 'error',    diagnostics }
 ```
 
+### `sinceRevision`
+
+A snapshot request may name a revision the caller already holds. The answer is then
+**partial**, and what it may leave out is a contract of its own:
+
+| | |
+| --- | --- |
+| Omitted | Nothing. Every observable state is named. |
+| Given | Every observable state the authority cannot **prove** unchanged since that revision: each stored state whose last committed revision is later, and every derived state. `partial: true`. |
+| Ahead of the authority's own revision | The complete snapshot. A revision it never issued tells it nothing, and "nothing changed" would be a lie. |
+| Not a non-negative integer | `MALFORMED_REQUEST`. |
+
+A state absent from a partial snapshot is unchanged since the revision asked for. The reverse
+does not hold: a state may be named without having moved. Derived states are always named,
+because a derived value follows states the response may not even be permitted to disclose and
+the authority will not guess. `snapshot.revision` is the authority's current revision either
+way, so it is what the caller passes as the next `sinceRevision`.
+
 No graph declares `POST /orders`. Transports:
 
 | Adapter | Use |
@@ -239,22 +344,59 @@ No graph declares `POST /orders`. Transports:
 
 A later WebSocket, worker or IPC transport changes nothing in a graph.
 
-## Observing authoritative state
+## Startup
 
-The model is the simplest correct one: **request, decide, apply**.
+`start()` is the whole startup sequence, and it is the same three steps whether or not there
+is an authority:
+
+1. **Render**, synchronously, from the client IR's initial values. A page is on screen before any network call.
+2. **Restore** persisted client state, where a state declares persistence.
+3. **Load authoritative state**, when a gateway is configured — one snapshot request, applied through the ordinary write path, then one re-render.
+
+`start()` returns a promise that settles when step 3 has settled. Awaiting it means "the page
+is showing authoritative state"; not awaiting it means "the page is showing something", which
+is a legitimate choice for a page that renders progressively.
 
 ```ts
-const app = createAxiomRuntime({ ir, rootElement, host, remote: createRemoteGateway(transport) });
-app.start();
-await app.syncAuthoritativeState();     // load the authoritative snapshot
+const app = createAxiomRuntime({ ir, rootElement, host, remote });
+await app.start();                      // rendered, restored, synchronized
+app.authoritativeStateLoaded();         // true
 ```
 
-- A remote invocation returns `{ ok: false, pending: true }` immediately, so a click never blocks on the network. The outcome arrives later and is recorded through the ordinary action-outcome lifecycle — which is how a `diagnostic` node presents a *server* refusal exactly as it presents a local one.
+Three things follow, and they are contract rather than implementation detail:
+
+- **A gateway must be configured before `start()`.** Adding one afterwards does not retroactively synchronize; call `syncAuthoritativeState()` yourself.
+- **A failed load is a diagnostic, not an exception.** The authority being unreachable reports `AUTHORITY_UNREACHABLE`, `start()` still resolves, the page still renders, and `authoritativeStateLoaded()` stays `false`. An empty authoritative collection and an unreachable authority are different situations and the runtime distinguishes them.
+- **`syncAuthoritativeState()` is idempotent and may be called at any time.** It is what a refresh button does.
+
+## Observing authoritative state
+
+The model is the simplest correct one: **request, decide, apply**.
+
+- A remote invocation returns `{ ok: false, pending: true }` immediately, so a click never blocks on the network. The outcome arrives later and is recorded through the ordinary action-outcome lifecycle — which is how a `diagnostic` node presents a *server* refusal exactly as it presents a local one. While it is outstanding, the control that started it renders `aria-busy` and refuses a second press; see [UI](./UI.md#pending-actions).
 - `invokeActionAsync(id, args)` awaits the answer, for tests and programmatic callers.
 - The answer's `changes` are applied through the client's single write path, under the one flag that permits writing server-owned state.
 - **Optimistic updates are not implemented.** There is no client-side rollback to get wrong.
 - A derivation that depends only on observed state is recomputed locally rather than transferred.
 
+### What `changes` contains
+
+**Every observable state whose value differs from what it was when the transaction opened,
+and no others.** Difference is the criterion, not provenance:
+
+| Situation | In `changes`? |
+| --- | --- |
+| A stored state the transaction wrote to a new value | yes |
+| A stored state written back to the value it already held | no |
+| A derived state whose recomputed value moved | yes, though no mutation named it |
+| A derived state recomputed to the same value | no |
+| A `serverOnly` state, however it changed | never — it is not observable |
+| Any state, when the invocation was refused or rolled back | no: `changes` is empty |
+| Any state, when the action committed nothing | no: `changes` is empty |
+
+A replayed response carries the `changes` that were recorded for the original request, not a
+freshly computed set.
+
 ## Diagnostics
 
 Server codes join the same structured vocabulary; a client matches on `code` exactly as it
@@ -290,21 +432,43 @@ implements logging of its own.
 
 ## Running one
 
-```bash
-node packages/cli/dist/index.js serve app.js --export=createGraph --port=3000 --store=state.db
+One graph, one process: the generated page and the authority that answers it.
+
+```ts
+import { compileToHtml, compileToServerIR } from '@cynodia/axiom-compiler';
+import { createSqlitePersistence, serveAxiomApplication } from '@cynodia/axiom-server';
+
+const graph = createApplicationGraph();
+const running = await serveAxiomApplication({
+  serverIR: compileToServerIR(graph),
+  page: compileToHtml(graph),
+  persistence: await createSqlitePersistence({ location: 'app.db' }),
+  authenticate: (credential) => resolveUser(credential),
+  port: 3000,
+});
+// running.pageUrl → http://127.0.0.1:3000/
 ```
 
-One process serves the client page and the authority on one semantic endpoint. Nothing
-application-specific is generated: no routes, no controllers, no handlers, no SQL. The
-deployment artifact is the client page plus a serialized Server IR, executed by a generic
-runtime.
+`GET /` is the page and `POST /axiom` is the semantic endpoint, for every Axiom application
+there will ever be. No application defines a route, a verb, a controller, a handler or a line
+of SQL, and the page needs no JavaScript of its own: `compileToHtml` wires the browser-safe
+gateway into the generated bootstrap whenever the IR contains a remote action.
+
+To point a page somewhere else, or to switch the gateway off for an application that has no
+authority:
 
 ```ts
-const server = createAxiomServer({ ir: serverIR, persistence, host });
-await server.start();
-await serveOverHttp({ server, port: 3000 });
+compileToHtml(graph, { remote: { endpoint: 'https://api.example.com/axiom' } });
+compileToHtml(graph, { remote: false });
 ```
 
+The two halves also run separately. `serveOverHttp({ server, port })` is the bare authority,
+and `createAxiomServer({ ir, persistence, host })` is the authority with no transport at all —
+which is what `createDirectTransport` drives in tests.
+
+**There is no published Axiom CLI.** `packages/cli` is a private development tool of this
+repository and is not on npm; the API above is the supported way to run an application.
+
 ## Conformance
 
 `@cynodia/axiom-server` ships `conformance/*.json`. Each fixture is pure data — a Server IR,
@@ -317,11 +481,100 @@ Running them requires no part of this implementation. That is the point: the Ser
 specification plus these fixtures are the whole contract, so an independent runtime in
 another language can be held to exactly the same standard.
 
-## Not in 0.6
+Enumerate the suite from its manifest rather than by listing a directory:
+
+```
+@cynodia/axiom-server/conformance            → the manifest
+@cynodia/axiom-server/conformance/<name>.json → one fixture
+```
+
+The manifest names the contracts the fixtures are written against (`axiom.conformance.v1`,
+`axiom.server.v1`, `axiom.protocol.v1`), the release, every area covered, and every fixture
+with its file. A runtime that does not implement a contract the manifest names should refuse
+the suite rather than discover the mismatch one assertion at a time. The files are plain JSON
+in a documented package directory, so a non-JavaScript consumer can read them straight out of
+the tarball without Node's module resolver.
+
+Every fixture is executed against the reference runtime by this repository's own test suite,
+and its expectations are exhaustive — a fixture that says which states changed must name all
+of them and no others. No fixture is permitted to disagree with the shipped runtime.
+
+## Machine-readable contracts
+
+```
+@cynodia/axiom-server/schema/server-ir.v1.schema.json
+@cynodia/axiom-server/schema/protocol.v1.schema.json
+```
+
+JSON Schema for the Server IR and for the wire protocol, so an implementer is not reading
+TypeScript declarations to find out what a document may contain. They are generated from the
+runtime's own vocabulary — expression kinds, built-in functions, operation kinds — so they
+cannot drift from what the runtime implements, and every shipped fixture is validated against
+them.
+
+They describe **structure**. What a conforming runtime must *do* with a valid document is this
+page plus the conformance fixtures.
+
+## Server IR v1 is frozen
+
+`axiom.server.v1` is a stable semantic contract as of 0.6.1. A runtime may depend on the
+semantics below exactly as written; a change that breaks them requires a new contract
+identifier, not a new version number.
+
+**Numbers.** Every numeric value is an IEEE-754 binary64 (double-precision) value, and every
+arithmetic operator (`add`, `subtract`, `multiply`, `divide`) is the corresponding IEEE-754
+operation. Ordered comparisons against a value that is not a number are **false**, both ways —
+so a guard over a computation that failed refuses rather than passing on a value it could not
+compute. `sum` over an empty collection is `0`. Integer-valued doubles are not a separate
+type; there is no integer type and no decimal type in this contract.
+
+**Text.** `to-string` of a number is its shortest round-tripping decimal form, without digit
+grouping and without a locale. `lowercase` is the Unicode default case conversion, unconditional
+and locale-independent. Text ordering — in `sort`, and in `compareValues` wherever two
+non-numeric values are ordered — is **lexicographic by Unicode code point**. Not locale
+collation, and not UTF-16 code-unit order: the two disagree whenever a string mixes astral
+characters with U+E000–U+FFFF, and code points are the ordering every language can reproduce.
+
+**Host values.** `now()` and `uuid()` are the only two places semantics may depend on something
+outside the graph, and their production values are the host's. For conformance the host is
+pinned: one counter shared by both, starting at zero and incremented before each value, so the
+nth host call in an execution is `id-<n>` or `2026-01-01T00:00:<n>.000Z` whichever it was. A
+runtime in another language reproduces this by counting host calls in execution order. The
+counter is per host instance; a restart does not rewind it.
+
+**Serialization.** A Server IR document is JSON and nothing else. It MUST NOT contain
+`undefined`, a function, a closure, `NaN`, `Infinity`, a `BigInt`, a host object, a `Date`, a
+`RegExp`, or an instance of a class that needs its prototype to be understood. It must survive
+a parse/serialize round trip unchanged. Record key order is not significant and MUST NOT be
+relied upon.
+
+**Diagnostics.** The codes in the table above are public vocabulary and are frozen: a
+conforming runtime reports these codes, with these meanings, and the fixtures assert on them.
+The details a diagnostic may carry across the boundary are the whitelist described under
+[What `serverOnly` hides](#what-serveronly-hides).
+
+**Authorization.** An `authorization` expression is an ordinary expression evaluated on the
+authority with `PRINCIPAL` bound, before any guard and before any transaction opens. There is
+no policy language, no rule engine and no evaluation order beyond that.
+
+**Persistence is not part of the contract.** `PersistenceAdapter` is how an authority keeps
+what it decided; nothing about *which* adapter is in use changes what a graph means. A
+conforming runtime may store state any way it likes, provided a semantic transaction persists
+as one unit and a stale revision refuses the commit.
+
+**Concurrency.** An authority serializes execution: one action at a time, its commit complete
+before the next begins. A conforming runtime may execute concurrently only if the observable
+result is identical to some serial order. Across processes, correctness rests on the
+persistence adapter's revision check — the contract guarantees that a commit from a stale
+snapshot is refused, not that two processes coordinate.
+
+## Not in 0.6.2
 
 Stated plainly rather than left to discovery:
 
+- **Generated values cannot be bound within an action.** An operation cannot name a value an earlier operation produced: `uuid()` evaluated in one `insert` cannot be referred to by a later `insert` in the same action. Give the record an identity the action already has — a parameter, or a field of something it read — or perform the second write in a second action. A semantic binding for this (`bindAs` on an operation, `ref` to it later) needs a lexical lifetime, a type, `for-each` and nested-invoke semantics, serialization and dependency analysis all decided together; doing that hastily would weaken a contract that is now frozen, so it is deferred to 0.7.
 - **Read authorization per caller or per record.** Visibility is per state.
+
 - **External effects.** A database write rolls back; an email does not. Nothing here makes an external side effect participate in a transaction, and `NativeOperation` MUST NOT be used to smuggle one in. A deliberate effect model — commands, a transactional outbox, idempotency — is future work.
 - **Realtime synchronization**, subscriptions and collaboration. Request/response only.
 - **Query semantics.** Authoritative collections are loaded into runtime state; large-data querying needs its own design.

package/docs/CONSTRAINTS.md

@@ -1,6 +1,6 @@
 # Constraints
 
-Axiom 0.6.0-alpha.1. Two constructs, answering different questions. They are not
+Axiom 0.6.2-alpha.1. Two constructs, answering different questions. They are not
 interchangeable.
 
 | | Question | Sees |

package/docs/EXPRESSIONS.md

@@ -1,6 +1,6 @@
 # Expressions
 
-Axiom 0.6.0-alpha.1. An expression describes **what value is computed**. It is a tree of
+Axiom 0.6.2-alpha.1. An expression describes **what value is computed**. It is a tree of
 plain data, never source text and never a callback. Evaluation is pure: an expression MUST
 NOT change state.
 

package/docs/GRAPH_MODEL.md

@@ -1,6 +1,6 @@
 # Graph model
 
-Axiom 0.6.0-alpha.1. The `ApplicationGraph` is the authoritative representation of an
+Axiom 0.6.2-alpha.1. The `ApplicationGraph` is the authoritative representation of an
 application. Everything else — the IR, the page, the DOM — is derived from it and is never
 edited.
 

package/docs/LOCATIONS.md

@@ -1,6 +1,6 @@
 # Locations
 
-Axiom 0.6.0-alpha.1.
+Axiom 0.6.2-alpha.1.
 
 ```text
 Expression = a value

package/docs/PRESENTATION.md

@@ -1,6 +1,6 @@
 # Presentation
 
-Axiom 0.6.0-alpha.1. Presentation is **semantic UX intent**, expressed as data on a UI
+Axiom 0.6.2-alpha.1. Presentation is **semantic UX intent**, expressed as data on a UI
 node. It names roles, tokens and device classes. It never names a colour, a length, a media
 query or a CSS property.
 

package/docs/RUNTIME.md

@@ -1,6 +1,6 @@
 # Runtime
 
-Axiom 0.6.0-alpha.1. The runtime executes an `ApplicationIR`. It is domain-independent: it
+Axiom 0.6.2-alpha.1. The runtime executes an `ApplicationIR`. It is domain-independent: it
 contains no knowledge of any application.
 
 ## Constructing
@@ -14,7 +14,8 @@ const app = createAxiomRuntime({
   rootElement,                     // a DomElement
   host,                            // a HostEnvironment
   nativeOperations?: Record<string, (inputs) => unknown>,
-  remote?: RemoteGateway,                       // required for server-authoritative state
+  remote?: RemoteGateway,                       // required for server-authoritative state,
+                                                // and required *before* start()
   inputValidation?: 'immediate' | 'deferred',   // DEFAULT: 'immediate'
   recordMutationValues?: boolean,               // default true
 });
@@ -60,7 +61,7 @@ carries `data-node="<node id>"`.
 
 | Member | Governed | Semantics |
 | --- | --- | --- |
-| `start()` | — | Subscribes to path changes and renders. Idempotent. |
+| `start()` | — | The whole startup sequence: render, restore, then load authoritative state. Returns a promise; awaiting it means authoritative state has been applied. Idempotent. See [Startup](#startup). |
 | `render()` | — | Re-renders from current state. |
 | `getState(id)` | — | A **deep clone** of the value. Derived state is recomputed. |
 | `invokeAction(id, args?)` | **yes** | Runs the action as a transaction. Returns `{ ok, diagnostics }` for that invocation. |
@@ -73,7 +74,9 @@ carries `data-node="<node id>"`.
 | `getMutationLog()` | — | Every attempted mutation, with source, path and outcome. |
 | `registerNativeOperation(id, fn)` | — | Registers an implementation for a `native` operation. |
 | `invokeActionAsync(id, args?)` | **yes** | Awaits the outcome, including an authority's answer. |
-| `syncAuthoritativeState()` | — | Loads the authoritative snapshot and applies it. See [`AUTHORITY.md`](AUTHORITY.md). |
+| `syncAuthoritativeState()` | — | Loads the authoritative snapshot and applies it. Idempotent; may be called at any time. See [`AUTHORITY.md`](AUTHORITY.md). |
+| `authoritativeStateLoaded()` | — | Whether a snapshot has been applied. `false` also after a failed load, which is why it is not the same question as "is this collection empty". |
+| `settled()` | — | Resolves when no remote invocation is outstanding. An action started by a click or a form submit leaves no promise for a caller to hold; this is how to wait for it without guessing a delay. |
 | `evaluate(expression)` | — | Evaluates in the root scope, reporting rather than throwing. A pure read. |
 
 ### `hydrateState` bypasses semantic enforcement
@@ -210,6 +213,7 @@ interface RuntimeDiagnostic {
 | `ROUTE_NOT_FOUND` | A `navigate` operation naming an unresolvable route. | action | — |
 | `NATIVE_OPERATION_MISSING` | No implementation registered for an `implementationId`. | `native` operation | — |
 | `REMOTE_ACTION_UNAVAILABLE` | An action belonging to the authority was invoked with no gateway configured, or the transport failed. | remote invocation | — |
+| `AUTHORITY_UNREACHABLE` | **Warning.** `start()` could not load authoritative state: no answer from the authority. The page renders with what it has, and `authoritativeStateLoaded()` stays false. | startup | — |
 | `UI_NODE_MISSING` | A child id that is not a UI node in the IR. | render | — |
 | `UNSUPPORTED_UI_NODE` | An unknown UI node kind. | render | — |
 | `PERSISTED_STATE_UNREADABLE` | **Warning.** A stored value could not be parsed; the initial value was used. | startup | — |
@@ -250,19 +254,43 @@ app.getMutationLog();
 - Only the outermost transaction decides an outcome, so the log never suggests that early iterations of a failed loop committed.
 - `recordMutationValues: false` omits `oldValue` / `newValue`.
 
+## Startup
+
+`start()` is the whole startup sequence, and it is the same three steps whether or not there
+is an authority:
+
+1. **Render**, synchronously, from the client IR's initial values. A page is on screen before any network call.
+2. **Restore** persisted client state, where a state declares persistence.
+3. **Load authoritative state**, when a gateway is configured — one snapshot request, applied through the ordinary write path, then one re-render.
+
+```ts
+const app = createAxiomRuntime({ ir, rootElement, host, remote });
+await app.start();              // rendered, restored, synchronized
+app.authoritativeStateLoaded(); // true
+```
+
+- `start()` returns a promise that settles when step 3 has settled. Not awaiting it is a legitimate choice for a page that renders progressively; the first two steps have already happened synchronously by the time it returns.
+- **A gateway must be configured before `start()`.** Adding one afterwards does not retroactively synchronize — call `syncAuthoritativeState()`.
+- **A failed load is a diagnostic, not an exception.** `AUTHORITY_UNREACHABLE` is reported, `start()` still resolves, the page still renders, and `authoritativeStateLoaded()` stays `false`. An empty authoritative collection and an unreachable authority are different situations, and the runtime does not conflate them.
+- `start()` is idempotent: calling it twice does not re-render twice or fetch twice.
+
 ## Reaching an authority
 
 An application with server-authoritative state gives the runtime a gateway:
 
 ```ts
 const app = createAxiomRuntime({ ir, rootElement, host, remote: createRemoteGateway(transport) });
-app.start();
-await app.syncAuthoritativeState();
+await app.start();
 ```
 
+A generated page does this for itself — `compileToHtml` wires the browser-safe gateway into
+the bootstrap whenever the IR contains a remote action, so an application author writes no
+JavaScript at all. See [`AUTHORITY.md`](AUTHORITY.md#running-one).
+
 `invokeAction` on a remote action returns `{ ok: false, pending: true }` immediately — a
 click never blocks on the network — and the outcome arrives through the ordinary
-action-outcome lifecycle. Full model: [`AUTHORITY.md`](AUTHORITY.md).
+action-outcome lifecycle. While it is outstanding the control that started it renders
+`aria-busy` and refuses a second press. Full model: [`AUTHORITY.md`](AUTHORITY.md).
 
 ## The browser bundle
 

package/docs/SEMANTIC_CONTRACT.md

@@ -1,7 +1,7 @@
 # Semantic contract
 
-Axiom 0.6.0-alpha.1. Runtime guarantees, stated formally. This file defines behavior; it
-does not teach. Where this file and any specification in `doc/` disagree, this file
+Axiom 0.6.2-alpha.1. Runtime guarantees, stated formally. This file defines behavior; it
+does not teach. Where this file and any specification in `../specs/` disagree, this file
 describes the implementation and is authoritative.
 
 `MUST` / `MUST NOT` describe guaranteed behavior. `MAY` describes a documented option.
@@ -196,22 +196,30 @@ Full model: [`AUTHORITY.md`](AUTHORITY.md).
 - The transaction guarantees above hold unchanged on the authority: the same semantic engine executes both halves.
 - A semantic transaction MUST persist atomically. An adapter MUST NOT apply a subset of a transaction's writes, and MUST refuse a commit whose expected revisions no longer hold.
 - Two actions MUST NOT both commit from incompatible snapshots. The authority serializes execution, and a stale commit is refused with `CONCURRENCY_CONFLICT`.
-- A repeated `requestId` MUST be answered from the record rather than executed again.
+- A repeated `requestId` MUST be answered from the record rather than executed again. Records MUST be scoped by principal as well as by request id: a request id is client-chosen, and one caller MUST NOT be able to receive another's recorded answer.
+- An automatically generated request id MUST be unique across independent runtime instances, whatever the host's uuid provider does.
+- `InvokeResponse.changes` MUST contain every observable state whose value differs from what it was when the transaction opened, and no others. A refused or no-op invocation MUST return an empty `changes`.
+- A `SnapshotRequest.sinceRevision` MUST affect the answer as documented: the response omits only states the authority can prove unchanged, and MUST mark itself `partial`. A revision the authority never issued MUST be answered completely.
+- A diagnostic crossing the trust boundary MUST NOT carry a state value. Its code, authored message and structural details cross; the record a rule was judging does not.
+- `PRINCIPAL` MUST resolve wherever an authority evaluates an expression — authorization, guards, operation values, postconditions and constraints alike — and MUST NOT resolve anywhere a client evaluates.
 - Server IR MUST be serializable, deterministic and free of closures, and MUST declare a contract version a runtime can refuse.
+- `axiom.server.v1` is **frozen**. Its semantics — IEEE-754 binary64 arithmetic, Unicode code-point text ordering, the deterministic host model, and the JSON serialization constraints — are normative and language-independent. An incompatible semantic change requires a new contract identifier.
 
-**Not guaranteed in 0.6**, and stated so rather than implied: read authorization per caller
-or per record, external side effects participating in a transaction, realtime
-synchronization, query semantics, and multi-node execution.
+**Not guaranteed in 0.6.2**, and stated so rather than implied: read authorization per caller
+or per record, binding a value generated by one operation in a later one, external side
+effects participating in a transaction, realtime synchronization, query semantics, and
+multi-node execution.
 
 ## Diagnostics as semantic UI
 
-- The runtime MUST record the outcome of each action's most recent invocation: `'ok'`, `'failed'` or `'cancelled'`, with that invocation's diagnostics.
+- The runtime MUST record the outcome of each action's most recent invocation: `'ok'`, `'failed'`, `'cancelled'` or `'pending'`, with that invocation's diagnostics.
 - The record MUST be replaced by the next invocation of the same action, whatever its outcome. It does not accumulate.
 - `'ok'` and `'cancelled'` MUST carry no diagnostics.
 - The record MUST be cleared by `clearDiagnostics()` and by navigating to another route.
 - A `diagnostic` UI node MUST present the diagnostics of its action's record at or above its own severity, and nothing else.
 - Diagnostics are ephemeral runtime state. They are not application state, are never persisted, and cannot be written.
 - The runtime MUST re-render after every top-level action invocation, including one refused before a transaction was opened, so a refusal reaches the interface without the application arranging it.
+- Action guards MUST be evaluated in declaration order, and the first that does not hold MUST stop evaluation and be the only failure reported. Guard failures MUST NOT be aggregated.
 - An application MUST NOT need to duplicate an action's guards, read console output, copy an `ActionResult` into its own state, or install a renderer-specific handler in order to present a refusal.
 
 ## Render identity
@@ -219,6 +227,7 @@ synchronization, query semantics, and multi-node execution.
 - A UI node inside a `repeat` is rendered once per member. `NodeId` MUST NOT be used alone to identify a rendered element.
 - Every renderer-generated identity and relationship — element id, label association, described-by relationships, error-region ids, control lookup, focus restoration — MUST be keyed by the render instance.
 - A rendered identity MUST be unique within the document, deterministic, and stable while the member's identity is stable. Nested repeats MUST compose rather than collide.
+- Where a semantic node renders as more than one element, every one of them MUST carry the node's identity, and the single element a person operates MUST additionally be distinguishable. Tooling MUST NOT have to infer which element is the control from its tag name.
 - Where the collection's member type carries an identity field, that identity MUST be preferred, so the identity follows a member through reordering. Otherwise a deterministic index is used.
 - Refusing a write in one rendered instance MUST NOT affect the accessibility state of another.
 - The graph still contains one semantic node. `AgentAPI` reasons about the node, never about instances.
@@ -262,5 +271,6 @@ These are current implementation limits, not design intentions.
 - Type inference is deliberately partial: it rejects obvious mismatches and stays silent where a type depends on an iteration scope.
 - Iteration scopes are ordinary `NodeId`s; misuse is caught by validation rather than by the type system.
 - Remote persistence is declared but not executed.
-- There are no asynchronous action semantics, and therefore no loading or pending presentation states.
+- Asynchronous action semantics extend no further than a remote invocation: the outcome is `pending` until the authority answers, and the control that started it is marked busy and refuses a second press. There is no general async workflow model, no progress reporting and no cancellation.
+- An action cannot bind a value it generated earlier in the same transaction; `uuid()` in one operation is not addressable by a later one.
 - Change sets are in memory and per `AgentAPI` instance. There is no semantic version control and no on-disk graph format.

package/docs/STATE.md

@@ -1,6 +1,6 @@
 # State
 
-Axiom 0.6.0-alpha.1. A `StateDef` is a named application value: stored, or computed from
+Axiom 0.6.2-alpha.1. A `StateDef` is a named application value: stored, or computed from
 other state.
 
 ```ts

package/docs/UI.md

@@ -1,6 +1,6 @@
 # UI
 
-Axiom 0.6.0-alpha.1. Ten semantic UI node kinds describe **what exists and what it does**.
+Axiom 0.6.2-alpha.1. Ten semantic UI node kinds describe **what exists and what it does**.
 How it looks is [presentation](PRESENTATION.md).
 
 All nine share `UIBase`:
@@ -110,10 +110,26 @@ graph.addNode<FormNode>({
 ```
 
 - `submitButtonId` MUST name a `ButtonNode` among the form's descendants.
-- The submit action is `submitActionId ?? <that button>.actionId`. If both are given they MUST agree.
+- The submit action is `submitActionId ?? <that button>.actionId`. If both are given they MUST agree. **That one resolution is used everywhere** — execution, validation, presentation inference, `AgentAPI` form structure and UX warnings — so a form with a declared submit button is a form with a primary action, and nothing has to infer it a second way.
 - The declared control is rendered with `type="submit"` and no click handler of its own, so a click runs the action exactly once.
 - `submitLabel` is ignored when `submitButtonId` is given.
 
+**A declared submit button keeps its arguments.** Submitting the form and clicking the button
+are the same invocation: the same `arguments`, evaluated in the same scope, at the moment the
+control is used. This matters most inside a `repeat`, where the button's arguments are what
+say *which row* — a submit path that ignored them would invoke a parameterized action with
+nothing bound and be refused.
+
+```ts
+graph.addNode<ButtonNode>({
+  id: UI_CONFIRM, kind: 'button', label: 'Confirm', actionId: ACTION_CONFIRM,
+  arguments: { [PARAM_ORDER]: field(ref(UI_ORDER_ROW), F_ORDER_ID) },   // survives form submit
+});
+```
+
+An action parameter that is `required` and never supplied is `MISSING_ACTION_ARGUMENT` at
+authoring time — from a `button`, and from a `form` that submits an action without one.
+
 ### `input`
 
 ```ts
@@ -162,8 +178,26 @@ the two. All three are keyed by render instance, so only the refused row is affe
 ```
 
 Invokes an action. `arguments` is keyed by the **action parameter id**; passing an unknown
-parameter is a validation error. `destructive` may be declared here, but declaring it on
-the action is enough — presentation is inferred from the action.
+parameter is a validation error, and omitting a required one is `MISSING_ACTION_ARGUMENT`.
+`destructive` may be declared here, but declaring it on the action is enough — presentation
+is inferred from the action.
+
+#### Pending actions
+
+An action the authority executes is not finished when the button is released. While its
+answer is outstanding the control renders:
+
+```html
+<button data-node="ui_place" data-control="ui_place"
+        data-pending="true" aria-busy="true" disabled>Place order</button>
+```
+
+and a second press does nothing — a second press is a second transaction, not a retry of the
+first, and by the time it reached the authority it would be a legitimately different request.
+The outcome is the ordinary `ActionOutcome` lifecycle (`pending` → `ok` / `failed`), so a
+`diagnostic` node presents a server refusal exactly as it presents a local one. There is no
+async vocabulary in the graph: `pending` is a runtime outcome, and this is the whole of its
+presentation.
 
 ### `diagnostic`
 
@@ -238,6 +272,7 @@ identify a rendered element, and two concepts are kept distinct:
 ```text
 NodeId          = semantic graph identity        → data-node
 RenderInstance  = runtime presentation identity  → data-instance
+Control         = the element a person operates  → data-control
 ```
 
 Every renderer-generated identity and relationship is keyed by the render instance:
@@ -256,14 +291,39 @@ Instance identity is:
 - **composing** for nested repeats, rather than colliding.
 
 ```html
-<input data-node="ui_line_quantity"
-       data-instance="ui_line_quantity--line-7f3a"
-       id="axiom-control-ui_line_quantity--line-7f3a">
+<label data-node="ui_line_quantity" data-instance="ui_line_quantity--line-7f3a"
+       for="axiom-control-ui_line_quantity--line-7f3a">
+  <span class="axiom-input-label">Quantity</span>
+  <input data-node="ui_line_quantity" data-control="ui_line_quantity"
+         data-instance="ui_line_quantity--line-7f3a"
+         id="axiom-control-ui_line_quantity--line-7f3a" type="number">
+</label>
 ```
 
 The exact encoding is an implementation detail; the properties above are the contract. The
 graph still holds one node, and `AgentAPI` reasons about that node.
 
+### `data-node` and `data-control`
+
+One semantic node can render as more than one element: an input is a label wrapping a control,
+and **both carry `data-node`, because both are that node**. Only one of them can be typed into,
+and `data-node` cannot say which.
+
+| Attribute | Selects | Cardinality |
+| --- | --- | --- |
+| `data-node` | every element that is this semantic node | one or more per rendering |
+| `data-control` | the single element a person operates | exactly one, on nodes that have one |
+| `data-instance` | this rendering of the node | one per element, inside a `repeat` |
+| `data-variant` | the control variant chosen from presentation intent — `switch`, `stepper`, `radio-group` | on the control |
+
+So `[data-control="ui_line_quantity"]` is the input, `[data-node="ui_line_quantity"]` is the
+input and its label, and inside a repeat `[data-control="…"][data-instance="…"]` is one row's.
+A `button` is its own control, so both attributes name the same element. A radio group has no
+single element to operate, so the group itself carries `data-control`.
+
+Semantic identity stays on the wrappers: `AgentAPI` and any tooling that reasons about the
+graph needs to find every element a node produced, not only the interactive one.
+
 ## Visibility is not authorization
 
 `visibleWhen` and `ConditionalNode` decide what is **rendered**. They decide nothing about

package/docs/VALIDATION.md

@@ -1,6 +1,6 @@
 # Validation
 
-Axiom 0.6.0-alpha.1. Validation is authoring-time structural checking. It is not the same
+Axiom 0.6.2-alpha.1. Validation is authoring-time structural checking. It is not the same
 as runtime constraint evaluation — see [`CONSTRAINTS.md`](CONSTRAINTS.md) for the four
 layers of correctness.
 
@@ -79,6 +79,7 @@ non-numeric collections, and obviously incompatible assignments.
 | `INVALID_SELECTOR_TYPE` | An index selector that is statically not a number. |
 | `EPHEMERAL_STATE_PERSISTED` | `ephemeral: true` together with `persistence`. |
 | `CLIENT_WRITE_TO_SERVER_STATE` | An input bound into server-authoritative state. See [Authority](#authority). |
+| `MISSING_ACTION_ARGUMENT` | A control invokes an action without supplying a required parameter. |
 
 ### Initial values
 
@@ -148,6 +149,7 @@ client commit authoritative state does not compile. Full model:
 | `SERVER_ONLY_STATE_OBSERVED` | Something the client receives reads a `serverOnly` state — an input, a derivation, a UI expression. | error |
 | `AUTHORIZATION_WITHOUT_PRINCIPAL` | An `authorization` expression with no principal entity declared. **Also raised as a warning** when an application has server state but no action declares authorization, so every caller may invoke everything. | error / warning |
 | `PRINCIPAL_REFERENCE_ON_CLIENT` | `PRINCIPAL` is read where a client evaluates, or an `authorization` sits on an action no authority executes. | error |
+| `MISSING_ACTION_ARGUMENT` | A `button`, or a `form` submitting without one, invokes an action with a required parameter it never supplies. The invocation would always be refused for a missing argument, so it is refused here instead. | error |
 | `INVALID_PRINCIPAL_ENTITY` | `principalEntityId` names something that is not an entity. | error |
 
 ### Accessibility

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom",
-  "version": "0.6.0-alpha.1",
+  "version": "0.6.2-alpha.1",
   "description": "AI-native semantic web application framework.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -32,10 +32,10 @@
     }
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.6.0-alpha.1",
-    "@cynodia/axiom-runtime": "0.6.0-alpha.1",
-    "@cynodia/axiom-compiler": "0.6.0-alpha.1",
-    "@cynodia/axiom-agent-api": "0.6.0-alpha.1"
+    "@cynodia/axiom-core": "0.6.2-alpha.1",
+    "@cynodia/axiom-runtime": "0.6.2-alpha.1",
+    "@cynodia/axiom-compiler": "0.6.2-alpha.1",
+    "@cynodia/axiom-agent-api": "0.6.2-alpha.1"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json"