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

package/README.md

@@ -6,13 +6,13 @@ 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
 
 ```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.5.2-alpha.1. An action is behavior expressed as data, executed as a transaction.
+Axiom 0.6.1-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
@@ -62,6 +78,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 +179,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.1-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
@@ -141,6 +142,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.1-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
@@ -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
 
@@ -469,6 +482,98 @@ 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.
+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
+{ 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** — 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
+
+One graph, one process — the generated page and the authority that answers it:
+
+```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, 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`
+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.1-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