@cynodia/axiom-core 0.14.0-alpha.1 → 0.14.0-alpha.2

package/dist/semantic-identity.d.ts

@@ -33,6 +33,14 @@ import type { ApplicationGraph } from './graph.js';
  * - `StorageDef` — `readAuthorization` / `uploadAuthorization` expressions, `retry`.
  * - `RelationshipDef` — endpoints and cardinality (also in the schema fingerprint; repeated
  *   here so a semantic-only comparison is self-contained).
+ * - `WorkflowDef` — `inputs`, `bindings`, `entry`, and every step's kind, control-flow edges
+ *   and step-specific executable semantics (the `ActionDef` / `EventDef` a step targets, an
+ *   `action` step's argument expressions / `retry` policy, a `wait-event` step's correlation
+ *   `where` / `bind` / `timeout`, a `timer` step's `after` / `at`, a `branch` step's `when`
+ *   and edges, `complete` / `fail` output/error expressions). A workflow's referenced
+ *   `ActionDef` / `EventDef` bodies are covered transitively — they are their own executable
+ *   nodes in this same projection (spec14pt3 §5, §7, §30-§33). Presentation-only fields
+ *   (`name` / `description` / `label`) are stripped exactly as elsewhere.
  * - `graph.schemaVersion`.
  *
  * ### Exclusions (what does NOT change it)
@@ -49,6 +57,16 @@ import type { ApplicationGraph } from './graph.js';
  */
 /** The projection algorithm's own version, mixed into the hash (spec12 §46). */
 export declare const SEMANTIC_FINGERPRINT_VERSION = 1;
