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

package/dist/authoring-metadata.d.ts

@@ -0,0 +1,53 @@
+import type { AnyNode } from './types.js';
+/**
+ * Metadata that describes how a node was **authored**, not how it executes.
+ *
+ * `metadata` has always been a free-form bag, which means anything put there travels with the
+ * node into the IR, into the browser, and across the trust boundary. That is right for
+ * metadata a runtime might consult and wrong for metadata only an authoring tool cares about
+ * — a generated node's origin, a design-tool reference, a migration marker. Such data is
+ * inert by construction, and inert data still costs payload and still crosses boundaries.
+ *
+ * Everything under the reserved key is therefore **authoring metadata**: stripped from every
+ * compiled artifact by default, present in the graph, and available to a tool that asks for
+ * it explicitly.
+ *
+ * ```ts
+ * metadata: { [AUTHORING_METADATA_KEY]: { generatedBy: 'entity-list' }, tracked: true }
+ * //          ↑ stripped from the IR                                    ↑ kept
+ * ```
+ *
+ * The mechanism is deliberately not toolkit-specific: a UI toolkit is the first thing that
+ * needs it, not the only one.
+ */
+export declare const AUTHORING_METADATA_KEY = "axiomAuthoring";
+export type AuthoringMetadata = Record<string, unknown>;
+/** The authoring metadata on a node, if it carries any. */
+export declare function authoringMetadata(node: {
+    metadata?: Record<string, unknown>;
+}): AuthoringMetadata | undefined;
+/** Whether a node carries authoring metadata at all. */
+export declare function hasAuthoringMetadata(node: {
+    metadata?: Record<string, unknown>;
+}): boolean;
+/**
+ * Attaches authoring metadata, merging with whatever is already there.
+ *
+ * Returns a new node: nothing here mutates a node an author still holds a reference to.
+ */
+export declare function withAuthoringMetadata<T extends {
+    metadata?: Record<string, unknown>;
+}>(node: T, authoring: AuthoringMetadata): T;
+/**
+ * Removes authoring metadata from one node.
+ *
+ * `metadata` itself is dropped when nothing else was in it, so a node that carried only
+ * authoring metadata comes out byte-identical to one that never had any. That equality is
+ * what makes "stripping equals never recording" testable rather than approximate.
+ */
+export declare function stripAuthoringMetadata<T extends {
+    metadata?: Record<string, unknown>;
+}>(node: T): T;
+/** Removes authoring metadata from every node in a collection. */
+export declare function stripAuthoringMetadataFrom<T extends AnyNode>(nodes: readonly T[]): T[];
+//# sourceMappingURL=authoring-metadata.d.ts.map

package/dist/authoring-metadata.js

@@ -0,0 +1,71 @@
+/**
+ * Metadata that describes how a node was **authored**, not how it executes.
+ *
+ * `metadata` has always been a free-form bag, which means anything put there travels with the
+ * node into the IR, into the browser, and across the trust boundary. That is right for
+ * metadata a runtime might consult and wrong for metadata only an authoring tool cares about
+ * — a generated node's origin, a design-tool reference, a migration marker. Such data is
+ * inert by construction, and inert data still costs payload and still crosses boundaries.
+ *
+ * Everything under the reserved key is therefore **authoring metadata**: stripped from every
+ * compiled artifact by default, present in the graph, and available to a tool that asks for
+ * it explicitly.
+ *
+ * ```ts
+ * metadata: { [AUTHORING_METADATA_KEY]: { generatedBy: 'entity-list' }, tracked: true }
+ * //          ↑ stripped from the IR                                    ↑ kept
+ * ```
+ *
+ * The mechanism is deliberately not toolkit-specific: a UI toolkit is the first thing that
+ * needs it, not the only one.
+ */
+export const AUTHORING_METADATA_KEY = 'axiomAuthoring';
+/** The authoring metadata on a node, if it carries any. */
+export function authoringMetadata(node) {
+    const found = node.metadata?.[AUTHORING_METADATA_KEY];
+    return found === undefined ? undefined : found;
+}
+/** Whether a node carries authoring metadata at all. */
+export function hasAuthoringMetadata(node) {
+    return authoringMetadata(node) !== undefined;
+}
+/**
+ * Attaches authoring metadata, merging with whatever is already there.
+ *
+ * Returns a new node: nothing here mutates a node an author still holds a reference to.
+ */
+export function withAuthoringMetadata(node, authoring) {
+    const existing = authoringMetadata(node);
+    return {
+        ...node,
+        metadata: {
+            ...node.metadata,
+            [AUTHORING_METADATA_KEY]: { ...existing, ...authoring },
+        },
+    };
+}
+/**
+ * Removes authoring metadata from one node.
+ *
+ * `metadata` itself is dropped when nothing else was in it, so a node that carried only
+ * authoring metadata comes out byte-identical to one that never had any. That equality is
+ * what makes "stripping equals never recording" testable rather than approximate.
+ */
+export function stripAuthoringMetadata(node) {
+    if (!node.metadata || !(AUTHORING_METADATA_KEY in node.metadata)) {
+        return node;
+    }
+    const { [AUTHORING_METADATA_KEY]: _authoring, ...rest } = node.metadata;
+    const next = { ...node };
+    if (Object.keys(rest).length === 0) {
+        delete next.metadata;
+    }
+    else {
+        next.metadata = rest;
+    }
+    return next;
+}
+/** Removes authoring metadata from every node in a collection. */
+export function stripAuthoringMetadataFrom(nodes) {
+    return nodes.map((node) => stripAuthoringMetadata(node));
+}

