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

package/README.md

@@ -1,14 +1,13 @@
 # Axiom
 
-AI-native semantic web application framework.
+AI-native semantic application framework.
 
-**Status: experimental / alpha.** Axiom is a research prototype. Its API may change
-between alpha releases, and it is not production-ready.
+Axiom represents application behavior, state, UI structure and presentation as structured
+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.
 
-An Axiom application is not source code. It is a typed semantic graph of entities,
-fields, state, actions, constraints, routes and UI nodes. A generic compiler normalizes
-that graph and a generic runtime executes it in an unmodified browser — the JavaScript
-and HTML that reach the browser are output, never something you maintain by hand.
+**Status: experimental / alpha (0.5.2-alpha.x).** The API may change between alpha
+releases. The documentation in `docs/` describes this exact version.
 
 ## Installation
 
@@ -16,236 +15,134 @@ and HTML that reach the browser are output, never something you maintain by hand
 npm install @cynodia/axiom@alpha
 ```
 
-## A minimal application
+## Canonical mental model
+
+| Concept | Is |
+| --- | --- |
+| `ApplicationGraph` | The authoritative representation of an application. |
+| `Expression` | What value is computed. Pure; never writes. |
+| `Location` | Where a writable value lives. An address, not a value. |
+| `StateDef` | A stored or derived application value. |
+| `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. |
+| `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. |
+
+```text
+ApplicationGraph → validateGraph → compileToIR → runtime (+ theme → renderer) → application
+```
+
+## Load-bearing invariants
+
+Know these before authoring an application. Each is stated in full in
+`docs/SEMANTIC_CONTRACT.md`.
+
+1. **Entity runtime values are keyed by `FieldId`**, not by field name.
+2. **Expressions produce values; Locations name writable addresses.** Stored state is deeply frozen.
+3. **Derived state is read-only.**
+4. **An action is a transaction.** Every mutation commits, or every mutation rolls back.
+5. **Operations see provisional state**, and `for-each` iteration N sees the writes of iterations `< N`.
+6. **Constraints are evaluated against proposed state**, per instance, wherever it is stored.
+7. **Transition constraints compare the instance at transaction entry with the instance proposed.** A newly inserted instance has no previous state and is not evaluated.
+8. **Input writes are governed** by the same constraints, through the same engine and transaction.
+9. **`hydrateState` bypasses semantic enforcement.** It is administrative.
+10. **Presentation never authorizes behavior.** `hidden` ≠ forbidden.
+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.**
+
+## Minimal application
 
 ```ts
 import {
-  ApplicationGraph,
-  binary,
-  call,
-  compileToHtml,
-  compileToIR,
-  createAxiomRuntime,
-  createMemoryHost,
-  literal,
-  nodeId,
-  primitiveType,
-  ref,
-  stateLocation,
-  synchronizeEdges,
-  validateGraph,
+  ApplicationGraph, binary, compileToIR, createAxiomRuntime, createMemoryHost,
+  literal, nodeId, primitiveType, ref, stateLocation, validateGraph,
 } from '@cynodia/axiom';
 import type { ActionDef, ButtonNode, RouteDef, StateDef, TextNode, ViewNode } from '@cynodia/axiom';
 
 const COUNT = nodeId('state_count');
 const INCREMENT = nodeId('action_increment');
-const DISPLAY = nodeId('ui_display');
-const BUTTON = nodeId('ui_increment');
 const VIEW = nodeId('ui_view');
 
 const graph = new ApplicationGraph('counter', 'Counter');
 
 graph.addNode<StateDef>({
-  id: COUNT,
-  kind: 'state',
-  name: 'count',
-  valueType: primitiveType('number'),
-  initialValue: 0,
+  id: COUNT, kind: 'state', name: 'count',
+  valueType: primitiveType('number'), initialValue: 0,
 });
 
