@unlaxer/tramli 1.0.0 → 1.2.0

package/dist/data-flow-graph.d.ts

@@ -1,5 +1,7 @@
 import type { FlowDefinition } from './flow-definition.js';
 import type { FlowKey } from './flow-key.js';
+import type { StateProcessor } from './types.js';
+import type { FlowContext } from './flow-context.js';
 export interface NodeInfo<S extends string> {
     name: string;
     fromState: S;
@@ -25,8 +27,36 @@ export declare class DataFlowGraph<S extends string> {
     consumersOf(key: FlowKey<unknown>): NodeInfo<S>[];
     /** Types produced but never required by any downstream processor/guard. */
     deadData(): Set<string>;
+    /** Data lifetime: which states a type is first produced and last consumed. */
+    lifetime(key: FlowKey<unknown>): {
+        firstProduced: S;
+        lastConsumed: S;
+    } | null;
+    /** Context pruning hints: for each state, types available but not required at that state. */
+    pruningHints(): Map<S, Set<string>>;
+    /**
+     * Check if processor B can replace processor A without breaking data-flow.
+     * B is compatible with A if: B requires no more than A, and B produces at least what A produces.
+     */
+    static isCompatible<S extends string>(a: {
+        requires: FlowKey<unknown>[];
+        produces: FlowKey<unknown>[];
+    }, b: {
+        requires: FlowKey<unknown>[];
+        produces: FlowKey<unknown>[];
+    }): boolean;
+    /**
+     * Verify a processor's declared requires/produces against actual context usage.
+     * Returns list of violations (empty = OK).
+     */
+    static verifyProcessor<S extends string>(processor: StateProcessor<S>, ctx: FlowContext): Promise<string[]>;
     /** All type nodes in the graph. */
     allTypes(): Set<string>;
+    /**
+     * Assert that a flow instance's context satisfies the data-flow invariant.
+     * Returns list of missing type keys (empty = OK).
+     */
+    assertDataFlow(ctx: FlowContext, currentState: S): string[];
     /** Generate Mermaid data-flow diagram. */
     toMermaid(): string;
     static build<S extends string>(def: FlowDefinition<S>, initiallyAvailable: string[]): DataFlowGraph<S>;

package/dist/data-flow-graph.js

@@ -34,6 +34,95 @@ export class DataFlowGraph {
             dead.delete(c);
         return dead;
     }
+    /** Data lifetime: which states a type is first produced and last consumed. */
+    lifetime(key) {
+        const prods = this._producers.get(key);
+        const cons = this._consumers.get(key);
+        if (!prods || prods.length === 0)
+            return null;
+        const firstProduced = prods[0].toState;
+        const lastConsumed = cons && cons.length > 0 ? cons[cons.length - 1].fromState : firstProduced;
+        return { firstProduced, lastConsumed };
+    }
+    /** Context pruning hints: for each state, types available but not required at that state. */
+    pruningHints() {
+        const consumedAt = new Map();
+        for (const [typeName, nodes] of this._consumers) {
+            for (const node of nodes) {
+                if (!consumedAt.has(node.fromState))
+                    consumedAt.set(node.fromState, new Set());
+                consumedAt.get(node.fromState).add(typeName);
+            }
+        }
+        const hints = new Map();
+        for (const [state, available] of this._availableAtState) {
+            const needed = consumedAt.get(state) ?? new Set();
+            const prunable = new Set();
+            for (const type of available) {
+                if (!needed.has(type))
+                    prunable.add(type);
+            }
+            if (prunable.size > 0)
+                hints.set(state, prunable);
+        }
+        return hints;
+    }
+    /**
+     * Check if processor B can replace processor A without breaking data-flow.
+     * B is compatible with A if: B requires no more than A, and B produces at least what A produces.
+     */
+    static isCompatible(a, b) {
+        const aReqs = new Set(a.requires);
+        const bReqs = new Set(b.requires);
+        const aProds = new Set(a.produces);
+        const bProds = new Set(b.produces);
+        for (const r of bReqs) {
+            if (!aReqs.has(r))
+                return false;
+        }
+        for (const p of aProds) {
+            if (!bProds.has(p))
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Verify a processor's declared requires/produces against actual context usage.
+     * Returns list of violations (empty = OK).
+     */
+    static async verifyProcessor(processor, ctx) {
+        const violations = [];
+        for (const req of processor.requires) {
+            if (!ctx.has(req))
+                violations.push(`requires ${req} but not in context`);
+        }
+        const beforeKeys = new Set();
+        for (const req of processor.requires) {
+            if (ctx.has(req))
+                beforeKeys.add(req);
+        }
+        // Capture all existing keys
+        const snapshot = ctx.snapshot();
+        const existingKeys = new Set(snapshot.keys());
+        try {
+            await processor.process(ctx);
+        }
+        catch (e) {
+            violations.push(`threw ${e.constructor.name}: ${e.message}`);
+            return violations;
+        }
+        const afterSnapshot = ctx.snapshot();
+        for (const prod of processor.produces) {
+            if (!afterSnapshot.has(prod))
+                violations.push(`declares produces ${prod} but did not put it`);
+        }
+        for (const [key] of afterSnapshot) {
+            if (!existingKeys.has(key) && !processor.produces.includes(key)) {
+                violations.push(`put ${key} but did not declare it in produces`);
+            }
+        }
+        return violations;
+    }
     /** All type nodes in the graph. */
     allTypes() {
         const types = new Set(this._allProduced);
@@ -41,6 +130,18 @@ export class DataFlowGraph {
             types.add(c);
         return types;
     }
+    /**
+     * Assert that a flow instance's context satisfies the data-flow invariant.
+     * Returns list of missing type keys (empty = OK).
+     */
+    assertDataFlow(ctx, currentState) {
+        const missing = [];
+        for (const type of this.availableAt(currentState)) {
+            if (!ctx.has(type))
+                missing.push(type);
+        }
+        return missing;
+    }
     /** Generate Mermaid data-flow diagram. */
     toMermaid() {
         const lines = ['flowchart LR'];

package/dist/flow-definition.d.ts

@@ -47,6 +47,7 @@ export declare class Builder<S extends string> {
     private checkRequiresProducesFrom;
     private checkAutoExternalConflict;
     private checkTerminalNoOutgoing;
+    private checkSubFlowExitCompleteness;
 }
 export declare class FromBuilder<S extends string> {
     private readonly builder;
@@ -55,6 +56,16 @@ export declare class FromBuilder<S extends string> {
     auto(to: S, processor: StateProcessor<S>): Builder<S>;
     external(to: S, guard: TransitionGuard<S>, processor?: StateProcessor<S>): Builder<S>;
     branch(branch: BranchProcessor<S>): BranchBuilder<S>;
+    subFlow(subFlowDef: FlowDefinition<any>): SubFlowBuilder<S>;
+}
+export declare class SubFlowBuilder<S extends string> {
+    private readonly builder;
+    private readonly fromState;
+    private readonly subFlowDef;
+    private readonly exitMap;
+    constructor(builder: Builder<S>, fromState: S, subFlowDef: FlowDefinition<any>);
+    onExit(terminalName: string, parentState: S): this;
+    endSubFlow(): Builder<S>;
 }
 export declare class BranchBuilder<S extends string> {
     private readonly builder;

package/dist/flow-definition.js

@@ -118,6 +118,7 @@ export class Builder {
         this.checkRequiresProduces(def, errors);
         this.checkAutoExternalConflict(def, errors);
         this.checkTerminalNoOutgoing(def, errors);
+        this.checkSubFlowExitCompleteness(def, errors);
         if (errors.length > 0) {
             throw new FlowError('INVALID_FLOW_DEFINITION', `Flow '${this.name}' has ${errors.length} validation error(s):\n  - ${errors.join('\n  - ')}`);
         }
@@ -131,6 +132,15 @@ export class Builder {
         while (queue.length > 0) {
             const current = queue.shift();
             for (const t of def.transitionsFrom(current)) {
+                if (t.type === 'sub_flow' && t.exitMappings) {
+                    for (const target of t.exitMappings.values()) {
+                        if (!visited.has(target)) {
+                            visited.add(target);
+                            queue.push(target);
+                        }
+                    }
+                    continue;
+                }
                 if (!visited.has(t.to)) {
                     visited.add(t.to);
                     queue.push(t.to);
@@ -163,6 +173,13 @@ export class Builder {
             return false;
         visited.add(state);
         for (const t of def.transitionsFrom(state)) {
+            if (t.type === 'sub_flow' && t.exitMappings) {
+                for (const target of t.exitMappings.values()) {
+                    if (this.canReachTerminal(def, target, visited))
+                        return true;
+                }
+                continue;
+            }
             if (this.canReachTerminal(def, t.to, visited))
                 return true;
         }
@@ -300,11 +317,23 @@ export class Builder {
     }
     checkTerminalNoOutgoing(def, errors) {
         for (const t of def.transitions) {
-            if (def.stateConfig[t.from].terminal) {
+            if (def.stateConfig[t.from].terminal && t.type !== 'sub_flow') {
                 errors.push(`Terminal state ${t.from} has an outgoing transition to ${t.to}`);
             }
         }
     }
+    checkSubFlowExitCompleteness(def, errors) {
+        for (const t of def.transitions) {
+            if (t.type !== 'sub_flow' || !t.subFlowDefinition)
+                continue;
+            const subDef = t.subFlowDefinition;
+            for (const terminal of subDef.terminalStates) {
+                if (!t.exitMappings?.has(terminal)) {
+                    errors.push(`SubFlow '${subDef.name}' at ${t.from} has terminal state ${terminal} with no onExit mapping`);
+                }
+            }
+        }
+    }
 }
 export class FromBuilder {
     builder;
@@ -330,6 +359,34 @@ export class FromBuilder {
     branch(branch) {
         return new BranchBuilder(this.builder, this.fromState, branch);
     }
+    subFlow(subFlowDef) {
+        return new SubFlowBuilder(this.builder, this.fromState, subFlowDef);
+    }
+}
+export class SubFlowBuilder {
+    builder;
+    fromState;
+    subFlowDef;
+    exitMap = new Map();
+    constructor(builder, fromState, subFlowDef) {
+        this.builder = builder;
+        this.fromState = fromState;
+        this.subFlowDef = subFlowDef;
+    }
+    onExit(terminalName, parentState) {
+        this.exitMap.set(terminalName, parentState);
+        return this;
+    }
+    endSubFlow() {
+        this.builder.addTransition({
+            from: this.fromState, to: this.fromState, type: 'sub_flow',
+            processor: undefined, guard: undefined, branch: undefined,
+            branchTargets: new Map(),
+            subFlowDefinition: this.subFlowDef,
+            exitMappings: new Map(this.exitMap),
+        });
+        return this.builder;
+    }
 }
 export class BranchBuilder {
     builder;

package/dist/flow-engine.d.ts

@@ -1,22 +1,13 @@
 import type { FlowDefinition } from './flow-definition.js';
 import { FlowInstance } from './flow-instance.js';
 import type { InMemoryFlowStore } from './in-memory-flow-store.js';
-/**
- * Generic engine that drives all flow state machines.
- *
- * Exceptions:
- * - FLOW_NOT_FOUND: resumeAndExecute with unknown or completed flowId
- * - INVALID_TRANSITION: resumeAndExecute when no external transition exists
- * - MAX_CHAIN_DEPTH: auto-chain exceeded 10 steps
- * - EXPIRED: flow TTL exceeded at resumeAndExecute entry
- *
- * Processor and branch exceptions are caught and routed to error transitions.
- */
 export declare class FlowEngine {
     private readonly store;
     constructor(store: InMemoryFlowStore);
     startFlow<S extends string>(definition: FlowDefinition<S>, sessionId: string, initialData: Map<string, unknown>): Promise<FlowInstance<S>>;
     resumeAndExecute<S extends string>(flowId: string, definition: FlowDefinition<S>, externalData?: Map<string, unknown>): Promise<FlowInstance<S>>;
     private executeAutoChain;
+    private executeSubFlow;
+    private resumeSubFlow;
     private handleError;
 }

package/dist/flow-engine.js

@@ -2,17 +2,6 @@ import { FlowContext } from './flow-context.js';
 import { FlowInstance } from './flow-instance.js';
 import { FlowError } from './flow-error.js';
 const MAX_CHAIN_DEPTH = 10;
-/**
- * Generic engine that drives all flow state machines.
- *
- * Exceptions:
- * - FLOW_NOT_FOUND: resumeAndExecute with unknown or completed flowId
- * - INVALID_TRANSITION: resumeAndExecute when no external transition exists
- * - MAX_CHAIN_DEPTH: auto-chain exceeded 10 steps
- * - EXPIRED: flow TTL exceeded at resumeAndExecute entry
- *
- * Processor and branch exceptions are caught and routed to error transitions.
- */
 export class FlowEngine {
     store;
     constructor(store) {
@@ -46,6 +35,10 @@ export class FlowEngine {
             this.store.save(flow);
             return flow;
         }
+        // If actively in a sub-flow, delegate resume
+        if (flow.activeSubFlow) {
+            return this.resumeSubFlow(flow, definition);
+        }
         const currentState = flow.currentState;
         const transition = definition.externalFrom(currentState);
         if (!transition)
@@ -108,6 +101,15 @@ export class FlowEngine {
                 break;
             }
             const transitions = flow.definition.transitionsFrom(current);
+            // Check for sub-flow transition
+            const subFlowT = transitions.find(t => t.type === 'sub_flow');
+            if (subFlowT) {
+                const advanced = await this.executeSubFlow(flow, subFlowT);
+                depth += advanced;
+                if (advanced === 0)
+                    break; // sub-flow stopped at external
+                continue;
+            }
             const autoOrBranch = transitions.find(t => t.type === 'auto' || t.type === 'branch');
             if (!autoOrBranch)
                 break;
@@ -145,6 +147,78 @@ export class FlowEngine {
         if (depth >= MAX_CHAIN_DEPTH)
             throw FlowError.maxChainDepth();
     }
+    async executeSubFlow(parentFlow, subFlowTransition) {
+        const subDef = subFlowTransition.subFlowDefinition;
+        const exitMappings = subFlowTransition.exitMappings;
+        const subInitial = subDef.initialState;
+        const subFlow = new FlowInstance(parentFlow.id, parentFlow.sessionId, subDef, parentFlow.context, subInitial, parentFlow.expiresAt);
+        parentFlow.setActiveSubFlow(subFlow);
+        await this.executeAutoChain(subFlow);
+        if (subFlow.isCompleted) {
+            parentFlow.setActiveSubFlow(null);
+            const target = exitMappings.get(subFlow.exitState);
+            if (target) {
+                const from = parentFlow.currentState;
+                parentFlow.transitionTo(target);
+                this.store.recordTransition(parentFlow.id, from, target, `subFlow:${subDef.name}/${subFlow.exitState}`, parentFlow.context);
+                return 1;
+            }
+        }
+        return 0; // sub-flow stopped at external
+    }
+    async resumeSubFlow(parentFlow, parentDef) {
+        const subFlow = parentFlow.activeSubFlow;
+        const subDef = subFlow.definition;
+        const transition = subDef.externalFrom(subFlow.currentState);
+        if (!transition) {
+            throw new FlowError('INVALID_TRANSITION', `No external transition from sub-flow state ${subFlow.currentState}`);
+        }
+        const guard = transition.guard;
+        if (guard) {
+            const output = await guard.validate(parentFlow.context);
+            if (output.type === 'accepted') {
+                if (output.data) {
+                    for (const [key, value] of output.data)
+                        parentFlow.context.put(key, value);
+                }
+                subFlow.transitionTo(transition.to);
+                this.store.recordTransition(parentFlow.id, subFlow.currentState, transition.to, guard.name, parentFlow.context);
+            }
+            else if (output.type === 'rejected') {
+                subFlow.incrementGuardFailure();
+                if (subFlow.guardFailureCount >= subDef.maxGuardRetries) {
+                    subFlow.complete('ERROR');
+                }
+                this.store.save(parentFlow);
+                return parentFlow;
+            }
+            else {
+                parentFlow.complete('EXPIRED');
+                this.store.save(parentFlow);
+                return parentFlow;
+            }
+        }
+        else {
+            subFlow.transitionTo(transition.to);
+        }
+        await this.executeAutoChain(subFlow);
+        if (subFlow.isCompleted) {
+            parentFlow.setActiveSubFlow(null);
+            const subFlowT = parentDef.transitionsFrom(parentFlow.currentState)
+                .find(t => t.type === 'sub_flow');
+            if (subFlowT?.exitMappings) {
+                const target = subFlowT.exitMappings.get(subFlow.exitState);
+                if (target) {
+                    const from = parentFlow.currentState;
+                    parentFlow.transitionTo(target);
+                    this.store.recordTransition(parentFlow.id, from, target, `subFlow:${subDef.name}/${subFlow.exitState}`, parentFlow.context);
+                    await this.executeAutoChain(parentFlow);
+                }
+            }
+        }
+        this.store.save(parentFlow);
+        return parentFlow;
+    }
     handleError(flow, fromState) {
         const errorTarget = flow.definition.errorTransitions.get(fromState);
         if (errorTarget) {

package/dist/flow-error.d.ts

@@ -1,6 +1,12 @@
 export declare class FlowError extends Error {
     readonly code: string;
+    /** Types that were available in context when the error occurred. */
+    availableTypes?: Set<string>;
+    /** Types that were expected but missing (if applicable). */
+    missingTypes?: Set<string>;
     constructor(code: string, message: string);
+    /** Attach context snapshot to this error. */
+    withContextSnapshot(available: Set<string>, missing: Set<string>): this;
     static invalidTransition(from: string, to: string): FlowError;
     static missingContext(key: string): FlowError;
     static dagCycle(detail: string): FlowError;

package/dist/flow-error.js

@@ -1,10 +1,20 @@
 export class FlowError extends Error {
     code;
+    /** Types that were available in context when the error occurred. */
+    availableTypes;
+    /** Types that were expected but missing (if applicable). */
+    missingTypes;
     constructor(code, message) {
         super(message);
         this.code = code;
         this.name = 'FlowError';
     }
+    /** Attach context snapshot to this error. */
+    withContextSnapshot(available, missing) {
+        this.availableTypes = available;
+        this.missingTypes = missing;
+        return this;
+    }
     static invalidTransition(from, to) {
         return new FlowError('INVALID_TRANSITION', `Invalid transition from ${from} to ${to}`);
     }

package/dist/flow-instance.d.ts

@@ -11,6 +11,7 @@ export declare class FlowInstance<S extends string> {
     readonly createdAt: Date;
     readonly expiresAt: Date;
     private _exitState;
+    private _activeSubFlow;
     constructor(id: string, sessionId: string, definition: FlowDefinition<S>, context: FlowContext, currentState: S, expiresAt: Date);
     /**
      * Restore a FlowInstance from persisted state.
@@ -22,8 +23,10 @@ export declare class FlowInstance<S extends string> {
     get version(): number;
     get exitState(): string | null;
     get isCompleted(): boolean;
+    get activeSubFlow(): FlowInstance<any> | null;
     /** @internal */ transitionTo(state: S): void;
     /** @internal */ incrementGuardFailure(): void;
     /** @internal */ complete(exitState: string): void;
     /** @internal */ setVersion(version: number): void;
+    /** @internal */ setActiveSubFlow(sub: FlowInstance<any> | null): void;
 }

package/dist/flow-instance.js

@@ -9,6 +9,7 @@ export class FlowInstance {
     createdAt;
     expiresAt;
     _exitState;
+    _activeSubFlow = null;
     constructor(id, sessionId, definition, context, currentState, expiresAt) {
         this.id = id;
         this.sessionId = sessionId;
@@ -45,8 +46,10 @@ export class FlowInstance {
     get version() { return this._version; }
     get exitState() { return this._exitState; }
     get isCompleted() { return this._exitState !== null; }
+    get activeSubFlow() { return this._activeSubFlow; }
     /** @internal */ transitionTo(state) { this._currentState = state; }
     /** @internal */ incrementGuardFailure() { this._guardFailureCount++; }
     /** @internal */ complete(exitState) { this._exitState = exitState; }
     /** @internal */ setVersion(version) { this._version = version; }
+    /** @internal */ setActiveSubFlow(sub) { this._activeSubFlow = sub; }
 }

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { Tramli } from './tramli.js';
 export { FlowEngine } from './flow-engine.js';
 export { FlowContext } from './flow-context.js';
 export { FlowInstance } from './flow-instance.js';
-export { FlowDefinition, Builder, FromBuilder, BranchBuilder } from './flow-definition.js';
+export { FlowDefinition, Builder, FromBuilder, BranchBuilder, SubFlowBuilder } from './flow-definition.js';
 export { FlowError } from './flow-error.js';
 export { InMemoryFlowStore } from './in-memory-flow-store.js';
 export type { TransitionRecord } from './in-memory-flow-store.js';

package/dist/index.js

@@ -2,7 +2,7 @@ export { Tramli } from './tramli.js';
 export { FlowEngine } from './flow-engine.js';
 export { FlowContext } from './flow-context.js';
 export { FlowInstance } from './flow-instance.js';
-export { FlowDefinition, Builder, FromBuilder, BranchBuilder } from './flow-definition.js';
+export { FlowDefinition, Builder, FromBuilder, BranchBuilder, SubFlowBuilder } from './flow-definition.js';
 export { FlowError } from './flow-error.js';
 export { InMemoryFlowStore } from './in-memory-flow-store.js';
 export { MermaidGenerator } from './mermaid-generator.js';

package/dist/types.d.ts

@@ -16,7 +16,7 @@ export type GuardOutput = {
     type: 'expired';
 };
 /** Transition types. */
-export type TransitionType = 'auto' | 'external' | 'branch';
+export type TransitionType = 'auto' | 'external' | 'branch' | 'sub_flow';
 /** A single transition in the flow definition. */
 export interface Transition<S extends string> {
     from: S;
@@ -26,6 +26,8 @@ export interface Transition<S extends string> {
     guard?: TransitionGuard<S>;
     branch?: BranchProcessor<S>;
     branchTargets: Map<string, S>;
+    subFlowDefinition?: import('./flow-definition.js').FlowDefinition<any>;
+    exitMappings?: Map<string, S>;
 }
 /**
  * Processes a state transition.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unlaxer/tramli",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Constrained flow engine — state machines that prevent invalid transitions at build time",
   "type": "module",
   "exports": {