@unlaxer/tramli 0.2.0 → 1.1.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.js

@@ -274,6 +274,18 @@ export class Builder {
                     newAvailable.add(p);
             }
             this.checkRequiresProducesFrom(def, t.to, newAvailable, stateAvailable, errors);
+            // Error path analysis: if processor fails, its produces are NOT available
+            if (t.processor) {
+                const errorTarget = def.errorTransitions.get(t.from);
+                if (errorTarget) {
+                    const errorAvailable = new Set(stateAvailable.get(state));
+                    if (t.guard) {
+                        for (const p of t.guard.produces)
+                            errorAvailable.add(p);
+                    }
+                    this.checkRequiresProducesFrom(def, errorTarget, errorAvailable, stateAvailable, errors);
+                }
+            }
         }
     }
     checkAutoExternalConflict(def, errors) {

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/package.json

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