@unlaxer/tramli 3.1.0 → 3.3.0

package/dist/cjs/flow-context.d.ts

@@ -9,6 +9,8 @@ export declare class FlowContext {
     readonly flowId: string;
     readonly createdAt: Date;
     private attributes;
+    private aliasToKey;
+    private keyToAlias;
     constructor(flowId: string, createdAt?: Date, attributes?: Map<string, unknown>);
     get<T>(key: FlowKey<T>): T;
     find<T>(key: FlowKey<T>): T | undefined;
@@ -16,4 +18,14 @@ export declare class FlowContext {
     has(key: FlowKey<unknown>): boolean;
     snapshot(): Map<string, unknown>;
     restoreFrom(snapshot: Map<string, unknown>): void;
+    /** Register a string alias for a FlowKey. Used for cross-language serialization. */
+    registerAlias(key: FlowKey<unknown>, alias: string): void;
+    /** Get the alias for a key (if registered). */
+    aliasOf(key: FlowKey<unknown>): string | undefined;
+    /** Get the key for an alias (if registered). */
+    keyOfAlias(alias: string): FlowKey<unknown> | undefined;
+    /** Export all registered aliases as a map (alias → key). */
+    toAliasMap(): Map<string, string>;
+    /** Import aliases from a map (alias → key). */
+    fromAliasMap(map: Map<string, string>): void;
 }

package/dist/cjs/flow-context.js

@@ -12,6 +12,8 @@ class FlowContext {
     flowId;
     createdAt;
     attributes;
+    aliasToKey = new Map();
+    keyToAlias = new Map();
     constructor(flowId, createdAt, attributes) {
         this.flowId = flowId;
         this.createdAt = createdAt ?? new Date();
@@ -40,5 +42,30 @@ class FlowContext {
         for (const [k, v] of snapshot)
             this.attributes.set(k, v);
     }
+    // ─── Alias support (for cross-language serialization) ──────────────────
+    /** Register a string alias for a FlowKey. Used for cross-language serialization. */
+    registerAlias(key, alias) {
+        this.aliasToKey.set(alias, key);
+        this.keyToAlias.set(key, alias);
+    }
+    /** Get the alias for a key (if registered). */
+    aliasOf(key) {
+        return this.keyToAlias.get(key);
+    }
+    /** Get the key for an alias (if registered). */
+    keyOfAlias(alias) {
+        return this.aliasToKey.get(alias);
+    }
+    /** Export all registered aliases as a map (alias → key). */
+    toAliasMap() {
+        return new Map(this.aliasToKey);
+    }
+    /** Import aliases from a map (alias → key). */
+    fromAliasMap(map) {
+        for (const [alias, key] of map) {
+            this.aliasToKey.set(alias, key);
+            this.keyToAlias.set(key, alias);
+        }
+    }
 }
 exports.FlowContext = FlowContext;

package/dist/cjs/flow-definition.d.ts

@@ -16,9 +16,17 @@ export declare class FlowDefinition<S extends string> {
         errorClass: new (...args: any[]) => Error;
         target: S;
     }>>;
+    readonly enterActions: Map<S, (ctx: import('./flow-context.js').FlowContext) => void>;
+    readonly exitActions: Map<S, (ctx: import('./flow-context.js').FlowContext) => void>;
+    /** Get enter action for a state (or undefined). */
+    enterAction(state: S): ((ctx: import('./flow-context.js').FlowContext) => void) | undefined;
+    /** Get exit action for a state (or undefined). */
+    exitAction(state: S): ((ctx: import('./flow-context.js').FlowContext) => void) | undefined;
     private constructor();
     transitionsFrom(state: S): Transition<S>[];
     externalFrom(state: S): Transition<S> | undefined;
+    /** All external transitions from a state (for multi-external). */
+    externalsFrom(state: S): Transition<S>[];
     allStates(): S[];
     /**
      * Create a new FlowDefinition with a sub-flow inserted before a specific transition.
@@ -34,7 +42,10 @@ export declare class Builder<S extends string> {
     private readonly transitions;
     private readonly errorTransitions;
     private readonly _exceptionRoutes;
+    private readonly _enterActions;
+    private readonly _exitActions;
     private readonly initiallyAvailableKeys;
+    private _perpetual;
     constructor(name: string, stateConfig: Record<S, StateConfig>);
     initiallyAvailable(...keys: FlowKey<unknown>[]): this;
     setTtl(ms: number): this;
@@ -44,6 +55,12 @@ export declare class Builder<S extends string> {
     /** Route specific error types to specific states. Checked before onError. */
     onStepError(from: S, errorClass: new (...args: any[]) => Error, to: S): this;
     onAnyError(errorState: S): this;
+    /** Callback when entering a state (pure data/metrics, no I/O). */
+    onStateEnter(state: S, action: (ctx: import('./flow-context.js').FlowContext) => void): this;
+    /** Callback when exiting a state (pure data/metrics, no I/O). */
+    onStateExit(state: S, action: (ctx: import('./flow-context.js').FlowContext) => void): this;
+    /** Allow perpetual flows (no terminal states). Skips path-to-terminal validation. */
+    allowPerpetual(): this;
     /** @internal */
     addTransition(t: Transition<S>): void;
     build(): FlowDefinition<S>;
@@ -53,7 +70,6 @@ export declare class Builder<S extends string> {
     private canReachTerminal;
     private checkDag;
     private hasCycle;
-    private checkExternalUniqueness;
     private checkBranchCompleteness;
     private checkRequiresProduces;
     private checkRequiresProducesFrom;

package/dist/cjs/flow-definition.js

@@ -15,6 +15,16 @@ class FlowDefinition {
     dataFlowGraph;
     warnings;
     exceptionRoutes;
+    enterActions;
+    exitActions;
+    /** Get enter action for a state (or undefined). */
+    enterAction(state) {
+        return this.enterActions?.get(state);
+    }
+    /** Get exit action for a state (or undefined). */
+    exitAction(state) {
+        return this.exitActions?.get(state);
+    }
     constructor(name, stateConfig, ttl, maxGuardRetries, transitions, errorTransitions) {
         this.name = name;
         this.stateConfig = stateConfig;
@@ -39,6 +49,10 @@ class FlowDefinition {
     externalFrom(state) {
         return this.transitions.find(t => t.from === state && t.type === 'external');
     }
+    /** All external transitions from a state (for multi-external). */
+    externalsFrom(state) {
+        return this.transitions.filter(t => t.from === state && t.type === 'external');
+    }
     allStates() {
         return Object.keys(this.stateConfig);
     }
@@ -75,6 +89,10 @@ class FlowDefinition {
             initialState: this.initialState,
             terminalStates: this.terminalStates,
             dataFlowGraph: this.dataFlowGraph, // reuse parent's graph
+            warnings: this.warnings,
+            exceptionRoutes: this.exceptionRoutes ? new Map(this.exceptionRoutes) : new Map(),
+            enterActions: this.enterActions ? new Map(this.enterActions) : new Map(),
+            exitActions: this.exitActions ? new Map(this.exitActions) : new Map(),
         });
         return result;
     }
@@ -92,7 +110,10 @@ class Builder {
     transitions = [];
     errorTransitions = new Map();
     _exceptionRoutes = new Map();
+    _enterActions = new Map();
+    _exitActions = new Map();
     initiallyAvailableKeys = [];
+    _perpetual = false;
     constructor(name, stateConfig) {
         this.name = name;
         this.stateConfig = stateConfig;
@@ -125,6 +146,18 @@ class Builder {
         }
         return this;
     }
+    /** Callback when entering a state (pure data/metrics, no I/O). */
+    onStateEnter(state, action) {
+        this._enterActions.set(state, action);
+        return this;
+    }
+    /** Callback when exiting a state (pure data/metrics, no I/O). */
+    onStateExit(state, action) {
+        this._exitActions.set(state, action);
+        return this;
+    }
+    /** Allow perpetual flows (no terminal states). Skips path-to-terminal validation. */
+    allowPerpetual() { this._perpetual = true; return this; }
     /** @internal */
     addTransition(t) { this.transitions.push(t); }
     build() {
@@ -162,6 +195,8 @@ class Builder {
         }
         result.warnings = warnings;
         result.exceptionRoutes = new Map(this._exceptionRoutes);
+        result.enterActions = new Map(this._enterActions);
+        result.exitActions = new Map(this._exitActions);
         return result;
     }
     validate(def) {
@@ -170,9 +205,10 @@ class Builder {
             errors.push('No initial state found (exactly one state must have initial=true)');
         }
         this.checkReachability(def, errors);
-        this.checkPathToTerminal(def, errors);
+        if (!this._perpetual)
+            this.checkPathToTerminal(def, errors);
         this.checkDag(def, errors);
-        this.checkExternalUniqueness(def, errors);
+        // checkExternalUniqueness removed (DD-020: multi-external allowed)
         this.checkBranchCompleteness(def, errors);
         this.checkRequiresProduces(def, errors);
         this.checkAutoExternalConflict(def, errors);
@@ -277,17 +313,6 @@ class Builder {
         inStack.delete(node);
         return false;
     }
-    checkExternalUniqueness(def, errors) {
-        const counts = new Map();
-        for (const t of def.transitions) {
-            if (t.type === 'external')
-                counts.set(t.from, (counts.get(t.from) ?? 0) + 1);
-        }
-        for (const [state, count] of counts) {
-            if (count > 1)
-                errors.push(`State ${state} has ${count} external transitions (max 1)`);
-        }
-    }
     checkBranchCompleteness(def, errors) {
         const allStates = new Set(def.allStates());
         for (const t of def.transitions) {

package/dist/cjs/flow-engine.d.ts

@@ -6,22 +6,36 @@ export declare const DEFAULT_MAX_CHAIN_DEPTH = 10;
 /** Log entry types for tramli's pluggable logger API. */
 export interface TransitionLogEntry {
     flowId: string;
+    flowName: string;
     from: string | null;
     to: string;
     trigger: string;
+    durationMicros: number;
 }
 export interface StateLogEntry {
     flowId: string;
+    flowName: string;
     state: string;
     key: string;
     value: unknown;
 }
 export interface ErrorLogEntry {
     flowId: string;
+    flowName: string;
     from: string | null;
     to: string | null;
     trigger: string;
     cause: Error | null;
+    durationMicros: number;
+}
+export interface GuardLogEntry {
+    flowId: string;
+    flowName: string;
+    state: string;
+    guardName: string;
+    result: 'accepted' | 'rejected' | 'expired';
+    reason?: string;
+    durationMicros: number;
 }
 export declare class FlowEngine {
     private readonly store;
@@ -30,6 +44,7 @@ export declare class FlowEngine {
     private transitionLogger?;
     private stateLogger?;
     private errorLogger?;
+    private guardLogger?;
     constructor(store: InMemoryFlowStore, options?: {
         strictMode?: boolean;
         maxChainDepth?: number;
@@ -37,6 +52,7 @@ export declare class FlowEngine {
     setTransitionLogger(logger: ((entry: TransitionLogEntry) => void) | null): void;
     setStateLogger(logger: ((entry: StateLogEntry) => void) | null): void;
     setErrorLogger(logger: ((entry: ErrorLogEntry) => void) | null): void;
+    setGuardLogger(logger: ((entry: GuardLogEntry) => void) | null): void;
     removeAllLoggers(): void;
     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>>;
@@ -44,5 +60,10 @@ export declare class FlowEngine {
     private executeSubFlow;
     private resumeSubFlow;
     private verifyProduces;
+    private fireEnter;
+    private fireExit;
+    private logTransition;
+    private logError;
+    private logGuard;
     private handleError;
 }

package/dist/cjs/flow-engine.js

@@ -13,6 +13,7 @@ class FlowEngine {
     transitionLogger;
     stateLogger;
     errorLogger;
+    guardLogger;
     constructor(store, options) {
         this.store = store;
         this.strictMode = options?.strictMode ?? false;
@@ -27,10 +28,14 @@ class FlowEngine {
     setErrorLogger(logger) {
         this.errorLogger = logger ?? undefined;
     }
+    setGuardLogger(logger) {
+        this.guardLogger = logger ?? undefined;
+    }
     removeAllLoggers() {
         this.transitionLogger = undefined;
         this.stateLogger = undefined;
         this.errorLogger = undefined;
+        this.guardLogger = undefined;
     }
     async startFlow(definition, sessionId, initialData) {
         const flowId = crypto.randomUUID();
@@ -65,9 +70,22 @@ class FlowEngine {
             return this.resumeSubFlow(flow, definition);
         }
         const currentState = flow.currentState;
-        const transition = definition.externalFrom(currentState);
-        if (!transition)
+        // Multi-external: select guard by requires matching
+        const externals = definition.externalsFrom(currentState);
+        if (externals.length === 0)
             throw flow_error_js_1.FlowError.invalidTransition(currentState, currentState);
+        let transition;
+        const dataKeys = externalData ? new Set(externalData.keys()) : new Set();
+        for (const ext of externals) {
+            if (ext.guard && ext.guard.requires.every(r => dataKeys.has(r))) {
+                transition = ext;
+                break;
+            }
+        }
+        if (!transition) {
+            // Fallback: first external
+            transition = externals[0];
+        }
         // Per-state timeout check
         if (transition.timeout != null) {
             const deadline = new Date(flow.stateEnteredAt.getTime() + transition.timeout);
@@ -79,9 +97,13 @@ class FlowEngine {
         }
         const guard = transition.guard;
         if (guard) {
+            const guardStart = this.guardLogger ? performance.now() : 0;
             const output = await guard.validate(flow.context);
+            const guardDurationMicros = this.guardLogger ? Math.round((performance.now() - guardStart) * 1000) : 0;
             switch (output.type) {
                 case 'accepted': {
+                    this.logGuard(flow, currentState, guard.name, 'accepted', guardDurationMicros);
+                    const transStart = this.transitionLogger ? performance.now() : 0;
                     const backup = flow.context.snapshot();
                     if (output.data) {
                         for (const [key, value] of output.data)
@@ -91,8 +113,11 @@ class FlowEngine {
                         if (transition.processor)
                             await transition.processor.process(flow.context);
                         const from = flow.currentState;
+                        this.fireExit(flow, from);
                         flow.transitionTo(transition.to);
+                        this.fireEnter(flow, transition.to);
                         this.store.recordTransition(flow.id, from, transition.to, guard.name, flow.context);
+                        this.logTransition(flow, from, transition.to, guard.name, transStart);
                     }
                     catch (e) {
                         flow.context.restoreFrom(backup);
@@ -103,7 +128,8 @@ class FlowEngine {
                     break;
                 }
                 case 'rejected': {
-                    flow.incrementGuardFailure();
+                    this.logGuard(flow, currentState, guard.name, 'rejected', guardDurationMicros, output.reason);
+                    flow.incrementGuardFailure(guard.name);
                     if (flow.guardFailureCount >= definition.maxGuardRetries) {
                         this.handleError(flow, currentState);
                     }
@@ -111,6 +137,7 @@ class FlowEngine {
                     return flow;
                 }
                 case 'expired': {
+                    this.logGuard(flow, currentState, guard.name, 'expired', guardDurationMicros);
                     flow.complete('EXPIRED');
                     this.store.save(flow);
                     return flow;
@@ -118,9 +145,13 @@ class FlowEngine {
             }
         }
         else {
+            const transStart = this.transitionLogger ? performance.now() : 0;
             const from = flow.currentState;
+            this.fireExit(flow, from);
             flow.transitionTo(transition.to);
+            this.fireEnter(flow, transition.to);
             this.store.recordTransition(flow.id, from, transition.to, 'external', flow.context);
+            this.logTransition(flow, from, transition.to, 'external', transStart);
         }
         await this.executeAutoChain(flow);
         this.store.save(flow);
@@ -148,6 +179,7 @@ class FlowEngine {
             if (!autoOrBranch)
                 break;
             const backup = flow.context.snapshot();
+            const stepStart = this.transitionLogger ? performance.now() : 0;
             try {
                 if (autoOrBranch.type === 'auto') {
                     if (autoOrBranch.processor) {
@@ -155,8 +187,12 @@ class FlowEngine {
                         this.verifyProduces(autoOrBranch.processor, flow.context);
                     }
                     const from = flow.currentState;
+                    this.fireExit(flow, from);
                     flow.transitionTo(autoOrBranch.to);
-                    this.store.recordTransition(flow.id, from, autoOrBranch.to, autoOrBranch.processor?.name ?? 'auto', flow.context);
+                    this.fireEnter(flow, autoOrBranch.to);
+                    const trigger = autoOrBranch.processor?.name ?? 'auto';
+                    this.store.recordTransition(flow.id, from, autoOrBranch.to, trigger, flow.context);
+                    this.logTransition(flow, from, autoOrBranch.to, trigger, stepStart);
                 }
                 else {
                     const branch = autoOrBranch.branch;
@@ -169,8 +205,12 @@ class FlowEngine {
                     if (specific.processor)
                         await specific.processor.process(flow.context);
                     const from = flow.currentState;
+                    this.fireExit(flow, from);
                     flow.transitionTo(target);
-                    this.store.recordTransition(flow.id, from, target, `${branch.name}:${label}`, flow.context);
+                    this.fireEnter(flow, target);
+                    const trigger = `${branch.name}:${label}`;
+                    this.store.recordTransition(flow.id, from, target, trigger, flow.context);
+                    this.logTransition(flow, from, target, trigger, stepStart);
                 }
             }
             catch (e) {
@@ -194,9 +234,14 @@ class FlowEngine {
             parentFlow.setActiveSubFlow(null);
             const target = exitMappings.get(subFlow.exitState);
             if (target) {
+                const sfStart = this.transitionLogger ? performance.now() : 0;
                 const from = parentFlow.currentState;
+                this.fireExit(parentFlow, from);
                 parentFlow.transitionTo(target);
-                this.store.recordTransition(parentFlow.id, from, target, `subFlow:${subDef.name}/${subFlow.exitState}`, parentFlow.context);
+                this.fireEnter(parentFlow, target);
+                const trigger = `subFlow:${subDef.name}/${subFlow.exitState}`;
+                this.store.recordTransition(parentFlow.id, from, target, trigger, parentFlow.context);
+                this.logTransition(parentFlow, from, target, trigger, sfStart);
                 return 1;
             }
             // Error bubbling: no exit mapping → fall back to parent's error transitions
@@ -214,14 +259,20 @@ class FlowEngine {
         }
         const guard = transition.guard;
         if (guard) {
+            const guardStart = this.guardLogger ? performance.now() : 0;
             const output = await guard.validate(parentFlow.context);
+            const guardDur = this.guardLogger ? Math.round((performance.now() - guardStart) * 1000) : 0;
             if (output.type === 'accepted') {
                 if (output.data) {
                     for (const [key, value] of output.data)
                         parentFlow.context.put(key, value);
                 }
+                const sfStart = this.transitionLogger ? performance.now() : 0;
+                const sfFrom = subFlow.currentState;
                 subFlow.transitionTo(transition.to);
-                this.store.recordTransition(parentFlow.id, subFlow.currentState, transition.to, guard.name, parentFlow.context);
+                this.store.recordTransition(parentFlow.id, sfFrom, transition.to, guard.name, parentFlow.context);
+                this.logTransition(parentFlow, sfFrom, transition.to, guard.name, sfStart);
+                this.logGuard(parentFlow, sfFrom, guard.name, 'accepted', guardDur);
             }
             else if (output.type === 'rejected') {
                 subFlow.incrementGuardFailure();
@@ -248,9 +299,14 @@ class FlowEngine {
             if (subFlowT?.exitMappings) {
                 const target = subFlowT.exitMappings.get(subFlow.exitState);
                 if (target) {
+                    const exitStart = this.transitionLogger ? performance.now() : 0;
                     const from = parentFlow.currentState;
+                    this.fireExit(parentFlow, from);
                     parentFlow.transitionTo(target);
-                    this.store.recordTransition(parentFlow.id, from, target, `subFlow:${subDef.name}/${subFlow.exitState}`, parentFlow.context);
+                    this.fireEnter(parentFlow, target);
+                    const trigger = `subFlow:${subDef.name}/${subFlow.exitState}`;
+                    this.store.recordTransition(parentFlow.id, from, target, trigger, parentFlow.context);
+                    this.logTransition(parentFlow, from, target, trigger, exitStart);
                     await this.executeAutoChain(parentFlow);
                 }
             }
@@ -267,7 +323,33 @@ class FlowEngine {
             }
         }
     }
+    fireEnter(flow, state) {
+        const action = flow.definition.enterAction(state);
+        if (action)
+            action(flow.context);
+    }
+    fireExit(flow, state) {
+        const action = flow.definition.exitAction(state);
+        if (action)
+            action(flow.context);
+    }
+    logTransition(flow, from, to, trigger, startMs) {
+        if (this.transitionLogger) {
+            const durationMicros = Math.round((performance.now() - startMs) * 1000);
+            this.transitionLogger({ flowId: flow.id, flowName: flow.definition.name, from, to, trigger, durationMicros });
+        }
+    }
+    logError(flow, from, to, trigger, cause, startMs) {
+        if (this.errorLogger) {
+            const durationMicros = Math.round((performance.now() - startMs) * 1000);
+            this.errorLogger({ flowId: flow.id, flowName: flow.definition.name, from, to, trigger, cause, durationMicros });
+        }
+    }
+    logGuard(flow, state, guardName, result, durationMicros, reason) {
+        this.guardLogger?.({ flowId: flow.id, flowName: flow.definition.name, state, guardName, result, reason, durationMicros });
+    }
     handleError(flow, fromState, cause) {
+        const errorStart = (this.transitionLogger || this.errorLogger) ? performance.now() : 0;
         if (cause) {
             flow.setLastError(`${cause.constructor.name}: ${cause.message}`);
             if (cause instanceof flow_error_js_1.FlowError) {
@@ -277,7 +359,7 @@ class FlowEngine {
                 cause.withContextSnapshot(available, new Set());
             }
         }
-        this.errorLogger?.({ flowId: flow.id, from: fromState, to: null, trigger: 'error', cause: cause ?? null });
+        this.logError(flow, fromState, null, 'error', cause ?? null, errorStart);
         // 1. Try exception-typed routes first (onStepError)
         if (cause && flow.definition.exceptionRoutes) {
             const routes = flow.definition.exceptionRoutes.get(fromState);
@@ -286,8 +368,10 @@ class FlowEngine {
                     if (cause instanceof route.errorClass) {
                         const from = flow.currentState;
                         flow.transitionTo(route.target);
-                        this.store.recordTransition(flow.id, from, route.target, `error:${cause.constructor.name}`, flow.context);
-                        if (flow.definition.stateConfig[route.target].terminal)
+                        const trigger = `error:${cause.constructor.name}`;
+                        this.store.recordTransition(flow.id, from, route.target, trigger, flow.context);
+                        this.logTransition(flow, from, route.target, trigger, errorStart);
+                        if (flow.definition.stateConfig[route.target]?.terminal)
                             flow.complete(route.target);
                         return;
                     }
@@ -300,7 +384,8 @@ class FlowEngine {
             const from = flow.currentState;
             flow.transitionTo(errorTarget);
             this.store.recordTransition(flow.id, from, errorTarget, 'error', flow.context);
-            if (flow.definition.stateConfig[errorTarget].terminal)
+            this.logTransition(flow, from, errorTarget, 'error', errorStart);
+            if (flow.definition.stateConfig[errorTarget]?.terminal)
                 flow.complete(errorTarget);
         }
         else {

package/dist/cjs/flow-instance.d.ts

@@ -7,6 +7,7 @@ export declare class FlowInstance<S extends string> {
     readonly context: FlowContext;
     private _currentState;
     private _guardFailureCount;
+    private _guardFailureCounts;
     private _version;
     readonly createdAt: Date;
     readonly expiresAt: Date;
@@ -22,6 +23,8 @@ export declare class FlowInstance<S extends string> {
     static restore<S extends string>(id: string, sessionId: string, definition: FlowDefinition<S>, context: FlowContext, currentState: S, createdAt: Date, expiresAt: Date, guardFailureCount: number, version: number, exitState: string | null): FlowInstance<S>;
     get currentState(): S;
     get guardFailureCount(): number;
+    /** Guard failure count for a specific guard (by name). */
+    guardFailureCountFor(guardName: string): number;
     get version(): number;
     get exitState(): string | null;
     get isCompleted(): boolean;
@@ -42,7 +45,7 @@ export declare class FlowInstance<S extends string> {
     withVersion(newVersion: number): FlowInstance<S>;
     get stateEnteredAt(): Date;
     /** @internal */ transitionTo(state: S): void;
-    /** @internal */ incrementGuardFailure(): void;
+    /** @internal */ incrementGuardFailure(guardName?: string): void;
     /** @internal */ complete(exitState: string): void;
     /** @internal */ setVersion(version: number): void;
     /** @internal */ setActiveSubFlow(sub: FlowInstance<any> | null): void;

package/dist/cjs/flow-instance.js

@@ -8,6 +8,7 @@ class FlowInstance {
     context;
     _currentState;
     _guardFailureCount;
+    _guardFailureCounts = new Map();
     _version;
     createdAt;
     expiresAt;
@@ -48,6 +49,8 @@ class FlowInstance {
     }
     get currentState() { return this._currentState; }
     get guardFailureCount() { return this._guardFailureCount; }
+    /** Guard failure count for a specific guard (by name). */
+    guardFailureCountFor(guardName) { return this._guardFailureCounts.get(guardName) ?? 0; }
     get version() { return this._version; }
     get exitState() { return this._exitState; }
     get isCompleted() { return this._exitState !== null; }
@@ -100,8 +103,20 @@ class FlowInstance {
         return copy;
     }
     get stateEnteredAt() { return this._stateEnteredAt; }
-    /** @internal */ transitionTo(state) { this._currentState = state; this._stateEnteredAt = new Date(); }
-    /** @internal */ incrementGuardFailure() { this._guardFailureCount++; }
+    /** @internal */ transitionTo(state) {
+        const stateChanged = this._currentState !== state;
+        this._currentState = state;
+        this._stateEnteredAt = new Date();
+        if (stateChanged) {
+            this._guardFailureCount = 0;
+            this._guardFailureCounts.clear();
+        }
+    }
+    /** @internal */ incrementGuardFailure(guardName) {
+        this._guardFailureCount++;
+        if (guardName)
+            this._guardFailureCounts.set(guardName, (this._guardFailureCounts.get(guardName) ?? 0) + 1);
+    }
     /** @internal */ complete(exitState) { this._exitState = exitState; }
     /** @internal */ setVersion(version) { this._version = version; }
     /** @internal */ setActiveSubFlow(sub) { this._activeSubFlow = sub; }

package/dist/cjs/index.d.ts

@@ -1,6 +1,6 @@
 export { Tramli } from './tramli.js';
 export { FlowEngine } from './flow-engine.js';
-export type { TransitionLogEntry, StateLogEntry, ErrorLogEntry } from './flow-engine.js';
+export type { TransitionLogEntry, StateLogEntry, ErrorLogEntry, GuardLogEntry } from './flow-engine.js';
 export { FlowContext } from './flow-context.js';
 export { FlowInstance } from './flow-instance.js';
 export { FlowDefinition, Builder, FromBuilder, BranchBuilder, SubFlowBuilder } from './flow-definition.js';

package/dist/cjs/pipeline.js

@@ -92,14 +92,16 @@ class Pipeline {
         const completed = [];
         let prev = 'initial';
         for (const step of this.steps) {
-            this.transitionLogger?.({ flowId, from: prev, to: step.name, trigger: step.name });
+            const stepStart = (this.transitionLogger || this.errorLogger) ? performance.now() : 0;
+            this.transitionLogger?.({ flowId, flowName: this.name, from: prev, to: step.name, trigger: step.name, durationMicros: 0 });
             const keysBefore = this.stateLogger ? new Set(ctx.snapshot().keys()) : null;
             try {
                 await step.process(ctx);
             }
             catch (e) {
                 const err = e instanceof Error ? e : new Error(String(e));
-                this.errorLogger?.({ flowId, from: prev, to: step.name, trigger: step.name, cause: err });
+                const durationMicros = Math.round((performance.now() - stepStart) * 1000);
+                this.errorLogger?.({ flowId, flowName: this.name, from: prev, to: step.name, trigger: step.name, cause: err, durationMicros });
                 throw new PipelineException(step.name, [...completed], ctx, err);
             }
             if (this.strictMode) {
@@ -113,7 +115,7 @@ class Pipeline {
             if (this.stateLogger && keysBefore) {
                 for (const [k] of ctx.snapshot()) {
                     if (!keysBefore.has(k)) {
-                        this.stateLogger({ flowId, state: step.name, key: k, value: ctx.snapshot().get(k) });
+                        this.stateLogger({ flowId, flowName: this.name, state: step.name, key: k, value: ctx.snapshot().get(k) });
                     }
                 }
             }

package/dist/esm/flow-context.d.ts

@@ -9,6 +9,8 @@ export declare class FlowContext {
     readonly flowId: string;
     readonly createdAt: Date;
     private attributes;
+    private aliasToKey;
+    private keyToAlias;
     constructor(flowId: string, createdAt?: Date, attributes?: Map<string, unknown>);
     get<T>(key: FlowKey<T>): T;
     find<T>(key: FlowKey<T>): T | undefined;
@@ -16,4 +18,14 @@ export declare class FlowContext {
     has(key: FlowKey<unknown>): boolean;
     snapshot(): Map<string, unknown>;
     restoreFrom(snapshot: Map<string, unknown>): void;
+    /** Register a string alias for a FlowKey. Used for cross-language serialization. */
+    registerAlias(key: FlowKey<unknown>, alias: string): void;
+    /** Get the alias for a key (if registered). */
+    aliasOf(key: FlowKey<unknown>): string | undefined;
+    /** Get the key for an alias (if registered). */
+    keyOfAlias(alias: string): FlowKey<unknown> | undefined;
+    /** Export all registered aliases as a map (alias → key). */
+    toAliasMap(): Map<string, string>;
+    /** Import aliases from a map (alias → key). */
+    fromAliasMap(map: Map<string, string>): void;
 }

package/dist/esm/flow-context.js

@@ -9,6 +9,8 @@ export class FlowContext {
     flowId;
     createdAt;
     attributes;
+    aliasToKey = new Map();
+    keyToAlias = new Map();
     constructor(flowId, createdAt, attributes) {
         this.flowId = flowId;
         this.createdAt = createdAt ?? new Date();
@@ -37,4 +39,29 @@ export class FlowContext {
         for (const [k, v] of snapshot)
             this.attributes.set(k, v);
     }
+    // ─── Alias support (for cross-language serialization) ──────────────────
+    /** Register a string alias for a FlowKey. Used for cross-language serialization. */
+    registerAlias(key, alias) {
+        this.aliasToKey.set(alias, key);
+        this.keyToAlias.set(key, alias);
+    }
+    /** Get the alias for a key (if registered). */
+    aliasOf(key) {
+        return this.keyToAlias.get(key);
+    }
+    /** Get the key for an alias (if registered). */
+    keyOfAlias(alias) {
+        return this.aliasToKey.get(alias);
+    }
+    /** Export all registered aliases as a map (alias → key). */
+    toAliasMap() {
+        return new Map(this.aliasToKey);
+    }
+    /** Import aliases from a map (alias → key). */
+    fromAliasMap(map) {
+        for (const [alias, key] of map) {
+            this.aliasToKey.set(alias, key);
+            this.keyToAlias.set(key, alias);
+        }
+    }
 }

package/dist/esm/flow-definition.d.ts

@@ -16,9 +16,17 @@ export declare class FlowDefinition<S extends string> {
         errorClass: new (...args: any[]) => Error;
         target: S;
     }>>;
+    readonly enterActions: Map<S, (ctx: import('./flow-context.js').FlowContext) => void>;
+    readonly exitActions: Map<S, (ctx: import('./flow-context.js').FlowContext) => void>;
+    /** Get enter action for a state (or undefined). */
+    enterAction(state: S): ((ctx: import('./flow-context.js').FlowContext) => void) | undefined;
+    /** Get exit action for a state (or undefined). */
+    exitAction(state: S): ((ctx: import('./flow-context.js').FlowContext) => void) | undefined;
     private constructor();
     transitionsFrom(state: S): Transition<S>[];
     externalFrom(state: S): Transition<S> | undefined;
+    /** All external transitions from a state (for multi-external). */
+    externalsFrom(state: S): Transition<S>[];
     allStates(): S[];
     /**
      * Create a new FlowDefinition with a sub-flow inserted before a specific transition.
@@ -34,7 +42,10 @@ export declare class Builder<S extends string> {
     private readonly transitions;
     private readonly errorTransitions;
     private readonly _exceptionRoutes;
+    private readonly _enterActions;
+    private readonly _exitActions;
     private readonly initiallyAvailableKeys;
+    private _perpetual;
     constructor(name: string, stateConfig: Record<S, StateConfig>);
     initiallyAvailable(...keys: FlowKey<unknown>[]): this;
     setTtl(ms: number): this;
@@ -44,6 +55,12 @@ export declare class Builder<S extends string> {
     /** Route specific error types to specific states. Checked before onError. */
     onStepError(from: S, errorClass: new (...args: any[]) => Error, to: S): this;
     onAnyError(errorState: S): this;
+    /** Callback when entering a state (pure data/metrics, no I/O). */
+    onStateEnter(state: S, action: (ctx: import('./flow-context.js').FlowContext) => void): this;
+    /** Callback when exiting a state (pure data/metrics, no I/O). */
+    onStateExit(state: S, action: (ctx: import('./flow-context.js').FlowContext) => void): this;
+    /** Allow perpetual flows (no terminal states). Skips path-to-terminal validation. */
+    allowPerpetual(): this;
     /** @internal */
     addTransition(t: Transition<S>): void;
     build(): FlowDefinition<S>;
@@ -53,7 +70,6 @@ export declare class Builder<S extends string> {
     private canReachTerminal;
     private checkDag;
     private hasCycle;
-    private checkExternalUniqueness;
     private checkBranchCompleteness;
     private checkRequiresProduces;
     private checkRequiresProducesFrom;

package/dist/esm/flow-definition.js

@@ -12,6 +12,16 @@ export class FlowDefinition {
     dataFlowGraph;
     warnings;
     exceptionRoutes;
+    enterActions;
+    exitActions;
+    /** Get enter action for a state (or undefined). */
+    enterAction(state) {
+        return this.enterActions?.get(state);
+    }
+    /** Get exit action for a state (or undefined). */
+    exitAction(state) {
+        return this.exitActions?.get(state);
+    }
     constructor(name, stateConfig, ttl, maxGuardRetries, transitions, errorTransitions) {
         this.name = name;
         this.stateConfig = stateConfig;
@@ -36,6 +46,10 @@ export class FlowDefinition {
     externalFrom(state) {
         return this.transitions.find(t => t.from === state && t.type === 'external');
     }
+    /** All external transitions from a state (for multi-external). */
+    externalsFrom(state) {
+        return this.transitions.filter(t => t.from === state && t.type === 'external');
+    }
     allStates() {
         return Object.keys(this.stateConfig);
     }
@@ -72,6 +86,10 @@ export class FlowDefinition {
             initialState: this.initialState,
             terminalStates: this.terminalStates,
             dataFlowGraph: this.dataFlowGraph, // reuse parent's graph
+            warnings: this.warnings,
+            exceptionRoutes: this.exceptionRoutes ? new Map(this.exceptionRoutes) : new Map(),
+            enterActions: this.enterActions ? new Map(this.enterActions) : new Map(),
+            exitActions: this.exitActions ? new Map(this.exitActions) : new Map(),
         });
         return result;
     }
@@ -88,7 +106,10 @@ export class Builder {
     transitions = [];
     errorTransitions = new Map();
     _exceptionRoutes = new Map();
+    _enterActions = new Map();
+    _exitActions = new Map();
     initiallyAvailableKeys = [];
+    _perpetual = false;
     constructor(name, stateConfig) {
         this.name = name;
         this.stateConfig = stateConfig;
@@ -121,6 +142,18 @@ export class Builder {
         }
         return this;
     }
+    /** Callback when entering a state (pure data/metrics, no I/O). */
+    onStateEnter(state, action) {
+        this._enterActions.set(state, action);
+        return this;
+    }
+    /** Callback when exiting a state (pure data/metrics, no I/O). */
+    onStateExit(state, action) {
+        this._exitActions.set(state, action);
+        return this;
+    }
+    /** Allow perpetual flows (no terminal states). Skips path-to-terminal validation. */
+    allowPerpetual() { this._perpetual = true; return this; }
     /** @internal */
     addTransition(t) { this.transitions.push(t); }
     build() {
@@ -158,6 +191,8 @@ export class Builder {
         }
         result.warnings = warnings;
         result.exceptionRoutes = new Map(this._exceptionRoutes);
+        result.enterActions = new Map(this._enterActions);
+        result.exitActions = new Map(this._exitActions);
         return result;
     }
     validate(def) {
@@ -166,9 +201,10 @@ export class Builder {
             errors.push('No initial state found (exactly one state must have initial=true)');
         }
         this.checkReachability(def, errors);
-        this.checkPathToTerminal(def, errors);
+        if (!this._perpetual)
+            this.checkPathToTerminal(def, errors);
         this.checkDag(def, errors);
-        this.checkExternalUniqueness(def, errors);
+        // checkExternalUniqueness removed (DD-020: multi-external allowed)
         this.checkBranchCompleteness(def, errors);
         this.checkRequiresProduces(def, errors);
         this.checkAutoExternalConflict(def, errors);
@@ -273,17 +309,6 @@ export class Builder {
         inStack.delete(node);
         return false;
     }
-    checkExternalUniqueness(def, errors) {
-        const counts = new Map();
-        for (const t of def.transitions) {
-            if (t.type === 'external')
-                counts.set(t.from, (counts.get(t.from) ?? 0) + 1);
-        }
-        for (const [state, count] of counts) {
-            if (count > 1)
-                errors.push(`State ${state} has ${count} external transitions (max 1)`);
-        }
-    }
     checkBranchCompleteness(def, errors) {
         const allStates = new Set(def.allStates());
         for (const t of def.transitions) {

package/dist/esm/flow-engine.d.ts

@@ -6,22 +6,36 @@ export declare const DEFAULT_MAX_CHAIN_DEPTH = 10;
 /** Log entry types for tramli's pluggable logger API. */
 export interface TransitionLogEntry {
     flowId: string;
+    flowName: string;
     from: string | null;
     to: string;
     trigger: string;
+    durationMicros: number;
 }
 export interface StateLogEntry {
     flowId: string;
+    flowName: string;
     state: string;
     key: string;
     value: unknown;
 }
 export interface ErrorLogEntry {
     flowId: string;
+    flowName: string;
     from: string | null;
     to: string | null;
     trigger: string;
     cause: Error | null;
+    durationMicros: number;
+}
+export interface GuardLogEntry {
+    flowId: string;
+    flowName: string;
+    state: string;
+    guardName: string;
+    result: 'accepted' | 'rejected' | 'expired';
+    reason?: string;
+    durationMicros: number;
 }
 export declare class FlowEngine {
     private readonly store;
@@ -30,6 +44,7 @@ export declare class FlowEngine {
     private transitionLogger?;
     private stateLogger?;
     private errorLogger?;
+    private guardLogger?;
     constructor(store: InMemoryFlowStore, options?: {
         strictMode?: boolean;
         maxChainDepth?: number;
@@ -37,6 +52,7 @@ export declare class FlowEngine {
     setTransitionLogger(logger: ((entry: TransitionLogEntry) => void) | null): void;
     setStateLogger(logger: ((entry: StateLogEntry) => void) | null): void;
     setErrorLogger(logger: ((entry: ErrorLogEntry) => void) | null): void;
+    setGuardLogger(logger: ((entry: GuardLogEntry) => void) | null): void;
     removeAllLoggers(): void;
     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>>;
@@ -44,5 +60,10 @@ export declare class FlowEngine {
     private executeSubFlow;
     private resumeSubFlow;
     private verifyProduces;
+    private fireEnter;
+    private fireExit;
+    private logTransition;
+    private logError;
+    private logGuard;
     private handleError;
 }

package/dist/esm/flow-engine.js

@@ -10,6 +10,7 @@ export class FlowEngine {
     transitionLogger;
     stateLogger;
     errorLogger;
+    guardLogger;
     constructor(store, options) {
         this.store = store;
         this.strictMode = options?.strictMode ?? false;
@@ -24,10 +25,14 @@ export class FlowEngine {
     setErrorLogger(logger) {
         this.errorLogger = logger ?? undefined;
     }
+    setGuardLogger(logger) {
+        this.guardLogger = logger ?? undefined;
+    }
     removeAllLoggers() {
         this.transitionLogger = undefined;
         this.stateLogger = undefined;
         this.errorLogger = undefined;
+        this.guardLogger = undefined;
     }
     async startFlow(definition, sessionId, initialData) {
         const flowId = crypto.randomUUID();
@@ -62,9 +67,22 @@ export class FlowEngine {
             return this.resumeSubFlow(flow, definition);
         }
         const currentState = flow.currentState;
-        const transition = definition.externalFrom(currentState);
-        if (!transition)
+        // Multi-external: select guard by requires matching
+        const externals = definition.externalsFrom(currentState);
+        if (externals.length === 0)
             throw FlowError.invalidTransition(currentState, currentState);
+        let transition;
+        const dataKeys = externalData ? new Set(externalData.keys()) : new Set();
+        for (const ext of externals) {
+            if (ext.guard && ext.guard.requires.every(r => dataKeys.has(r))) {
+                transition = ext;
+                break;
+            }
+        }
+        if (!transition) {
+            // Fallback: first external
+            transition = externals[0];
+        }
         // Per-state timeout check
         if (transition.timeout != null) {
             const deadline = new Date(flow.stateEnteredAt.getTime() + transition.timeout);
@@ -76,9 +94,13 @@ export class FlowEngine {
         }
         const guard = transition.guard;
         if (guard) {
+            const guardStart = this.guardLogger ? performance.now() : 0;
             const output = await guard.validate(flow.context);
+            const guardDurationMicros = this.guardLogger ? Math.round((performance.now() - guardStart) * 1000) : 0;
             switch (output.type) {
                 case 'accepted': {
+                    this.logGuard(flow, currentState, guard.name, 'accepted', guardDurationMicros);
+                    const transStart = this.transitionLogger ? performance.now() : 0;
                     const backup = flow.context.snapshot();
                     if (output.data) {
                         for (const [key, value] of output.data)
@@ -88,8 +110,11 @@ export class FlowEngine {
                         if (transition.processor)
                             await transition.processor.process(flow.context);
                         const from = flow.currentState;
+                        this.fireExit(flow, from);
                         flow.transitionTo(transition.to);
+                        this.fireEnter(flow, transition.to);
                         this.store.recordTransition(flow.id, from, transition.to, guard.name, flow.context);
+                        this.logTransition(flow, from, transition.to, guard.name, transStart);
                     }
                     catch (e) {
                         flow.context.restoreFrom(backup);
@@ -100,7 +125,8 @@ export class FlowEngine {
                     break;
                 }
                 case 'rejected': {
-                    flow.incrementGuardFailure();
+                    this.logGuard(flow, currentState, guard.name, 'rejected', guardDurationMicros, output.reason);
+                    flow.incrementGuardFailure(guard.name);
                     if (flow.guardFailureCount >= definition.maxGuardRetries) {
                         this.handleError(flow, currentState);
                     }
@@ -108,6 +134,7 @@ export class FlowEngine {
                     return flow;
                 }
                 case 'expired': {
+                    this.logGuard(flow, currentState, guard.name, 'expired', guardDurationMicros);
                     flow.complete('EXPIRED');
                     this.store.save(flow);
                     return flow;
@@ -115,9 +142,13 @@ export class FlowEngine {
             }
         }
         else {
+            const transStart = this.transitionLogger ? performance.now() : 0;
             const from = flow.currentState;
+            this.fireExit(flow, from);
             flow.transitionTo(transition.to);
+            this.fireEnter(flow, transition.to);
             this.store.recordTransition(flow.id, from, transition.to, 'external', flow.context);
+            this.logTransition(flow, from, transition.to, 'external', transStart);
         }
         await this.executeAutoChain(flow);
         this.store.save(flow);
@@ -145,6 +176,7 @@ export class FlowEngine {
             if (!autoOrBranch)
                 break;
             const backup = flow.context.snapshot();
+            const stepStart = this.transitionLogger ? performance.now() : 0;
             try {
                 if (autoOrBranch.type === 'auto') {
                     if (autoOrBranch.processor) {
@@ -152,8 +184,12 @@ export class FlowEngine {
                         this.verifyProduces(autoOrBranch.processor, flow.context);
                     }
                     const from = flow.currentState;
+                    this.fireExit(flow, from);
                     flow.transitionTo(autoOrBranch.to);
-                    this.store.recordTransition(flow.id, from, autoOrBranch.to, autoOrBranch.processor?.name ?? 'auto', flow.context);
+                    this.fireEnter(flow, autoOrBranch.to);
+                    const trigger = autoOrBranch.processor?.name ?? 'auto';
+                    this.store.recordTransition(flow.id, from, autoOrBranch.to, trigger, flow.context);
+                    this.logTransition(flow, from, autoOrBranch.to, trigger, stepStart);
                 }
                 else {
                     const branch = autoOrBranch.branch;
@@ -166,8 +202,12 @@ export class FlowEngine {
                     if (specific.processor)
                         await specific.processor.process(flow.context);
                     const from = flow.currentState;
+                    this.fireExit(flow, from);
                     flow.transitionTo(target);
-                    this.store.recordTransition(flow.id, from, target, `${branch.name}:${label}`, flow.context);
+                    this.fireEnter(flow, target);
+                    const trigger = `${branch.name}:${label}`;
+                    this.store.recordTransition(flow.id, from, target, trigger, flow.context);
+                    this.logTransition(flow, from, target, trigger, stepStart);
                 }
             }
             catch (e) {
@@ -191,9 +231,14 @@ export class FlowEngine {
             parentFlow.setActiveSubFlow(null);
             const target = exitMappings.get(subFlow.exitState);
             if (target) {
+                const sfStart = this.transitionLogger ? performance.now() : 0;
                 const from = parentFlow.currentState;
+                this.fireExit(parentFlow, from);
                 parentFlow.transitionTo(target);
-                this.store.recordTransition(parentFlow.id, from, target, `subFlow:${subDef.name}/${subFlow.exitState}`, parentFlow.context);
+                this.fireEnter(parentFlow, target);
+                const trigger = `subFlow:${subDef.name}/${subFlow.exitState}`;
+                this.store.recordTransition(parentFlow.id, from, target, trigger, parentFlow.context);
+                this.logTransition(parentFlow, from, target, trigger, sfStart);
                 return 1;
             }
             // Error bubbling: no exit mapping → fall back to parent's error transitions
@@ -211,14 +256,20 @@ export class FlowEngine {
         }
         const guard = transition.guard;
         if (guard) {
+            const guardStart = this.guardLogger ? performance.now() : 0;
             const output = await guard.validate(parentFlow.context);
+            const guardDur = this.guardLogger ? Math.round((performance.now() - guardStart) * 1000) : 0;
             if (output.type === 'accepted') {
                 if (output.data) {
                     for (const [key, value] of output.data)
                         parentFlow.context.put(key, value);
                 }
+                const sfStart = this.transitionLogger ? performance.now() : 0;
+                const sfFrom = subFlow.currentState;
                 subFlow.transitionTo(transition.to);
-                this.store.recordTransition(parentFlow.id, subFlow.currentState, transition.to, guard.name, parentFlow.context);
+                this.store.recordTransition(parentFlow.id, sfFrom, transition.to, guard.name, parentFlow.context);
+                this.logTransition(parentFlow, sfFrom, transition.to, guard.name, sfStart);
+                this.logGuard(parentFlow, sfFrom, guard.name, 'accepted', guardDur);
             }
             else if (output.type === 'rejected') {
                 subFlow.incrementGuardFailure();
@@ -245,9 +296,14 @@ export class FlowEngine {
             if (subFlowT?.exitMappings) {
                 const target = subFlowT.exitMappings.get(subFlow.exitState);
                 if (target) {
+                    const exitStart = this.transitionLogger ? performance.now() : 0;
                     const from = parentFlow.currentState;
+                    this.fireExit(parentFlow, from);
                     parentFlow.transitionTo(target);
-                    this.store.recordTransition(parentFlow.id, from, target, `subFlow:${subDef.name}/${subFlow.exitState}`, parentFlow.context);
+                    this.fireEnter(parentFlow, target);
+                    const trigger = `subFlow:${subDef.name}/${subFlow.exitState}`;
+                    this.store.recordTransition(parentFlow.id, from, target, trigger, parentFlow.context);
+                    this.logTransition(parentFlow, from, target, trigger, exitStart);
                     await this.executeAutoChain(parentFlow);
                 }
             }
@@ -264,7 +320,33 @@ export class FlowEngine {
             }
         }
     }
+    fireEnter(flow, state) {
+        const action = flow.definition.enterAction(state);
+        if (action)
+            action(flow.context);
+    }
+    fireExit(flow, state) {
+        const action = flow.definition.exitAction(state);
+        if (action)
+            action(flow.context);
+    }
+    logTransition(flow, from, to, trigger, startMs) {
+        if (this.transitionLogger) {
+            const durationMicros = Math.round((performance.now() - startMs) * 1000);
+            this.transitionLogger({ flowId: flow.id, flowName: flow.definition.name, from, to, trigger, durationMicros });
+        }
+    }
+    logError(flow, from, to, trigger, cause, startMs) {
+        if (this.errorLogger) {
+            const durationMicros = Math.round((performance.now() - startMs) * 1000);
+            this.errorLogger({ flowId: flow.id, flowName: flow.definition.name, from, to, trigger, cause, durationMicros });
+        }
+    }
+    logGuard(flow, state, guardName, result, durationMicros, reason) {
+        this.guardLogger?.({ flowId: flow.id, flowName: flow.definition.name, state, guardName, result, reason, durationMicros });
+    }
     handleError(flow, fromState, cause) {
+        const errorStart = (this.transitionLogger || this.errorLogger) ? performance.now() : 0;
         if (cause) {
             flow.setLastError(`${cause.constructor.name}: ${cause.message}`);
             if (cause instanceof FlowError) {
@@ -274,7 +356,7 @@ export class FlowEngine {
                 cause.withContextSnapshot(available, new Set());
             }
         }
-        this.errorLogger?.({ flowId: flow.id, from: fromState, to: null, trigger: 'error', cause: cause ?? null });
+        this.logError(flow, fromState, null, 'error', cause ?? null, errorStart);
         // 1. Try exception-typed routes first (onStepError)
         if (cause && flow.definition.exceptionRoutes) {
             const routes = flow.definition.exceptionRoutes.get(fromState);
@@ -283,8 +365,10 @@ export class FlowEngine {
                     if (cause instanceof route.errorClass) {
                         const from = flow.currentState;
                         flow.transitionTo(route.target);
-                        this.store.recordTransition(flow.id, from, route.target, `error:${cause.constructor.name}`, flow.context);
-                        if (flow.definition.stateConfig[route.target].terminal)
+                        const trigger = `error:${cause.constructor.name}`;
+                        this.store.recordTransition(flow.id, from, route.target, trigger, flow.context);
+                        this.logTransition(flow, from, route.target, trigger, errorStart);
+                        if (flow.definition.stateConfig[route.target]?.terminal)
                             flow.complete(route.target);
                         return;
                     }
@@ -297,7 +381,8 @@ export class FlowEngine {
             const from = flow.currentState;
             flow.transitionTo(errorTarget);
             this.store.recordTransition(flow.id, from, errorTarget, 'error', flow.context);
-            if (flow.definition.stateConfig[errorTarget].terminal)
+            this.logTransition(flow, from, errorTarget, 'error', errorStart);
+            if (flow.definition.stateConfig[errorTarget]?.terminal)
                 flow.complete(errorTarget);
         }
         else {

package/dist/esm/flow-instance.d.ts

@@ -7,6 +7,7 @@ export declare class FlowInstance<S extends string> {
     readonly context: FlowContext;
     private _currentState;
     private _guardFailureCount;
+    private _guardFailureCounts;
     private _version;
     readonly createdAt: Date;
     readonly expiresAt: Date;
@@ -22,6 +23,8 @@ export declare class FlowInstance<S extends string> {
     static restore<S extends string>(id: string, sessionId: string, definition: FlowDefinition<S>, context: FlowContext, currentState: S, createdAt: Date, expiresAt: Date, guardFailureCount: number, version: number, exitState: string | null): FlowInstance<S>;
     get currentState(): S;
     get guardFailureCount(): number;
+    /** Guard failure count for a specific guard (by name). */
+    guardFailureCountFor(guardName: string): number;
     get version(): number;
     get exitState(): string | null;
     get isCompleted(): boolean;
@@ -42,7 +45,7 @@ export declare class FlowInstance<S extends string> {
     withVersion(newVersion: number): FlowInstance<S>;
     get stateEnteredAt(): Date;
     /** @internal */ transitionTo(state: S): void;
-    /** @internal */ incrementGuardFailure(): void;
+    /** @internal */ incrementGuardFailure(guardName?: string): void;
     /** @internal */ complete(exitState: string): void;
     /** @internal */ setVersion(version: number): void;
     /** @internal */ setActiveSubFlow(sub: FlowInstance<any> | null): void;

package/dist/esm/flow-instance.js

@@ -5,6 +5,7 @@ export class FlowInstance {
     context;
     _currentState;
     _guardFailureCount;
+    _guardFailureCounts = new Map();
     _version;
     createdAt;
     expiresAt;
@@ -45,6 +46,8 @@ export class FlowInstance {
     }
     get currentState() { return this._currentState; }
     get guardFailureCount() { return this._guardFailureCount; }
+    /** Guard failure count for a specific guard (by name). */
+    guardFailureCountFor(guardName) { return this._guardFailureCounts.get(guardName) ?? 0; }
     get version() { return this._version; }
     get exitState() { return this._exitState; }
     get isCompleted() { return this._exitState !== null; }
@@ -97,8 +100,20 @@ export class FlowInstance {
         return copy;
     }
     get stateEnteredAt() { return this._stateEnteredAt; }
-    /** @internal */ transitionTo(state) { this._currentState = state; this._stateEnteredAt = new Date(); }
-    /** @internal */ incrementGuardFailure() { this._guardFailureCount++; }
+    /** @internal */ transitionTo(state) {
+        const stateChanged = this._currentState !== state;
+        this._currentState = state;
+        this._stateEnteredAt = new Date();
+        if (stateChanged) {
+            this._guardFailureCount = 0;
+            this._guardFailureCounts.clear();
+        }
+    }
+    /** @internal */ incrementGuardFailure(guardName) {
+        this._guardFailureCount++;
+        if (guardName)
+            this._guardFailureCounts.set(guardName, (this._guardFailureCounts.get(guardName) ?? 0) + 1);
+    }
     /** @internal */ complete(exitState) { this._exitState = exitState; }
     /** @internal */ setVersion(version) { this._version = version; }
     /** @internal */ setActiveSubFlow(sub) { this._activeSubFlow = sub; }

package/dist/esm/index.d.ts

@@ -1,6 +1,6 @@
 export { Tramli } from './tramli.js';
 export { FlowEngine } from './flow-engine.js';
-export type { TransitionLogEntry, StateLogEntry, ErrorLogEntry } from './flow-engine.js';
+export type { TransitionLogEntry, StateLogEntry, ErrorLogEntry, GuardLogEntry } from './flow-engine.js';
 export { FlowContext } from './flow-context.js';
 export { FlowInstance } from './flow-instance.js';
 export { FlowDefinition, Builder, FromBuilder, BranchBuilder, SubFlowBuilder } from './flow-definition.js';

package/dist/esm/pipeline.js

@@ -87,14 +87,16 @@ export class Pipeline {
         const completed = [];
         let prev = 'initial';
         for (const step of this.steps) {
-            this.transitionLogger?.({ flowId, from: prev, to: step.name, trigger: step.name });
+            const stepStart = (this.transitionLogger || this.errorLogger) ? performance.now() : 0;
+            this.transitionLogger?.({ flowId, flowName: this.name, from: prev, to: step.name, trigger: step.name, durationMicros: 0 });
             const keysBefore = this.stateLogger ? new Set(ctx.snapshot().keys()) : null;
             try {
                 await step.process(ctx);
             }
             catch (e) {
                 const err = e instanceof Error ? e : new Error(String(e));
-                this.errorLogger?.({ flowId, from: prev, to: step.name, trigger: step.name, cause: err });
+                const durationMicros = Math.round((performance.now() - stepStart) * 1000);
+                this.errorLogger?.({ flowId, flowName: this.name, from: prev, to: step.name, trigger: step.name, cause: err, durationMicros });
                 throw new PipelineException(step.name, [...completed], ctx, err);
             }
             if (this.strictMode) {
@@ -108,7 +110,7 @@ export class Pipeline {
             if (this.stateLogger && keysBefore) {
                 for (const [k] of ctx.snapshot()) {
                     if (!keysBefore.has(k)) {
-                        this.stateLogger({ flowId, state: step.name, key: k, value: ctx.snapshot().get(k) });
+                        this.stateLogger({ flowId, flowName: this.name, state: step.name, key: k, value: ctx.snapshot().get(k) });
                     }
                 }
             }

package/package.json

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