-// Values are expressions; writable positions are locations.
+// A value is an Expression. The position written to is a Location.
 graph.addNode<ActionDef>({
-  id: INCREMENT,
-  kind: 'action',
-  name: 'increment',
+  id: INCREMENT, kind: 'action', name: 'increment',
   operations: [
     { kind: 'set', target: stateLocation(COUNT), value: binary('add', ref(COUNT), literal(1)) },
   ],
 });
 
 graph.addNode<TextNode>({
-  id: DISPLAY,
-  kind: 'text',
-  value: call('concat', literal('Count: '), call('to-string', ref(COUNT))),
+  id: nodeId('ui_display'), kind: 'text', value: ref(COUNT),
+  presentation: { textRole: 'title', format: { kind: 'number' } },
+});
+graph.addNode<ButtonNode>({
+  id: nodeId('ui_increment'), kind: 'button', label: 'Add one', actionId: INCREMENT,
+  presentation: { uxRole: 'primary-action', icon: 'add' },
+});
+graph.addNode<ViewNode>({
+  id: VIEW, kind: 'view', name: 'Counter',
+  children: [nodeId('ui_display'), nodeId('ui_increment')],
 });
-graph.addNode<ButtonNode>({ id: BUTTON, kind: 'button', label: 'Add one', actionId: INCREMENT });
-graph.addNode<ViewNode>({ id: VIEW, kind: 'view', children: [DISPLAY, BUTTON] });
 graph.addNode<RouteDef>({ id: nodeId('route_root'), kind: 'route', path: '/', viewId: VIEW });
 
