@cynodia/axiom-core 0.3.1-alpha.1

package/dist/graph.js

@@ -0,0 +1,176 @@
+import { createEdgeId, createNodeId } from './ids.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.
+ */
+export class ApplicationGraph {
+    data;
+    outgoing = new Map();
+    incoming = new Map();
+    fieldIndex = new Map();
+    constructor(id, name, version = '0.3.0') {
+        this.data = { id, name, version, nodes: {}, edges: {} };
+    }
+    get id() {
+        return this.data.id;
+    }
+    get name() {
+        return this.data.name;
+    }
+    get version() {
+        return this.data.version;
+    }
+    addNode(node) {
+        const id = (node.id ?? createNodeId(node.kind));
+        if (this.data.nodes[id]) {
+            throw new Error(`Node ${id} already exists`);
+        }
+        this.data.nodes[id] = clone({ ...node, id });
+        this.indexNodeFields(this.data.nodes[id]);
+        return id;
+    }
+    getNode(id) {
+        const node = this.data.nodes[id];
+        return node ? clone(node) : undefined;
+    }
+    hasNode(id) {
+        return Boolean(this.data.nodes[id]);
+    }
+    updateNode(node) {
+        if (!this.data.nodes[node.id]) {
+            throw new Error(`Node ${node.id} does not exist`);
+        }
+        this.data.nodes[node.id] = clone(node);
+        this.rebuildFieldIndex();
+    }
+    removeNode(id) {
+        if (!this.data.nodes[id]) {
+            return false;
+        }
+        delete this.data.nodes[id];
+        for (const [edgeKey, edge] of Object.entries(this.data.edges)) {
+            if (edge.from === id || edge.to === id) {
+                delete this.data.edges[edgeKey];
+            }
+        }
+        this.rebuildIndexes();
+        return true;
+    }
+    getNodesByKind(kind) {
+        return Object.values(this.data.nodes)
+            .filter((node) => node.kind === kind)
+            .map((node) => clone(node));
+    }
+    listNodes() {
+        return Object.values(this.data.nodes).map((node) => clone(node));
+    }
+    /** Resolves a field id to its owning entity. Fields are globally identifiable. */
+    getField(id) {
+        const location = this.fieldIndex.get(id);
+        return location ? clone(location) : undefined;
+    }
+    listFields() {
+        return [...this.fieldIndex.values()].map((location) => clone(location));
+    }
+    addEdge(from, to, kind, options = {}) {
+        if (!this.data.nodes[from]) {
+            throw new Error(`Cannot add edge from missing node ${from}`);
+        }
+        if (!this.data.nodes[to]) {
+            throw new Error(`Cannot add edge to missing node ${to}`);
+        }
+        const existing = Object.values(this.data.edges).find((edge) => edge.from === from && edge.to === to && edge.kind === kind);
+        if (existing) {
+            return existing.id;
+        }
+        const id = options.id ?? createEdgeId();
+        const edge = { id, from, to, kind, ...(options.metadata ? { metadata: options.metadata } : {}) };
+        this.data.edges[id] = edge;
+        this.indexEdge(edge);
+        return id;
+    }
+    removeEdge(id) {
+        if (!this.data.edges[id]) {
+            return false;
+        }
+        delete this.data.edges[id];
+        this.rebuildEdgeIndexes();
+        return true;
+    }
+    getEdge(id) {
+        const edge = this.data.edges[id];
+        return edge ? clone(edge) : undefined;
+    }
+    listEdges() {
+        return Object.values(this.data.edges).map((edge) => clone(edge));
+    }
+    getEdges(nodeId, query = {}) {
+        return [...this.getOutgoingEdges(nodeId, query), ...this.getIncomingEdges(nodeId, query)];
+    }
+    getOutgoingEdges(nodeId, query = {}) {
+        return filterEdges(this.outgoing.get(nodeId) ?? [], query).map((edge) => clone(edge));
+    }
+    getIncomingEdges(nodeId, query = {}) {
+        return filterEdges(this.incoming.get(nodeId) ?? [], query).map((edge) => clone(edge));
+    }
+    toJSON() {
+        return clone(this.data);
+    }
+    serialize() {
+        return JSON.stringify(this.data, null, 2);
+    }
+    restore(input) {
+        this.data = typeof input === 'string' ? JSON.parse(input) : clone(input);
+        this.rebuildIndexes();
+    }
+    static deserialize(input) {
+        const data = typeof input === 'string' ? JSON.parse(input) : clone(input);
+        const graph = new ApplicationGraph(data.id, data.name, data.version);
+        graph.restore(data);
+        return graph;
+    }
+    indexEdge(edge) {
+        const outgoing = this.outgoing.get(edge.from) ?? [];
+        outgoing.push(edge);
+        this.outgoing.set(edge.from, outgoing);
+        const incoming = this.incoming.get(edge.to) ?? [];
+        incoming.push(edge);
+        this.incoming.set(edge.to, incoming);
+    }
+    indexNodeFields(node) {
+        if (node.kind !== 'entity') {
+            return;
+        }
+        for (const field of node.fields) {
+            this.fieldIndex.set(field.id, { entityId: node.id, field });
+        }
+    }
+    rebuildFieldIndex() {
+        this.fieldIndex.clear();
+        for (const node of Object.values(this.data.nodes)) {
+            this.indexNodeFields(node);
+        }
+    }
+    rebuildEdgeIndexes() {
+        this.outgoing.clear();
+        this.incoming.clear();
+        for (const edge of Object.values(this.data.edges)) {
+            this.indexEdge(edge);
+        }
+    }
+    rebuildIndexes() {
+        this.rebuildEdgeIndexes();
+        this.rebuildFieldIndex();
+    }
+}
+function filterEdges(edges, query) {
+    if (!query.kinds) {
+        return edges;
+    }
+    const kinds = new Set(query.kinds);
+    return edges.filter((edge) => kinds.has(edge.kind));
+}

