@unlaxer/tramli 3.2.0 → 3.4.0

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

@@ -88,5 +88,5 @@ export declare class DataFlowGraph<S extends string> {
     private static collectEdges;
     /** Version compatibility: check if v1 instances can resume on v2 definition. */
     static versionCompatibility<S extends string>(before: DataFlowGraph<S>, after: DataFlowGraph<S>): string[];
-    static build<S extends string>(def: FlowDefinition<S>, initiallyAvailable: string[]): DataFlowGraph<S>;
+    static build<S extends string>(def: FlowDefinition<S>, initiallyAvailable: string[], externallyProvided?: string[]): DataFlowGraph<S>;
 }

package/dist/cjs/data-flow-graph.js

@@ -370,14 +370,15 @@ class DataFlowGraph {
         return issues;
     }
     // ─── Builder ─────────────────────────────────────────────
-    static build(def, initiallyAvailable) {
+    static build(def, initiallyAvailable, externallyProvided = []) {
         const stateAvail = new Map();
         const producers = new Map();
         const consumers = new Map();
         const allProduced = new Set(initiallyAvailable);
         const allConsumed = new Set();
+        const extSet = new Set(externallyProvided);
         if (def.initialState) {
-            traverse(def, def.initialState, new Set(initiallyAvailable), stateAvail, producers, consumers, allProduced, allConsumed);
+            traverse(def, def.initialState, new Set(initiallyAvailable), extSet, stateAvail, producers, consumers, allProduced, allConsumed);
             // Mark initially available types as produced by "initial"
             for (const key of initiallyAvailable) {
                 if (!producers.has(key))
@@ -391,7 +392,7 @@ class DataFlowGraph {
     }
 }
 exports.DataFlowGraph = DataFlowGraph;
-function traverse(def, state, available, stateAvail, producers, consumers, allProduced, allConsumed) {
+function traverse(def, state, available, externallyProvided, stateAvail, producers, consumers, allProduced, allConsumed) {
     if (stateAvail.has(state)) {
         const existing = stateAvail.get(state);
         let isSubset = true;
@@ -413,6 +414,10 @@ function traverse(def, state, available, stateAvail, producers, consumers, allPr
     }
     for (const t of def.transitionsFrom(state)) {
         const newAvail = new Set(stateAvail.get(state));
+        if (t.type === 'external') {
+            for (const k of externallyProvided)
+                newAvail.add(k);
+        }
         if (t.guard) {
             for (const req of t.guard.requires) {
                 addTo(consumers, req, { name: t.guard.name, fromState: t.from, toState: t.to, kind: 'guard' });
@@ -441,7 +446,7 @@ function traverse(def, state, available, stateAvail, producers, consumers, allPr
                 newAvail.add(prod);
             }
         }
-        traverse(def, t.to, newAvail, stateAvail, producers, consumers, allProduced, allConsumed);
+        traverse(def, t.to, newAvail, externallyProvided, stateAvail, producers, consumers, allProduced, allConsumed);
     }
 }
 function addTo(map, key, info) {

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

@@ -45,9 +45,12 @@ export declare class Builder<S extends string> {
     private readonly _enterActions;
     private readonly _exitActions;
     private readonly initiallyAvailableKeys;
+    private readonly externallyProvidedKeys;
     private _perpetual;
     constructor(name: string, stateConfig: Record<S, StateConfig>);
     initiallyAvailable(...keys: FlowKey<unknown>[]): this;
+    /** Declare data keys injected via resumeAndExecute(externalData), not available at start. */
+    externallyProvided(...keys: FlowKey<unknown>[]): this;
     setTtl(ms: number): this;
     setMaxGuardRetries(max: number): this;
     from(state: S): FromBuilder<S>;

package/dist/cjs/flow-definition.js

@@ -113,6 +113,7 @@ class Builder {
     _enterActions = new Map();
     _exitActions = new Map();
     initiallyAvailableKeys = [];
+    externallyProvidedKeys = [];
     _perpetual = false;
     constructor(name, stateConfig) {
         this.name = name;
@@ -123,6 +124,12 @@ class Builder {
             this.initiallyAvailableKeys.push(k);
         return this;
     }
+    /** Declare data keys injected via resumeAndExecute(externalData), not available at start. */
+    externallyProvided(...keys) {
+        for (const k of keys)
+            this.externallyProvidedKeys.push(k);
+        return this;
+    }
     setTtl(ms) { this.ttl = ms; return this; }
     setMaxGuardRetries(max) { this.maxGuardRetries = max; return this; }
     from(state) {
@@ -185,7 +192,7 @@ class Builder {
         result.terminalStates = terminals;
         result.dataFlowGraph = null;
         this.validate(result);
-        result.dataFlowGraph = data_flow_graph_js_1.DataFlowGraph.build(result, this.initiallyAvailableKeys);
+        result.dataFlowGraph = data_flow_graph_js_1.DataFlowGraph.build(result, this.initiallyAvailableKeys, this.externallyProvidedKeys);
         // Build warnings
         const warnings = [];
         const perpetual = terminals.size === 0;
@@ -354,6 +361,10 @@ class Builder {
         }
         for (const t of def.transitionsFrom(state)) {
             const newAvailable = new Set(stateAvailable.get(state));
+            if (t.type === 'external') {
+                for (const k of this.externallyProvidedKeys)
+                    newAvailable.add(k);
+            }
             if (t.guard) {
                 for (const req of t.guard.requires) {
                     if (!newAvailable.has(req))
@@ -534,6 +545,7 @@ class BranchBuilder {
                 processor: this.processors.get(label),
                 guard: undefined, branch: this.branch,
                 branchTargets: new Map(this.targets),
+                branchLabel: label,
             });
         }
         return this.builder;

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

@@ -10,6 +10,7 @@ export interface TransitionLogEntry {
     from: string | null;
     to: string;
     trigger: string;
+    durationMicros: number;
 }
 export interface StateLogEntry {
     flowId: string;
@@ -25,6 +26,7 @@ export interface ErrorLogEntry {
     to: string | null;
     trigger: string;
     cause: Error | null;
+    durationMicros: number;
 }
 export interface GuardLogEntry {
     flowId: string;
@@ -33,6 +35,7 @@ export interface GuardLogEntry {
     guardName: string;
     result: 'accepted' | 'rejected' | 'expired';
     reason?: string;
+    durationMicros: number;
 }
 export declare class FlowEngine {
     private readonly store;

package/dist/cjs/flow-engine.js

@@ -97,10 +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');
+                    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)
@@ -114,7 +117,7 @@ class FlowEngine {
                         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);
+                        this.logTransition(flow, from, transition.to, guard.name, transStart);
                     }
                     catch (e) {
                         flow.context.restoreFrom(backup);
@@ -125,7 +128,7 @@ class FlowEngine {
                     break;
                 }
                 case 'rejected': {
-                    this.logGuard(flow, currentState, guard.name, 'rejected', output.reason);
+                    this.logGuard(flow, currentState, guard.name, 'rejected', guardDurationMicros, output.reason);
                     flow.incrementGuardFailure(guard.name);
                     if (flow.guardFailureCount >= definition.maxGuardRetries) {
                         this.handleError(flow, currentState);
@@ -134,7 +137,7 @@ class FlowEngine {
                     return flow;
                 }
                 case 'expired': {
-                    this.logGuard(flow, currentState, guard.name, 'expired');
+                    this.logGuard(flow, currentState, guard.name, 'expired', guardDurationMicros);
                     flow.complete('EXPIRED');
                     this.store.save(flow);
                     return flow;
@@ -142,12 +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');
+            this.logTransition(flow, from, transition.to, 'external', transStart);
         }
         await this.executeAutoChain(flow);
         this.store.save(flow);
@@ -175,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) {
@@ -187,7 +192,7 @@ class FlowEngine {
                     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);
+                    this.logTransition(flow, from, autoOrBranch.to, trigger, stepStart);
                 }
                 else {
                     const branch = autoOrBranch.branch;
@@ -196,7 +201,7 @@ class FlowEngine {
                     if (!target) {
                         throw new flow_error_js_1.FlowError('UNKNOWN_BRANCH', `Branch '${branch.name}' returned unknown label: ${label}`);
                     }
-                    const specific = transitions.find(t => t.type === 'branch' && t.to === target) ?? autoOrBranch;
+                    const specific = transitions.find(t => t.type === 'branch' && t.branchLabel === label) ?? transitions.find(t => t.type === 'branch' && t.to === target) ?? autoOrBranch;
                     if (specific.processor)
                         await specific.processor.process(flow.context);
                     const from = flow.currentState;
@@ -205,7 +210,7 @@ class FlowEngine {
                     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);
+                    this.logTransition(flow, from, target, trigger, stepStart);
                 }
             }
             catch (e) {
@@ -229,13 +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.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);
+                this.logTransition(parentFlow, from, target, trigger, sfStart);
                 return 1;
             }
             // Error bubbling: no exit mapping → fall back to parent's error transitions
@@ -253,17 +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, sfFrom, transition.to, guard.name, parentFlow.context);
-                this.logTransition(parentFlow, sfFrom, transition.to, guard.name);
-                this.logGuard(parentFlow, sfFrom, guard.name, 'accepted');
+                this.logTransition(parentFlow, sfFrom, transition.to, guard.name, sfStart);
+                this.logGuard(parentFlow, sfFrom, guard.name, 'accepted', guardDur);
             }
             else if (output.type === 'rejected') {
                 subFlow.incrementGuardFailure();
@@ -290,13 +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.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);
+                    this.logTransition(parentFlow, from, target, trigger, exitStart);
                     await this.executeAutoChain(parentFlow);
                 }
             }
@@ -323,16 +333,23 @@ class FlowEngine {
         if (action)
             action(flow.context);
     }
-    logTransition(flow, from, to, trigger) {
-        this.transitionLogger?.({ flowId: flow.id, flowName: flow.definition.name, from, to, trigger });
+    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) {
-        this.errorLogger?.({ flowId: flow.id, flowName: flow.definition.name, from, to, trigger, cause });
+    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, reason) {
-        this.guardLogger?.({ flowId: flow.id, flowName: flow.definition.name, state, guardName, result, reason });
+    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) {
@@ -342,7 +359,7 @@ class FlowEngine {
                 cause.withContextSnapshot(available, new Set());
             }
         }
-        this.logError(flow, fromState, null, 'error', 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);
@@ -353,7 +370,7 @@ class FlowEngine {
                         flow.transitionTo(route.target);
                         const trigger = `error:${cause.constructor.name}`;
                         this.store.recordTransition(flow.id, from, route.target, trigger, flow.context);
-                        this.logTransition(flow, from, route.target, trigger);
+                        this.logTransition(flow, from, route.target, trigger, errorStart);
                         if (flow.definition.stateConfig[route.target]?.terminal)
                             flow.complete(route.target);
                         return;
@@ -367,7 +384,7 @@ class FlowEngine {
             const from = flow.currentState;
             flow.transitionTo(errorTarget);
             this.store.recordTransition(flow.id, from, errorTarget, 'error', flow.context);
-            this.logTransition(flow, from, errorTarget, 'error');
+            this.logTransition(flow, from, errorTarget, 'error', errorStart);
             if (flow.definition.stateConfig[errorTarget]?.terminal)
                 flow.complete(errorTarget);
         }

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, flowName: this.name, 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, flowName: this.name, 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) {

package/dist/cjs/types.d.ts

@@ -26,6 +26,8 @@ export interface Transition<S extends string> {
     guard?: TransitionGuard<S>;
     branch?: BranchProcessor<S>;
     branchTargets: Map<string, S>;
+    /** Label assigned by builder .to(target, label, processor). Used for branch label-specific processor matching. */
+    branchLabel?: string;
     subFlowDefinition?: import('./flow-definition.js').FlowDefinition<any>;
     exitMappings?: Map<string, S>;
     /** Per-state timeout in milliseconds. If set, resumeAndExecute checks this before guard. */

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

@@ -88,5 +88,5 @@ export declare class DataFlowGraph<S extends string> {
     private static collectEdges;
     /** Version compatibility: check if v1 instances can resume on v2 definition. */
     static versionCompatibility<S extends string>(before: DataFlowGraph<S>, after: DataFlowGraph<S>): string[];
-    static build<S extends string>(def: FlowDefinition<S>, initiallyAvailable: string[]): DataFlowGraph<S>;
+    static build<S extends string>(def: FlowDefinition<S>, initiallyAvailable: string[], externallyProvided?: string[]): DataFlowGraph<S>;
 }

package/dist/esm/data-flow-graph.js

@@ -367,14 +367,15 @@ export class DataFlowGraph {
         return issues;
     }
     // ─── Builder ─────────────────────────────────────────────
-    static build(def, initiallyAvailable) {
+    static build(def, initiallyAvailable, externallyProvided = []) {
         const stateAvail = new Map();
         const producers = new Map();
         const consumers = new Map();
         const allProduced = new Set(initiallyAvailable);
         const allConsumed = new Set();
+        const extSet = new Set(externallyProvided);
         if (def.initialState) {
-            traverse(def, def.initialState, new Set(initiallyAvailable), stateAvail, producers, consumers, allProduced, allConsumed);
+            traverse(def, def.initialState, new Set(initiallyAvailable), extSet, stateAvail, producers, consumers, allProduced, allConsumed);
             // Mark initially available types as produced by "initial"
             for (const key of initiallyAvailable) {
                 if (!producers.has(key))
@@ -387,7 +388,7 @@ export class DataFlowGraph {
         return new DataFlowGraph(stateAvail, producers, consumers, allProduced, allConsumed);
     }
 }
-function traverse(def, state, available, stateAvail, producers, consumers, allProduced, allConsumed) {
+function traverse(def, state, available, externallyProvided, stateAvail, producers, consumers, allProduced, allConsumed) {
     if (stateAvail.has(state)) {
         const existing = stateAvail.get(state);
         let isSubset = true;
@@ -409,6 +410,10 @@ function traverse(def, state, available, stateAvail, producers, consumers, allPr
     }
     for (const t of def.transitionsFrom(state)) {
         const newAvail = new Set(stateAvail.get(state));
+        if (t.type === 'external') {
+            for (const k of externallyProvided)
+                newAvail.add(k);
+        }
         if (t.guard) {
             for (const req of t.guard.requires) {
                 addTo(consumers, req, { name: t.guard.name, fromState: t.from, toState: t.to, kind: 'guard' });
@@ -437,7 +442,7 @@ function traverse(def, state, available, stateAvail, producers, consumers, allPr
                 newAvail.add(prod);
             }
         }
-        traverse(def, t.to, newAvail, stateAvail, producers, consumers, allProduced, allConsumed);
+        traverse(def, t.to, newAvail, externallyProvided, stateAvail, producers, consumers, allProduced, allConsumed);
     }
 }
 function addTo(map, key, info) {

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

@@ -45,9 +45,12 @@ export declare class Builder<S extends string> {
     private readonly _enterActions;
     private readonly _exitActions;
     private readonly initiallyAvailableKeys;
+    private readonly externallyProvidedKeys;
     private _perpetual;
     constructor(name: string, stateConfig: Record<S, StateConfig>);
     initiallyAvailable(...keys: FlowKey<unknown>[]): this;
+    /** Declare data keys injected via resumeAndExecute(externalData), not available at start. */
+    externallyProvided(...keys: FlowKey<unknown>[]): this;
     setTtl(ms: number): this;
     setMaxGuardRetries(max: number): this;
     from(state: S): FromBuilder<S>;

package/dist/esm/flow-definition.js

@@ -109,6 +109,7 @@ export class Builder {
     _enterActions = new Map();
     _exitActions = new Map();
     initiallyAvailableKeys = [];
+    externallyProvidedKeys = [];
     _perpetual = false;
     constructor(name, stateConfig) {
         this.name = name;
@@ -119,6 +120,12 @@ export class Builder {
             this.initiallyAvailableKeys.push(k);
         return this;
     }
+    /** Declare data keys injected via resumeAndExecute(externalData), not available at start. */
+    externallyProvided(...keys) {
+        for (const k of keys)
+            this.externallyProvidedKeys.push(k);
+        return this;
+    }
     setTtl(ms) { this.ttl = ms; return this; }
     setMaxGuardRetries(max) { this.maxGuardRetries = max; return this; }
     from(state) {
@@ -181,7 +188,7 @@ export class Builder {
         result.terminalStates = terminals;
         result.dataFlowGraph = null;
         this.validate(result);
-        result.dataFlowGraph = DataFlowGraph.build(result, this.initiallyAvailableKeys);
+        result.dataFlowGraph = DataFlowGraph.build(result, this.initiallyAvailableKeys, this.externallyProvidedKeys);
         // Build warnings
         const warnings = [];
         const perpetual = terminals.size === 0;
@@ -350,6 +357,10 @@ export class Builder {
         }
         for (const t of def.transitionsFrom(state)) {
             const newAvailable = new Set(stateAvailable.get(state));
+            if (t.type === 'external') {
+                for (const k of this.externallyProvidedKeys)
+                    newAvailable.add(k);
+            }
             if (t.guard) {
                 for (const req of t.guard.requires) {
                     if (!newAvailable.has(req))
@@ -527,6 +538,7 @@ export class BranchBuilder {
                 processor: this.processors.get(label),
                 guard: undefined, branch: this.branch,
                 branchTargets: new Map(this.targets),
+                branchLabel: label,
             });
         }
         return this.builder;

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

@@ -10,6 +10,7 @@ export interface TransitionLogEntry {
     from: string | null;
     to: string;
     trigger: string;
+    durationMicros: number;
 }
 export interface StateLogEntry {
     flowId: string;
@@ -25,6 +26,7 @@ export interface ErrorLogEntry {
     to: string | null;
     trigger: string;
     cause: Error | null;
+    durationMicros: number;
 }
 export interface GuardLogEntry {
     flowId: string;
@@ -33,6 +35,7 @@ export interface GuardLogEntry {
     guardName: string;
     result: 'accepted' | 'rejected' | 'expired';
     reason?: string;
+    durationMicros: number;
 }
 export declare class FlowEngine {
     private readonly store;

package/dist/esm/flow-engine.js

@@ -94,10 +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');
+                    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)
@@ -111,7 +114,7 @@ export class FlowEngine {
                         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);
+                        this.logTransition(flow, from, transition.to, guard.name, transStart);
                     }
                     catch (e) {
                         flow.context.restoreFrom(backup);
@@ -122,7 +125,7 @@ export class FlowEngine {
                     break;
                 }
                 case 'rejected': {
-                    this.logGuard(flow, currentState, guard.name, 'rejected', output.reason);
+                    this.logGuard(flow, currentState, guard.name, 'rejected', guardDurationMicros, output.reason);
                     flow.incrementGuardFailure(guard.name);
                     if (flow.guardFailureCount >= definition.maxGuardRetries) {
                         this.handleError(flow, currentState);
@@ -131,7 +134,7 @@ export class FlowEngine {
                     return flow;
                 }
                 case 'expired': {
-                    this.logGuard(flow, currentState, guard.name, 'expired');
+                    this.logGuard(flow, currentState, guard.name, 'expired', guardDurationMicros);
                     flow.complete('EXPIRED');
                     this.store.save(flow);
                     return flow;
@@ -139,12 +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');
+            this.logTransition(flow, from, transition.to, 'external', transStart);
         }
         await this.executeAutoChain(flow);
         this.store.save(flow);
@@ -172,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) {
@@ -184,7 +189,7 @@ export class FlowEngine {
                     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);
+                    this.logTransition(flow, from, autoOrBranch.to, trigger, stepStart);
                 }
                 else {
                     const branch = autoOrBranch.branch;
@@ -193,7 +198,7 @@ export class FlowEngine {
                     if (!target) {
                         throw new FlowError('UNKNOWN_BRANCH', `Branch '${branch.name}' returned unknown label: ${label}`);
                     }
-                    const specific = transitions.find(t => t.type === 'branch' && t.to === target) ?? autoOrBranch;
+                    const specific = transitions.find(t => t.type === 'branch' && t.branchLabel === label) ?? transitions.find(t => t.type === 'branch' && t.to === target) ?? autoOrBranch;
                     if (specific.processor)
                         await specific.processor.process(flow.context);
                     const from = flow.currentState;
@@ -202,7 +207,7 @@ export class FlowEngine {
                     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);
+                    this.logTransition(flow, from, target, trigger, stepStart);
                 }
             }
             catch (e) {
@@ -226,13 +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.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);
+                this.logTransition(parentFlow, from, target, trigger, sfStart);
                 return 1;
             }
             // Error bubbling: no exit mapping → fall back to parent's error transitions
@@ -250,17 +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, sfFrom, transition.to, guard.name, parentFlow.context);
-                this.logTransition(parentFlow, sfFrom, transition.to, guard.name);
-                this.logGuard(parentFlow, sfFrom, guard.name, 'accepted');
+                this.logTransition(parentFlow, sfFrom, transition.to, guard.name, sfStart);
+                this.logGuard(parentFlow, sfFrom, guard.name, 'accepted', guardDur);
             }
             else if (output.type === 'rejected') {
                 subFlow.incrementGuardFailure();
@@ -287,13 +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.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);
+                    this.logTransition(parentFlow, from, target, trigger, exitStart);
                     await this.executeAutoChain(parentFlow);
                 }
             }
@@ -320,16 +330,23 @@ export class FlowEngine {
         if (action)
             action(flow.context);
     }
-    logTransition(flow, from, to, trigger) {
-        this.transitionLogger?.({ flowId: flow.id, flowName: flow.definition.name, from, to, trigger });
+    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) {
-        this.errorLogger?.({ flowId: flow.id, flowName: flow.definition.name, from, to, trigger, cause });
+    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, reason) {
-        this.guardLogger?.({ flowId: flow.id, flowName: flow.definition.name, state, guardName, result, reason });
+    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) {
@@ -339,7 +356,7 @@ export class FlowEngine {
                 cause.withContextSnapshot(available, new Set());
             }
         }
-        this.logError(flow, fromState, null, 'error', 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);
@@ -350,7 +367,7 @@ export class FlowEngine {
                         flow.transitionTo(route.target);
                         const trigger = `error:${cause.constructor.name}`;
                         this.store.recordTransition(flow.id, from, route.target, trigger, flow.context);
-                        this.logTransition(flow, from, route.target, trigger);
+                        this.logTransition(flow, from, route.target, trigger, errorStart);
                         if (flow.definition.stateConfig[route.target]?.terminal)
                             flow.complete(route.target);
                         return;
@@ -364,7 +381,7 @@ export class FlowEngine {
             const from = flow.currentState;
             flow.transitionTo(errorTarget);
             this.store.recordTransition(flow.id, from, errorTarget, 'error', flow.context);
-            this.logTransition(flow, from, errorTarget, 'error');
+            this.logTransition(flow, from, errorTarget, 'error', errorStart);
             if (flow.definition.stateConfig[errorTarget]?.terminal)
                 flow.complete(errorTarget);
         }

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, flowName: this.name, 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, flowName: this.name, 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) {

package/dist/esm/types.d.ts

@@ -26,6 +26,8 @@ export interface Transition<S extends string> {
     guard?: TransitionGuard<S>;
     branch?: BranchProcessor<S>;
     branchTargets: Map<string, S>;
+    /** Label assigned by builder .to(target, label, processor). Used for branch label-specific processor matching. */
+    branchLabel?: string;
     subFlowDefinition?: import('./flow-definition.js').FlowDefinition<any>;
     exitMappings?: Map<string, S>;
     /** Per-state timeout in milliseconds. If set, resumeAndExecute checks this before guard. */

package/package.json

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