-synchronizeEdges(graph);
-
-const result = validateGraph(graph);
-if (!result.valid) {
-  throw new Error(result.errors.map((problem) => problem.message).join('\n'));
+if (!validateGraph(graph).valid) {
+  throw new Error('invalid graph');
 }
 
-// Run it headlessly...
 const host = createMemoryHost({ path: '/' });
 const app = createAxiomRuntime({ ir: compileToIR(graph), rootElement: host.root, host });
 app.start();
 app.invokeAction(INCREMENT);
 console.log(app.getState(COUNT)); // 1
-
-// ...or emit a self-contained page.
-const page = compileToHtml(graph);
-```
-
-## Actions are transactions
-
-This is the guarantee the framework is built around:
-
-> An Axiom action executes as a semantic transaction. Its mutations are applied
-> provisionally, the relevant constraints are evaluated against the resulting **proposed
-> state**, and either the complete action commits or every one of its state mutations is
-> rolled back.
-
-That includes iteration. If an action reduces stock for twenty order lines and the
-seventeenth breaks an invariant, the first sixteen do not survive — you never write
-rollback logic yourself, and `runtime.getMutationLog()` shows every attempted write with
-its `outcome` of `committed` or `rolled-back`.
-
-Within one action, each `for-each` iteration reads the state the previous iterations
-proposed. Two lines for the same product debit it twice:
-
-```text
-stock 5  →  line A (−3)  →  2  →  line A (−3)  →  −1  →  stock >= 0 fails  →  all rolled back
-```
-
-That is a guarantee, not an implementation detail: an aggregate rule can be expressed as a
-simple per-record invariant.
-
-## What is enforced, and where
-
-Two kinds of rule, and they answer different questions:
-
-| | Question | Applies to |
-| --- | --- | --- |
-| **Constraint** | Is this state allowed? | Every instance of an entity, wherever it is stored — including instances nested inside other entities. |
-| **Transition constraint** | Is this *change* allowed? | The instance as it was when the transaction began, compared with the instance the transaction proposes. |
-
-A transition constraint is what makes a rule like "a confirmed order never changes" hold
-no matter which path attempts the write:
-
-```ts
-graph.addNode<TransitionConstraintDef>({
-  id: ORDER_SEALED,
-  kind: 'transition-constraint',
-  entityId: ORDER,
-  previousScopeId: PREVIOUS,
-  proposedScopeId: PROPOSED,
-  message: 'A confirmed order cannot be changed.',
-  expression: binary(
-    'or',
-    binary('neq', field(ref(PREVIOUS), STATUS), literal('confirmed')),
-    binary('eq', ref(PROPOSED), ref(PREVIOUS)),
-  ),
-});
-```
-
-**Governed paths** — actions, `for-each` iterations, and input bindings — all evaluate
-entity constraints *and* transition constraints against the proposed state, and roll the
-whole transaction back if either refuses. You do not have to remember not to bind an input
-to a protected location: binding it and typing into it is simply refused, with a
-`TRANSITION_CONSTRAINT_VIOLATION` naming the rule, the entity, and the previous and
-proposed values.
-
-**`hydrateState` is not governed.** It replaces a state value outright for hosts, tests and
-seeding, and evaluates nothing. It is deliberately not named like a normal write.
-
-**"Previous" means transaction entry** — committed state as it was before the outermost
-transaction began. Not the previous operation, and not the previous iteration.
-
-## Collections
-
-Values are described by expressions, writable positions by **locations**. Collections add
-projection, aggregation and ordering to the first, and iteration to the second.
-
-```ts
-import { binary, field, filter, forEach, map, ref, sum } from '@cynodia/axiom';
-
-// An order total: project each line to its amount, then sum the projection.
-const orderTotal = sum(
-  map(ref(LINES), LINE, binary('multiply', field(ref(LINE), QUANTITY), field(ref(LINE), PRICE))),
-);
-
-// How much of one product this order asks for, across every line that mentions it.
-const requested = sum(
-  map(
-    filter(ref(LINES), LINE, binary('eq', field(ref(LINE), PRODUCT), field(ref(P), PRODUCT_ID))),
-    LINE,
-    field(ref(LINE), QUANTITY),
-  ),
-);
-
-// Reduce the stock of every product the order mentions — one mutation per line, one
-// transaction for the action.
-const confirm = forEach(ref(LINES), LINE, [
-  {
-    kind: 'set',
-    target: fieldLocation(
-      itemLocation(stateLocation(PRODUCTS), identitySelector(PRODUCT_ID, field(ref(LINE), PRODUCT))),
-      STOCK,
-    ),
-    value: binary('subtract', currentStock, field(ref(LINE), QUANTITY)),
-  },
-]);
 ```
 
-None of this is a callback. `map`, `sort`, `filter`, `find`, `every`, `some`, `flatten`,
-`conditional` and `for-each` are data: they serialize, they validate, and an agent can ask
-what they read and write.
+`compileToHtml(graph)` emits the same application as one self-contained page.
 
-**Collection operators are strict about their source.** `null` means a missing or invalid
-collection and fails the evaluation; `[]` means an empty collection and works normally
-(`sum([])` is `0`, `count([])` is `0`, `every([])` is `true`). Nothing returns a
-plausible-looking value while reporting a failure. Where a collection may legitimately be
-absent, say so:
+## Documentation
 
-```ts
-coalesce(field(ref(CURRENT_ORDER), LINES), literal([]))
-```
-
-**Presence is not emptiness.** `required(value)` asks only whether a value exists:
-
-```text
-required(null) → false      required([])  → true
-required(0)    → true       required('')  → true
-required(false)→ true
-```
+The complete operational contract ships with this package, in `docs/`.
 
-Use `is-empty` / `non-empty` for collections and strings, and `coalesce` to fall back on
-absence — which means falling back *to* an empty collection now works.
-
-## Diagnostics
-
-Failures are structured. Match on `code` rather than reading the message:
-
-```ts
-import { RUNTIME_DIAGNOSTIC_CODES } from '@cynodia/axiom';
-
-const result = app.invokeAction(CONFIRM_ORDER);
-if (!result.ok) {
-  const stock = result.diagnostics.find(
-    (diagnostic) => diagnostic.code === RUNTIME_DIAGNOSTIC_CODES.PRECONDITION_FAILED,
-  );
-  console.log(stock?.details); // { preconditionIndex: 2, failureMode: 'insufficient-stock' }
-}
-```
+| Need to understand | Read |
+| --- | --- |
+| Compressed reference for authoring or modifying an app | `docs/AGENT_REFERENCE.md` |
+| Exact runtime guarantees | `docs/SEMANTIC_CONTRACT.md` |
+| Graph, ids, types, entity value representation | `docs/GRAPH_MODEL.md` |
+| Every expression kind, builtin and scope rule | `docs/EXPRESSIONS.md` |
+| Addressing writable positions | `docs/LOCATIONS.md` |
+| Stored, derived, draft and ephemeral state | `docs/STATE.md` |
+| Actions, operations, transactions, iteration | `docs/ACTIONS_TRANSACTIONS.md` |
+| Constraints and transition constraints | `docs/CONSTRAINTS.md` |
+| Semantic UI nodes and bindings | `docs/UI.md` |
+| Presentation, UX intent, themes, formatting | `docs/PRESENTATION.md` |
+| Runtime API and diagnostic codes | `docs/RUNTIME.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` |
 
-`result.diagnostics` belongs to that invocation. `app.diagnostics()` keeps the history and
-`app.clearDiagnostics()` empties it.
+Start with `docs/AGENT_REFERENCE.md`. It plus the `.d.ts` declarations are intended to be
+sufficient on their own.
 
 ## What is in the box
 
-`@cynodia/axiom` re-exports the framework packages, which can also be installed
-individually:
+This package re-exports four, which can also be installed individually:
 
-| Package | Contents |
-| ------- | -------- |
-| `@cynodia/axiom-core` | The Application Graph, semantic types, expressions, locations, validation. |
-| `@cynodia/axiom-compiler` | Normalization into an IR, and self-contained page emission. |
-| `@cynodia/axiom-runtime` | The generic runtime: state, mutation engine, renderer, routing. |
-| `@cynodia/axiom-agent-api` | Semantic queries, mutation impact, transactional transformations. |
+| Package | Responsibility |
+| --- | --- |
+| `@cynodia/axiom-core` | Graph, semantic types, expressions, locations, presentation, themes, validation. |
+| `@cynodia/axiom-compiler` | Normalization into an IR, theme stylesheet, page emission. |
+| `@cynodia/axiom-runtime` | State store, evaluation, mutation engine, constraint checking, renderer, routing. |
+| `@cynodia/axiom-agent-api` | Semantic and presentation queries, mutation impact, transactional transformations. |
 
 ## License
 

package/docs/ACTIONS_TRANSACTIONS.md

@@ -0,0 +1,237 @@
+# Actions and transactions
+
+Axiom 0.5.2-alpha.1. An action is behavior expressed as data, executed as a transaction.
+
+```ts
+{
+  id, kind: 'action', name?,
+  parameters?: [{ id, name?, valueType?, required? }],
+  guards?: [{ condition: Expression, failureMode?: { code, message? } }],
+  preconditions?: Expression[],          // older, positional form
+  failureModes?: [{ code, message? }],   // aligned with preconditions by index
+  operations: Operation[],
+  postconditions?: Expression[],
+  destructive?: boolean,
+  requiresConfirmation?: boolean,
+  confirmationMessage?: string,
+  confirmation?: { title?, description?, confirmLabel?, cancelLabel?, severity? },
+}
+```
+
+## Guards and failure modes
+
+Prefer `guards`: it pairs each condition with the failure it reports, so the two cannot
+drift apart.
+
+```ts
+guards: [
+  { condition: isDraft, failureMode: { code: 'not-draft', message: 'This order is confirmed.' } },
+  { condition: hasLines, failureMode: { code: 'empty-order', message: 'Add a line first.' } },
+]
+```
+
+The older parallel arrays align **by position**: `failureModes[2]` reports
+`preconditions[2]`. The compiler normalizes `guards` into that form, so the IR always
+carries aligned arrays and a refusal names the condition that actually failed:
+
+```ts
+result.diagnostics[0].details  // { preconditionIndex: 2, failureMode: 'insufficient-stock' }
+```
+
+`actionGuards(action)` returns the conditions however they were written.
+
+## Lifecycle
+
+```text
+resolve the action                 → ACTION_NOT_FOUND, stop
+bind parameters                    → PARAMETER_MISSING for an absent required parameter, stop
+evaluate preconditions in order    → PRECONDITION_FAILED { preconditionIndex, failureMode }, stop
+ask for confirmation if required   → declined: stop
+        ── nothing above opens a transaction; nothing has been mutated ──
+BEGIN TRANSACTION (entry state is captured here)
+        execute operations sequentially against provisional state
+        evaluate entity constraints + schema conformance over proposed state
+        evaluate transition constraints over entry state → proposed state
+        evaluate postconditions
+        any error-severity failure?
+                no  → COMMIT
+                yes → ROLL BACK every mutation of the transaction
+re-render
+```
+
+`invokeAction(id, args?)` returns `{ ok, diagnostics }` for **that invocation**. No diffing
+of global history is needed.
+
+All four failure sources are evaluated; the action does not stop at the first.
+
+## Operations
+
+Seven kinds, enumerated by `OPERATION_KINDS`. `set`, `insert` and `remove` are the
+mutations; each addresses a [`Location`](LOCATIONS.md).
+
+### `set`
+
+```ts
+{ kind: 'set', target: Location, value: Expression }
+```
+
+Writes the value. A missing field along the path is created; a missing collection **item**
+is `LOCATION_RESOLUTION_FAILED`.
+
+### `insert`
+
+```ts
+{ kind: 'insert', target: Location, value: Expression, position?: 'start' | 'end' }
+```
+
+Appends by default. The target must address a collection; a non-array current value is
+treated as `[]`. The constructed value is deep-cloned before storing.
+
+### `remove`
+
+```ts
+{ kind: 'remove', target: CollectionItemLocation }
+```
+
+**A selector matching nothing is a no-op** — no mutation, no log entry, no diagnostic.
+
+### `for-each`
+
+```ts
+forEach(collection: Expression, scopeId: NodeId, operations: MutationOperation[])
+```
+
+- The collection is evaluated **once**, before any member is mutated.
+- Iteration N observes the provisional writes of iterations `< N`.
+- It opens **no transaction of its own**: the mutations belong to the action's transaction.
+- A failure in iteration N rolls back iterations `0..N-1` and the whole action.
+- Nested operations MUST be mutations only. Nested iteration, navigation and invocation are not supported (`UNSUPPORTED_OPERATION`).
+- `ref(scopeId)` is the current member, and a nested location may use it to address the canonical record that member points at.
+
+Two members touching the same record debit it twice, and the invariant catches the total:
+
+```text
+stock 5 → member A (−3) → 2 → member B (−3) → −1 → `stock >= 0` fails → all rolled back
+```
+
+That is public contract, not incidental behavior. It is what lets an aggregate rule be
+written as a per-record invariant.
+
+### `invoke`
+
+```ts
+{ kind: 'invoke', actionId: NodeId, arguments?: Record<string, Expression> }
+```
+
+Runs another action. The nested transaction **joins the outermost** one and shares its
+fate: if the nested action fails, everything rolls back and the enclosing action fails too.
+Arguments are keyed by the target action's parameter ids.
+
+### `navigate`
+
+```ts
+{ kind: 'navigate', routeId?: NodeId, path?: string, parameters?: Record<string, Expression> }
+```
+
+Changes the route. Parameters are keyed by route parameter id and are rendered as text. An
+unresolvable `routeId` reports `ROUTE_NOT_FOUND`. Navigation is not a state mutation and is
+not rolled back.
+
+### `native`
+
+```ts
+{
+  kind: 'native',
+  implementationId: string,
+  inputs?: Record<string, Expression>,
+  resultTarget?: Location,
+  declaredEffects?: NativeEffect[],
+}
+```
+
+The controlled boundary for behavior the operation vocabulary cannot express.
+
+- The implementation is registered with the runtime (`registerNativeOperation` or `nativeOperations`), never embedded in the graph. Missing → `NATIVE_OPERATION_MISSING`.
+- Inputs are **cloned copies**; native code can never reach into managed state.
+- Native code does not write state. It returns a value, which the mutation engine writes to `resultTarget` with source `native`.
+- Without `declaredEffects`, dependency analysis reports `analysisComplete: false` and names the gap.
+
+**Use it only where no semantic primitive exists.** A native operation is opaque to every
+analysis Axiom offers.
+
+## Postconditions
+
+Evaluated after the operations, inside the transaction, against proposed state. A failure
+is `POSTCONDITION_FAILED` and rolls the action back. Use them for a property of the whole
+action; use constraints for a property of the state.
+
+## Confirmation
+
+`requiresConfirmation: true` asks the host before the transaction opens. `confirmation`
+describes what is asked, without constructing any dialog markup:
+
+```ts
+requiresConfirmation: true,
+confirmation: {
+  title: 'Confirm this order?',
+  description: 'Confirming reduces stock for every line and seals the order.',
+  confirmLabel: 'Confirm order',
+  severity: 'warning',
+},
+```
+
+A host that implements `confirmRequest` receives the structured request; a host that only
+has `confirm(message)` receives a composed sentence. `confirmationMessage` overrides the
+composed message.
+
+A declined confirmation ends the invocation with `ok: false` and no diagnostics.
+
+## Destructive intent
+
+`destructive: true` declares that the action destroys something. It is what
+`AgentAPI.findDestructiveActions()` reports, and presentation is inferred from it — a bound
+button is presented as destructive without the graph saying so twice.
+
+An action containing a `remove` operation is *treated* as destructive by inference, and
+validation warns (`DESTRUCTIVE_ACTION_UNMARKED`) if it does not declare the flag, because
+the declaration is what an agent reads.
+
+`destructive` is metadata. It does not restrict anything — see
+[Presentation never authorizes](PRESENTATION.md#presentation-never-authorizes-behavior).
+
+## The mutation log
+
+```ts
+app.getMutationLog();
+// [{ transactionId, source, sourceNodeId, operation, path, description,
+//    oldValue?, newValue?, outcome }]
+```
+
+- `source` is `action` | `ui` | `system` | `native`.
+- `description` renders the resolved path: `state_products → [product-1] → field_product_stock`.
+- `outcome` is set when the surrounding transaction settles. Rejected attempts remain in the log as `rolled-back`.
+- Only the outermost transaction decides an outcome, so the log never suggests that early iterations of a failed loop committed.
+- `oldValue` / `newValue` are recorded unless `recordMutationValues: false`.
+
+## Invalid usage
+
+```ts
+// WRONG — nested iteration is not supported and is rejected by validateGraph.
+forEach(a, S1, [forEach(b, S2, [...])])
+```
+
+```ts
+// WRONG — enforcing a rule by not offering the control.
+{ kind: 'button', visibleWhen: isDraft, actionId: ACTION_EDIT }
+
+// RIGHT — the control may be hidden for clarity, but the rule lives in the graph.
+{ kind: 'transition-constraint', entityId: ENTITY_ORDER, expression: … }
+```
+
+```ts
+// WRONG — a native operation for something the vocabulary expresses.
+{ kind: 'native', implementationId: 'app.computeTotal', resultTarget: … }
+
+// RIGHT
+{ id: STATE_TOTAL, kind: 'state', derivation: sum(map(...)) }
+```