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

package/README.md

@@ -6,7 +6,7 @@ Axiom represents application behavior, state, UI structure and presentation as s
 semantic data executed by generic runtimes. An application is a typed graph, not source
 files: the JavaScript and HTML that reach the browser are output, and are never edited.
 
-**Status: experimental / alpha (0.5.2-alpha.x).** The API may change between alpha
+**Status: experimental / alpha (0.6.0-alpha.x).** The API may change between alpha
 releases. The documentation in `docs/` describes this exact version.
 
 ## Installation

package/docs/ACTIONS_TRANSACTIONS.md

@@ -1,6 +1,6 @@
 # Actions and transactions
 
-Axiom 0.5.2-alpha.1. An action is behavior expressed as data, executed as a transaction.
+Axiom 0.6.0-alpha.1. An action is behavior expressed as data, executed as a transaction.
 
 ```ts
 {
@@ -62,6 +62,10 @@ re-render
 `invokeAction(id, args?)` returns `{ ok, diagnostics }` for **that invocation**. No diffing
 of global history is needed.
 
+An action that writes server-authoritative state runs this lifecycle **on the authority**
+instead, unchanged; the client dispatches it and receives the result. See
+[`AUTHORITY.md`](AUTHORITY.md).
+
 All four failure sources are evaluated; the action does not stop at the first.
 
 ## Operations
@@ -159,6 +163,20 @@ The controlled boundary for behavior the operation vocabulary cannot express.
 **Use it only where no semantic primitive exists.** A native operation is opaque to every
 analysis Axiom offers.
 
+## Authorization
+
+```ts
+authorization?: Expression
+```
+
+Whether the caller may invoke this action at all, evaluated **on the authority** with the
+caller bound to `PRINCIPAL`, before any guard and before any transaction opens. It is
+stripped from the client IR, so a client never learns the rule and cannot satisfy it by
+claiming to.
+
+A guard asks whether the application's state permits this invocation. Authorization asks
+whether this *caller* may make it. See [`AUTHORITY.md`](AUTHORITY.md#authentication-and-authorization).
+
 ## Postconditions
 
 Evaluated after the operations, inside the transaction, against proposed state. A failure

package/docs/AGENT_API.md

@@ -1,6 +1,6 @@
 # Agent API
 
-Axiom 0.5.2-alpha.1. The machine-facing interface. Agents query semantics and apply
+Axiom 0.6.0-alpha.1. The machine-facing interface. Agents query semantics and apply
 structural transformations; they never edit generated code.
 
 ```ts
@@ -141,6 +141,24 @@ Presentation resolution is recomputed per call rather than cached: a transaction
 the graph underneath these queries, and a stale presentation answer would be worse than a
 slow one.
 
+## Authority queries
+
+```ts
+agent.getAuthority(stateId)                  // 'client' | 'server'
+agent.getActionAuthority(actionId)           // where it executes — derived, not declared
+agent.getServerActions()
+agent.getClientWritableStates()
+agent.getServerWritableStates()
+agent.getServerOnlyStates()                  // what the client never receives
+agent.getActionsAffectingServerState()       // [{ action, stateIds }]
+agent.getAuthorizationForAction(actionId)    // the rule, or undefined
+agent.getUnauthorizedServerActions()         // server actions any caller may invoke
+agent.getPersistenceForState(stateId)
+```
+
+Authority is derived from what an action writes, so these answers cannot disagree with what
+the graph does. See [`AUTHORITY.md`](AUTHORITY.md).
+
 ## Transactions
 
 Every change is staged on a private copy. The graph an agent or a runtime can observe is

package/docs/AGENT_REFERENCE.md

@@ -1,6 +1,6 @@
 # Agent reference
 
