@cynodia/axiom 0.6.3-alpha.1 → 0.7.0-alpha.2

package/README.md

@@ -6,13 +6,15 @@ 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.6.0-alpha.x).** The API may change between alpha
+**Status: experimental / alpha (0.7.0-alpha.x).** The API may change between alpha
 releases. The documentation in `docs/` describes this exact version.
 
 ## Installation
 
 ```bash
-npm install @cynodia/axiom
+npm install @cynodia/axiom            # the graph, compiler, runtime and agent API
+npm install @cynodia/axiom-ui         # semantic UI authoring patterns (build time only)
+npm install @cynodia/axiom-server     # only if the application has an authority
 ```
 
 ## Canonical mental model
@@ -26,15 +28,24 @@ npm install @cynodia/axiom
 | `ActionDef` | A transactional semantic operation. |
 | `ConstraintDef` | An invariant over proposed state. |
 | `TransitionConstraintDef` | An invariant over previous committed state → proposed state. |
-| UI nodes | Semantic interaction structure. |
+| UI nodes | Semantic interaction structure (view, container, text, repeat, field-display, form, input, button, conditional, diagnostic, dialog). |
 | `Presentation` | Semantic UX intent. Roles and tokens, never CSS. |
 | `Theme` | Translation of presentation intent into visual design. |
 | Renderer | Platform-specific materialization. Not part of the graph. |
+| `StateDef.authority` | Who may commit a value: the client, or the server. The one declaration the split follows from. |
+| `ServerIR` | The half an authority executes. Portable JSON, frozen as `axiom.server.v1`. |
+| Semantic protocol | What a client may ask for: named actions with arguments, never mutation programs. |
+| `PersistenceAdapter` | Where a decided value survives. Not part of the semantics. |
 
 ```text
-ApplicationGraph → validateGraph → compileToIR → runtime (+ theme → renderer) → application
+ApplicationGraph → validateGraph → compileToIR      → runtime (+ theme → renderer) → page
+                                 → compileToServerIR → authority (+ persistence)
 ```
 
+Authority is **derived, never declared twice**: an action that writes server-owned state is a
+server action, so where code runs cannot disagree with what it does. Full model:
+`docs/AUTHORITY.md`.
+
 ## Load-bearing invariants
 
 Know these before authoring an application. Each is stated in full in
@@ -53,6 +64,10 @@ Know these before authoring an application. Each is stated in full in
 11. **`null` and `[]` are distinct.** `null` fails a collection operator; `[]` does not. A collection is truthy only when non-empty.
 12. **`required(x)` asks only whether a value exists.** `required([])` is `true`.
 13. **A theme changes presentation only.**
+14. **A client cannot commit server-authoritative state**, by any path. An action that writes it executes on the authority.
+15. **The client is untrusted.** Guards, authorization and argument types are checked again on the authority.
+16. **A client requests semantic actions, never mutation programs.** The protocol carries no way to send operations.
+17. **`axiom.server.v1` is frozen and language-independent.** Its semantics are defined by `docs/AUTHORITY.md`, the published JSON Schemas and the conformance fixtures — not by this implementation.
 
 ## Minimal application
 
@@ -126,6 +141,7 @@ The complete operational contract ships with this package, in `docs/`.
 | Semantic UI nodes and bindings | `docs/UI.md` |
 | Presentation, UX intent, themes, formatting | `docs/PRESENTATION.md` |
 | Runtime API and diagnostic codes | `docs/RUNTIME.md` |
+| Server authority, Server IR, the protocol and persistence | `docs/AUTHORITY.md` |
 | Machine queries and graph transformations | `docs/AGENT_API.md` |
 | Validation codes | `docs/VALIDATION.md` |
 | Mistakes that compile but are wrong | `docs/ANTI_PATTERNS.md` |
@@ -144,6 +160,13 @@ This package re-exports four, which can also be installed individually:
 | `@cynodia/axiom-runtime` | State store, evaluation, mutation engine, constraint checking, renderer, routing. |
 | `@cynodia/axiom-agent-api` | Semantic and presentation queries, mutation impact, transactional transformations. |
 
+Two published packages are deliberately **not** re-exported, and are installed separately:
+
+| Package | Why it stands apart |
+| --- | --- |
+| `@cynodia/axiom-server` | The authoritative runtime: Server IR execution, persistence adapters, the semantic protocol and the Node host. It imports `node:http` and `node:sqlite`, and a browser bundle must not. |
+| `@cynodia/axiom-ui` | Semantic UI authoring patterns, expanded into ordinary graph nodes at **build time**. Re-exporting it would make every application carry an authoring dependency forever, and would make "this application no longer needs the toolkit" impossible to state or to test. |
+
 ## License
 
 MIT

