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

package/README.md

@@ -6,8 +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.
+
+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
 
@@ -21,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/diagnostics.d.ts

@@ -50,5 +50,20 @@ export declare const VALIDATION_CODES: {
     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

@@ -33,4 +33,21 @@ export const VALIDATION_CODES = {
     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/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;
@@ -9,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;
@@ -25,6 +32,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,12 +1,19 @@
 import { deriveEdges } from './derive-edges.js';
 import { createEdgeId, createNodeId } from './ids.js';
+import { resolveTheme } from './theme.js';
 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;
@@ -16,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.4.1') {
+    constructor(id, name, version = '0.5.2') {
         this.data = { id, name, version, nodes: {}, edges: {} };
     }
     get id() {
@@ -28,6 +35,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

@@ -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,8 @@ 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;
@@ -48,5 +50,30 @@ 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 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 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,21 +2,29 @@ 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;
     metadata?: Record<string, unknown>;
 }
+/**
+ * A field of an entity.
+ *
+ * Fields are independently identifiable and globally unique across the graph, and
+ * **instance data is keyed by `FieldId`, never by `name`**: a record looks like
+ * `{ [F_TITLE]: 'Dune' }`, not `{ title: 'Dune' }`. `name` is metadata for humans and
+ * resolves nothing.
+ */
 export interface FieldDef {
     id: FieldId;
     name?: string;
     valueType: TypeRef;
+    /**
+     * The value must be **present** in every canonical instance — not `null` and not
+     * `undefined`. It says nothing about emptiness: `0`, `false`, `''` and `[]` all satisfy
+     * it. Express "must not be blank" as a `ConstraintDef` using `non-empty`.
+     */
     required?: boolean;
     defaultValue?: LiteralValue;
     metadata?: Record<string, unknown>;
@@ -24,10 +32,21 @@ export interface FieldDef {
 export type LiteralValue = string | number | boolean | null | LiteralValue[] | {
     [key: string]: LiteralValue;
 };
+/**
+ * A record type. Instances of it are found wherever a state's declared type says they
+ * live — including nested inside collections and inside other entities — and are validated
+ * there.
+ */
 export interface EntityDef extends NodeBase {
     kind: 'entity';
     fields: FieldDef[];
-    /** Field used to distinguish instances of this entity. */
+    /**
+     * Field used to distinguish instances of this entity.
+     *
+     * Required in order to address an instance by identity (`identitySelector`), and
+     * required by every `TransitionConstraintDef` on this entity — without it such a rule is
+     * **silently skipped**. Declare it on every entity stored in a collection.
+     */
     identityFieldId?: FieldId;
 }
 export type StatePersistence = {
@@ -39,17 +58,50 @@ export type StatePersistence = {
     kind: 'remote';
     sourceId: NodeId;
 };
+/**
+ * A named application value: stored, or computed from other state.
+ *
+ * A state with no `derivation` is stored, and one that is neither `draft` nor `ephemeral`
+ * is **canonical** — the state entity constraints and schema conformance apply to. Stored
+ * values are deeply frozen on entry to the store, and every read hands out a copy.
+ */
 export interface StateDef extends NodeBase {
     kind: 'state';
     valueType: TypeRef;
+    /**
+     * Seed data, keyed by `FieldId` wherever it contains a record. It is walked against
+     * `valueType` recursively at validation time, so data keyed by field *name* is rejected
+     * rather than surfacing later as an inexplicably empty UI.
+     *
+     * Absent, the state starts at the default for its type: `optional` → `null`,
+     * `collection` → `[]`, `number` → `0`, `boolean` → `false`, other primitive → `''`,
+     * `enum` → its first value, `entity` → `null`.
+     */
     initialValue?: LiteralValue;
-    /** When present the state is computed rather than stored. */
+    /**
+     * When present the state is computed rather than stored.
+     *
+     * Derived state is **read-only**: a write is rejected by `validateGraph` and by the
+     * runtime. It is recomputed on demand and handed out as a frozen deep copy, so nothing
+     * can work by sharing an object with the state it was derived from. Instance validation
+     * skips it, because the data is already validated where it is stored.
+     */
     derivation?: Expression;
     /**
      * Marks a state that holds work in progress. Draft instances are incomplete by
      * 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 {
@@ -67,6 +119,18 @@ export interface ActionGuard {
     condition: Expression;
     failureMode?: FailureMode;
 }
+/**
+ * Behaviour expressed as data, executed as a transaction.
+ *
+ * An invocation proceeds: resolve the action, bind parameters, evaluate preconditions in
+ * order, ask for confirmation if required — **none of which opens a transaction, so a
+ * refusal at any of those stages mutates nothing** — then begin a transaction, run the
+ * operations sequentially against provisional state, evaluate entity constraints,
+ * transition constraints and postconditions, and either commit everything or roll back
+ * every mutation.
+ *
+ * `invokeAction` returns the diagnostics of that invocation.
+ */
 export interface ActionDef extends NodeBase {
     kind: 'action';
     parameters?: ActionParameter[];
@@ -80,6 +144,8 @@ 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
@@ -92,30 +158,53 @@ export type OperationKind = Operation['kind'];
 export declare const OPERATION_KINDS: readonly OperationKind[];
 /** Every mutation is a set, an insert or a remove against an addressed Location. */
 export type MutationOperation = SetOperation | InsertOperation | RemoveOperation;
+/**
+ * Writes a value to an addressed position.
+ *
+ * A missing field along the path is created. A missing **collection item** is not: an
+ * identity selector that matches nothing reports `LOCATION_RESOLUTION_FAILED`.
+ */
 export interface SetOperation {
     kind: 'set';
     target: Location;
     value: Expression;
 }
+/**
+ * Adds a member to a collection. The constructed value is deep-cloned before it is stored.
+ *
+ * A newly inserted entity instance has no previous state, so **no transition constraint is
+ * evaluated for it**. Govern creation with an action guard or an entity constraint.
+ */
 export interface InsertOperation {
     kind: 'insert';
-    /** A location addressing a collection. */
+    /** A location addressing a collection. A non-array current value is treated as `[]`. */
     target: Location;
     value: Expression;
+    /** Defaults to `'end'`. */
     position?: 'start' | 'end';
 }
+/**
+ * Removes one member of a collection.
+ *
+ * A selector that matches nothing is a **no-op**: no mutation, no log entry and no
+ * diagnostic. Removing an existing instance *is* a transition, with the proposed value
+ * bound to nothing.
+ */
 export interface RemoveOperation {
     kind: 'remove';
     target: CollectionItemLocation;
 }
 /**
- * Performs a set of mutations once per member of a collection. The iteration is not a
- * transaction of its own: it runs inside the action's transaction, so a failure in any
- * iteration rolls the whole action back.
+ * Performs a set of mutations once per member of a collection.
+ *
+ * Iteration N observes provisional writes from previous iterations. The loop executes
+ * inside the containing action's transaction and opens none of its own, so any failure
+ * rolls back the complete action — every iteration included. The collection itself is
+ * evaluated **once**, before the first member is mutated.
  *
  * `scopeId` introduces an iteration scope. Nested expressions refer to the current member
  * as `ref(scopeId)`, and nested locations may use it to address the canonical record the
- * member points at.
+ * member points at. Nested operations must be mutations only.
  */
 export interface ForEachOperation {
     kind: 'for-each';
@@ -163,11 +252,22 @@ export interface NativeOperation {
     resultTarget?: Location;
     declaredEffects?: NativeEffect[];
 }
+/**
+ * An invariant over proposed state, evaluated after every governed mutation.
+ *
+ * A constraint that cannot be evaluated counts as **violated**, never as satisfied.
+ */
 export interface ConstraintDef extends NodeBase {
     kind: 'constraint';
     expression: Expression;
-    /** When set, the expression is evaluated once per instance of this entity. */
+    /**
+     * When set, the expression is evaluated once per canonical instance of this entity, with
+     * the instance bound to `ref(entityId)` — wherever that instance is stored, including
+     * nested inside another entity. Without it the expression is evaluated once, in the root
+     * scope.
+     */
     entityId?: NodeId;
+    /** Defaults to `'error'`. A `'warning'` is advice and **never blocks a write**. */
     severity?: 'error' | 'warning';
     message?: string;
 }
@@ -182,6 +282,13 @@ export interface ConstraintDef extends NodeBase {
  *
  * `previousScopeId` and `proposedScopeId` bind those two instances for the expression.
  * When the instance is being removed, the proposed scope is bound to nothing.
+ *
+ * "Previous" means committed state as it stood immediately before the **outermost**
+ * transaction began — not the previous operation, and not the previous iteration.
+ *
+ * A **newly inserted** instance has no previous state and is therefore **not evaluated**.
+ * Govern creation with an action guard or an entity constraint. The entity must declare
+ * `identityFieldId`; without one this rule is silently skipped.
  */
 export interface TransitionConstraintDef extends NodeBase {
     kind: 'transition-constraint';