-Axiom 0.5.2-alpha.1. Compressed operational contract. Read this plus the `.d.ts`
+Axiom 0.6.0-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:
@@ -31,7 +31,7 @@ One canonical term per concept. These are not interchangeable.
 ## Graph construction
 
 ```ts
-const graph = new ApplicationGraph(id, name);      // version defaults to '0.5.2'
+const graph = new ApplicationGraph(id, name);      // version defaults to '0.6.0'
 graph.addNode<StateDef>({ id, kind: 'state', ... }); // returns NodeId; throws if id exists
 graph.getNode<StateDef>(id);                        // deep clone, or undefined
 graph.updateNode(node);                             // write a modified node back
@@ -469,6 +469,65 @@ agent.transact((tx) => { tx.setDensity(FORM, 'compact'); }, { reason });
 a native operation with undeclared effects — cannot be analyzed. **An incomplete answer
 says so; it is never presented as exhaustive.** Detail: [`AGENT_API.md`](AGENT_API.md).
 
+## SERVER AUTHORITY
+
+Full model: [`AUTHORITY.md`](AUTHORITY.md). These are the invariants to know before
+authoring an application that crosses the trust boundary.
+
+1. **AUTHORITY** — a client cannot commit server-authoritative state, by any path.
+2. **EXECUTION** — a server action executes against state the authority owns, on the authority.
+3. **TRUST** — a client's validation results, derived values and claims are never authoritative.
+4. **TRANSACTION** — one semantic action commits atomically or not at all, wherever it runs.
+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.
+
+```ts
+{ id: STATE_PRODUCTS, kind: 'state', authority: 'server' }                  // the authority owns it
+{ id: STATE_AUDIT,    kind: 'state', authority: 'server', serverOnly: true } // and the client never sees it
+```
+
+- `authority` defaults to `'client'`. **Every 0.5.x graph is unchanged and still runs with no server.**
+- Authority is separate from persistence: one says who decides a value, the other where a decided value survives.
+- **Where an action executes is derived, never declared**: an action that writes any server-authoritative state is a server action.
+- A server action reaches the client as its id, name and parameters only — no operations, no guards, no failure modes, no authorization.
+- A server action MUST NOT read client state. Pass the value as an action parameter; that is what a draft is for.
+
+```ts
+compileToIR(graph)         // the client half, filtered at the boundary
+compileToServerIR(graph)   // what an authority executes: no UI, no presentation, no routes
+```
+
+### Authorization
+
+```ts
+graph.setPrincipalEntity(ENTITY_USER);
+{ kind: 'action', authorization: binary('eq', field(ref(PRINCIPAL), F_ROLE), literal('admin')), … }
+```
+
+`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.
+
+### Running one
+
+```ts
+const server = createAxiomServer({ ir: compileToServerIR(graph), persistence, host });
+await server.start();
+await serveOverHttp({ server, port: 3000 });
+
+const app = createAxiomRuntime({ ir, rootElement, host, remote: createRemoteGateway(transport) });
+await app.syncAuthoritativeState();
+```
+
+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.
+
+Boundary diagnostics: `UNKNOWN_SERVER_ACTION` `ARGUMENT_TYPE_MISMATCH` `AUTHORIZATION_DENIED`
+`CONCURRENCY_CONFLICT` `MALFORMED_REQUEST` `AUTHORITY_UNREACHABLE`, plus `SERVER_STATE_WRITE`
+and `REMOTE_ACTION_UNAVAILABLE` on the client.
+
 ## Serialization
 
 The whole graph, theme included, is JSON. `graph.serialize()` /

package/docs/ANTI_PATTERNS.md

@@ -1,6 +1,6 @@
 # Anti-patterns
 
-Axiom 0.5.2-alpha.1. Each of these compiles. Each is wrong. Each is followed by the correct
+Axiom 0.6.0-alpha.1. Each of these compiles. Each is wrong. Each is followed by the correct
 alternative.
 
 ## 1. Field names as entity runtime keys
@@ -334,7 +334,66 @@ Renderer-generated ids are keyed by **render instance**: `data-node` is the sema
 all — see anti-pattern 3 — but a test or a host that must locate an element should select on
 `data-node` and pick the instance it means.
 