package/dist/authority.d.ts

@@ -1,6 +1,6 @@
 import type { Expression } from './expressions.js';
 import type { NodeId } from './ids.js';
-import type { ActionDef, ConstraintDef, StateDef, TransitionConstraintDef } from './nodes.js';
+import type { ActionDef, ConstraintDef, ExpressionDef, StateDef, TransitionConstraintDef } from './nodes.js';
 import type { AnyNode } from './types.js';
 /**
  * Who may commit a canonical mutation.
@@ -36,6 +36,8 @@ export interface AuthorityContext {
     actions: Map<NodeId, ActionDef>;
     constraints: ConstraintDef[];
     transitionConstraints: TransitionConstraintDef[];
+    /** Named expressions, so a rule that reuses one still declares what it reads. */
+    expressions: Map<NodeId, ExpressionDef>;
     principalEntityId?: NodeId;
 }
 export declare function authorityContext(nodes: readonly AnyNode[], principalEntityId?: NodeId): AuthorityContext;

package/dist/authority.js

@@ -31,6 +31,7 @@ export function authorityContext(nodes, principalEntityId) {
     const actions = new Map();
     const constraints = [];
     const transitionConstraints = [];
+    const expressions = new Map();
     for (const node of nodes) {
         switch (node.kind) {
             case 'state':
@@ -45,6 +46,9 @@ export function authorityContext(nodes, principalEntityId) {
             case 'transition-constraint':
                 transitionConstraints.push(node);
                 break;
+            case 'expression':
+                expressions.set(node.id, node);
+                break;
             default:
         }
     }
@@ -53,6 +57,7 @@ export function authorityContext(nodes, principalEntityId) {
         actions,
         constraints,
         transitionConstraints,
+        expressions,
         ...(principalEntityId ? { principalEntityId } : {}),
     };
 }
@@ -61,7 +66,9 @@ export function statesReadBy(expressions, context) {
     const found = new Set();
     const seen = new Set();
     const walk = (expression) => {
-        for (const id of referencedIds(expression)) {
+        // Following named expressions matters here more than anywhere: a rule that reads
+        // server state through a reused calculation reads server state.
+        for (const id of referencedIds(expression, (target) => context.expressions.get(target))) {
             const state = context.states.get(id);
             if (!state || seen.has(id)) {
                 continue;

package/dist/context.js

@@ -14,6 +14,12 @@ export function semanticContextFromGraph(graph) {
             parameterNames.set(parameter.id, parameter.name);
         }
     }
+    for (const definition of graph.getNodesByKind('expression')) {
+        for (const parameter of definition.parameters ?? []) {
+            parameterTypes.set(parameter.id, parameter.valueType);
+            parameterNames.set(parameter.id, parameter.name);
+        }
+    }
     return {
         getState: (id) => {
             const node = graph.getNode(id);
@@ -24,6 +30,10 @@ export function semanticContextFromGraph(graph) {
             return node?.kind === 'entity' ? node : undefined;
         },
         getField: (id) => graph.getField(id),
+        getExpressionDef: (id) => {
+            const node = graph.getNode(id);
+            return node?.kind === 'expression' ? node : undefined;
+        },
         getParameterType: (id) => parameterTypes.get(id),
         getName: (id) => graph.getNode(id)?.name ?? parameterNames.get(id),
     };

package/dist/derive-edges.d.ts

@@ -1,10 +1,17 @@
 import type { Expression } from './expressions.js';
 import type { NodeId } from './ids.js';
-import type { GraphEdge } from './nodes.js';
+import type { ExpressionDef, GraphEdge } from './nodes.js';
 import type { AnyNode } from './types.js';
 import type { ApplicationGraph } from './graph.js';
-/** Ids a `ref` expression mentions anywhere in the tree. */
-export declare function referencedIds(expression: Expression): NodeId[];
+/**
+ * Ids a `ref` expression mentions anywhere in the tree.
+ *
+ * A `resolve` function makes the walk follow `expression-ref` into the definition's body, so
+ * a caller that asks "what does this expression read" gets the same answer whether the
+ * calculation was written inline or named. Without one, only the arguments are seen —
+ * which is right for a caller that is asking about this tree alone.
+ */
+export declare function referencedIds(expression: Expression, resolve?: (id: NodeId) => ExpressionDef | undefined, seen?: Set<NodeId>): NodeId[];
 /**
  * Recomputes the structural edges implied by node definitions. Edges index semantics that
  * already exist in the nodes, so they are derived rather than hand maintained — see

package/dist/derive-edges.js

@@ -1,13 +1,28 @@
-import { constructedFieldIds, expressionFieldIds, walkExpression } from './expressions.js';
+import { constructedFieldIds, expressionDefsIn, expressionFieldIds, walkExpression } from './expressions.js';
 import { locationExpressions, locationFieldIds, locationRootStateId, locationSelectorFieldIds, } from './location.js';
+import { isGroupFieldId } from './group.js';
 import { isUINode } from './ui.js';
-/** Ids a `ref` expression mentions anywhere in the tree. */
-export function referencedIds(expression) {
+/**
+ * Ids a `ref` expression mentions anywhere in the tree.
+ *
+ * A `resolve` function makes the walk follow `expression-ref` into the definition's body, so
+ * a caller that asks "what does this expression read" gets the same answer whether the
+ * calculation was written inline or named. Without one, only the arguments are seen —
+ * which is right for a caller that is asking about this tree alone.
+ */
+export function referencedIds(expression, resolve, seen = new Set()) {
     const found = [];
     walkExpression(expression, (node) => {
         if (node.kind === 'ref') {
             found.push(node.targetId);
         }
+        if (node.kind === 'expression-ref' && resolve && !seen.has(node.expressionId)) {
+            seen.add(node.expressionId);
+            const definition = resolve(node.expressionId);
+            if (definition) {
+                found.push(...referencedIds(definition.expression, resolve, seen));
+            }
+        }
     });
     return found;
 }
@@ -35,11 +50,13 @@ export function deriveEdges(nodes) {
     const known = new Set(nodes.map((node) => node.id));
     const states = new Set(nodes.filter((node) => node.kind === 'state').map((node) => node.id));
     const pending = new Map();
+    // Named expressions, so a consumer's reads include what the definition reads.
+    const defs = new Map(nodes.filter((node) => node.kind === 'expression').map((node) => [node.id, node]));
     // A repeat's template refers to the current item by the repeat node's own id.
     const rootScope = new Map();
     for (const node of nodes) {
         if (node.kind === 'repeat') {
-            rootScope.set(node.id, statesOf(node.source, new Map(), states));
+            rootScope.set(node.id, statesOf(node.source, new Map(), states, defs));
         }
     }
     // Which states can hold instances of an entity, including nested ones. An entity-scoped
@@ -67,9 +84,14 @@ export function deriveEdges(nodes) {
         pending.set(key, entry);
     };
     const reads = (from, expression, scope, kind = 'reads') => {
-        for (const [stateId, fieldIds] of collectReads(expression, scope, states)) {
+        for (const [stateId, fieldIds] of collectReads(expression, scope, states, new Map(), defs)) {
             link(from, stateId, kind, [...fieldIds]);
         }
+        // Using a named expression is a relationship in its own right: it is how "what depends
+        // on this calculation" is answerable without re-walking every expression in the graph.
+        for (const expressionId of expressionDefsIn(expression)) {
+            link(from, expressionId, 'references');
+        }
     };
     const writes = (from, location, scope, kind = 'writes', extraFields = []) => {
         link(from, locationRootStateId(location), kind, [...locationFieldIds(location), ...extraFields]);
@@ -103,12 +125,12 @@ export function deriveEdges(nodes) {
                 break;
             case 'constraint':
                 if (node.entityId) {
-                    link(node.id, node.entityId, 'constrains', expressionFieldIds(node.expression));
+                    link(node.id, node.entityId, 'constrains', fieldsRead(node.expression, defs));
                 }
                 reads(node.id, node.expression, node.entityId ? entityScope(node.entityId) : rootScope);
                 break;
             case 'transition-constraint': {
-                link(node.id, node.entityId, 'constrains', expressionFieldIds(node.expression));
+                link(node.id, node.entityId, 'constrains', fieldsRead(node.expression, defs));
                 const holders = statesByEntity.get(node.entityId) ?? [];
                 reads(node.id, node.expression, new Map([...rootScope, [node.previousScopeId, holders], [node.proposedScopeId, holders]]));
                 break;
@@ -116,6 +138,11 @@ export function deriveEdges(nodes) {
             case 'route':
                 link(node.id, node.viewId, 'routes-to');
                 break;
+            case 'expression':
+                // The body is evaluated in isolation, so it is analyzed in isolation: no repeat
+                // bindings, no caller scope. Its parameters resolve to nothing here by design.
+                reads(node.id, node.expression, new Map());
+                break;
             default:
         }
     }
@@ -135,7 +162,7 @@ export function deriveEdges(nodes) {
  * 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) {
+function statesOf(expression, scope, states, defs = new Map()) {
     switch (expression.kind) {
         case 'ref': {
             const bound = scope.get(expression.targetId);
@@ -149,22 +176,75 @@ function statesOf(expression, scope, states) {
         case 'sort':
         case 'map':
         case 'flatten':
-            return statesOf(expression.source, scope, states);
+        case 'group':
+            return statesOf(expression.source, scope, states, defs);
         case 'conditional':
             return [
                 ...new Set([
-                    ...statesOf(expression.whenTrue, scope, states),
-                    ...statesOf(expression.whenFalse, scope, states),
+                    ...statesOf(expression.whenTrue, scope, states, defs),
+                    ...statesOf(expression.whenFalse, scope, states, defs),
                 ]),
             ];
         case 'field':
-            return statesOf(expression.source, scope, states);
+            return statesOf(expression.source, scope, states, defs);
         case 'call':
-            return [...new Set(expression.arguments.flatMap((argument) => statesOf(argument, scope, states)))];
+            return [
+                ...new Set(expression.arguments.flatMap((argument) => statesOf(argument, scope, states, defs))),
+            ];
+        case 'expression-ref': {
+            // A named calculation's members come from wherever its body draws them, which may be
+            // an argument the caller supplied. Following it is what keeps a repeat over a reused
+            // expression attributable to the state its rows actually live in.
+            const definition = defs.get(expression.expressionId);
+            if (!definition) {
+                return [];
+            }
+            return statesOf(definition.expression, definitionScope(expression, definition, scope, states, defs), states, withoutDefinition(defs, expression.expressionId));
+        }
         default:
             return [];
     }
 }
+/**
+ * Fields an expression reads, including those a named expression reads on its behalf.
+ *
+ * A rule that reuses a calculation constrains the same fields as one that inlined it, so
+ * "which fields does this rule watch" must not depend on how it was written.
+ */
+function fieldsRead(expression, defs, seen = new Set()) {
+    const found = new Set(expressionFieldIds(expression));
+    for (const id of expressionDefsIn(expression)) {
+        if (seen.has(id)) {
+            continue;
+        }
+        seen.add(id);
+        const definition = defs.get(id);
+        if (definition) {
+            for (const fieldId of fieldsRead(definition.expression, defs, seen)) {
+                found.add(fieldId);
+            }
+        }
+    }
+    return [...found];
+}
+/** Stops a cyclic definition — which validation rejects — from recursing here. */
+function withoutDefinition(defs, id) {
+    const next = new Map(defs);
+    next.delete(id);
+    return next;
+}
+/**
+ * The bindings a definition's body sees: its parameters bound to what the caller passed,
+ * and nothing of the caller's own scope. The same isolation validation enforces.
+ */
+function definitionScope(reference, definition, callerScope, states, defs) {
+    const bindings = new Map();
+    for (const parameter of definition.parameters ?? []) {
+        const argument = reference.arguments?.[String(parameter.id)];
+        bindings.set(parameter.id, argument ? statesOf(argument, callerScope, states, defs) : []);
+    }
+    return bindings;
+}
 /** Entities reachable from a type, following entity fields as well as collections. */
 function reachableEntities(type, entities, seen = new Set()) {
     const found = [];
@@ -190,7 +270,7 @@ function bind(scope, id, targets) {
  * projecting a field of each member is recorded as a read of that field of the state the
  * members came from.
  */
-function collectReads(expression, scope, states, found = new Map()) {
+function collectReads(expression, scope, states, found = new Map(), defs = new Map()) {
     const record = (stateId, fieldId) => {
         const entry = found.get(stateId) ?? new Set();
         if (fieldId) {
@@ -200,31 +280,33 @@ function collectReads(expression, scope, states, found = new Map()) {
     };
     switch (expression.kind) {
         case 'ref':
-            for (const stateId of statesOf(expression, scope, states)) {
+            for (const stateId of statesOf(expression, scope, states, defs)) {
                 record(stateId);
             }
             return found;
         case 'field':
-            for (const stateId of statesOf(expression.source, scope, states)) {
-                record(stateId, expression.fieldId);
+            for (const stateId of statesOf(expression.source, scope, states, defs)) {
+                // A group's own positions belong to no entity, so they are not recorded as field
+                // reads; reading them is still a read of the state the group was built from.
+                record(stateId, isGroupFieldId(expression.fieldId) ? undefined : expression.fieldId);
             }
-            collectReads(expression.source, scope, states, found);
+            collectReads(expression.source, scope, states, found, defs);
             return found;
         case 'object':
             for (const entry of expression.entries) {
-                collectReads(entry.value, scope, states, found);
+                collectReads(entry.value, scope, states, found, defs);
             }
             return found;
         case 'binary':
-            collectReads(expression.left, scope, states, found);
-            collectReads(expression.right, scope, states, found);
+            collectReads(expression.left, scope, states, found, defs);
+            collectReads(expression.right, scope, states, found, defs);
             return found;
         case 'unary':
-            collectReads(expression.operand, scope, states, found);
+            collectReads(expression.operand, scope, states, found, defs);
             return found;
         case 'call':
             for (const argument of expression.arguments) {
-                collectReads(argument, scope, states, found);
+                collectReads(argument, scope, states, found, defs);
             }
             return found;
         case 'filter':
@@ -232,25 +314,37 @@ function collectReads(expression, scope, states, found = new Map()) {
         case 'map':
         case 'sort':
         case 'every':
-        case 'some': {
-            collectReads(expression.source, scope, states, found);
-            const inner = bind(scope, expression.scopeId, statesOf(expression.source, scope, states));
+        case 'some':
+        case 'group': {
+            collectReads(expression.source, scope, states, found, defs);
+            const inner = bind(scope, expression.scopeId, statesOf(expression.source, scope, states, defs));
             const body = expression.kind === 'map'
                 ? expression.projection
-                : expression.kind === 'sort'
+                : expression.kind === 'sort' || expression.kind === 'group'
                     ? expression.by
                     : expression.predicate;
-            collectReads(body, inner, states, found);
+            collectReads(body, inner, states, found, defs);
             return found;
         }
         case 'flatten':
-            collectReads(expression.source, scope, states, found);
+            collectReads(expression.source, scope, states, found, defs);
             return found;
         case 'conditional':
-            collectReads(expression.condition, scope, states, found);
-            collectReads(expression.whenTrue, scope, states, found);
-            collectReads(expression.whenFalse, scope, states, found);
+            collectReads(expression.condition, scope, states, found, defs);
+            collectReads(expression.whenTrue, scope, states, found, defs);
+            collectReads(expression.whenFalse, scope, states, found, defs);
             return found;
+        case 'expression-ref': {
+            // The arguments are read in the caller's scope; the body in the definition's own.
+            for (const argument of Object.values(expression.arguments ?? {})) {
+                collectReads(argument, scope, states, found, defs);
+            }
+            const definition = defs.get(expression.expressionId);
+            if (definition) {
+                collectReads(definition.expression, definitionScope(expression, definition, scope, states, defs), states, found, withoutDefinition(defs, expression.expressionId));
+            }
+            return found;
+        }
         default:
             return found;
     }

package/dist/diagnostics.d.ts

@@ -51,6 +51,18 @@ export declare const VALIDATION_CODES: {
     readonly scopeShadowing: "SCOPE_SHADOWING";
     readonly scopeCollidesWithNode: "SCOPE_COLLIDES_WITH_NODE";
     readonly ephemeralStatePersisted: "EPHEMERAL_STATE_PERSISTED";
+    /** A `field` read of a group position where the source is not a group, or the reverse. */
+    readonly invalidGroupField: "INVALID_GROUP_FIELD";
+    /** An entity declaring one of the reserved group field ids. */
+    readonly reservedFieldId: "RESERVED_FIELD_ID";
+    /** An `expression-ref` naming something that is not an expression definition. */
+    readonly unknownExpressionDef: "UNKNOWN_EXPRESSION_DEF";
+    /** A definition that reaches itself, directly or through another definition. */
+    readonly expressionDefCycle: "EXPRESSION_DEF_CYCLE";
+    /** A parameter the reference does not supply — the body would resolve nothing. */
+    readonly missingExpressionArgument: "MISSING_EXPRESSION_ARGUMENT";
+    /** An argument the definition declares no parameter for. */
+    readonly unknownExpressionArgument: "UNKNOWN_EXPRESSION_ARGUMENT";
     readonly unknownPresentationToken: "UNKNOWN_PRESENTATION_TOKEN";
     readonly presentationSemanticConflict: "PRESENTATION_SEMANTIC_CONFLICT";
     readonly multiplePrimaryActions: "MULTIPLE_PRIMARY_ACTIONS";
@@ -59,6 +71,10 @@ export declare const VALIDATION_CODES: {
     readonly destructiveActionUnmarked: "DESTRUCTIVE_ACTION_UNMARKED";
     readonly excessiveHorizontalActions: "EXCESSIVE_HORIZONTAL_ACTIONS";
     readonly emptyStateWithoutRecoveryAction: "EMPTY_STATE_WITHOUT_RECOVERY_ACTION";
+    /** A UI node kind the intended renderer cannot draw. */
+    readonly unsupportedUiNodeKind: "UNSUPPORTED_UI_NODE_KIND";
+    /** A dialog whose declaration cannot produce a usable dialog. */
+    readonly invalidDialog: "INVALID_DIALOG";
     readonly rigidHorizontalLayout: "RIGID_HORIZONTAL_LAYOUT";
     readonly conflictingSizing: "CONFLICTING_SIZING";
     readonly interactiveElementMissingLabel: "INTERACTIVE_ELEMENT_MISSING_LABEL";

package/dist/diagnostics.js

@@ -34,6 +34,19 @@ export const VALIDATION_CODES = {
     scopeShadowing: 'SCOPE_SHADOWING',
     scopeCollidesWithNode: 'SCOPE_COLLIDES_WITH_NODE',
     ephemeralStatePersisted: 'EPHEMERAL_STATE_PERSISTED',
+    // Reusable expressions and grouping.
+    /** A `field` read of a group position where the source is not a group, or the reverse. */
+    invalidGroupField: 'INVALID_GROUP_FIELD',
+    /** An entity declaring one of the reserved group field ids. */
+    reservedFieldId: 'RESERVED_FIELD_ID',
+    /** An `expression-ref` naming something that is not an expression definition. */
+    unknownExpressionDef: 'UNKNOWN_EXPRESSION_DEF',
+    /** A definition that reaches itself, directly or through another definition. */
+    expressionDefCycle: 'EXPRESSION_DEF_CYCLE',
+    /** A parameter the reference does not supply — the body would resolve nothing. */
+    missingExpressionArgument: 'MISSING_EXPRESSION_ARGUMENT',
+    /** An argument the definition declares no parameter for. */
+    unknownExpressionArgument: 'UNKNOWN_EXPRESSION_ARGUMENT',
     // Presentation and UX. Everything here is a warning except an unknown token, which the
     // renderer genuinely cannot act on.
     unknownPresentationToken: 'UNKNOWN_PRESENTATION_TOKEN',
@@ -44,6 +57,10 @@ export const VALIDATION_CODES = {
     destructiveActionUnmarked: 'DESTRUCTIVE_ACTION_UNMARKED',
     excessiveHorizontalActions: 'EXCESSIVE_HORIZONTAL_ACTIONS',
     emptyStateWithoutRecoveryAction: 'EMPTY_STATE_WITHOUT_RECOVERY_ACTION',
+    /** A UI node kind the intended renderer cannot draw. */
+    unsupportedUiNodeKind: 'UNSUPPORTED_UI_NODE_KIND',
+    /** A dialog whose declaration cannot produce a usable dialog. */
+    invalidDialog: 'INVALID_DIALOG',
     rigidHorizontalLayout: 'RIGID_HORIZONTAL_LAYOUT',
     conflictingSizing: 'CONFLICTING_SIZING',
     interactiveElementMissingLabel: 'INTERACTIVE_ELEMENT_MISSING_LABEL',

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 | EveryExpression | SomeExpression | FlattenExpression | ConditionalExpression;
+export type Expression = LiteralExpression | RefExpression | FieldExpression | ObjectExpression | BinaryExpression | UnaryExpression | CallExpression | FilterExpression | FindExpression | MapExpression | SortExpression | EveryExpression | SomeExpression | FlattenExpression | ConditionalExpression | GroupExpression | ExpressionRefExpression;
 export type ExpressionKind = Expression['kind'];
 /** Every expression kind the runtime is required to evaluate. */
 export declare const EXPRESSION_KINDS: readonly ExpressionKind[];
@@ -118,6 +118,46 @@ export interface FlattenExpression {
     kind: 'flatten';
     source: Expression;
 }
+/**
+ * Partitions a collection by a key.
+ *
+ * `Collection<A>` becomes `Collection<Group<K, A>>`, where the key is `by` evaluated with
+ * each member bound to `scopeId` — the same iteration scope every other collection operator
+ * introduces. A group is read with `groupKey` and `groupItems`.
+ *
+ * The **ordering contract** is part of the semantics, not an accident of implementation:
+ *
+ * - groups appear in the order their key was **first seen** in the source collection;
+ * - members within a group keep their source order;
+ * - two keys are the same key when they are structurally equal, so a key may be a nested
+ *   record and not only a primitive;
+ * - an empty collection produces no groups, and a source that is `null` fails the
+ *   evaluation like every other 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.
+ */
+export interface GroupExpression {
+    kind: 'group';
+    source: Expression;
+    scopeId: NodeId;
+    by: Expression;
+}
+/**
+ * Evaluates a named expression definition — the reuse mechanism (`ExpressionDef`).
+ *
+ * `arguments` are keyed by the definition's parameter ids and are evaluated in **this**
+ * scope; the body is then evaluated in an **isolated** scope that sees the parameters and
+ * application state and nothing else. That isolation is the whole point: a definition
+ * reused in three places cannot pick up an iteration scope from one of them, and its own
+ * internal scope ids can never collide with a caller's.
+ */
+export interface ExpressionRefExpression {
+    kind: 'expression-ref';
+    expressionId: NodeId;
+    /** Keyed by parameter id. */
+    arguments?: Record<string, Expression>;
+}
 /** Chooses between two values. Both branches are expressions, never callbacks. */
 export interface ConditionalExpression {
     kind: 'conditional';
@@ -149,6 +189,19 @@ 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 group(source: Expression, scopeId: NodeId, by: Expression): GroupExpression;
+/** The key every member of a group shares. */
+export declare function groupKey(source: Expression): FieldExpression;
+/** The members of a group, in the order they appeared in the source collection. */
+export declare function groupItems(source: Expression): FieldExpression;
+/**
+ * References a named expression definition, optionally supplying its parameters.
+ *
+ * Deliberately not `ref`: `ref` resolves a value in the scope chain, and a definition is not
+ * a value in scope. A separate kind means a reader can see that an expression reaches into a
+ * definition without resolving anything first.
+ */
+export declare function expressionRef(expressionId: NodeId, args?: Record<string, Expression>): ExpressionRefExpression;
 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;
@@ -157,6 +210,8 @@ export declare function walkExpression(expression: Expression, visit: (node: Exp
  * expressions that compute those values are reads, not writes.
  */
 export declare function constructedFieldIds(expression: Expression): FieldId[];
+/** Expression definitions an expression reaches directly, in tree order. */
+export declare function expressionDefsIn(expression: Expression): NodeId[];
 /** Field ids an expression reads, including nested sources and constructed records. */
 export declare function expressionFieldIds(expression: Expression): FieldId[];
 //# sourceMappingURL=expressions.d.ts.map