@cynodia/axiom-core 0.3.1-alpha.1

package/dist/nodes.d.ts

@@ -0,0 +1,164 @@
+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';
+}
+export interface NodeBase {
+    id: NodeId;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface FieldDef {
+    id: FieldId;
+    name?: string;
+    valueType: TypeRef;
+    required?: boolean;
+    defaultValue?: LiteralValue;
+    metadata?: Record<string, unknown>;
+}
+export type LiteralValue = string | number | boolean | null | LiteralValue[] | {
+    [key: string]: LiteralValue;
+};
+export interface EntityDef extends NodeBase {
+    kind: 'entity';
+    fields: FieldDef[];
+    /** Field used to distinguish instances of this entity. */
+    identityFieldId?: FieldId;
+}
+export type StatePersistence = {
+    kind: 'memory';
+} | {
+    kind: 'local-storage';
+    key?: string;
+} | {
+    kind: 'remote';
+    sourceId: NodeId;
+};
+export interface StateDef extends NodeBase {
+    kind: 'state';
+    valueType: TypeRef;
+    initialValue?: LiteralValue;
+    /** When present the state is computed rather than 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;
+    persistence?: StatePersistence;
+}
+export interface ActionParameter {
+    id: NodeId;
+    name?: string;
+    valueType?: TypeRef;
+    required?: boolean;
+}
+export interface FailureMode {
+    code: string;
+    message?: string;
+}
+export interface ActionDef extends NodeBase {
+    kind: 'action';
+    parameters?: ActionParameter[];
+    preconditions?: Expression[];
+    operations: Operation[];
+    postconditions?: Expression[];
+    failureModes?: FailureMode[];
+    /** Declared destructive intent. Semantics may also be inferred from operations. */
+    destructive?: boolean;
+    requiresConfirmation?: boolean;
+    confirmationMessage?: string;
+}
+export type Operation = SetOperation | InsertOperation | RemoveOperation | InvokeOperation | NavigateOperation | NativeOperation;
+/** Every mutation is a set, an insert or a remove against an addressed Location. */
+export type MutationOperation = SetOperation | InsertOperation | RemoveOperation;
+export interface SetOperation {
+    kind: 'set';
+    target: Location;
+    value: Expression;
+}
+export interface InsertOperation {
+    kind: 'insert';
+    /** A location addressing a collection. */
+    target: Location;
+    value: Expression;
+    position?: 'start' | 'end';
+}
+export interface RemoveOperation {
+    kind: 'remove';
+    target: CollectionItemLocation;
+}
+export declare function isMutationOperation(operation: Operation): operation is MutationOperation;
+export interface InvokeOperation {
+    kind: 'invoke';
+    actionId: NodeId;
+    arguments?: Record<string, Expression>;
+}
+export interface NavigateOperation {
+    kind: 'navigate';
+    routeId?: NodeId;
+    path?: string;
+    /** Keyed by route parameter id. */
+    parameters?: Record<string, Expression>;
+}
+export type NativeEffect = {
+    kind: 'reads-state';
+    stateId: NodeId;
+} | {
+    kind: 'writes-state';
+    stateId: NodeId;
+} | {
+    kind: 'external';
+    description: string;
+};
+/**
+ * Controlled boundary for behaviour the operation vocabulary cannot express. The graph
+ * declares an implementation id and its effects; the implementation itself is registered
+ * with the runtime and is never embedded in the graph as source text.
+ */
+export interface NativeOperation {
+    kind: 'native';
+    implementationId: string;
+    inputs?: Record<string, Expression>;
+    /**
+     * Where the implementation's return value is stored. Native code never writes Axiom
+     * state itself; it returns a value that the mutation engine then sets.
+     */
+    resultTarget?: Location;
+    declaredEffects?: NativeEffect[];
+}
+export interface ConstraintDef extends NodeBase {
+    kind: 'constraint';
+    expression: Expression;
+    /** When set, the expression is evaluated once per instance of this entity. */
+    entityId?: NodeId;
+    severity?: 'error' | 'warning';
+    message?: string;
+}
+export interface RouteParameter {
+    id: NodeId;
+    /** Matches the `:name` placeholder in the route path. */
+    name: string;
+    valueType?: TypeRef;
+}
+export interface RouteDef extends NodeBase {
+    kind: 'route';
+    path: string;
+    viewId: NodeId;
+    parameters?: RouteParameter[];
+}
+export type EdgeKind = 'contains' | 'reads' | 'writes' | 'invokes' | 'renders' | 'binds' | 'depends-on' | 'derives-from' | 'constrains' | 'routes-to' | 'references';
+export declare const EDGE_KINDS: readonly EdgeKind[];
+export interface GraphEdge {
+    id: EdgeId;
+    from: NodeId;
+    to: NodeId;
+    kind: EdgeKind;
+    metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=nodes.d.ts.map

package/dist/nodes.js

@@ -0,0 +1,16 @@
+export function isMutationOperation(operation) {
+    return operation.kind === 'set' || operation.kind === 'insert' || operation.kind === 'remove';
+}
+export const EDGE_KINDS = [
+    'contains',
+    'reads',
+    'writes',
+    'invokes',
+    'renders',
+    'binds',
+    'depends-on',
+    'derives-from',
+    'constrains',
+    'routes-to',
+    'references',
+];

package/dist/type-ref.d.ts

@@ -0,0 +1,35 @@
+import type { NodeId } from './ids.js';
+/**
+ * Structured type references. Types are never encoded as strings such as
+ * "Collection<X>" — every type is a walkable structure.
+ */
+export type TypeRef = PrimitiveTypeRef | EntityTypeRef | CollectionTypeRef | OptionalTypeRef | EnumTypeRef;
+export type PrimitiveKind = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'binary';
+export interface PrimitiveTypeRef {
+    kind: 'primitive';
+    primitive: PrimitiveKind;
+}
+export interface EntityTypeRef {
+    kind: 'entity';
+    entityId: NodeId;
+}
+export interface CollectionTypeRef {
+    kind: 'collection';
+    itemType: TypeRef;
+}
+export interface OptionalTypeRef {
+    kind: 'optional';
+    valueType: TypeRef;
+}
+export interface EnumTypeRef {
+    kind: 'enum';
+    values: string[];
+}
+export declare function primitiveType(primitive: PrimitiveKind): PrimitiveTypeRef;
+export declare function entityType(entityId: NodeId): EntityTypeRef;
+export declare function collectionType(itemType: TypeRef): CollectionTypeRef;
+export declare function optionalType(valueType: TypeRef): OptionalTypeRef;
+export declare function enumType(values: string[]): EnumTypeRef;
+/** Removes an `optional` wrapper, if present. */
+export declare function unwrapOptional(type: TypeRef): TypeRef;
+//# sourceMappingURL=type-ref.d.ts.map

package/dist/type-ref.js

@@ -0,0 +1,19 @@
+export function primitiveType(primitive) {
+    return { kind: 'primitive', primitive };
+}
+export function entityType(entityId) {
+    return { kind: 'entity', entityId };
+}
+export function collectionType(itemType) {
+    return { kind: 'collection', itemType };
+}
+export function optionalType(valueType) {
+    return { kind: 'optional', valueType };
+}
+export function enumType(values) {
+    return { kind: 'enum', values };
+}
+/** Removes an `optional` wrapper, if present. */
+export function unwrapOptional(type) {
+    return type.kind === 'optional' ? unwrapOptional(type.valueType) : type;
+}

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+import type { ActionDef, ConstraintDef, EntityDef, GraphEdge, RouteDef, StateDef } from './nodes.js';
+import type { NodeId } from './ids.js';
+import type { UINode, UINodeKind } from './ui.js';
+export type SemanticNodeKind = 'entity' | 'state' | 'action' | 'constraint' | 'route';
+export type NodeKind = SemanticNodeKind | UINodeKind;
+export type AnyNode = EntityDef | StateDef | ActionDef | ConstraintDef | RouteDef | UINode;
+export type NodeOfKind<K extends NodeKind> = Extract<AnyNode, {
+    kind: K;
+}>;
+/** A node as supplied by a caller: the id may be omitted and will be generated. */
+export type NodeInput<T extends AnyNode = AnyNode> = T extends AnyNode ? Omit<T, 'id'> & {
+    id?: NodeId;
+} : never;
+export interface ApplicationGraphData {
+    id: string;
+    name: string;
+    version: string;
+    nodes: Record<NodeId, AnyNode>;
+    edges: Record<string, GraphEdge>;
+    metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ui.d.ts

@@ -0,0 +1,101 @@
+import type { Expression } from './expressions.js';
+import type { FieldId, NodeId } from './ids.js';
+import type { Location } from './location.js';
+import type { PresentationHints } from './nodes.js';
+export type UINodeKind = 'view' | 'container' | 'text' | 'repeat' | 'field-display' | 'form' | 'input' | 'button' | 'conditional';
+export declare const UI_NODE_KINDS: readonly UINodeKind[];
+export interface UIBase {
+    id: NodeId;
+    kind: UINodeKind;
+    name?: string;
+    visibleWhen?: Expression;
+    presentation?: PresentationHints;
+    metadata?: Record<string, unknown>;
+}
+/** A routable or independently renderable UI root. */
+export interface ViewNode extends UIBase {
+    kind: 'view';
+    children: NodeId[];
+}
+export interface ContainerNode extends UIBase {
+    kind: 'container';
+    layout?: 'vertical' | 'horizontal' | 'stack';
+    children: NodeId[];
+}
+export interface TextNode extends UIBase {
+    kind: 'text';
+    value: string | Expression;
+}
+/**
+ * Repeats `templateId` over `source`. The current item is bound to this node's own id,
+ * so templates reference it with `{ kind: 'ref', targetId: <repeat node id> }`.
+ */
+export interface RepeatNode extends UIBase {
+    kind: 'repeat';
+    source: Expression;
+    itemAlias?: string;
+    templateId: NodeId;
+    emptyTemplateId?: NodeId;
+}
+export interface FieldDisplayNode extends UIBase {
+    kind: 'field-display';
+    source: Expression;
+    fieldId: FieldId;
+    label?: string;
+}
+export interface FormNode extends UIBase {
+    kind: 'form';
+    target: Expression;
+    children: NodeId[];
+    submitActionId?: NodeId;
+    submitLabel?: string;
+}
+/**
+ * An input writes to an addressed Location, never to whatever object an expression
+ * happened to evaluate to.
+ */
+export interface InputBinding {
+    location: Location;
+}
+export type InputHint = 'text' | 'email' | 'number' | 'password' | 'date' | 'checkbox' | 'multiline' | 'select';
+/**
+ * Offers a choice drawn from application data rather than a fixed enum, which is how a
+ * value that identifies another record is entered. Each candidate is bound to `scopeId`
+ * while `valueFieldId` and `labelFieldId` are read.
+ */
+export interface InputOptionsSource {
+    source: Expression;
+    scopeId: NodeId;
+    valueFieldId: FieldId;
+    labelFieldId?: FieldId;
+}
+export interface InputNode extends UIBase {
+    kind: 'input';
+    binding: InputBinding;
+    /** Presentation hint only; the runtime infers a control from the field type otherwise. */
+    inputHint?: InputHint;
+    options?: InputOptionsSource;
+    label?: string;
+    placeholder?: string;
+}
+export interface ButtonNode extends UIBase {
+    kind: 'button';
+    label: string | Expression;
+    actionId: NodeId;
+    /** Keyed by action parameter id. */
+    arguments?: Record<string, Expression>;
+    destructive?: boolean;
+}
+export interface ConditionalNode extends UIBase {
+    kind: 'conditional';
+    condition: Expression;
+    whenTrue: NodeId[];
+    whenFalse?: NodeId[];
+}
+export type UINode = ViewNode | ContainerNode | TextNode | RepeatNode | FieldDisplayNode | FormNode | InputNode | ButtonNode | ConditionalNode;
+export declare function isUINode(node: {
+    kind: string;
+}): node is UINode;
+/** Child ids declared by a UI node, in render order. */
+export declare function uiChildIds(node: UINode): NodeId[];
+//# sourceMappingURL=ui.d.ts.map

package/dist/ui.js

@@ -0,0 +1,29 @@
+export const UI_NODE_KINDS = [
+    'view',
+    'container',
+    'text',
+    'repeat',
+    'field-display',
+    'form',
+    'input',
+    'button',
+    'conditional',
+];
+export function isUINode(node) {
+    return UI_NODE_KINDS.includes(node.kind);
+}
+/** Child ids declared by a UI node, in render order. */
+export function uiChildIds(node) {
+    switch (node.kind) {
+        case 'view':
+        case 'container':
+        case 'form':
+            return [...node.children];
+        case 'repeat':
+            return node.emptyTemplateId ? [node.templateId, node.emptyTemplateId] : [node.templateId];
+        case 'conditional':
+            return [...node.whenTrue, ...(node.whenFalse ?? [])];
+        default:
+            return [];
+    }
+}

package/dist/validate-location.d.ts

@@ -0,0 +1,16 @@
+import type { ValidationIssue } from './diagnostics.js';
+import type { NodeId } from './ids.js';
+import type { SemanticContext } from './infer.js';
+import type { Location } from './location.js';
+export interface LocationValidationOptions {
+    /** Node the location belongs to, for diagnostics. */
+    ownerId?: NodeId;
+    /** Whether the location will be written to. Read-only uses skip writability checks. */
+    requireWritable?: boolean;
+}
+/**
+ * Structural validation of a location: does every state, field and selector it names
+ * exist, do they fit together, and may it be written to?
+ */
+export declare function validateLocation(location: Location, context: SemanticContext, options?: LocationValidationOptions): ValidationIssue[];
+//# sourceMappingURL=validate-location.d.ts.map

package/dist/validate-location.js

@@ -0,0 +1,78 @@
+import { VALIDATION_CODES } from './diagnostics.js';
+import { inferLocationType, locationCapabilities } from './infer.js';
+import { locationRootStateId } from './location.js';
+/**
+ * Structural validation of a location: does every state, field and selector it names
+ * exist, do they fit together, and may it be written to?
+ */
+export function validateLocation(location, context, options = {}) {
+    const problems = [];
+    const ownerId = options.ownerId;
+    const report = (code, message, extra = {}) => {
+        problems.push({ code, message, ...(ownerId ? { nodeId: ownerId } : {}), ...extra });
+    };
+    walk(location, context, report);
+    if (problems.length === 0 && options.requireWritable) {
+        const capabilities = locationCapabilities(location, context);
+        if (!capabilities.writable) {
+            report(VALIDATION_CODES.derivedStateWrite, `${locationRootStateId(location)} is derived state and cannot be written to; address the state the value is stored in instead`);
+        }
+    }
+    return problems;
+}
+function walk(location, context, report) {
+    switch (location.kind) {
+        case 'state': {
+            if (!context.getState(location.stateId)) {
+                report(VALIDATION_CODES.unknownStateRef, `Location references unknown state ${location.stateId}`);
+            }
+            return;
+        }
+        case 'field': {
+            walk(location.target, context, report);
+            const entry = context.getField(location.fieldId);
+            if (!entry) {
+                report(VALIDATION_CODES.danglingFieldRef, `Location references unknown field ${location.fieldId}`, { fieldId: location.fieldId });
+                return;
+            }
+            const parent = inferLocationType(location.target, context);
+            const resolved = parent?.kind === 'optional' ? parent.valueType : parent;
+            if (!resolved) {
+                return;
+            }
+            if (resolved.kind !== 'entity') {
+                report(VALIDATION_CODES.fieldOnNonEntity, `Field ${location.fieldId} was selected on a ${resolved.kind} value, which has no fields`, { fieldId: location.fieldId });
+                return;
+            }
+            if (entry.entityId !== resolved.entityId) {
+                report(VALIDATION_CODES.fieldNotOnEntity, `Field ${location.fieldId} belongs to ${entry.entityId}, not to ${resolved.entityId}`, { fieldId: location.fieldId });
+            }
+            return;
+        }
+        case 'collection-item': {
+            walk(location.collection, context, report);
+            const parent = inferLocationType(location.collection, context);
+            const resolved = parent?.kind === 'optional' ? parent.valueType : parent;
+            if (resolved && resolved.kind !== 'collection') {
+                report(VALIDATION_CODES.selectorOnNonCollection, `An item selector was applied to a ${resolved.kind} value`);
+                return;
+            }
+            if (location.selector.kind !== 'identity') {
+                return;
+            }
+            const entry = context.getField(location.selector.fieldId);
+            if (!entry) {
+                report(VALIDATION_CODES.danglingFieldRef, `Item selector references unknown field ${location.selector.fieldId}`, { fieldId: location.selector.fieldId });
+                return;
+            }
+            const item = resolved?.kind === 'collection' ? resolved.itemType : undefined;
+            const itemType = item?.kind === 'optional' ? item.valueType : item;
+            if (itemType?.kind === 'entity' && entry.entityId !== itemType.entityId) {
+                report(VALIDATION_CODES.identityFieldMismatch, `Item selector uses field ${location.selector.fieldId} of ${entry.entityId}, but the collection holds ${itemType.entityId}`, { fieldId: location.selector.fieldId });
+            }
+            return;
+        }
+        default:
+            report(VALIDATION_CODES.unknownStateRef, `Unknown location kind "${location.kind}"`);
+    }
+}

package/dist/validate.d.ts

@@ -0,0 +1,9 @@
+import type { ValidationResult } from './diagnostics.js';
+import type { ApplicationGraph } from './graph.js';
+/**
+ * Verifies referential integrity of an application graph. An invalid graph must never
+ * be executed, so every reference — nodes, fields, edges, expressions, UI children —
+ * is resolved here.
+ */
+export declare function validateGraph(graph: ApplicationGraph): ValidationResult;
+//# sourceMappingURL=validate.d.ts.map