-## 26. Restating what the model already knows
+## 26. Binding an input into server-authoritative state
+
+```ts
+// WRONG — rejected by validateGraph (CLIENT_WRITE_TO_SERVER_STATE), and refused at run time.
+{ kind: 'input', binding: { location: itemFieldLocation(STATE_PRODUCTS, F_ID, …, F_STOCK) } }
+
+// RIGHT — edit a client draft, and commit it through an action the authority executes.
+{ kind: 'input', binding: { location: stateLocation(STATE_DRAFT_QUANTITY) } }
+{ kind: 'button', actionId: ACTION_PLACE_ORDER, arguments: { [PARAM_QUANTITY]: ref(STATE_DRAFT_QUANTITY) } }
+```
+
+Do not force every keystroke across the boundary either: a draft is client-local on purpose.
+
+## 27. A server action reading client state
+
+```ts
+// WRONG — the authority does not have the client's draft. SERVER_DEPENDS_ON_CLIENT_STATE.
+{ kind: 'action', operations: [{ kind: 'insert', target: stateLocation(STATE_ORDERS), value: ref(STATE_DRAFT) }] }
+
+// RIGHT — the client proposes values as arguments; the authority decides.
+{
+  kind: 'action',
+  parameters: [{ id: PARAM_QUANTITY, valueType: primitiveType('number'), required: true }],
+  operations: [{ kind: 'insert', target: stateLocation(STATE_ORDERS), value: object([…]) }],
+}
+```
+
+## 28. Treating client-side checks as authoritative
+
+```ts
+// WRONG — a guard the client evaluated proves nothing. So does an argument saying so.
+invoke(ACTION_PLACE_ORDER, { quantity: 5, alreadyValidated: true })
+```
+
+The authority re-evaluates guards, constraints, transition rules, argument types and
+authorization against **its own** state, every time. An extra argument is not a parameter and
+is refused outright. Confirmation is interaction, never authorization.
+
+## 29. Putting a secret in the graph
+
+```ts
+// WRONG — a graph is a serializable artifact, and this state ships to the client.
+{ id: STATE_API_KEY, kind: 'state', valueType: primitiveType('string'), initialValue: 'sk-…' }
+```
+
+Server-only information belongs behind `authority: 'server'` with `serverOnly: true`, and a
+credential belongs to the host, not the graph.
+
+## 30. Reaching for a native operation to make an external call
+
+```ts
+// WRONG — a database write rolls back; an email does not. Nothing makes this participate
+// in the transaction, and pretending it does is worse than not having it.
+{ kind: 'native', implementationId: 'app.sendEmail' }
+```
+
+External effects are deliberately unsolved in 0.6. A design involving commands, a
+transactional outbox and idempotency is future work; do not smuggle one in meanwhile.
+
+## 31. Restating what the model already knows
 
 ```ts
 // UNNECESSARY — required comes from the field, the label from the field's name, the

package/docs/AUTHORITY.md

@@ -0,0 +1,330 @@
+# Authority
+
+Axiom 0.6.0-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
+describes both halves, so there is no backend to write.
+
+```text
+                  ApplicationGraph
+                         │
+        ┌────────────────┴────────────────┐
+   compileToIR                    compileToServerIR
+        │                                 │
+   Client runtime  ──semantic protocol──▶ Authority
+        │                                 │
+   presentation                    PersistenceAdapter
+```
+
+## Load-bearing server invariants
+
+1. **AUTHORITY** — a client cannot commit server-authoritative state, by any path.
+2. **EXECUTION** — a server action executes against state the authority owns, on the authority.
+3. **TRUST** — a client's validation results, derived values and claims are never authoritative.
+4. **TRANSACTION** — one semantic action commits atomically or not at all, wherever it runs.
+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.
+
+## Authority and persistence are different questions
+
+| | Asks | Declared by |
+| --- | --- | --- |
+| **Authority** | who may commit this value | `StateDef.authority` |
+| **Persistence** | where a committed value survives | `StateDef.persistence`, and the adapter the authority runs with |
+
+A server-authoritative state may live only in memory; a client-authoritative state may be
+persisted to local storage. Do not conflate them.
+
+```ts
+{ id: STATE_PRODUCTS, kind: 'state', authority: 'server', valueType: … }   // the authority owns it
+{ id: STATE_DRAFT,    kind: 'state', draft: true,        valueType: … }   // the client owns it
+{ id: STATE_AUDIT,    kind: 'state', authority: 'server', serverOnly: true } // and the client never sees it
+```
+
+- `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.
+
+## Where an action executes
+
+**Derived, never declared.** An action that writes any server-authoritative state is a
+server action — following `for-each`, `invoke` and declared native effects. It cannot
+disagree with what the action actually does.
+
+```ts
+agent.getActionAuthority(ACTION_PLACE_ORDER);   // 'server'
+agent.getServerActions();
+```
+
+A server action is dispatched by the client, not executed by it: its operations, guards and
+authorization are **absent** from the client IR.
+
+## The trust boundary
+
+The client is untrusted. The authority never trusts client state, client-derived values,
+client constraint results, client permission checks, client presentation state, or any
+claim that validation already happened.
+
+| Attempt | Refused by |
+| --- | --- |
+| Bind an input into server state | `validateGraph` → `CLIENT_WRITE_TO_SERVER_STATE` |
+| Write server state from the client at run time | the client store's single write path → `SERVER_STATE_WRITE` |
+| Execute a server action locally | it has no operations in the client IR |
+| Send mutation operations | the protocol has no such request |
+| Forge an action id | resolved from the authority's own IR → `UNKNOWN_SERVER_ACTION` |
+| Send an argument of the wrong shape | checked against the declared type → `ARGUMENT_TYPE_MISMATCH` |
+| Invoke without permission | `authorization`, evaluated on the authority → `AUTHORIZATION_DENIED` |
+| Read server-only state | it is not in the client IR, the snapshot or any answer |
+
+## Server IR
+
+```ts
+const serverIR = compileToServerIR(graph);   // throws GraphValidationError if invalid
+```
+
+`ServerIR` is what an authority executes: entities, the state authoritative execution needs,
+the server actions in full, constraints, transition constraints, the principal entity, and
+which states a client may observe. It carries **no UI, no presentation, no theme and no
+routes**, because none of that decides anything.
+
+It is plain JSON — deterministic, closure-free, and specific to no language or host. It
+declares `contract: 'axiom.server.v1'`, and a runtime that does not recognize the value MUST
+refuse it rather than interpret it partially.
+
+Guards are normalized into aligned `preconditions` / `failureModes`, exactly as in the
+client IR, so an authority that read one and not the other cannot silently skip a check.
+
+## Client IR
+
+`compileToIR` is authority-aware. From the same graph it produces the client's half:
+
+| In the graph | In the client IR |
+| --- | --- |
+| A server-authoritative state | present, typed, with `initialValue` stripped — the authority owns the value |
+| A `serverOnly` state | **absent**, along with any edge, constraint or transition rule that names it |
+| A server action | its id, name, parameters and confirmation only — no operations, no guards, no failure modes, no authorization |
+| `authority` | `ApplicationIR.authority`, so the client runtime refuses to write what it does not own |
+| Server actions | `ApplicationIR.remoteActionIds`, so the runtime dispatches instead of executing |
+
+Entity type declarations are shared: they are the schema, not the rules.
+
+## Executing an action
+
+The authority runs **the same semantic engine** the client runs. Transaction boundaries,
+provisional writes, `for-each` ordering, constraint and transition evaluation, rollback and
+the mutation log are not reimplemented, so a graph cannot behave differently merely because
+execution moved.
+
+```text
+resolve the action from the authority's own IR   → UNKNOWN_SERVER_ACTION
+authenticate the credential (host)
+validate arguments against declared types        → ARGUMENT_TYPE_MISMATCH
+evaluate authorization with PRINCIPAL bound      → AUTHORIZATION_DENIED
+  ── nothing above opens a transaction ──
+BEGIN TRANSACTION  (the ordinary Axiom lifecycle, unchanged)
+COMMIT to persistence, atomically                → CONCURRENCY_CONFLICT
+answer with diagnostics and authoritative changes
+```
+
+A refusal at any stage before the commit leaves authoritative state exactly as it was.
+
+## Authentication and authorization
+
+They are separate. **Authentication** — who is asking — is the host's business:
+
+```ts
+createServerHost({
+  authenticate: (credential) => resolveUser(credential),   // → a PrincipalRecord, or null
+});
+```
+
+Axiom 0.6 ships no authentication provider. **Authorization** — whether this caller may
+perform this operation — is semantic:
+
+```ts
+graph.setPrincipalEntity(ENTITY_USER);
+
+{
+  kind: 'action',
+  authorization: binary('eq', field(ref(PRINCIPAL), F_USER_ROLE), literal('admin')),
+  …
+}
+```
+
+- `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.
+
+**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.
+
+## Persistence
+
+```ts
+interface PersistenceAdapter {
+  load(): Promise<PersistedState[]>;
+  commit(commit: PersistenceCommit): Promise<CommitOutcome>;
+  revision(): Promise<number>;
+  close?(): Promise<void>;
+}
+```
+
+- A semantic transaction that writes several states MUST persist as **one unit**. An adapter must never apply a subset.
+- `commit` carries the revision each written state had when the transaction began. A mismatch MUST refuse the commit rather than overwrite.
+- Derived state is recomputed, never stored.
+
+| Adapter | For |
+| --- | --- |
+| `createMemoryPersistence(seed?)` | Deterministic tests, conformance runs, experimentation. Implements the whole model, revision checks included. |
+| `createSqlitePersistence({ location })` | The durable reference, on Node's built-in `node:sqlite`. |
+
+State is stored in **document form** — one row per state, holding its serialized semantic
+value and its revision. That is deliberate: 0.6 is about persistence semantics. Relational
+projection, migrations and schema generation are future work, and no ApplicationGraph
+mentions SQL.
+
+## Concurrency
+
+The authority **serializes** execution: one action at a time, and its commit completes
+before the next begins. Within one process that alone prevents a lost update.
+
+The revision check is the second layer, and the one that matters beyond a single process: a
+commit whose expected revisions no longer hold is refused, in-memory state is restored to
+what it was, and the caller receives `CONCURRENCY_CONFLICT`.
+
+```text
+stock 5 · caller A wants 4 · caller B wants 4  →  exactly one commits
+```
+
+Multi-node execution is not a 0.6 goal, but the interface does not preclude it: an adapter
+backed by a shared store already refuses a stale commit.
+
+## Idempotency
+
+A network retry must not run an action twice.
+
+```ts
+{ kind: 'invoke', actionId, arguments, requestId: 'a-stable-key' }
+```
+
+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.
+
+## The protocol
+
+Transport-independent by construction. One endpoint, semantic requests:
+
+```ts
+{ kind: 'snapshot', protocol: 'axiom.protocol.v1', credential? }
+{ 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: 'error',    diagnostics }
+```
+
+No graph declares `POST /orders`. Transports:
+
+| Adapter | Use |
+| --- | --- |
+| `createDirectTransport(server, { credential? })` | In-process. A whole client/authority test with no port. |
+| `createHttpTransport({ url, credential?, timeoutMs? })` | The reference network transport. |
+
+A later WebSocket, worker or IPC transport changes nothing in a graph.
+
+## Observing authoritative state
+
+The model is the simplest correct one: **request, decide, apply**.
+
+```ts
+const app = createAxiomRuntime({ ir, rootElement, host, remote: createRemoteGateway(transport) });
+app.start();
+await app.syncAuthoritativeState();     // load the authoritative snapshot
+```
+
+- 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.
+- `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.
+
+## Diagnostics
+
+Server codes join the same structured vocabulary; a client matches on `code` exactly as it
+does for a local failure.
+
+| Code | Meaning |
+| --- | --- |
+| `UNKNOWN_SERVER_ACTION` | The request named an action this authority does not execute. |
+| `ARGUMENT_TYPE_MISMATCH` | An argument did not conform to its declared parameter type, or is not a parameter at all. |
+| `AUTHORIZATION_DENIED` | The caller may not invoke this action, or the rule could not be evaluated. |
+| `CONCURRENCY_CONFLICT` | Another transaction committed the same state first. Nothing was applied. |
+| `MALFORMED_REQUEST` | The request was not an Axiom semantic request, or spoke an unknown protocol. |
+| `AUTHORITY_UNREACHABLE` | The authority could not be reached, timed out, or answered with a transport error. |
+
+Two client-side codes belong to the boundary as well:
+
+| Code | Meaning |
+| --- | --- |
+| `SERVER_STATE_WRITE` | A local write was attempted against state the authority owns. It did not occur. |
+| `REMOTE_ACTION_UNAVAILABLE` | A remote action was invoked with no gateway configured, or the transport failed. |
+
+A network failure becomes a diagnostic, never an exception escaping into application code.
+
+## Observability
+
+```ts
+createServerHost({ report: (event) => log(event) });
+```
+
+Every invocation reports its kind, action, the caller's **identity field only**, request id,
+outcome, duration, revision, diagnostics and the states it committed. No application
+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 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.
+
+```ts
+const server = createAxiomServer({ ir: serverIR, persistence, host });
+await server.start();
+await serveOverHttp({ server, port: 3000 });
+```
+
+## Conformance
+
+`@cynodia/axiom-server` ships `conformance/*.json`. Each fixture is pure data — a Server IR,
+the state to start from, invocations, and expected results — covering expression evaluation,
+guards, mutation, rollback, constraints, transition constraints, `for-each` provisional
+writes, authorization, argument validation, persistence, restart, idempotency and concurrent
+mutation.
+
+Running them requires no part of this implementation. That is the point: the Server IR
+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
+
+Stated plainly rather than left to discovery:
+
+- **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.
+- **Relational schema generation**, migrations and ORM behaviour.
+- **Multi-node distributed execution.** Correctness is guaranteed within one authority process.
+- **File storage, background jobs, scheduling.**