package/docs/ACTIONS_TRANSACTIONS.md

@@ -1,6 +1,6 @@
 # Actions and transactions
 
-Axiom 0.6.3-alpha.1. An action is behavior expressed as data, executed as a transaction.
+Axiom 0.7.0-alpha.2. An action is behavior expressed as data, executed as a transaction.
 
 ```ts
 {

package/docs/AGENT_API.md

@@ -1,6 +1,6 @@
 # Agent API
 
-Axiom 0.6.3-alpha.1. The machine-facing interface. Agents query semantics and apply
+Axiom 0.7.0-alpha.2. The machine-facing interface. Agents query semantics and apply
 structural transformations; they never edit generated code.
 
 ```ts

package/docs/AGENT_REFERENCE.md

@@ -1,6 +1,6 @@
 # Agent reference
 
-Axiom 0.6.3-alpha.1. Compressed operational contract. Read this plus the `.d.ts`
+Axiom 0.7.0-alpha.2. 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.6.0'
+const graph = new ApplicationGraph(id, name);      // version defaults to '0.7.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
@@ -92,7 +92,7 @@ output, and anything read back with `getState`.
 
 ## Expressions
 
-15 kinds. Full semantics: [`EXPRESSIONS.md`](EXPRESSIONS.md).
+Every kind is in `EXPRESSION_KINDS`. Full semantics: [`EXPRESSIONS.md`](EXPRESSIONS.md).
 
 ```ts
 literal(v) ref(id) field(src, fieldId) object(entries, entityId?)
@@ -100,8 +100,12 @@ binary(op, l, r) unary(op, operand) call(fn, ...args) conditional(c, t, f)
 filter(src, scopeId, predicate) find(src, scopeId, predicate)
 map(src, scopeId, projection) sort(src, scopeId, by, direction?)
 every(src, scopeId, predicate) some(src, scopeId, predicate) flatten(src)
+group(src, scopeId, by) expressionRef(expressionId, args?)
 ```
 
+- `group` partitions a collection: `Collection<A>` → `Collection<Group<K, A>>`, read with `groupKey(g)` and `groupItems(g)`. Groups appear in **first-seen key order**, members keep source order, keys compare structurally. Nothing is sorted — use `sort` for that.
+- `expressionRef` evaluates a named `ExpressionDef` node: the calculation exists **once** in the graph and every consumer references it. Arguments are evaluated in the calling scope; **the body is evaluated in an isolated scope** that sees its parameters and application state and nothing else, so a definition means the same thing everywhere and its scope ids can never collide with a caller's.
+
 Builtins (14): `required` `is-empty` `non-empty` `length` `contains` `concat` `coalesce`
 `one-of` `count` `sum` `lowercase` `to-string` `now` `uuid`.
 
@@ -316,13 +320,14 @@ boolean types (`TYPE_MISMATCH`).
 
 ## UI nodes
 
-Ten kinds: `view` `container` `text` `repeat` `field-display` `form` `input` `button`
-`conditional` `diagnostic`. Detail: [`UI.md`](UI.md).
+Every kind is in `UI_NODE_KINDS`: `view` `container` `text` `repeat` `field-display` `form`
+`input` `button` `conditional` `diagnostic` `dialog`. Detail: [`UI.md`](UI.md).
 
 - `RepeatNode` binds the current item to **the repeat node's own id**; the template refers to it as `ref(repeatNodeId)`.
 - `InputNode.binding` is `{ location }` — no expression, no field id. An input write goes through the same mutation engine and transaction as an action.
 - `ButtonNode.arguments` is keyed by **action parameter id**.
 - `FormNode` submits either a generated button (`submitActionId` + `submitLabel`) or a declared one (`submitButtonId`), which stays an ordinary queryable node.
