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

package/README.md

@@ -6,13 +6,17 @@ framework.
 **Status: experimental / alpha.** The API may change between alpha releases.
 
 The Application Graph and its semantic model: nodes, fields, structured types,
-expressions, **locations** (addressable writable positions), edge derivation,
-validation and type inference.
+expressions, **locations** (addressable writable positions), edge derivation, validation
+and type inference. It also owns the presentation and UX layer — semantic roles, layout and
+spacing tokens, device classes, value formats and the `Theme` — with presentation
+resolution and validation.
 
-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.
+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.
+
+Main exports: `ApplicationGraph`, `TypeRef` builders, expression builders, `Location`
+builders, `Presentation`, `Theme`, `resolvePresentationMap`, `validateGraph`,
+`VALIDATION_CODES`, `ApplicationIR`.
 
 ## Installation
 
@@ -26,6 +30,13 @@ Most applications should install the facade package instead, which re-exports th
 npm install @cynodia/axiom@alpha
 ```
 
+
+## Documentation
+
+The canonical operational contract lives in the `docs/` directory of the
+[`@cynodia/axiom`](https://www.npmjs.com/package/@cynodia/axiom) package, and in
+[the repository](https://github.com/cynodia/axiom). Start with `docs/AGENT_REFERENCE.md`.
+
 ## License
 
 MIT

package/dist/authority.d.ts

@@ -0,0 +1,63 @@
+import type { Expression } from './expressions.js';
+import type { NodeId } from './ids.js';
+import type { ActionDef, ConstraintDef, StateDef, TransitionConstraintDef } from './nodes.js';
+import type { AnyNode } from './types.js';
+/**
+ * Who may commit a canonical mutation.
+ *
+ * Authority and persistence are separate concerns. Authority says *who decides* a value;
+ * persistence says *where a decided value survives*. A server-authoritative state may be
+ * held only in memory, and a client-authoritative state may be persisted to local storage.
+ */
+export type Authority = 'client' | 'server';
+export declare const AUTHORITIES: readonly Authority[];
+/**
+ * The scope an authorization expression resolves the caller through.
+ *
+ * It is bound to a record keyed by the field ids of the graph's principal entity, so an
+ * authorization rule is written with the same `field`/`ref` vocabulary as everything else:
+ *
+ * ```ts
+ * binary('eq', field(ref(PRINCIPAL), F_USER_ROLE), literal('admin'))
+ * ```
+ *
+ * It is bound only where a server evaluates. A client never sees it.
+ */
+export declare const PRINCIPAL: NodeId;
+/**
+ * The authority of a state. Absent metadata means `client`, so every 0.5.x graph keeps
+ * executing exactly as it did.
+ */
+export declare function stateAuthority(state: StateDef): Authority;
+/** Whether the client may observe this state at all. */
+export declare function isObservable(state: StateDef): boolean;
+export interface AuthorityContext {
+    states: Map<NodeId, StateDef>;
+    actions: Map<NodeId, ActionDef>;
+    constraints: ConstraintDef[];
+    transitionConstraints: TransitionConstraintDef[];
+    principalEntityId?: NodeId;
+}
+export declare function authorityContext(nodes: readonly AnyNode[], principalEntityId?: NodeId): AuthorityContext;
+/** Every state a set of expressions reads, following derived state transitively. */
+export declare function statesReadBy(expressions: readonly Expression[], context: AuthorityContext): Set<NodeId>;
+/** The states an action writes, following `for-each`, `invoke` and declared native effects. */
+export declare function statesWrittenBy(action: ActionDef, context: AuthorityContext, visited?: Set<NodeId>): Set<NodeId>;
+/** The states an action reads: its guards, its values, its selectors, its authorization. */
+export declare function statesReadByAction(action: ActionDef, context: AuthorityContext, visited?: Set<NodeId>): Set<NodeId>;
+/**
+ * Where an action must execute.
+ *
+ * An action that writes any server-authoritative state is a **server action**: only the
+ * authority that owns the state may commit it. This is derived, never declared, so it
+ * cannot disagree with what the action actually does.
+ */
+export declare function actionAuthority(action: ActionDef, context: AuthorityContext): Authority;
+/** Actions the client must send to the authority rather than execute itself. */
+export declare function serverActionIds(context: AuthorityContext): NodeId[];
+/**
+ * Every state a server action needs in order to execute: what it writes, what it reads,
+ * and the derived state either of those depends on.
+ */
+export declare function serverStateClosure(context: AuthorityContext): Set<NodeId>;
+//# sourceMappingURL=authority.d.ts.map

package/dist/authority.js

@@ -0,0 +1,253 @@
+import { referencedIds } from './derive-edges.js';
+import { actionGuards, isMutationOperation } from './nodes.js';
+import { locationExpressions, locationRootStateId } from './location.js';
+export const AUTHORITIES = ['client', 'server'];
+/**
+ * The scope an authorization expression resolves the caller through.
+ *
+ * It is bound to a record keyed by the field ids of the graph's principal entity, so an
+ * authorization rule is written with the same `field`/`ref` vocabulary as everything else:
+ *
+ * ```ts
+ * binary('eq', field(ref(PRINCIPAL), F_USER_ROLE), literal('admin'))
+ * ```
+ *
+ * It is bound only where a server evaluates. A client never sees it.
+ */
+export const PRINCIPAL = 'axiom_principal';
+/**
+ * The authority of a state. Absent metadata means `client`, so every 0.5.x graph keeps
+ * executing exactly as it did.
+ */
+export function stateAuthority(state) {
+    return state.authority === 'server' ? 'server' : 'client';
+}
+/** Whether the client may observe this state at all. */
+export function isObservable(state) {
+    return state.serverOnly !== true;
+}
+export function authorityContext(nodes, principalEntityId) {
+    const states = new Map();
+    const actions = new Map();
+    const constraints = [];
+    const transitionConstraints = [];
+    for (const node of nodes) {
+        switch (node.kind) {
+            case 'state':
+                states.set(node.id, node);
+                break;
+            case 'action':
+                actions.set(node.id, node);
+                break;
+            case 'constraint':
+                constraints.push(node);
+                break;
+            case 'transition-constraint':
+                transitionConstraints.push(node);
+                break;
+            default:
+        }
+    }
+    return {
+        states,
+        actions,
+        constraints,
+        transitionConstraints,
+        ...(principalEntityId ? { principalEntityId } : {}),
+    };
+}
+/** Every state a set of expressions reads, following derived state transitively. */
+export function statesReadBy(expressions, context) {
+    const found = new Set();
+    const seen = new Set();
+    const walk = (expression) => {
+        for (const id of referencedIds(expression)) {
+            const state = context.states.get(id);
+            if (!state || seen.has(id)) {
+                continue;
+            }
+            seen.add(id);
+            found.add(id);
+            if (state.derivation) {
+                walk(state.derivation);
+            }
+        }
+    };
+    expressions.forEach(walk);
+    return found;
+}
+/** Every expression an operation evaluates, including those inside its locations. */
+function operationExpressions(operation) {
+    const found = [];
+    if (isMutationOperation(operation)) {
+        const target = operation.kind === 'remove' ? operation.target : operation.target;
+        found.push(...locationExpressions(target));
+        if (operation.kind !== 'remove') {
+            found.push(operation.value);
+        }
+    }
+    switch (operation.kind) {
+        case 'for-each':
+            found.push(operation.collection);
+            for (const nested of operation.operations ?? []) {
+                found.push(...operationExpressions(nested));
+            }
+            break;
+        case 'invoke':
+            found.push(...Object.values(operation.arguments ?? {}));
+            break;
+        case 'navigate':
+            found.push(...Object.values(operation.parameters ?? {}));
+            break;
+        case 'native':
+            found.push(...Object.values(operation.inputs ?? {}));
+            if (operation.resultTarget) {
+                found.push(...locationExpressions(operation.resultTarget));
+            }
+            break;
+        default:
+    }
+    return found;
+}
+/** The states an action writes, following `for-each`, `invoke` and declared native effects. */
+export function statesWrittenBy(action, context, visited = new Set()) {
+    const found = new Set();
+    if (visited.has(action.id)) {
+        return found;
+    }
+    visited.add(action.id);
+    const walk = (operations) => {
+        for (const operation of operations) {
+            if (isMutationOperation(operation)) {
+                found.add(locationRootStateId(operation.target));
+                continue;
+            }
+            switch (operation.kind) {
+                case 'for-each':
+                    walk(operation.operations ?? []);
+                    break;
+                case 'invoke': {
+                    const target = context.actions.get(operation.actionId);
+                    if (target) {
+                        for (const id of statesWrittenBy(target, context, visited)) {
+                            found.add(id);
+                        }
+                    }
+                    break;
+                }
+                case 'native':
+                    if (operation.resultTarget) {
+                        found.add(locationRootStateId(operation.resultTarget));
+                    }
+                    for (const effect of operation.declaredEffects ?? []) {
+                        if (effect.kind === 'writes-state') {
+                            found.add(effect.stateId);
+                        }
+                    }
+                    break;
+                default:
+            }
+        }
+    };
+    walk(action.operations ?? []);
+    return found;
+}
+/** The states an action reads: its guards, its values, its selectors, its authorization. */
+export function statesReadByAction(action, context, visited = new Set()) {
+    if (visited.has(action.id)) {
+        return new Set();
+    }
+    visited.add(action.id);
+    const expressions = [
+        ...actionGuards(action).map((guard) => guard.condition),
+        ...(action.postconditions ?? []),
+        ...(action.authorization ? [action.authorization] : []),
+    ];
+    for (const operation of action.operations ?? []) {
+        expressions.push(...operationExpressions(operation));
+    }
+    const found = statesReadBy(expressions, context);
+    for (const operation of action.operations ?? []) {
+        if (operation.kind === 'invoke') {
+            const target = context.actions.get(operation.actionId);
+            if (target) {
+                for (const id of statesReadByAction(target, context, visited)) {
+                    found.add(id);
+                }
+            }
+        }
+    }
+    return found;
+}
+/**
+ * Where an action must execute.
+ *
+ * An action that writes any server-authoritative state is a **server action**: only the
+ * authority that owns the state may commit it. This is derived, never declared, so it
+ * cannot disagree with what the action actually does.
+ */
+export function actionAuthority(action, context) {
+    for (const stateId of statesWrittenBy(action, context)) {
+        const state = context.states.get(stateId);
+        if (state && stateAuthority(state) === 'server') {
+            return 'server';
+        }
+    }
+    return 'client';
+}
+/** Actions the client must send to the authority rather than execute itself. */
+export function serverActionIds(context) {
+    return [...context.actions.values()]
+        .filter((action) => actionAuthority(action, context) === 'server')
+        .map((action) => action.id);
+}
+/**
+ * Every state a server action needs in order to execute: what it writes, what it reads,
+ * and the derived state either of those depends on.
+ */
+export function serverStateClosure(context) {
+    const needed = new Set();
+    for (const state of context.states.values()) {
+        if (stateAuthority(state) === 'server') {
+            needed.add(state.id);
+        }
+    }
+    for (const action of context.actions.values()) {
+        if (actionAuthority(action, context) !== 'server') {
+            continue;
+        }
+        for (const id of statesWrittenBy(action, context)) {
+            needed.add(id);
+        }
+        for (const id of statesReadByAction(action, context)) {
+            needed.add(id);
+        }
+    }
+    // Constraints and transition rules that govern what the server commits are evaluated
+    // there, so whatever they read has to be present too.
+    const ruleExpressions = [
+        ...context.constraints.map((constraint) => constraint.expression),
+        ...context.transitionConstraints.map((constraint) => constraint.expression),
+    ];
+    for (const id of statesReadBy(ruleExpressions, context)) {
+        needed.add(id);
+    }
+    // Derived state is only meaningful if what it derives from is present as well.
+    let growing = true;
+    while (growing) {
+        growing = false;
+        for (const id of [...needed]) {
+            const state = context.states.get(id);
+            if (!state?.derivation) {
+                continue;
+            }
+            for (const dependency of statesReadBy([state.derivation], context)) {
+                if (!needed.has(dependency)) {
+                    needed.add(dependency);
+                    growing = true;
+                }
+            }
+        }
+    }
+    return needed;
+}

package/dist/diagnostics.d.ts

@@ -65,5 +65,11 @@ export declare const VALIDATION_CODES: {
     readonly formInputMissingLabel: "FORM_INPUT_MISSING_LABEL";
     readonly invalidHeadingStructure: "INVALID_HEADING_STRUCTURE";
     readonly opaquePresentation: "OPAQUE_PRESENTATION";
+    readonly clientWriteToServerState: "CLIENT_WRITE_TO_SERVER_STATE";
+    readonly serverDependsOnClientState: "SERVER_DEPENDS_ON_CLIENT_STATE";
+    readonly authorizationWithoutPrincipal: "AUTHORIZATION_WITHOUT_PRINCIPAL";
+    readonly principalReferenceOnClient: "PRINCIPAL_REFERENCE_ON_CLIENT";
+    readonly serverOnlyStateObserved: "SERVER_ONLY_STATE_OBSERVED";
+    readonly invalidPrincipalEntity: "INVALID_PRINCIPAL_ENTITY";
 };
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.js

@@ -50,4 +50,12 @@ export const VALIDATION_CODES = {
     formInputMissingLabel: 'FORM_INPUT_MISSING_LABEL',
     invalidHeadingStructure: 'INVALID_HEADING_STRUCTURE',
     opaquePresentation: 'OPAQUE_PRESENTATION',
+    // Authority. A graph that cannot execute safely across the trust boundary is rejected
+    // rather than left to fail at run time.
+    clientWriteToServerState: 'CLIENT_WRITE_TO_SERVER_STATE',
+    serverDependsOnClientState: 'SERVER_DEPENDS_ON_CLIENT_STATE',
+    authorizationWithoutPrincipal: 'AUTHORIZATION_WITHOUT_PRINCIPAL',
+    principalReferenceOnClient: 'PRINCIPAL_REFERENCE_ON_CLIENT',
+    serverOnlyStateObserved: 'SERVER_ONLY_STATE_OBSERVED',
+    invalidPrincipalEntity: 'INVALID_PRINCIPAL_ENTITY',
 };

package/dist/graph.d.ts

@@ -10,9 +10,15 @@ export interface EdgeQuery {
     kinds?: readonly EdgeKind[];
 }
 /**
- * The Application Graph is the canonical representation of an application. Reads return
- * deep clones, so a node retrieved from the graph must be written back with
- * `updateNode` for the change to take effect.
+ * The Application Graph is the canonical representation of an application. Everything else
+ * — the IR, the emitted page, the DOM — is derived from it and is never edited.
+ *
+ * Reads return **deep clones**, so a node retrieved from the graph must be written back
+ * with `updateNode` for the change to take effect.
+ *
+ * Relationships are derived from the current nodes on demand and cached against a revision
+ * counter, so an edge cannot fall out of step with the nodes it describes and no
+ * correctness property depends on resynchronizing anything.
  */
 export declare class ApplicationGraph {
     private data;
@@ -33,6 +39,12 @@ export declare class ApplicationGraph {
     get theme(): Theme;
     /** Exactly what the application declared, before defaults were filled in. */
     get declaredTheme(): ThemeInput | undefined;
+    /**
+     * The entity an authorization expression reads the caller through, bound to `PRINCIPAL`
+     * when the authority evaluates the rule.
+     */
+    get principalEntityId(): NodeId | undefined;
+    setPrincipalEntity(entityId: NodeId | undefined): void;
     setTheme(theme: ThemeInput | undefined): void;
     addNode<T extends AnyNode>(node: NodeInput<T>): NodeId;
     getNode<T extends AnyNode = AnyNode>(id: NodeId): T | undefined;

package/dist/graph.js

@@ -5,9 +5,15 @@ function clone(value) {
     return structuredClone(value);
 }
 /**
- * The Application Graph is the canonical representation of an application. Reads return
- * deep clones, so a node retrieved from the graph must be written back with
- * `updateNode` for the change to take effect.
+ * The Application Graph is the canonical representation of an application. Everything else
+ * — the IR, the emitted page, the DOM — is derived from it and is never edited.
+ *
+ * Reads return **deep clones**, so a node retrieved from the graph must be written back
+ * with `updateNode` for the change to take effect.
+ *
+ * Relationships are derived from the current nodes on demand and cached against a revision
+ * counter, so an edge cannot fall out of step with the nodes it describes and no
+ * correctness property depends on resynchronizing anything.
  */
 export class ApplicationGraph {
     data;
@@ -17,7 +23,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.5.0') {
+    constructor(id, name, version = '0.6.0') {
         this.data = { id, name, version, nodes: {}, edges: {} };
     }
     get id() {
@@ -40,6 +46,22 @@ export class ApplicationGraph {
     get declaredTheme() {
         return this.data.theme ? structuredClone(this.data.theme) : undefined;
     }
+    /**
+     * The entity an authorization expression reads the caller through, bound to `PRINCIPAL`
+     * when the authority evaluates the rule.
+     */
+    get principalEntityId() {
+        return this.data.principalEntityId;
+    }
+    setPrincipalEntity(entityId) {
+        if (entityId === undefined) {
+            delete this.data.principalEntityId;
+        }
+        else {
+            this.data.principalEntityId = entityId;
+        }
+        this.revision += 1;
+    }
     setTheme(theme) {
         if (theme === undefined) {
             delete this.data.theme;

package/dist/index.d.ts

@@ -15,6 +15,10 @@ export * from './validate-location.js';
 export * from './resolve-presentation.js';
 export * from './validate.js';
 export * from './validate-presentation.js';
+export * from './validate-authority.js';
+export * from './validate-value.js';
 export * from './derive-edges.js';
+export * from './authority.js';
 export * from './ir.js';
+export * from './server-ir.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -15,5 +15,9 @@ export * from './validate-location.js';
 export * from './resolve-presentation.js';
 export * from './validate.js';
 export * from './validate-presentation.js';
+export * from './validate-authority.js';
+export * from './validate-value.js';
 export * from './derive-edges.js';
+export * from './authority.js';
 export * from './ir.js';
+export * from './server-ir.js';

package/dist/infer.js

@@ -131,6 +131,15 @@ export function inferExpressionType(expression, context, scope) {
                     return primitiveType('string');
                 case 'now':
                     return primitiveType('datetime');
+                case 'coalesce': {
+                    // The type of the first argument, with its optionality removed: a fallback is
+                    // what makes the value present. Inferring this is what lets a repeat over
+                    // `coalesce(field(...), [])` still know how to identify its members.
+                    const first = expression.arguments[0]
+                        ? inferExpressionType(expression.arguments[0], context, scope)
+                        : undefined;
+                    return first?.kind === 'optional' ? first.valueType : first;
+                }
                 default:
                     return undefined;
             }

package/dist/ir.d.ts

@@ -4,6 +4,7 @@ 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 { Authority } from './authority.js';
 import type { ResolvedPresentation } from './presentation.js';
 import type { Theme } from './theme.js';
 export interface RouteSegment {
@@ -55,6 +56,26 @@ export interface ApplicationIR {
      * renderer can mark it without re-deriving the model.
      */
     locationRequired: Record<NodeId, boolean>;
+    /**
+     * The field that distinguishes the members of each `repeat` node's collection, resolved
+     * here so a runtime carries no type inference of its own.
+     *
+     * A renderer uses it to give every rendered repeat instance a stable identity. A repeat
+     * whose member type cannot be resolved statically is absent from this map, and the
+     * renderer falls back to the iteration index.
+     */
+    repeatIdentityFields: Record<NodeId, FieldId>;
+    /**
+     * The authority of each state. A client runtime refuses to write a state whose authority
+     * is `server`, whatever path attempts it.
+     */
+    authority: Record<NodeId, Authority>;
+    /**
+     * Actions the client must send to the authority rather than execute itself. Their
+     * operations, guards and authorization are **absent** from this IR: a client is never
+     * given the rules it is not trusted to apply.
+     */
+    remoteActionIds: NodeId[];
     /** The application's visual identity, completed against the default theme. */
     theme: Theme;
     /**