package/docs/CONSTRAINTS.md

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

package/docs/EXPRESSIONS.md

@@ -1,6 +1,6 @@
 # Expressions
 
-Axiom 0.5.2-alpha.1. An expression describes **what value is computed**. It is a tree of
+Axiom 0.6.0-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.5.2-alpha.1. The `ApplicationGraph` is the authoritative representation of an
+Axiom 0.6.0-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.
 
@@ -25,7 +25,7 @@ edited.
 ## API
 
 ```ts
-const graph = new ApplicationGraph(id, name, version?);   // version defaults to '0.5.2'
+const graph = new ApplicationGraph(id, name, version?);   // version defaults to '0.6.0'
 
 graph.addNode<T>(node): NodeId        // generates an id if omitted; throws if it exists
 graph.getNode<T>(id): T | undefined   // deep clone

package/docs/LOCATIONS.md

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

package/docs/PRESENTATION.md

@@ -1,6 +1,6 @@
 # Presentation
 
-Axiom 0.5.2-alpha.1. Presentation is **semantic UX intent**, expressed as data on a UI
+Axiom 0.6.0-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.5.2-alpha.1. The runtime executes an `ApplicationIR`. It is domain-independent: it
+Axiom 0.6.0-alpha.1. The runtime executes an `ApplicationIR`. It is domain-independent: it
 contains no knowledge of any application.
 
 ## Constructing
@@ -14,6 +14,7 @@ const app = createAxiomRuntime({
   rootElement,                     // a DomElement
   host,                            // a HostEnvironment
   nativeOperations?: Record<string, (inputs) => unknown>,
+  remote?: RemoteGateway,                       // required for server-authoritative state
   inputValidation?: 'immediate' | 'deferred',   // DEFAULT: 'immediate'
   recordMutationValues?: boolean,               // default true
 });
@@ -71,6 +72,9 @@ carries `data-node="<node id>"`.
 | `getActionOutcome(id)` | — | The outcome of that action's most recent invocation. See below. |
 | `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). |