+/**
+ * Every graph node kind that carries executable meaning — the single source of truth for
+ * "which graph changes alter executable semantic meaning" (spec14pt3 §5 G1). Both the
+ * graph-level {@link semanticFingerprint} and the ServerIR-side authority-compatibility
+ * fingerprint MUST derive from this same list; a `packages/server` test pins that they do,
+ * so a future primitive cannot be added to one and silently omitted from the other
+ * (spec14pt3 §189, §190 — the deeper architectural correction behind Phase 22 F3).
+ */
+export declare const EXECUTABLE_KINDS: readonly ["action", "integration", "integration-operation", "trigger", "event", "subscription", "read-policy", "query", "expression", "constraint", "transition-constraint", "storage", "relationship", "workflow"];
+export type ExecutableKind = (typeof EXECUTABLE_KINDS)[number];
 export interface SemanticProjection {
     fingerprintVersion: number;
     schemaVersion: number;

package/dist/semantic-identity.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { canonicalJSON } from './schema-identity.js';
 import { AUTHORING_METADATA_KEY } from './authoring-metadata.js';
+import { canonicalWorkflowForFingerprint } from './workflows.js';
 /**
  * Application **semantic** identity (spec12 §45, §46).
  *
@@ -35,6 +36,14 @@ import { AUTHORING_METADATA_KEY } from './authoring-metadata.js';
  * - `StorageDef` — `readAuthorization` / `uploadAuthorization` expressions, `retry`.
  * - `RelationshipDef` — endpoints and cardinality (also in the schema fingerprint; repeated
  *   here so a semantic-only comparison is self-contained).
+ * - `WorkflowDef` — `inputs`, `bindings`, `entry`, and every step's kind, control-flow edges
+ *   and step-specific executable semantics (the `ActionDef` / `EventDef` a step targets, an
+ *   `action` step's argument expressions / `retry` policy, a `wait-event` step's correlation
+ *   `where` / `bind` / `timeout`, a `timer` step's `after` / `at`, a `branch` step's `when`
+ *   and edges, `complete` / `fail` output/error expressions). A workflow's referenced
+ *   `ActionDef` / `EventDef` bodies are covered transitively — they are their own executable
+ *   nodes in this same projection (spec14pt3 §5, §7, §30-§33). Presentation-only fields
+ *   (`name` / `description` / `label`) are stripped exactly as elsewhere.
  * - `graph.schemaVersion`.
  *
  * ### Exclusions (what does NOT change it)
@@ -51,7 +60,15 @@ import { AUTHORING_METADATA_KEY } from './authoring-metadata.js';
  */
 /** The projection algorithm's own version, mixed into the hash (spec12 §46). */
 export const SEMANTIC_FINGERPRINT_VERSION = 1;
-const EXECUTABLE_KINDS = [
+/**
+ * Every graph node kind that carries executable meaning — the single source of truth for
+ * "which graph changes alter executable semantic meaning" (spec14pt3 §5 G1). Both the
+ * graph-level {@link semanticFingerprint} and the ServerIR-side authority-compatibility
+ * fingerprint MUST derive from this same list; a `packages/server` test pins that they do,
+ * so a future primitive cannot be added to one and silently omitted from the other
+ * (spec14pt3 §189, §190 — the deeper architectural correction behind Phase 22 F3).
+ */
+export const EXECUTABLE_KINDS = [
     'action',
     'integration',
     'integration-operation',
@@ -96,7 +113,7 @@ export function semanticProjection(graph) {
         if (group.length === 0) {
             continue;
         }
-        nodes[kind] = byId(group).map((node) => stripNonSemantic(node));
+        nodes[kind] = byId(group).map((node) => stripNonSemantic(kind === 'workflow' ? canonicalWorkflowForFingerprint(node) : node));
     }
     return {
         fingerprintVersion: SEMANTIC_FINGERPRINT_VERSION,

package/dist/validate.js

@@ -1052,10 +1052,11 @@ function validateWorkflow(workflow, context) {
     // Reachability + acyclicity + terminal reachability.
     const reachable = workflowReachableSteps(workflow);
     for (const step of steps) {
-        if (typeof step.id === 'string' && !reachable.has(String(step.id))) {
+        const sid = step && typeof step === 'object' ? step.id : undefined;
+        if (typeof sid === 'string' && !reachable.has(sid)) {
             context.errors.push({
                 code: VALIDATION_CODES.workflowUnreachableStep,
-                message: `Workflow ${workflow.id} step ${String(step.id)} is unreachable from entry`,
+                message: `Workflow ${workflow.id} step ${sid} is unreachable from entry`,
                 nodeId: workflow.id,
             });
         }

package/dist/workflows.d.ts

@@ -109,11 +109,18 @@ export interface WorkflowDef extends NodeBase {
     entry: NodeId;
     steps: WorkflowStep[];
 }
+/**
+ * Whether a value is a structurally recognizable workflow step — an object with an `id` and
+ * one of the six {@link WORKFLOW_STEP_TYPES}. The accessors below are total over *any* input
+ * (a malformed graph, a hand-tampered Server IR) precisely so a bad step produces a
+ * structured diagnostic rather than a native `TypeError` (spec14pt3 F1 / F2 §39-§48).
+ */
+export declare function isWorkflowStep(step: unknown): step is WorkflowStep;
 export declare function workflowStepById(workflow: WorkflowDef, stepId: NodeId | string): WorkflowStep | undefined;
-/** Every step id a step can hand control to (control-flow successors). */
+/** Every step id a step can hand control to (control-flow successors). Total over bad input. */
 export declare function workflowStepSuccessors(step: WorkflowStep): NodeId[];
 export declare function workflowIsTerminalStep(step: WorkflowStep): boolean;
-/** Every `Expression` embedded in a step — the leaves dependency / scope analysis walks. */
+/** Every `Expression` embedded in a step — the leaves dependency / scope analysis walks. Total over bad input. */
 export declare function workflowStepExpressions(step: WorkflowStep): Expression[];
 /** Every `Expression` in a workflow — inputs carry none, so this is the step leaves. */
 export declare function workflowExpressions(workflow: WorkflowDef): Expression[];
@@ -121,6 +128,32 @@ export declare function workflowExpressions(workflow: WorkflowDef): Expression[]
 export declare function workflowActionIds(workflow: WorkflowDef): NodeId[];
 /** The `EventDef` ids a workflow waits on. */
 export declare function workflowEventIds(workflow: WorkflowDef): NodeId[];
+/**
+ * A `WorkflowDef` reduced to a form where **authoring order is not semantic** (spec14pt3
+ * §19, §64): `steps`, `inputs` and `bindings` are ordered by id. Control flow is by explicit
+ * `entry` / `next` / `then` / `else` / `onError` / `onTimeout` edges, never by array
+ * position, so two workflows that differ only in the order their steps were declared are the
+ * same executable meaning. Both the graph-level `semanticFingerprint` and the ServerIR-side
+ * authority-compatibility fingerprint pass workflows through this before hashing, so they
+ * agree (spec14pt3 §5 G1). Non-`id` fields are untouched; human metadata is stripped by the
+ * caller's projection exactly as elsewhere.
+ */
+export declare function canonicalWorkflowForFingerprint<T extends Partial<WorkflowDef>>(workflow: T): T;
+export interface WorkflowStructuralProblem {
+    code: 'WORKFLOW_INVALID_STEP' | 'WORKFLOW_ENTRY_NOT_FOUND' | 'WORKFLOW_STEP_NOT_FOUND' | 'WORKFLOW_INVALID_TIMER';
+    message: string;
+}
+/**
+ * A **runtime-boundary** structural check on a `WorkflowDef`, independent of an
+ * `ApplicationGraph` (spec14pt3 §44-§49). `validateGraph` remains the authoring-time
+ * authority; this is what the authoritative runtime runs on a `ServerIR` it did not compile
+ * itself — stored, transported or hand-tampered — so structurally invalid workflow IR fails
+ * closed with a structured result instead of reaching a native `TypeError`, a silently
+ * skipped step or a permanently wedged instance. It checks only what the engine dereferences
+ * to execute; cross-node references (`ActionDef` / `EventDef` ids) are a compile-time
+ * concern and are not re-checked here.
+ */
+export declare function workflowStructuralProblems(workflow: WorkflowDef): WorkflowStructuralProblem[];
 /**
  * Step ids reachable from `entry` by control flow (spec14 §122). A step not in this set is
  * unreachable and an authoring mistake.

package/dist/workflows.js

@@ -25,11 +25,27 @@ export const WORKFLOW_STEP_TYPES = [
     'fail',
 ];
 // ---------------------------------------------------------------------------- accessors
+/**
+ * Whether a value is a structurally recognizable workflow step — an object with an `id` and
+ * one of the six {@link WORKFLOW_STEP_TYPES}. The accessors below are total over *any* input
+ * (a malformed graph, a hand-tampered Server IR) precisely so a bad step produces a
+ * structured diagnostic rather than a native `TypeError` (spec14pt3 F1 / F2 §39-§48).
+ */
+export function isWorkflowStep(step) {
+    return (!!step &&
+        typeof step === 'object' &&
+        !Array.isArray(step) &&
+        typeof step.id === 'string' &&
+        WORKFLOW_STEP_TYPES.includes(step.type));
+}
 export function workflowStepById(workflow, stepId) {
-    return workflow.steps.find((step) => String(step.id) === String(stepId));
+    const steps = Array.isArray(workflow?.steps) ? workflow.steps : [];
+    return steps.find((step) => !!step && typeof step === 'object' && String(step.id) === String(stepId));
 }
-/** Every step id a step can hand control to (control-flow successors). */
+/** Every step id a step can hand control to (control-flow successors). Total over bad input. */
 export function workflowStepSuccessors(step) {
+    if (!isWorkflowStep(step))
+        return [];
     switch (step.type) {
         case 'action':
             return step.onError ? [step.next, step.onError] : [step.next];
@@ -42,13 +58,17 @@ export function workflowStepSuccessors(step) {
         case 'complete':
         case 'fail':
             return [];
+        default:
+            return [];
     }
 }
 export function workflowIsTerminalStep(step) {
-    return step.type === 'complete' || step.type === 'fail';
+    return isWorkflowStep(step) && (step.type === 'complete' || step.type === 'fail');
 }
-/** Every `Expression` embedded in a step — the leaves dependency / scope analysis walks. */
+/** Every `Expression` embedded in a step — the leaves dependency / scope analysis walks. Total over bad input. */
 export function workflowStepExpressions(step) {
+    if (!isWorkflowStep(step))
+        return [];
     switch (step.type) {
         case 'action':
             return Object.values(step.arguments ?? {});
@@ -62,6 +82,8 @@ export function workflowStepExpressions(step) {
             return Object.values(step.output ?? {});
         case 'fail':
             return Object.values(step.error ?? {});
+        default:
+            return [];
     }
 }
 /** Every `Expression` in a workflow — inputs carry none, so this is the step leaves. */
@@ -70,11 +92,126 @@ export function workflowExpressions(workflow) {
 }
 /** The `ActionDef` ids a workflow invokes. */
 export function workflowActionIds(workflow) {
-    return workflow.steps.filter((s) => s.type === 'action').map((s) => s.action);
+    return (Array.isArray(workflow?.steps) ? workflow.steps : [])
+        .filter((s) => isWorkflowStep(s) && s.type === 'action')
+        .map((s) => s.action);
 }
 /** The `EventDef` ids a workflow waits on. */
 export function workflowEventIds(workflow) {
-    return workflow.steps.filter((s) => s.type === 'wait-event').map((s) => s.event);
+    return (Array.isArray(workflow?.steps) ? workflow.steps : [])
+        .filter((s) => isWorkflowStep(s) && s.type === 'wait-event')
+        .map((s) => s.event);
+}
+// ----------------------------------------------------- canonical form for fingerprinting
+/**
+ * A `WorkflowDef` reduced to a form where **authoring order is not semantic** (spec14pt3
+ * §19, §64): `steps`, `inputs` and `bindings` are ordered by id. Control flow is by explicit
+ * `entry` / `next` / `then` / `else` / `onError` / `onTimeout` edges, never by array
+ * position, so two workflows that differ only in the order their steps were declared are the
+ * same executable meaning. Both the graph-level `semanticFingerprint` and the ServerIR-side
+ * authority-compatibility fingerprint pass workflows through this before hashing, so they
+ * agree (spec14pt3 §5 G1). Non-`id` fields are untouched; human metadata is stripped by the
+ * caller's projection exactly as elsewhere.
+ */
+export function canonicalWorkflowForFingerprint(workflow) {
+    const byId = (list) => [...(list ?? [])].sort((a, b) => {
+        const ai = String(a?.id ?? '');
+        const bi = String(b?.id ?? '');
+        return ai < bi ? -1 : ai > bi ? 1 : 0;
+    });
+    return {
+        ...workflow,
+        ...(Array.isArray(workflow.steps) ? { steps: byId(workflow.steps) } : {}),
+        ...(Array.isArray(workflow.inputs) ? { inputs: byId(workflow.inputs) } : {}),
+        ...(Array.isArray(workflow.bindings) ? { bindings: byId(workflow.bindings) } : {}),
+    };
+}
+/**
+ * A **runtime-boundary** structural check on a `WorkflowDef`, independent of an
+ * `ApplicationGraph` (spec14pt3 §44-§49). `validateGraph` remains the authoring-time
+ * authority; this is what the authoritative runtime runs on a `ServerIR` it did not compile
+ * itself — stored, transported or hand-tampered — so structurally invalid workflow IR fails
+ * closed with a structured result instead of reaching a native `TypeError`, a silently
+ * skipped step or a permanently wedged instance. It checks only what the engine dereferences
+ * to execute; cross-node references (`ActionDef` / `EventDef` ids) are a compile-time
+ * concern and are not re-checked here.
+ */
+export function workflowStructuralProblems(workflow) {
+    const problems = [];
+    const wid = String(workflow?.id ?? '<unknown>');
+    const steps = Array.isArray(workflow?.steps) ? workflow.steps : [];
+    const ids = new Set();
+    for (const step of steps) {
+        if (!isWorkflowStep(step)) {
+            problems.push({
+                code: 'WORKFLOW_INVALID_STEP',
+                message: `Workflow ${wid} has a step that is not an object with an id and a known kind`,
+            });
+            continue;
+        }
+        ids.add(String(step.id));
+    }
+    if (workflow?.entry === undefined || !ids.has(String(workflow.entry))) {
+        problems.push({
+            code: 'WORKFLOW_ENTRY_NOT_FOUND',
+            message: `Workflow ${wid} entry ${String(workflow?.entry)} is not one of its steps`,
+        });
+    }
+    const edge = (target, from) => {
+        if (target !== undefined && !ids.has(String(target))) {
+            problems.push({
+                code: 'WORKFLOW_STEP_NOT_FOUND',
+                message: `Workflow ${wid} step ${from} points at ${String(target)}, which is not a step`,
+            });
+        }
+    };
+    for (const step of steps) {
+        if (!isWorkflowStep(step))
+            continue;
+        const from = String(step.id);
+        switch (step.type) {
+            case 'action':
+                if (typeof step.action !== 'string') {
+                    problems.push({ code: 'WORKFLOW_INVALID_STEP', message: `Workflow ${wid} action step ${from} has no action target` });
+                }
+                edge(step.next, from);
+                edge(step.onError, from);
+                break;
+            case 'wait-event':
+                if (typeof step.event !== 'string') {
+                    problems.push({ code: 'WORKFLOW_INVALID_STEP', message: `Workflow ${wid} wait-event step ${from} has no event target` });
+                }
+                edge(step.next, from);
+                edge(step.onTimeout, from);
+                if (step.timeout !== undefined && !(Number(step.timeout?.seconds) > 0)) {
+                    problems.push({ code: 'WORKFLOW_INVALID_TIMER', message: `Workflow ${wid} wait-event step ${from} has a non-positive timeout` });
+                }
+                break;
+            case 'timer': {
+                const hasAfter = step.after !== undefined;
+                const hasAt = step.at !== undefined;
+                if (hasAfter === hasAt) {
+                    problems.push({ code: 'WORKFLOW_INVALID_TIMER', message: `Workflow ${wid} timer step ${from} must declare exactly one of after / at` });
+                }
+                else if (hasAfter && !(Number(step.after?.seconds) > 0)) {
+                    problems.push({ code: 'WORKFLOW_INVALID_TIMER', message: `Workflow ${wid} timer step ${from} has a non-positive after.seconds` });
+                }
+                edge(step.next, from);
+                break;
+            }
+            case 'branch':
+                if (step.when === undefined) {
+                    problems.push({ code: 'WORKFLOW_INVALID_STEP', message: `Workflow ${wid} branch step ${from} has no when expression` });
+                }
+                edge(step.then, from);
+                edge(step.else, from);
+                break;
+            case 'complete':
+            case 'fail':
+                break;
+        }
+    }
+    return problems;
 }
 /**
  * Step ids reachable from `entry` by control flow (spec14 §122). A step not in this set is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom-core",
-  "version": "0.14.0-alpha.1",
+  "version": "0.14.0-alpha.2",
   "description": "Application Graph, semantic types, locations and validation for Axiom.",
   "license": "MIT",
   "author": "AskTech AS",