package/dist/ids.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Semantic identifiers are branded so that node, field and edge references cannot be
+ * mixed accidentally. The brands are erased at runtime; JSON round-trips are plain
+ * strings and must be re-branded through the helpers below.
+ */
+export type NodeId = string & {
+    readonly __brand: 'NodeId';
+};
+export type FieldId = string & {
+    readonly __brand: 'FieldId';
+};
+export type EdgeId = string & {
+    readonly __brand: 'EdgeId';
+};
+export declare function randomHex(bytes?: number): string;
+export declare function nodeId(value: string): NodeId;
+export declare function fieldId(value: string): FieldId;
+export declare function edgeId(value: string): EdgeId;
+export declare function createNodeId(prefix?: string): NodeId;
+export declare function createFieldId(prefix?: string): FieldId;
+export declare function createEdgeId(prefix?: string): EdgeId;
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.js

@@ -0,0 +1,22 @@
+import { randomBytes } from 'node:crypto';
+export function randomHex(bytes = 4) {
+    return randomBytes(bytes).toString('hex');
+}
+export function nodeId(value) {
+    return value;
+}
+export function fieldId(value) {
+    return value;
+}
+export function edgeId(value) {
+    return value;
+}
+export function createNodeId(prefix = 'node') {
+    return `${prefix}_${randomHex(6)}`;
+}
+export function createFieldId(prefix = 'field') {
+    return `${prefix}_${randomHex(6)}`;
+}
+export function createEdgeId(prefix = 'edge') {
+    return `${prefix}_${randomHex(6)}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export * from './ids.js';
+export * from './diagnostics.js';
+export * from './location.js';
+export * from './type-ref.js';
+export * from './expressions.js';
+export * from './nodes.js';
+export * from './ui.js';
+export * from './types.js';
+export * from './graph.js';
+export * from './infer.js';
+export * from './context.js';
+export * from './validate-location.js';
+export * from './validate.js';
+export * from './derive-edges.js';
+export * from './ir.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,15 @@
+export * from './ids.js';
+export * from './diagnostics.js';
+export * from './location.js';
+export * from './type-ref.js';
+export * from './expressions.js';
+export * from './nodes.js';
+export * from './ui.js';
+export * from './types.js';
+export * from './graph.js';
+export * from './infer.js';
+export * from './context.js';
+export * from './validate-location.js';
+export * from './validate.js';
+export * from './derive-edges.js';
+export * from './ir.js';

package/dist/infer.d.ts

@@ -0,0 +1,41 @@
+import type { Expression } from './expressions.js';
+import type { FieldId, NodeId } from './ids.js';
+import type { EntityDef, StateDef } from './nodes.js';
+import type { FieldIndexEntry } from './graph.js';
+import type { Location } from './location.js';
+import type { TypeRef } from './type-ref.js';
+/**
+ * The lookups static analysis needs. Both an authoring graph and a compiled IR can
+ * provide them, so validation and the runtime reason about locations the same way.
+ */
+export interface SemanticContext {
+    getState(id: NodeId): StateDef | undefined;
+    getEntity(id: NodeId): EntityDef | undefined;
+    getField(id: FieldId): FieldIndexEntry | undefined;
+    /** Type of an action or route parameter, where declared. */
+    getParameterType?(id: NodeId): TypeRef | undefined;
+    /** Name of any node, for human-readable rendering only. */
+    getName?(id: NodeId): string | undefined;
+}
+export interface LocationCapabilities {
+    readable: boolean;
+    writable: boolean;
+}
+/** The type of the value a location addresses, where it can be determined statically. */
+export declare function inferLocationType(location: Location, context: SemanticContext): TypeRef | undefined;
+/** Derived state is readable but never writable; everything else follows its root. */
+export declare function locationCapabilities(location: Location, context: SemanticContext): LocationCapabilities;
+/**
+ * A best-effort type for an expression. Returns undefined wherever the type depends on
+ * an iteration scope or another value only known at run time — 0.3 deliberately stops
+ * short of a complete static type checker.
+ */
+export declare function inferExpressionType(expression: Expression, context: SemanticContext): TypeRef | undefined;
+/**
+ * True when a value of `value` type clearly cannot be stored at a `target` type. Unknown
+ * types are never reported: this rejects obvious mistakes, not everything questionable.
+ */
+export declare function isObviouslyIncompatible(target: TypeRef | undefined, value: TypeRef | undefined): boolean;
+/** Renders a location for people. The stored representation stays id-based. */
+export declare function formatLocation(location: Location, context: SemanticContext): string;
+//# sourceMappingURL=infer.d.ts.map

package/dist/infer.js

@@ -0,0 +1,186 @@
+import { entityType, optionalType, primitiveType } from './type-ref.js';
+function unwrap(type) {
+    return type?.kind === 'optional' ? unwrap(type.valueType) : type;
+}
+/** The type of the value a location addresses, where it can be determined statically. */
+export function inferLocationType(location, context) {
+    switch (location.kind) {
+        case 'state':
+            return context.getState(location.stateId)?.valueType;
+        case 'field': {
+            const parent = unwrap(inferLocationType(location.target, context));
+            if (parent?.kind === 'entity') {
+                const entity = context.getEntity(parent.entityId);
+                const field = entity?.fields.find((candidate) => candidate.id === location.fieldId);
+                if (field) {
+                    return field.valueType;
+                }
+                return undefined;
+            }
+            return parent === undefined ? context.getField(location.fieldId)?.field.valueType : undefined;
+        }
+        case 'collection-item': {
+            const parent = unwrap(inferLocationType(location.collection, context));
+            return parent?.kind === 'collection' ? parent.itemType : undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+/** Derived state is readable but never writable; everything else follows its root. */
+export function locationCapabilities(location, context) {
+    const root = rootState(location, context);
+    if (!root) {
+        return { readable: false, writable: false };
+    }
+    return { readable: true, writable: root.derivation === undefined };
+}
+function rootState(location, context) {
+    switch (location.kind) {
+        case 'state':
+            return context.getState(location.stateId);
+        case 'field':
+            return rootState(location.target, context);
+        case 'collection-item':
+            return rootState(location.collection, context);
+        default:
+            return undefined;
+    }
+}
+/**
+ * A best-effort type for an expression. Returns undefined wherever the type depends on
+ * an iteration scope or another value only known at run time — 0.3 deliberately stops
+ * short of a complete static type checker.
+ */
+export function inferExpressionType(expression, context) {
+    switch (expression.kind) {
+        case 'literal': {
+            const value = expression.value;
+            if (typeof value === 'string') {
+                return primitiveType('string');
+            }
+            if (typeof value === 'number') {
+                return primitiveType('number');
+            }
+            if (typeof value === 'boolean') {
+                return primitiveType('boolean');
+            }
+            return undefined;
+        }
+        case 'ref': {
+            const state = context.getState(expression.targetId);
+            if (state) {
+                return state.valueType;
+            }
+            const entity = context.getEntity(expression.targetId);
+            if (entity) {
+                return entityType(entity.id);
+            }
+            return context.getParameterType?.(expression.targetId);
+        }
+        case 'field': {
+            const source = unwrap(inferExpressionType(expression.source, context));
+            if (source?.kind === 'entity') {
+                const entity = context.getEntity(source.entityId);
+                return entity?.fields.find((candidate) => candidate.id === expression.fieldId)?.valueType;
+            }
+            return source === undefined ? context.getField(expression.fieldId)?.field.valueType : undefined;
+        }
+        case 'object':
+            return expression.entityId ? entityType(expression.entityId) : undefined;
+        case 'binary':
+            return ['add', 'subtract', 'multiply', 'divide'].includes(expression.operator)
+                ? primitiveType('number')
+                : primitiveType('boolean');
+        case 'unary':
+            return expression.operator === 'not' ? primitiveType('boolean') : primitiveType('number');
+        case 'call':
+            switch (expression.function) {
+                case 'required':
+                case 'is-empty':
+                case 'contains':
+                case 'one-of':
+                    return primitiveType('boolean');
+                case 'length':
+                case 'count':
+                    return primitiveType('number');
+                case 'concat':
+                case 'lowercase':
+                case 'to-string':
+                case 'uuid':
+                    return primitiveType('string');
+                case 'now':
+                    return primitiveType('datetime');
+                default:
+                    return undefined;
+            }
+        case 'filter':
+            return inferExpressionType(expression.source, context);
+        case 'find': {
+            const source = unwrap(inferExpressionType(expression.source, context));
+            return source?.kind === 'collection' ? optionalType(source.itemType) : undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * True when a value of `value` type clearly cannot be stored at a `target` type. Unknown
+ * types are never reported: this rejects obvious mistakes, not everything questionable.
+ */
+export function isObviouslyIncompatible(target, value) {
+    const wanted = unwrap(target);
+    const given = unwrap(value);
+    if (!wanted || !given) {
+        return false;
+    }
+    if (wanted.kind !== given.kind) {
+        // An enum accepts strings, and a date is carried as a string.
+        if (wanted.kind === 'enum' && given.kind === 'primitive' && given.primitive === 'string') {
+            return false;
+        }
+        if (given.kind === 'enum' && wanted.kind === 'primitive' && wanted.primitive === 'string') {
+            return false;
+        }
+        return true;
+    }
+    if (wanted.kind === 'primitive' && given.kind === 'primitive') {
+        const interchangeable = new Set(['string', 'date', 'datetime']);
+        if (interchangeable.has(wanted.primitive) && interchangeable.has(given.primitive)) {
+            return false;
+        }
+        return wanted.primitive !== given.primitive;
+    }
+    if (wanted.kind === 'entity' && given.kind === 'entity') {
+        return wanted.entityId !== given.entityId;
+    }
+    if (wanted.kind === 'collection' && given.kind === 'collection') {
+        return isObviouslyIncompatible(wanted.itemType, given.itemType);
+    }
+    return false;
+}
+/** Renders a location for people. The stored representation stays id-based. */
+export function formatLocation(location, context) {
+    const name = (id) => context.getName?.(id) ?? id;
+    const fieldName = (id) => context.getField(id)?.field.name ?? id;
+    switch (location.kind) {
+        case 'state':
+            return name(location.stateId);
+        case 'field':
+            return `${formatLocation(location.target, context)} → ${fieldName(location.fieldId)}`;
+        case 'collection-item': {
+            const parent = formatLocation(location.collection, context);
+            if (location.selector.kind === 'identity') {
+                const value = location.selector.value.kind === 'ref'
+                    ? name(location.selector.value.targetId)
+                    : location.selector.value.kind === 'literal'
+                        ? JSON.stringify(location.selector.value.value)
+                        : 'expression';
+                return `${parent} → [${fieldName(location.selector.fieldId)} = ${value}]`;
+            }
+            return `${parent} → [index]`;
+        }
+        default:
+            return 'unknown location';
+    }
+}

package/dist/ir.d.ts

@@ -0,0 +1,50 @@
+import type { FieldId, NodeId } from './ids.js';
+import type { ActionDef, ConstraintDef, EntityDef, GraphEdge, RouteParameter, StateDef } from './nodes.js';
+import type { FieldIndexEntry } from './graph.js';
+import type { UINode } from './ui.js';
+import type { AnyNode } from './types.js';
+import type { TypeRef } from './type-ref.js';
+export interface RouteSegment {
+    kind: 'static' | 'parameter';
+    value: string;
+    parameterId?: NodeId;
+}
+export interface CompiledRoute {
+    id: NodeId;
+    path: string;
+    viewId: NodeId;
+    segments: RouteSegment[];
+    parameters: RouteParameter[];
+    /** Number of dynamic segments; routes are matched most-specific first. */
+    specificity: number;
+}
+/**
+ * The normalized form a compiler hands to a runtime: the same semantics as the graph,
+ * with references resolved and lookups pre-indexed. It is the shared contract between
+ * `@cynodia/axiom-compiler` and `@cynodia/axiom-runtime`, which is why it lives in core.
+ */
+export interface ApplicationIR {
+    id: string;
+    name: string;
+    version: string;
+    nodes: Record<NodeId, AnyNode>;
+    fields: Record<FieldId, FieldIndexEntry>;
+    entities: EntityDef[];
+    states: StateDef[];
+    actions: Record<NodeId, ActionDef>;
+    uiNodes: Record<NodeId, UINode>;
+    constraints: ConstraintDef[];
+    routes: CompiledRoute[];
+    edges: GraphEdge[];
+    /**
+     * The type each input's bound location addresses, resolved during normalization so a
+     * runtime never has to re-derive it.
+     */
+    locationTypes: Record<NodeId, TypeRef>;
+    /**
+     * The state each input's bound location is rooted in. A runtime uses it to tell a write
+     * to canonical application state from a write to a draft.
+     */
+    locationRoots: Record<NodeId, NodeId>;
+}
+//# sourceMappingURL=ir.d.ts.map

package/dist/ir.js

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

package/dist/location.d.ts

@@ -0,0 +1,57 @@
+import type { Expression } from './expressions.js';
+import type { FieldId, NodeId } from './ids.js';
+/**
+ * A Location is an addressable position in application state: where a value lives, as
+ * opposed to an Expression, which says what a value is. Nothing writable is ever
+ * expressed as an Expression, so no mutation depends on JavaScript object identity.
+ */
+export type Location = StateLocation | FieldLocation | CollectionItemLocation;
+export interface StateLocation {
+    kind: 'state';
+    stateId: NodeId;
+}
+export interface FieldLocation {
+    kind: 'field';
+    target: Location;
+    fieldId: FieldId;
+}
+export interface CollectionItemLocation {
+    kind: 'collection-item';
+    collection: Location;
+    selector: CollectionSelector;
+}
+export type CollectionSelector = IdentitySelector | IndexSelector;
+/** Addresses an item by the value of its identity field. Preferred over an index. */
+export interface IdentitySelector {
+    kind: 'identity';
+    fieldId: FieldId;
+    value: Expression;
+}
+export interface IndexSelector {
+    kind: 'index';
+    index: Expression;
+}
+export declare function stateLocation(stateId: NodeId): StateLocation;
+export declare function fieldLocation(target: Location, fieldId: FieldId): FieldLocation;
+export declare function itemLocation(collection: Location, selector: CollectionSelector): CollectionItemLocation;
+export declare function identitySelector(fieldId: FieldId, value: Expression): IdentitySelector;
+export declare function indexSelector(index: Expression): IndexSelector;
+/** Convenience for the common shape: one field of one item of a collection state. */
+export declare function itemFieldLocation(stateId: NodeId, identityFieldId: FieldId, identityValue: Expression, fieldId: FieldId): FieldLocation;
+/** The state node every location is ultimately rooted in. */
+export declare function locationRootStateId(location: Location): NodeId;
+/**
+ * Expressions embedded in a location — selector values and indexes. These are read
+ * dependencies of whatever uses the location.
+ */
+export declare function locationExpressions(location: Location): Expression[];
+/** Fields a write through this location touches, outermost first. */
+export declare function locationFieldIds(location: Location): FieldId[];
+/** Fields a location reads in order to address itself, such as identity selectors. */
+export declare function locationSelectorFieldIds(location: Location): FieldId[];
+/**
+ * Structural equality. Two locations that address the same position are equal even
+ * though the value a selector expression produces is only known at run time.
+ */
+export declare function locationsEqual(left: Location, right: Location): boolean;
+//# sourceMappingURL=location.d.ts.map

package/dist/location.js

@@ -0,0 +1,77 @@
+export function stateLocation(stateId) {
+    return { kind: 'state', stateId };
+}
+export function fieldLocation(target, fieldId) {
+    return { kind: 'field', target, fieldId };
+}
+export function itemLocation(collection, selector) {
+    return { kind: 'collection-item', collection, selector };
+}
+export function identitySelector(fieldId, value) {
+    return { kind: 'identity', fieldId, value };
+}
+export function indexSelector(index) {
+    return { kind: 'index', index };
+}
+/** Convenience for the common shape: one field of one item of a collection state. */
+export function itemFieldLocation(stateId, identityFieldId, identityValue, fieldId) {
+    return fieldLocation(itemLocation(stateLocation(stateId), identitySelector(identityFieldId, identityValue)), fieldId);
+}
+/** The state node every location is ultimately rooted in. */
+export function locationRootStateId(location) {
+    switch (location.kind) {
+        case 'state':
+            return location.stateId;
+        case 'field':
+            return locationRootStateId(location.target);
+        case 'collection-item':
+            return locationRootStateId(location.collection);
+        default:
+            throw new Error(`Unknown location kind "${location.kind}"`);
+    }
+}
+/**
+ * Expressions embedded in a location — selector values and indexes. These are read
+ * dependencies of whatever uses the location.
+ */
+export function locationExpressions(location) {
+    switch (location.kind) {
+        case 'state':
+            return [];
+        case 'field':
+            return locationExpressions(location.target);
+        case 'collection-item': {
+            const own = location.selector.kind === 'identity' ? [location.selector.value] : [location.selector.index];
+            return [...locationExpressions(location.collection), ...own];
+        }
+        default:
+            return [];
+    }
+}
+/** Fields a write through this location touches, outermost first. */
+export function locationFieldIds(location) {
+    return location.kind === 'field' ? [location.fieldId, ...locationFieldIds(location.target)] : [];
+}
+/** Fields a location reads in order to address itself, such as identity selectors. */
+export function locationSelectorFieldIds(location) {
+    switch (location.kind) {
+        case 'state':
+            return [];
+        case 'field':
+            return locationSelectorFieldIds(location.target);
+        case 'collection-item':
+            return [
+                ...locationSelectorFieldIds(location.collection),
+                ...(location.selector.kind === 'identity' ? [location.selector.fieldId] : []),
+            ];
+        default:
+            return [];
+    }
+}
+/**
+ * Structural equality. Two locations that address the same position are equal even
+ * though the value a selector expression produces is only known at run time.
+ */
+export function locationsEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}