+| `evaluate(expression)` | — | Evaluates in the root scope, reporting rather than throwing. A pure read. |
 
 ### `hydrateState` bypasses semantic enforcement
 
@@ -196,6 +200,7 @@ interface RuntimeDiagnostic {
 | `DERIVED_STATE_WRITE` | An attempt to write derived state. The write did not occur. | any write path | — |
 | `UNKNOWN_STATE` | An attempt to write a state that does not exist. | any write path | — |
 | `INPUT_REJECTED` | **Warning.** An input write was rolled back; the control kept its previous value. Accompanied by the violation that caused it. | input binding | `source: 'input'` |
+| `SERVER_STATE_WRITE` | A local write was attempted against state whose authority is the server. It did not occur — through any path, `hydrateState` included. | any write path | — |
 
 ### Operations, routing, UI
 
@@ -204,6 +209,7 @@ interface RuntimeDiagnostic {
 | `UNSUPPORTED_OPERATION` | An operation kind the runtime does not execute. | action | — |
 | `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 | — |
 | `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 | — |
@@ -244,6 +250,20 @@ 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`.
 
+## 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();
+```
+
+`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).
+
 ## The browser bundle
 
 The runtime modules are ordinary type-checked TypeScript that import nothing at run time

package/docs/SEMANTIC_CONTRACT.md

@@ -1,6 +1,6 @@
 # Semantic contract
 
-Axiom 0.5.2-alpha.1. Runtime guarantees, stated formally. This file defines behavior; it
+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
 describes the implementation and is authoritative.
 
@@ -181,6 +181,28 @@ location.
 
 Full per-kind semantics: [`EXPRESSIONS.md`](EXPRESSIONS.md).
 
+## Authority
+
+Full model: [`AUTHORITY.md`](AUTHORITY.md).
+
+- `StateDef.authority` is `'client'` unless declared otherwise, so a graph with no authority metadata behaves exactly as it did in 0.5.x and needs no server.
+- A client MUST NOT commit a mutation to server-authoritative state through any path. An input bound into one is a validation error; a runtime write is refused at the store's single write path.
+- Where an action executes is **derived** from what it writes, following `for-each`, `invoke` and declared native effects. It is never declared, so it cannot disagree with the action.
+- A server action MUST NOT read client-authoritative state, and server state MUST NOT derive from it.
+- State marked `serverOnly` MUST be absent from the client IR, from snapshots, and from every answer — along with anything the client receives that reads it.
+- An authority MUST resolve an action from its own IR, and MUST NOT accept semantic definitions, operations or validation results from a caller.
+- An authority MUST validate arguments against declared parameter types before executing. Network data is untyped input.
+- `authorization` is evaluated on the authority, before any guard and before any transaction opens. A rule that cannot be evaluated MUST deny. `requiresConfirmation` is interaction and MUST NOT be treated as authorization.
+- 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.
+- Server IR MUST be serializable, deterministic and free of closures, and MUST declare a contract version a runtime can refuse.
+
+**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.
+
 ## 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.

package/docs/STATE.md

@@ -1,6 +1,6 @@
 # State
 
-Axiom 0.5.2-alpha.1. A `StateDef` is a named application value: stored, or computed from
+Axiom 0.6.0-alpha.1. A `StateDef` is a named application value: stored, or computed from
 other state.
 
 ```ts
@@ -24,6 +24,10 @@ other state.
 | **Draft** | `draft: true` | as stored | skipped | no |
 | **Ephemeral** | `ephemeral: true` | as stored | skipped | no |
 
+`authority: 'server'` is a separate axis: it says **who may commit** the value, not where it
+is stored or whether it is validated. A client observes such a state and can never write it.
+See [`AUTHORITY.md`](AUTHORITY.md).
+
 **Canonical** state means stored state that is neither draft nor ephemeral. It is the state
 constraints apply to.
 
@@ -144,7 +148,7 @@ rooted in.
 | --- | --- |
 | `memory` | The default. Nothing outside the runtime. |
 | `local-storage` | Read at startup, written through on every write, keyed by `key ?? "<graphId>:<stateId>"`. Requires a host that provides `storage`. |
-| `remote` | **Validates and does nothing.** Declared, not executed. |
+| `remote` | **Validates and does nothing.** Declared, not executed. For state an authority owns, use `authority: 'server'` and give the authority a `PersistenceAdapter`. |
 
 ## Validation
 

package/docs/UI.md

@@ -1,6 +1,6 @@
 # UI
 
-Axiom 0.5.2-alpha.1. Ten semantic UI node kinds describe **what exists and what it does**.
+Axiom 0.6.0-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`:

package/docs/VALIDATION.md

@@ -1,6 +1,6 @@
 # Validation
 
-Axiom 0.5.2-alpha.1. Validation is authoring-time structural checking. It is not the same
+Axiom 0.6.0-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.
 
@@ -36,7 +36,7 @@ non-numeric collections, and obviously incompatible assignments.
 
 ## Codes
 
-49 codes, exported as `VALIDATION_CODES`. Every one is reachable.
+55 codes, exported as `VALIDATION_CODES`. Every one is reachable.
 
 ### Ids and references
 
@@ -78,6 +78,7 @@ non-numeric collections, and obviously incompatible assignments.
 | `IDENTITY_FIELD_MISMATCH` | An identity selector using a field of the wrong entity. |
 | `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). |
 
 ### Initial values
 
@@ -134,6 +135,21 @@ application from compiling.
 | `CONFLICTING_SIZING` | `minWidth` wider than `maxWidth`. | warning |
 | `OPAQUE_PRESENTATION` | A node carries `rendererOverrides`, which semantic analysis cannot understand. | warning |
 
+### Authority
+
+The boundary between a client and an authority is structural, so a graph that could let a
+client commit authoritative state does not compile. Full model:
+[`AUTHORITY.md`](AUTHORITY.md).
+
+| Code | Raised when | Severity |
+| --- | --- | --- |
+| `CLIENT_WRITE_TO_SERVER_STATE` | An input is bound into server-authoritative state. Bind it to a draft and commit through an action. | error |
+| `SERVER_DEPENDS_ON_CLIENT_STATE` | A server action reads, or server state derives from, state the authority does not own. Pass the value as an action parameter. | error |
+| `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 |
+| `INVALID_PRINCIPAL_ENTITY` | `principalEntityId` names something that is not an entity. | error |
+
 ### Accessibility
 
 Only structurally determinable checks. Nothing speculative.

package/package.json

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