@cynodia/axiom-core 0.4.0-alpha.1 → 0.5.0-alpha.1

package/README.md

@@ -9,6 +9,11 @@ The Application Graph and its semantic model: nodes, fields, structured types,
 expressions, **locations** (addressable writable positions), edge derivation,
 validation and type inference.
 
+It also owns the presentation and UX layer — semantic roles, layout, spacing and sizing
+tokens, device classes, value formats and the `Theme` — together with presentation
+resolution and validation. Presentation lives here because it is part of the canonical
+graph: it is intent, not styling, and it names no colour, length or CSS property.
+
 ## Installation
 
 ```bash

package/dist/derive-edges.js

@@ -1,4 +1,4 @@
-import { expressionFieldIds, walkExpression } from './expressions.js';
+import { constructedFieldIds, expressionFieldIds, walkExpression } from './expressions.js';
 import { locationExpressions, locationFieldIds, locationRootStateId, locationSelectorFieldIds, } from './location.js';
 import { isUINode } from './ui.js';
 /** Ids a `ref` expression mentions anywhere in the tree. */
@@ -42,6 +42,19 @@ export function deriveEdges(nodes) {
             rootScope.set(node.id, statesOf(node.source, new Map(), states));
         }
     }
+    // Which states can hold instances of an entity, including nested ones. An entity-scoped
+    // constraint reads its fields wherever those instances actually live.
+    const entities = new Map(nodes.filter((node) => node.kind === 'entity').map((node) => [node.id, node]));
+    const statesByEntity = new Map();
+    for (const node of nodes) {
+        if (node.kind !== 'state' || node.draft || node.derivation) {
+            continue;
+        }
+        for (const entityId of reachableEntities(node.valueType, entities)) {
+            statesByEntity.set(entityId, [...(statesByEntity.get(entityId) ?? []), node.id]);
+        }
+    }
+    const entityScope = (entityId) => new Map([...rootScope, [entityId, statesByEntity.get(entityId) ?? []]]);
     const link = (from, to, kind, fieldIds = []) => {
         if (from === to || !known.has(from) || !known.has(to)) {
             return;
@@ -92,8 +105,14 @@ export function deriveEdges(nodes) {
                 if (node.entityId) {
                     link(node.id, node.entityId, 'constrains', expressionFieldIds(node.expression));
                 }
-                reads(node.id, node.expression, rootScope);
+                reads(node.id, node.expression, node.entityId ? entityScope(node.entityId) : rootScope);
+                break;
+            case 'transition-constraint': {
+                link(node.id, node.entityId, 'constrains', expressionFieldIds(node.expression));
+                const holders = statesByEntity.get(node.entityId) ?? [];
+                reads(node.id, node.expression, new Map([...rootScope, [node.previousScopeId, holders], [node.proposedScopeId, holders]]));
                 break;
+            }
             case 'route':
                 link(node.id, node.viewId, 'routes-to');
                 break;
@@ -111,7 +130,11 @@ export function deriveEdges(nodes) {
         },
     }));
 }
-/** The states an expression ultimately draws its members from. */
+/**
+ * The states an expression ultimately draws its members from. Following `field` and calls
+ * matters: a collection reached as `coalesce(field(ref(state), lines), [])` still comes
+ * from that state, and its members' fields are still reads of it.
+ */
 function statesOf(expression, scope, states) {
     switch (expression.kind) {
         case 'ref': {
@@ -125,11 +148,38 @@ function statesOf(expression, scope, states) {
         case 'find':
         case 'sort':
         case 'map':
+        case 'flatten':
+            return statesOf(expression.source, scope, states);
+        case 'conditional':
+            return [
+                ...new Set([
+                    ...statesOf(expression.whenTrue, scope, states),
+                    ...statesOf(expression.whenFalse, scope, states),
+                ]),
+            ];
+        case 'field':
             return statesOf(expression.source, scope, states);
+        case 'call':
+            return [...new Set(expression.arguments.flatMap((argument) => statesOf(argument, scope, states)))];
         default:
             return [];
     }
 }
+/** Entities reachable from a type, following entity fields as well as collections. */
+function reachableEntities(type, entities, seen = new Set()) {
+    const found = [];
+    for (const entityId of entityIdsIn(type)) {
+        if (seen.has(entityId)) {
+            continue;
+        }
+        seen.add(entityId);
+        found.push(entityId);
+        for (const field of entities.get(entityId)?.fields ?? []) {
+            found.push(...reachableEntities(field.valueType, entities, seen));
+        }
+    }
+    return found;
+}
 function bind(scope, id, targets) {
     const next = new Map(scope);
     next.set(id, targets);
@@ -180,7 +230,9 @@ function collectReads(expression, scope, states, found = new Map()) {
         case 'filter':
         case 'find':
         case 'map':
-        case 'sort': {
+        case 'sort':
+        case 'every':
+        case 'some': {
             collectReads(expression.source, scope, states, found);
             const inner = bind(scope, expression.scopeId, statesOf(expression.source, scope, states));
             const body = expression.kind === 'map'
@@ -191,6 +243,14 @@ function collectReads(expression, scope, states, found = new Map()) {
             collectReads(body, inner, states, found);
             return found;
         }
+        case 'flatten':
+            collectReads(expression.source, scope, states, found);
+            return found;
+        case 'conditional':
+            collectReads(expression.condition, scope, states, found);
+            collectReads(expression.whenTrue, scope, states, found);
+            collectReads(expression.whenFalse, scope, states, found);
+            return found;
         default:
             return found;
     }
@@ -217,8 +277,9 @@ function linkOperations(actionId, operations, linker, scope) {
                 linker.reads(actionId, operation.value, scope);
                 break;
             case 'insert':
-                // Inserting a constructed record writes every field the record declares.
-                linker.writes(actionId, operation.target, scope, 'writes', expressionFieldIds(operation.value));
+                // A constructed record writes the fields it declares. Fields consulted while
+                // computing those values are reads, and must not be reported as writes.
+                linker.writes(actionId, operation.target, scope, 'writes', constructedFieldIds(operation.value));
                 linker.reads(actionId, operation.value, scope);
                 break;
             case 'remove':

package/dist/diagnostics.d.ts

@@ -48,5 +48,22 @@ export declare const VALIDATION_CODES: {
     readonly initialValueUnknownField: "INITIAL_VALUE_UNKNOWN_FIELD";
     readonly initialValueMissingRequiredField: "INITIAL_VALUE_MISSING_REQUIRED_FIELD";
     readonly initialValueInvalidEntity: "INITIAL_VALUE_INVALID_ENTITY";
+    readonly scopeShadowing: "SCOPE_SHADOWING";
+    readonly scopeCollidesWithNode: "SCOPE_COLLIDES_WITH_NODE";
+    readonly ephemeralStatePersisted: "EPHEMERAL_STATE_PERSISTED";
+    readonly unknownPresentationToken: "UNKNOWN_PRESENTATION_TOKEN";
+    readonly presentationSemanticConflict: "PRESENTATION_SEMANTIC_CONFLICT";
+    readonly multiplePrimaryActions: "MULTIPLE_PRIMARY_ACTIONS";
+    readonly formWithoutPrimaryAction: "FORM_WITHOUT_PRIMARY_ACTION";
+    readonly destructiveActionPresentedAsSuccess: "DESTRUCTIVE_ACTION_PRESENTED_AS_SUCCESS";
+    readonly destructiveActionUnmarked: "DESTRUCTIVE_ACTION_UNMARKED";
+    readonly excessiveHorizontalActions: "EXCESSIVE_HORIZONTAL_ACTIONS";
+    readonly emptyStateWithoutRecoveryAction: "EMPTY_STATE_WITHOUT_RECOVERY_ACTION";
+    readonly rigidHorizontalLayout: "RIGID_HORIZONTAL_LAYOUT";
+    readonly conflictingSizing: "CONFLICTING_SIZING";
+    readonly interactiveElementMissingLabel: "INTERACTIVE_ELEMENT_MISSING_LABEL";
+    readonly formInputMissingLabel: "FORM_INPUT_MISSING_LABEL";
+    readonly invalidHeadingStructure: "INVALID_HEADING_STRUCTURE";
+    readonly opaquePresentation: "OPAQUE_PRESENTATION";
 };
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.js

@@ -31,4 +31,23 @@ export const VALIDATION_CODES = {
     initialValueUnknownField: 'INITIAL_VALUE_UNKNOWN_FIELD',
     initialValueMissingRequiredField: 'INITIAL_VALUE_MISSING_REQUIRED_FIELD',
     initialValueInvalidEntity: 'INITIAL_VALUE_INVALID_ENTITY',
+    scopeShadowing: 'SCOPE_SHADOWING',
+    scopeCollidesWithNode: 'SCOPE_COLLIDES_WITH_NODE',
+    ephemeralStatePersisted: 'EPHEMERAL_STATE_PERSISTED',
+    // Presentation and UX. Everything here is a warning except an unknown token, which the
+    // renderer genuinely cannot act on.
+    unknownPresentationToken: 'UNKNOWN_PRESENTATION_TOKEN',
+    presentationSemanticConflict: 'PRESENTATION_SEMANTIC_CONFLICT',
+    multiplePrimaryActions: 'MULTIPLE_PRIMARY_ACTIONS',
+    formWithoutPrimaryAction: 'FORM_WITHOUT_PRIMARY_ACTION',
+    destructiveActionPresentedAsSuccess: 'DESTRUCTIVE_ACTION_PRESENTED_AS_SUCCESS',
+    destructiveActionUnmarked: 'DESTRUCTIVE_ACTION_UNMARKED',
+    excessiveHorizontalActions: 'EXCESSIVE_HORIZONTAL_ACTIONS',
+    emptyStateWithoutRecoveryAction: 'EMPTY_STATE_WITHOUT_RECOVERY_ACTION',
+    rigidHorizontalLayout: 'RIGID_HORIZONTAL_LAYOUT',
+    conflictingSizing: 'CONFLICTING_SIZING',
+    interactiveElementMissingLabel: 'INTERACTIVE_ELEMENT_MISSING_LABEL',
+    formInputMissingLabel: 'FORM_INPUT_MISSING_LABEL',
+    invalidHeadingStructure: 'INVALID_HEADING_STRUCTURE',
+    opaquePresentation: 'OPAQUE_PRESENTATION',
 };

package/dist/expressions.d.ts

@@ -5,7 +5,7 @@ import type { LiteralValue } from './nodes.js';
  * identifier: `ref` resolves an id against the evaluation scope chain (route parameters,
  * action parameters, iteration scopes, then state), and `field` reads a field by id.
  */
-export type Expression = LiteralExpression | RefExpression | FieldExpression | ObjectExpression | BinaryExpression | UnaryExpression | CallExpression | FilterExpression | FindExpression | MapExpression | SortExpression;
+export type Expression = LiteralExpression | RefExpression | FieldExpression | ObjectExpression | BinaryExpression | UnaryExpression | CallExpression | FilterExpression | FindExpression | MapExpression | SortExpression | EveryExpression | SomeExpression | FlattenExpression | ConditionalExpression;
 export type ExpressionKind = Expression['kind'];
 /** Every expression kind the runtime is required to evaluate. */
 export declare const EXPRESSION_KINDS: readonly ExpressionKind[];
@@ -57,7 +57,7 @@ export interface UnaryExpression {
  * must be implemented by the runtime: a function that is declared here but unevaluated
  * would be a construct that typechecks, validates and then does nothing.
  */
-export type BuiltinFunction = 'required' | 'is-empty' | 'length' | 'contains' | 'concat' | 'coalesce' | 'one-of' | 'count' | 'sum' | 'lowercase' | 'to-string' | 'now' | 'uuid';
+export type BuiltinFunction = 'required' | 'is-empty' | 'non-empty' | 'length' | 'contains' | 'concat' | 'coalesce' | 'one-of' | 'count' | 'sum' | 'lowercase' | 'to-string' | 'now' | 'uuid';
 export declare const BUILTIN_FUNCTIONS: readonly BuiltinFunction[];
 /** Functions that reduce a collection of numbers to a number. */
 export declare const AGGREGATE_FUNCTIONS: readonly BuiltinFunction[];
@@ -99,6 +99,32 @@ export interface SortExpression {
     by: Expression;
     direction?: 'asc' | 'desc';
 }
+/** True when every member satisfies the predicate. An empty collection satisfies it. */
+export interface EveryExpression {
+    kind: 'every';
+    source: Expression;
+    scopeId: NodeId;
+    predicate: Expression;
+}
+/** True when at least one member satisfies the predicate. An empty collection does not. */
+export interface SomeExpression {
+    kind: 'some';
+    source: Expression;
+    scopeId: NodeId;
+    predicate: Expression;
+}
+/** Collapses one level of nesting: Collection<Collection<T>> becomes Collection<T>. */
+export interface FlattenExpression {
+    kind: 'flatten';
+    source: Expression;
+}
+/** Chooses between two values. Both branches are expressions, never callbacks. */
+export interface ConditionalExpression {
+    kind: 'conditional';
+    condition: Expression;
+    whenTrue: Expression;
+    whenFalse: Expression;
+}
 export declare function literal(value: LiteralValue): LiteralExpression;
 export declare function ref(targetId: NodeId): RefExpression;
 export declare function field(source: Expression, id: FieldId): FieldExpression;
@@ -113,8 +139,24 @@ export declare function sort(source: Expression, scopeId: NodeId, by: Expression
 /** Sums a collection of numbers. An empty collection sums to zero. */
 export declare function sum(source: Expression): CallExpression;
 export declare function count(source: Expression): CallExpression;
+/** True when a value exists at all — an empty collection or string still exists. */
+export declare function required(value: Expression): CallExpression;
+/** True when a collection or string has no members. */
+export declare function isEmpty(value: Expression): CallExpression;
+export declare function nonEmpty(value: Expression): CallExpression;
+/** The first value that exists. Only null and undefined are skipped. */
+export declare function coalesce(...values: Expression[]): CallExpression;
+export declare function every(source: Expression, scopeId: NodeId, predicate: Expression): EveryExpression;
+export declare function some(source: Expression, scopeId: NodeId, predicate: Expression): SomeExpression;
+export declare function flatten(source: Expression): FlattenExpression;
+export declare function conditional(condition: Expression, whenTrue: Expression, whenFalse: Expression): ConditionalExpression;
 /** Visits every sub-expression, parents before children. */
 export declare function walkExpression(expression: Expression, visit: (node: Expression) => void): void;
+/**
+ * Field ids a constructed record assigns. Only the record's own entries count: the
+ * expressions that compute those values are reads, not writes.
+ */
+export declare function constructedFieldIds(expression: Expression): FieldId[];
 /** Field ids an expression reads, including nested sources and constructed records. */
 export declare function expressionFieldIds(expression: Expression): FieldId[];
 //# sourceMappingURL=expressions.d.ts.map

package/dist/expressions.js

@@ -11,10 +11,15 @@ export const EXPRESSION_KINDS = [
     'find',
     'map',
     'sort',
+    'every',
+    'some',
+    'flatten',
+    'conditional',
 ];
 export const BUILTIN_FUNCTIONS = [
     'required',
     'is-empty',
+    'non-empty',
     'length',
     'contains',
     'concat',
@@ -69,6 +74,33 @@ export function sum(source) {
 export function count(source) {
     return call('count', source);
 }
+/** True when a value exists at all — an empty collection or string still exists. */
+export function required(value) {
+    return call('required', value);
+}
+/** True when a collection or string has no members. */
+export function isEmpty(value) {
+    return call('is-empty', value);
+}
+export function nonEmpty(value) {
+    return call('non-empty', value);
+}
+/** The first value that exists. Only null and undefined are skipped. */
+export function coalesce(...values) {
+    return call('coalesce', ...values);
+}
+export function every(source, scopeId, predicate) {
+    return { kind: 'every', source, scopeId, predicate };
+}
+export function some(source, scopeId, predicate) {
+    return { kind: 'some', source, scopeId, predicate };
+}
+export function flatten(source) {
+    return { kind: 'flatten', source };
+}
+export function conditional(condition, whenTrue, whenFalse) {
+    return { kind: 'conditional', condition, whenTrue, whenFalse };
+}
 /** Visits every sub-expression, parents before children. */
 export function walkExpression(expression, visit) {
     visit(expression);
@@ -106,9 +138,29 @@ export function walkExpression(expression, visit) {
             walkExpression(expression.source, visit);
             walkExpression(expression.by, visit);
             return;
+        case 'every':
+        case 'some':
+            walkExpression(expression.source, visit);
+            walkExpression(expression.predicate, visit);
+            return;
+        case 'flatten':
+            walkExpression(expression.source, visit);
+            return;
+        case 'conditional':
+            walkExpression(expression.condition, visit);
+            walkExpression(expression.whenTrue, visit);
+            walkExpression(expression.whenFalse, visit);
+            return;
         default:
     }
 }
+/**
+ * Field ids a constructed record assigns. Only the record's own entries count: the
+ * expressions that compute those values are reads, not writes.
+ */
+export function constructedFieldIds(expression) {
+    return expression.kind === 'object' ? expression.entries.map((entry) => entry.fieldId) : [];
+}
 /** Field ids an expression reads, including nested sources and constructed records. */
 export function expressionFieldIds(expression) {
     const found = [];

package/dist/graph.d.ts

@@ -1,6 +1,7 @@
 import type { EdgeId, FieldId, NodeId } from './ids.js';
 import type { EdgeKind, FieldDef, GraphEdge } from './nodes.js';
 import type { AnyNode, ApplicationGraphData, NodeInput, NodeKind, NodeOfKind } from './types.js';
+import type { Theme, ThemeInput } from './theme.js';
 export interface FieldIndexEntry {
     entityId: NodeId;
     field: FieldDef;
@@ -25,6 +26,14 @@ export declare class ApplicationGraph {
     get id(): string;
     get name(): string;
     get version(): string;
+    /**
+     * The application's visual identity, completed against the default theme. A theme is
+     * presentation only: changing it cannot change an action, a constraint or a route.
+     */
+    get theme(): Theme;
+    /** Exactly what the application declared, before defaults were filled in. */
+    get declaredTheme(): ThemeInput | undefined;
+    setTheme(theme: ThemeInput | undefined): void;
     addNode<T extends AnyNode>(node: NodeInput<T>): NodeId;
     getNode<T extends AnyNode = AnyNode>(id: NodeId): T | undefined;
     hasNode(id: NodeId): boolean;

package/dist/graph.js

@@ -1,5 +1,6 @@
 import { deriveEdges } from './derive-edges.js';
 import { createEdgeId, createNodeId } from './ids.js';
+import { resolveTheme } from './theme.js';
 function clone(value) {
     return structuredClone(value);
 }
@@ -16,7 +17,7 @@ export class ApplicationGraph {
     /** Bumped by every change, so the derived edge index can never serve stale data. */
     revision = 0;
     semanticIndex;
-    constructor(id, name, version = '0.4.0') {
+    constructor(id, name, version = '0.5.0') {
         this.data = { id, name, version, nodes: {}, edges: {} };
     }
     get id() {
@@ -28,6 +29,26 @@ export class ApplicationGraph {
     get version() {
         return this.data.version;
     }
+    /**
+     * The application's visual identity, completed against the default theme. A theme is
+     * presentation only: changing it cannot change an action, a constraint or a route.
+     */
+    get theme() {
+        return resolveTheme(this.data.theme);
+    }
+    /** Exactly what the application declared, before defaults were filled in. */
+    get declaredTheme() {
+        return this.data.theme ? structuredClone(this.data.theme) : undefined;
+    }
+    setTheme(theme) {
+        if (theme === undefined) {
+            delete this.data.theme;
+        }
+        else {
+            this.data.theme = structuredClone(theme);
+        }
+        this.revision += 1;
+    }
     addNode(node) {
         const id = (node.id ?? createNodeId(node.kind));
         if (this.data.nodes[id]) {

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export * from './ids.js';
 export * from './diagnostics.js';
 export * from './location.js';
+export * from './presentation.js';
+export * from './theme.js';
 export * from './type-ref.js';
 export * from './expressions.js';
 export * from './nodes.js';
@@ -10,7 +12,9 @@ export * from './graph.js';
 export * from './infer.js';
 export * from './context.js';
 export * from './validate-location.js';
+export * from './resolve-presentation.js';
 export * from './validate.js';
+export * from './validate-presentation.js';
 export * from './derive-edges.js';
 export * from './ir.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,6 +1,8 @@
 export * from './ids.js';
 export * from './diagnostics.js';
 export * from './location.js';
+export * from './presentation.js';
+export * from './theme.js';
 export * from './type-ref.js';
 export * from './expressions.js';
 export * from './nodes.js';
@@ -10,6 +12,8 @@ export * from './graph.js';
 export * from './infer.js';
 export * from './context.js';
 export * from './validate-location.js';
+export * from './resolve-presentation.js';
 export * from './validate.js';
+export * from './validate-presentation.js';
 export * from './derive-edges.js';
 export * from './ir.js';

package/dist/infer.js

@@ -141,6 +141,14 @@ export function inferExpressionType(expression, context, scope) {
             const item = itemTypeOf(inferExpressionType(expression.source, context, scope));
             return item ? optionalType(item) : undefined;
         }
+        case 'every':
+        case 'some':
+            return primitiveType('boolean');
+        case 'flatten':
+            return itemTypeOf(inferExpressionType(expression.source, context, scope));
+        case 'conditional':
+            return (inferExpressionType(expression.whenTrue, context, scope) ??
+                inferExpressionType(expression.whenFalse, context, scope));
         case 'map': {
             const item = itemTypeOf(inferExpressionType(expression.source, context, scope));
             const projected = inferExpressionType(expression.projection, context, withScope(scope, expression.scopeId, item));
@@ -157,6 +165,8 @@ export function scopeForExpression(expression, context, scope) {
         case 'find':
         case 'map':
         case 'sort':
+        case 'every':
+        case 'some':
             return withScope(scope, expression.scopeId, itemTypeOf(inferExpressionType(expression.source, context, scope)));
         default:
             return scope ?? new Map();

package/dist/ir.d.ts

@@ -1,9 +1,11 @@
 import type { FieldId, NodeId } from './ids.js';
-import type { ActionDef, ConstraintDef, EntityDef, GraphEdge, RouteParameter, StateDef } from './nodes.js';
+import type { ActionDef, ConstraintDef, EntityDef, GraphEdge, RouteParameter, StateDef, TransitionConstraintDef } from './nodes.js';
 import type { FieldIndexEntry } from './graph.js';
 import type { UINode } from './ui.js';
 import type { AnyNode } from './types.js';
 import type { TypeRef } from './type-ref.js';
+import type { ResolvedPresentation } from './presentation.js';
+import type { Theme } from './theme.js';
 export interface RouteSegment {
     kind: 'static' | 'parameter';
     value: string;
@@ -34,6 +36,8 @@ export interface ApplicationIR {
     actions: Record<NodeId, ActionDef>;
     uiNodes: Record<NodeId, UINode>;
     constraints: ConstraintDef[];
+    /** Rules about how state may change, enforced on every governed mutation path. */
+    transitionConstraints: TransitionConstraintDef[];
     routes: CompiledRoute[];
     edges: GraphEdge[];
     /**
@@ -46,5 +50,21 @@ export interface ApplicationIR {
      * to canonical application state from a write to a draft.
      */
     locationRoots: Record<NodeId, NodeId>;
+    /**
+     * Whether the field each input addresses is declared required, resolved here so a
+     * renderer can mark it without re-deriving the model.
+     */
+    locationRequired: Record<NodeId, boolean>;
+    /** The application's visual identity, completed against the default theme. */
+    theme: Theme;
+    /**
+     * Presentation with every question already answered, per UI node: renderer defaults,
+     * theme, inheritance, semantic inference, node declaration and responsive overrides all
+     * resolved. A renderer reads this and needs to know nothing about how it was decided.
+     *
+     * It is deliberately still semantic — roles, tokens and device classes, not CSS — so a
+     * second renderer remains possible.
+     */
+    presentation: Record<NodeId, ResolvedPresentation>;
 }
 //# sourceMappingURL=ir.d.ts.map

package/dist/nodes.d.ts

@@ -2,12 +2,7 @@ import type { Expression } from './expressions.js';
 import type { CollectionItemLocation, Location } from './location.js';
 import type { EdgeId, FieldId, NodeId } from './ids.js';
 import type { TypeRef } from './type-ref.js';
-/** Minimal, optional presentation hints. Styling is not a 0.2 research objective. */
-export interface PresentationHints {
-    role?: 'primary' | 'secondary' | 'danger';
-    density?: 'compact' | 'normal';
-    emphasis?: 'normal' | 'strong';
-}
+import type { ConfirmationPresentation } from './presentation.js';
 export interface NodeBase {
     id: NodeId;
     name?: string;
@@ -50,6 +45,16 @@ export interface StateDef extends NodeBase {
      * definition, so instance validation skips them until an action commits the value.
      */
     draft?: boolean;
+    /**
+     * Marks ephemeral presentation state — which panel is expanded, which tab is selected,
+     * whether a dialog is open. It is not canonical domain state: instance validation skips
+     * it, and it may not be persisted. Marking it says so in the graph instead of leaving an
+     * agent to guess which states are domain facts.
+     *
+     * It changes what a state *is*, never what is permitted: a write reaching domain state
+     * is governed exactly as before.
+     */
+    ephemeral?: boolean;
     persistence?: StatePersistence;
 }
 export interface ActionParameter {
@@ -62,9 +67,16 @@ export interface FailureMode {
     code: string;
     message?: string;
 }
+/** A condition together with the failure it reports, so the two cannot drift apart. */
+export interface ActionGuard {
+    condition: Expression;
+    failureMode?: FailureMode;
+}
 export interface ActionDef extends NodeBase {
     kind: 'action';
     parameters?: ActionParameter[];
+    /** Preferred over the parallel `preconditions` and `failureModes` arrays. */
+    guards?: ActionGuard[];
     preconditions?: Expression[];
     operations: Operation[];
     postconditions?: Expression[];
@@ -73,7 +85,14 @@ export interface ActionDef extends NodeBase {
     destructive?: boolean;
     requiresConfirmation?: boolean;
     confirmationMessage?: string;
+    /** What the confirmation says, when a plain message is not enough. */
+    confirmation?: ConfirmationPresentation;
 }
+/**
+ * The conditions an action checks, however they were written. `guards` pairs each
+ * condition with its failure; the older parallel arrays are matched by position.
+ */
+export declare function actionGuards(action: ActionDef): ActionGuard[];
 export type Operation = SetOperation | InsertOperation | RemoveOperation | ForEachOperation | InvokeOperation | NavigateOperation | NativeOperation;
 export type OperationKind = Operation['kind'];
 /** Every operation kind the runtime is required to execute. */
@@ -159,6 +178,29 @@ export interface ConstraintDef extends NodeBase {
     severity?: 'error' | 'warning';
     message?: string;
 }
+/**
+ * A rule about how state may change, rather than about what state may be.
+ *
+ * An ordinary constraint judges the proposed state on its own; a transition constraint
+ * sees the instance as it was when the transaction began *and* as the transaction
+ * proposes it. That is what lets a rule like "once confirmed, an order may not change"
+ * hold no matter which path attempts the write — an action, an input binding, an
+ * iteration, or something added later.
+ *
+ * `previousScopeId` and `proposedScopeId` bind those two instances for the expression.
+ * When the instance is being removed, the proposed scope is bound to nothing.
+ */
+export interface TransitionConstraintDef extends NodeBase {
+    kind: 'transition-constraint';
+    /** The entity whose transitions are governed. It must have an identity field. */
+    entityId: NodeId;
+    previousScopeId: NodeId;
+    proposedScopeId: NodeId;
+    /** Must hold for every governed transition. */
+    expression: Expression;
+    severity?: 'error' | 'warning';
+    message?: string;
+}
 export interface RouteParameter {
     id: NodeId;
     /** Matches the `:name` placeholder in the route path. */

package/dist/nodes.js

@@ -1,3 +1,16 @@
+/**
+ * The conditions an action checks, however they were written. `guards` pairs each
+ * condition with its failure; the older parallel arrays are matched by position.
+ */
+export function actionGuards(action) {
+    if (action.guards && action.guards.length > 0) {
+        return action.guards;
+    }
+    return (action.preconditions ?? []).map((condition, index) => ({
+        condition,
+        ...(action.failureModes?.[index] ? { failureMode: action.failureModes[index] } : {}),
+    }));
+}
 /** Every operation kind the runtime is required to execute. */
 export const OPERATION_KINDS = [
     'set',