+- **`DialogNode` is how you ask for confirmation in a modal**, not `ActionDef.requiresConfirmation`. The two are different things: `requiresConfirmation` delegates to the host's own confirmation — `window.confirm` in a browser — which the application cannot label, focus, style or observe. A `dialog` declares the accessible name, the content, what closes it and where focus starts and returns; the runtime performs focus movement, containment, `Escape` and the ARIA relationships. Use `requiresConfirmation` for a coarse "are you sure" with no content of its own, and a `dialog` for anything a person needs to read.
 - `DiagnosticNode` presents why an action refused. See [Action diagnostics](#action-diagnostics).
 - `visibleWhen` and `ConditionalNode` are interaction behavior, **not authorization**.
 
@@ -343,6 +348,30 @@ identity field and falls back to a deterministic index; nested repeats compose.
 
 The graph still holds one node. `AgentAPI` reasons about that node, never about instances.
 
+## Authoring UI: pattern, primitive, or node
+
+Nodes are the model. They are not the only authoring surface, and choosing between the three
+is a decision an agent should make deliberately:
+
+| The requirement is | Use | Where |
+| --- | --- | --- |
+| recurring application UX that expands deterministically into existing semantics | a **pattern** | `@cynodia/axiom-ui` |
+| interaction behaviour the runtime must perform | a **canonical interaction primitive** | `dialog`, in core |
+| custom but already expressible | **canonical nodes**, composed | this document |
+| genuinely unsupported presentation | `rendererOverrides.web.className`, and nothing more | [`PRESENTATION.md`](PRESENTATION.md) |
+
+The five patterns are `page`, `metric-grid`, `entity-list`, `entity-form` and `action-bar`.
+Expansion happens **at authoring time**: afterwards the graph is ordinary canonical Axiom, and
+nothing at run time knows a pattern existed. Ownership defaults to the **declaration**, so
+editing a generated node is drift, reported per node and per property; `materializePattern`
+hands ownership to the graph when an edit is what you actually want. A pattern never creates
+state, an action, a constraint or an authority.
+
+Interaction behaviour is never a pattern: a pattern can only emit nodes that already exist, so
+focus movement, containment, `Escape`, typeahead and active descendant are unreachable from one
+— see [interaction primitives](UI.md#interaction-primitives) for the classification, including
+`combobox`, which is classified and not implemented.
+
 ## Action diagnostics
 
 The runtime already knows why an action refused. A `DiagnosticNode` makes that available
@@ -574,6 +603,50 @@ Boundary diagnostics: `UNKNOWN_SERVER_ACTION` `ARGUMENT_TYPE_MISMATCH` `AUTHORIZ
 `CONCURRENCY_CONFLICT` `MALFORMED_REQUEST` `AUTHORITY_UNREACHABLE`, plus `SERVER_STATE_WRITE`
 and `REMOTE_ACTION_UNAVAILABLE` on the client.
 
+## Metadata classes
+
+```ts
+metadata: { [AUTHORING_METADATA_KEY]: { … }, tracked: true }
+//          ↑ stripped from every compiled artifact       ↑ kept
+```
+
+Authoring metadata describes how a node was authored, never how it executes. Stripped from
+client IR, server IR and the generated page by default; `compileToIR(graph, {
+includeAuthoringMetadata: true })` keeps it for a tool. Nothing may branch on it at run time.
+
+## Renderability
+
+```ts
+validateGraph(graph, { renderer: BROWSER_RENDERER_CAPABILITIES });  // UNSUPPORTED_UI_NODE_KIND
+compileToIR(graph);                                                 // applies it by default
+```
+
+A UI node kind is only in the contract if a renderer implements it. A renderer publishes
+`{ target, supportedUiKinds }` and must implement everything it publishes.
+
+Capabilities describe **node-kind** support, not partial support: a renderer cannot yet say
+that it draws a kind but not one of its options. Nothing in the current vocabulary needs that,
+and it is a deliberate future extension rather than an oversight.
+
+## Named expressions
+
+```ts
+graph.addNode<ExpressionDef>({
+  id: X_LOW_STOCK,
+  kind: 'expression',
+  name: 'Low stock',
+  parameters: [{ id: P_SOURCE, valueType: collectionType(entityType(E_PRODUCT)) }],
+  expression: filter(ref(P_SOURCE), SC, binary('lte', field(ref(SC), F_STOCK), ref(S_THRESHOLD))),
+});
+
+expressionRef(X_LOW_STOCK, { [P_SOURCE]: ref(S_PRODUCTS) })   // in any number of consumers
+```
+
+- **MUST** supply every declared parameter; an unsupplied one is `MISSING_EXPRESSION_ARGUMENT`.
+- **MUST NOT** reach the caller's scope from the body. It resolves parameters and state only.
+- A definition that reaches itself is `EXPRESSION_DEF_CYCLE`.
+- Dependencies are graph edges: `agent.getExpressionConsumers(id)`, `agent.getExpressionDependencies(id)`, and a consumer's read edges include everything the definition reads — so an answer does not change because a calculation was given a name.
+
 ## Serialization
 
 The whole graph, theme included, is JSON. `graph.serialize()` /

package/docs/ANTI_PATTERNS.md

@@ -1,6 +1,6 @@
 # Anti-patterns
 
-Axiom 0.6.3-alpha.1. Each of these compiles. Each is wrong. Each is followed by the correct
+Axiom 0.7.0-alpha.2. 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.3-alpha.1. How an application crosses the trust boundary.
+Axiom 0.7.0-alpha.2. 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
@@ -95,8 +95,10 @@ which states a client may observe. It carries **no UI, no presentation, no theme
 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.
+declares a `contract`, and a runtime that does not recognize the value MUST refuse it rather
+than interpret it partially. **The declared contract is the oldest one that can carry the
+document**, computed from the document rather than asserted: see
+[contract identifiers](#contract-identifiers).
 
 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.
@@ -515,6 +517,34 @@ them.
 They describe **structure**. What a conforming runtime must *do* with a valid document is this
 page plus the conformance fixtures.
 
+## Contract identifiers
+
+| Contract | Adds | Since |
+| --- | --- | --- |
+| `axiom.server.v1` | the frozen 0.6.1 contract, below | 0.6.1 |
+| `axiom.server.v2` | the expression kinds `group` and `expression-ref`, and the `expressionDefs` they resolve against | 0.7.0 |
+
+`SERVER_IR_CONTRACTS` enumerates both. The rules:
+
+- **A document declares the oldest contract that can carry it.** `compileToServerIR` computes the label from the vocabulary the document actually uses, so an application that uses nothing from 0.7 produces a byte-identical `axiom.server.v1` document, and the committed v1 conformance fixtures are unchanged.
+- **A runtime MUST refuse a contract it does not implement**, and MUST refuse a document whose vocabulary exceeds its declared contract. A v2 runtime executing a v1-labelled document that uses `group` would accept what a conforming v1 runtime elsewhere refuses, and the two would then disagree about the same file. `createAxiomServer` raises rather than executing one.
+- **A frozen contract gains nothing.** `axiom.server.v1` does not contain `group`, `expression-ref` or `expressionDefs`, and `server-ir.v1.schema.json` is byte-frozen. Vocabulary arrives under a new identifier or not at all.
+
+There is one JSON Schema per contract, each generated from the runtime's own vocabulary and
+each shipped: `server-ir.v1.schema.json`, `server-ir.v2.schema.json`.
+
+**`group`.** Partitions a collection: `Collection<A>` → `Collection<Group<K, A>>`. Groups appear
+in the order their key was **first seen** in the source; members keep source order; two keys are
+the same key when they are **structurally** equal; an empty source produces no groups; a `null`
+source fails the evaluation as every collection operator does. Nothing is sorted. A group is a
+record carrying the two reserved field ids `field_group_key` and `field_group_items`, and no
+entity may declare either.
+
+**`expression-ref`.** Evaluates a named `ExpressionDef` from `expressionDefs`. Arguments are
+evaluated in the calling scope; the body is evaluated in an **isolated** scope binding the
+definition's parameters and application state and nothing else. Every declared parameter MUST be
+supplied. A definition that reaches itself is invalid and MUST be refused rather than executed.
+
 ## Server IR v1 is frozen
 
 `axiom.server.v1` is a stable semantic contract as of 0.6.1. A runtime may depend on the
@@ -568,7 +598,7 @@ result is identical to some serial order. Across processes, correctness rests on
 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.3
+## Not in 0.7.0
 
 Stated plainly rather than left to discovery:
 

package/docs/CONSTRAINTS.md

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

package/docs/EXPRESSIONS.md

@@ -1,6 +1,6 @@
 # Expressions
 
-Axiom 0.6.3-alpha.1. An expression describes **what value is computed**. It is a tree of
+Axiom 0.7.0-alpha.2. 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.
 
@@ -116,7 +116,7 @@ Both branches are expressions. Only the chosen branch is evaluated.
 
 ### Collection operators
 
-All six bind the current member to `scopeId` and are strict about their source: `null`
+All seven bind the current member to `scopeId` and are strict about their source: `null`
 fails, `[]` behaves normally.
 
 | Builder | Input | Output | On `[]` |
@@ -127,6 +127,7 @@ fails, `[]` behaves normally.
 | `sort(src, scopeId, by, direction?)` | `Collection<A>` | `Collection<A>` | `[]` |
 | `every(src, scopeId, predicate)` | `Collection<A>` | `boolean` | **`true`** |
 | `some(src, scopeId, predicate)` | `Collection<A>` | `boolean` | **`false`** |
+| `group(src, scopeId, by)` | `Collection<A>` | `Collection<Group<K, A>>` | `[]` |
 | `flatten(src)` | `Collection<Collection<A>>` | `Collection<A>` | `[]` |
 
 - `sort` orders by the projected key, ascending unless `direction: 'desc'`. Numbers compare numerically; anything else compares as text. The sort is stable.
@@ -146,6 +147,67 @@ sum(
 )
 ```
 
+### `group(source, scopeId, by)`
+
+Builds `{ kind: 'group', source, scopeId, by }`. Partitions a collection by a key projected
+from each member. `Collection<A>` becomes
+`Collection<Group<K, A>>`, where `by` is evaluated with the member bound to `scopeId` — the
+same iteration scope every other collection operator introduces.
+
+A group is a **record keyed by two reserved field ids**, so it is read with the ordinary
+`field` vocabulary rather than an accessor invented for the occasion:
+
+```ts
+group(ref(LINES), LINE, field(ref(LINE), F_CATEGORY))   // Collection<Group<string, Line>>
+
+groupKey(ref(GROUP))     // field(ref(GROUP), GROUP_KEY_FIELD)   — the shared key
+groupItems(ref(GROUP))   // field(ref(GROUP), GROUP_ITEMS_FIELD) — the members
+```
+
+**The ordering contract is part of the semantics**, not an accident of implementation:
+
+| | |
+| --- | --- |
+| Group order | the order each key was **first seen** in the source |
+| Member order within a group | source order, preserved |
+| Key identity | structural equality, so a key may be a nested record and not only a primitive |
+| Empty source | no groups |
+| `null` source | fails the evaluation, like every collection operator |
+
+Nothing is sorted. A caller that wants groups in key order says so with `sort`, which is the
+operator whose job that is.
+
+`GROUP_KEY_FIELD` and `GROUP_ITEMS_FIELD` are **reserved**: an entity that declares either is
+`RESERVED_FIELD_ID`, and reading either from something that is not a group — or reading
+anything else *from* a group — is `INVALID_GROUP_FIELD`. A field id that meant one thing in
+one place and another elsewhere would defeat the reason ids exist.
+
+### `expressionRef(expressionId, arguments?)`
+
+Builds `{ kind: 'expression-ref', expressionId, arguments? }`, which evaluates a named
+`ExpressionDef` — the reuse mechanism. Without it, an expression used in
+three places is written three times, each needing its own scope ids.
+
+```ts
+graph.addNode<ExpressionDef>({
+  id: LINES_IN_CATEGORY,
+  kind: 'expression',
+  parameters: [{ id: P_CATEGORY, valueType: primitiveType('string') }],
+  expression: filter(ref(STATE_LINES), LINE, binary('eq', field(ref(LINE), F_CATEGORY), ref(P_CATEGORY))),
+});
+
+expressionRef(LINES_IN_CATEGORY, { [P_CATEGORY]: literal('fasteners') })
+```
+
+**Arguments are evaluated in the calling scope; the body is evaluated in an isolated one.**
+The body sees its parameters and application state, and nothing else. That isolation is the
+point: a definition reused in three places cannot pick up an iteration scope from one of
+them, and its internal scope ids can never collide with a caller's.
+
+Validation: `UNKNOWN_EXPRESSION_DEF` for a reference to something that is not one;
+`EXPRESSION_DEF_CYCLE` if a definition reaches itself; `MISSING_EXPRESSION_ARGUMENT` and
+`UNKNOWN_EXPRESSION_ARGUMENT` for arguments that do not match the declared parameters.
+
 ## Built-in functions
 
 14 names, enumerated by `BUILTIN_FUNCTIONS`. `AGGREGATE_FUNCTIONS` lists those that reduce

package/docs/GRAPH_MODEL.md

@@ -1,6 +1,6 @@
 # Graph model
 
-Axiom 0.6.3-alpha.1. The `ApplicationGraph` is the authoritative representation of an
+Axiom 0.7.0-alpha.2. 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.6.0'
+const graph = new ApplicationGraph(id, name, version?);   // version defaults to '0.7.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.6.3-alpha.1.
+Axiom 0.7.0-alpha.2.
 
 ```text
 Expression = a value

package/docs/PRESENTATION.md

@@ -1,6 +1,6 @@
 # Presentation
 
-Axiom 0.6.3-alpha.1. Presentation is **semantic UX intent**, expressed as data on a UI
+Axiom 0.7.0-alpha.2. 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.3-alpha.1. The runtime executes an `ApplicationIR`. It is domain-independent: it
+Axiom 0.7.0-alpha.2. The runtime executes an `ApplicationIR`. It is domain-independent: it
 contains no knowledge of any application.
 
 ## Constructing

package/docs/SEMANTIC_CONTRACT.md

@@ -1,6 +1,6 @@
 # Semantic contract
 
-Axiom 0.6.3-alpha.1. Runtime guarantees, stated formally. This file defines behavior; it
+Axiom 0.7.0-alpha.2. 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.
 
@@ -205,7 +205,7 @@ Full model: [`AUTHORITY.md`](AUTHORITY.md).
 - 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.3**, and stated so rather than implied: read authorization per caller
+**Not guaranteed in 0.7.0**, 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.
@@ -222,6 +222,20 @@ multi-node execution.
 - 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.
 
+## Metadata classes
+
+- `metadata` is free-form and travels with a node. Anything under the reserved key `AUTHORING_METADATA_KEY` is **authoring metadata**: it describes how a node was authored, never how it executes.
+- Authoring metadata MUST be stripped from every compiled artifact — client IR, server IR, generated page — unless `includeAuthoringMetadata` is passed. Semantic metadata beside it is untouched.
+- Nothing may branch on authoring metadata at run time. Removing it MUST change validation, compilation, presentation resolution, rendering and runtime behaviour by exactly nothing.
+- The mechanism is generic. A UI toolkit is the first thing that needs it, not the only one.
+
+## Renderability
+
+- A UI node kind is part of the contract only if a renderer implements it. `validateGraph(graph, { renderer })` rejects a kind the named target cannot draw, with `UNSUPPORTED_UI_NODE_KIND`.
+- `compileToIR` applies the browser renderer's capabilities by default, so compiling a page rejects an unrenderable node at authoring time rather than producing one that reports `UNSUPPORTED_UI_NODE` on screen.
+- With no renderer named, every kind is accepted: a graph is not rejected for a target nobody named.
+- A renderer publishes what it implements, and MUST implement everything it publishes.
+
 ## Render identity
 
 - A UI node inside a `repeat` is rendered once per member. `NodeId` MUST NOT be used alone to identify a rendered element.
@@ -271,6 +285,7 @@ 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.
+- A `dialog` declares what is open, its accessible name, its content, what closes it and whether it is modal. The runtime performs focus movement, focus containment, `Escape` dismissal, focus return and the ARIA relationships. Dismissing a dialog invokes its close action and infers no other meaning: closing is not cancelling.
 - 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.3-alpha.1. A `StateDef` is a named application value: stored, or computed from
+Axiom 0.7.0-alpha.2. A `StateDef` is a named application value: stored, or computed from
 other state.
 
 ```ts

package/docs/UI.md

@@ -1,9 +1,9 @@
 # UI
 
-Axiom 0.6.3-alpha.1. Ten semantic UI node kinds describe **what exists and what it does**.
+Axiom 0.7.0-alpha.2. Eleven semantic UI node kinds describe **what exists and what it does**.
 How it looks is [presentation](PRESENTATION.md).
 
-All nine share `UIBase`:
+All eleven share `UIBase`:
 
 ```ts
 { id, kind, name?, visibleWhen?: Expression, presentation?: Presentation, metadata? }
@@ -229,6 +229,48 @@ Lifecycle — see [`RUNTIME.md`](RUNTIME.md#action-diagnostics) for the full con
 - Messages come from the structured diagnostics — `failureMode.message` for a refused guard, `ConstraintDef.message` for a broken invariant. The renderer invents no wording.
 - The region is a live region (`role="alert"` for errors, `role="status"` for warnings) and is rendered even when empty, so later content is announced. A control invoking the same action is related to it with `aria-describedby` while it has content.
 
+### `dialog`
+
+```ts
+{
+  kind: 'dialog',
+  openWhen: Expression,           // true while it is open
+  title: string | Expression,     // the accessible name; required
+  description?: string | Expression,
+  children: NodeId[],
+  closeActionId: NodeId,          // what dismissal invokes
+  modal?: boolean,                // default true
+  initialFocusId?: NodeId,        // a descendant
+  returnFocusId?: NodeId,         // usually whatever opened it
+}
+```
+
+Content that interrupts, together with the interaction rules that make it a dialog rather
+than a box that appears. It is the case where composing existing nodes stops being enough:
+visibility is expressible with a `conditional`, but focus movement, focus containment,
+`Escape`, focus return and the announcement to assistive technology are behaviour no node
+describes.
+
+**The graph says what; the runtime does how.**
+
+| The graph declares | The runtime performs |
+| --- | --- |
+| what is open, and what closes it | moving focus in when it opens |
+| the accessible name and description | containing focus while it is modal |
+| the content | dismissing on `Escape` |
+| whether it is modal | returning focus when it closes |
+| where focus starts and returns to | `role="dialog"`, `aria-modal`, `aria-labelledby`, `aria-describedby` |
+
+- **Openness is ordinary state.** `openWhen` is an expression over ordinary state — usually an `ephemeral` boolean — not hidden runtime state. Opening and closing therefore go through actions and the mutation log, and are as inspectable as anything else.
+- **A closed dialog is absent, not hidden.** Nothing inside it renders, so nothing inside it is reachable by keyboard or by assistive technology.
+- **Dismissal is not cancellation.** `Escape` invokes `closeActionId` and nothing else. Closing a dialog does not revert, cancel or roll anything back unless that action does — the runtime never infers that it should.
+- **Focus moves in once**, when the dialog is first rendered open, not on every re-render. A full re-render must not take focus back from wherever the person moved it.
+- `title` MUST NOT be empty: a dialog with no accessible name is `INVALID_DIALOG`. `initialFocusId` MUST be inside the dialog and `returnFocusId` MUST NOT be, since it has to exist after the dialog is gone.
+- Nothing here names an element, a class, a position or a stacking order. A renderer that is not a browser implements the same semantics its own way.
+- **Verified in a real browser.** Role, accessible name, `aria-modal`, focus entry, `Tab` and `Shift+Tab` containment, `Escape`, focus return to the correct render instance, a text field inside the dialog, and the absence of a closed dialog are all asserted against Chromium, not only against the in-memory host.
+- **Keyboard containment, not pointer containment.** A modal contains focus and announces itself as modal. It does **not** currently make the rest of the document inert, so a pointer can still reach what is behind it. Declare the rule in a guard, never in the dialog — see [visibility is not authorization](#visibility-is-not-authorization).
+- **Focus return prefers the exact render instance that opened it**, and falls back to another instance of the same control when the action removed that row. A destructive confirmation usually deletes the row its trigger was in; dropping focus to the top of the document instead would lose a keyboard user's place.
+
 ### `conditional`
 
 ```ts
@@ -238,6 +280,55 @@ Lifecycle — see [`RUNTIME.md`](RUNTIME.md#action-diagnostics) for the full con
 Renders one branch. The condition uses the truthiness rules in
 [`EXPRESSIONS.md`](EXPRESSIONS.md#conversions) — note that `[]` is falsy.
 
+## Interaction primitives
+
+`dialog` is the first of a class, and the rule that puts it here rather than in a pattern
+library is worth stating once:
+
+> Interaction semantics that **cannot be reduced to existing canonical nodes** belong in core.
+
+An authoring pattern can only emit nodes that already exist. So anything whose defining
+behaviour is not a node — focus movement, containment, `Escape`, typeahead, active descendant,
+the ARIA relationships that go with them — is unreachable from a pattern at any level of
+cleverness, and has to be canonical semantics with runtime support.
+
+| Candidate | Class | State |
+| --- | --- | --- |
+| `dialog` | canonical-semantic | implemented, browser-verified |
+| `combobox` | canonical-semantic | **classified, not implemented** |
+| `menu`, `tabs`, `accordion`, `tooltip`, `popover` | canonical-semantic | unexamined; each needs its own contract |
+| focus trap, keyboard scheme, live announcement | renderer-only | reached through canonical semantics, never declared |
+| page, metric grid, entity list, entity form, action bar | pattern-expandable | `@cynodia/axiom-ui` |
+
+**Combobox** was probed deliberately because it looks least like a dialog: no modality, no
+interruption, a control inside a form. It divides at the identical seam. Expressible today,
+with no new node kind: the bound value, the option source (`InputNode.options`), option
+identity and label, filtering, and open state — all ordinary state and expressions. Not
+expressible at all: arrow-key navigation, active descendant, typeahead, `aria-expanded` and the
+listbox relationships. Two primitives that share no shape dividing the same way is what makes
+the split a rule rather than an observation about dialogs.
+
+## Semantic UI authoring
+
+Nodes are the model, not the authoring surface an application has to use. `@cynodia/axiom-ui`
+adds five patterns that expand — at build time — into exactly the nodes described on this page.
+
+**Which to reach for:**
+
+| The requirement is | Use |
+| --- | --- |
+| recurring application UX that expands deterministically into existing semantics | a **pattern** (`page`, `metric-grid`, `entity-list`, `entity-form`, `action-bar`) |
+| interaction behaviour that needs the runtime to do something | a **canonical interaction primitive** (`dialog`) |
+| custom, but already expressible | **ordinary canonical nodes**, composed |
+| genuinely unsupported presentation | the renderer escape (`rendererOverrides.web.className`), and nothing more |
+
+A pattern is an authoring abstraction and nothing else: after expansion the application is an
+ordinary Axiom application, and `validateGraph`, `compileToIR`, `AgentAPI` and the runtime know
+nothing about patterns. Ownership defaults to the **declaration**, so editing a generated node
+is drift rather than an edit. The contract travels with the package rather than being restated here: install
+`@cynodia/axiom-ui` and read its `README.md`, `docs/TOOLKIT_AGENT_REFERENCE.md` and
+`docs/PATTERN_CATALOG.json` — the last is addressable as `@cynodia/axiom-ui/catalog`.
+
 ## Containment
 
 `uiChildIds(node)` returns a node's children in render order, for every kind:

package/docs/VALIDATION.md

@@ -1,6 +1,6 @@
 # Validation
 
-Axiom 0.6.3-alpha.1. Validation is authoring-time structural checking. It is not the same
+Axiom 0.7.0-alpha.2. 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.
 
@@ -80,6 +80,14 @@ non-numeric collections, and obviously incompatible assignments.
 | `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. |
+| `UNSUPPORTED_UI_NODE_KIND` | A UI node kind the intended renderer cannot draw. |
+| `INVALID_DIALOG` | A `dialog` whose declaration cannot produce a usable dialog. |
+| `RESERVED_FIELD_ID` | An entity declaring a field id reserved for group results. |
+| `INVALID_GROUP_FIELD` | Reading a group field from a non-group, or a non-group field from a group. |
+| `UNKNOWN_EXPRESSION_DEF` | An `expression-ref` naming something that is not an expression definition. |
+| `EXPRESSION_DEF_CYCLE` | An expression definition that reaches itself. |
+| `MISSING_EXPRESSION_ARGUMENT` | An `expression-ref` that omits a declared parameter. |
+| `UNKNOWN_EXPRESSION_ARGUMENT` | An `expression-ref` supplying a parameter the definition does not declare. |
 
 ### Initial values
 
@@ -150,6 +158,14 @@ client commit authoritative state does not compile. Full model:
 | `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_DIALOG` | A `dialog` with an empty title (no accessible name), an initial focus target outside itself, or a return focus target inside itself. **Also a warning** when a non-modal dialog moves focus on open. | error / warning |
+| `RESERVED_FIELD_ID` | An entity declares `field_group_key` or `field_group_items`. Both are reserved for the records a `group` expression returns; an id meaning one thing in one place and another elsewhere would defeat the reason ids exist. | error |
+| `INVALID_GROUP_FIELD` | A `field` expression reads a group field from a source that is statically not a group, or reads anything other than the two group fields *from* a group. Read `groupItems` first, then the member's own fields. | error |
+| `UNKNOWN_EXPRESSION_DEF` | An `expression-ref` names a node that is not an `ExpressionDef`. | error |
+| `EXPRESSION_DEF_CYCLE` | An expression definition reaches itself, directly or through others. The message names the cycle. | error |
+| `MISSING_EXPRESSION_ARGUMENT` | An `expression-ref` does not supply a parameter the definition declares. | error |
+| `UNKNOWN_EXPRESSION_ARGUMENT` | An `expression-ref` supplies an argument the definition declares no parameter for. | error |
+| `UNSUPPORTED_UI_NODE_KIND` | The graph contains a UI node kind the target renderer does not implement. Raised only when `validateGraph` is given a `renderer`; `compileToIR` supplies the browser renderer's capabilities by default. Without it a graph could validate and then render nothing — the failure would surface as a runtime `UNSUPPORTED_UI_NODE` diagnostic instead of an authoring error. | 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.3-alpha.1",
+  "version": "0.7.0-alpha.2",
   "description": "AI-native semantic web application framework.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -32,10 +32,10 @@
     }
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.6.3-alpha.1",
-    "@cynodia/axiom-runtime": "0.6.3-alpha.1",
-    "@cynodia/axiom-compiler": "0.6.3-alpha.1",
-    "@cynodia/axiom-agent-api": "0.6.3-alpha.1"
+    "@cynodia/axiom-core": "0.7.0-alpha.2",
+    "@cynodia/axiom-runtime": "0.7.0-alpha.2",
+    "@cynodia/axiom-compiler": "0.7.0-alpha.2",
+    "@cynodia/axiom-agent-api": "0.7.0-alpha.2"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json"