@unlaxer/tramli 0.1.0

package/dist/flow-context.d.ts

@@ -0,0 +1,19 @@
+import type { FlowKey } from './flow-key.js';
+/**
+ * Accumulator for flow data. Keyed by FlowKey — each key appears at most once.
+ *
+ * Use dedicated FlowKey instances as keys (e.g., flowKey<OrderRequest>('OrderRequest')),
+ * not raw strings. Putting the same key twice silently overwrites the previous value.
+ */
+export declare class FlowContext {
+    readonly flowId: string;
+    readonly createdAt: Date;
+    private attributes;
+    constructor(flowId: string, createdAt?: Date, attributes?: Map<string, unknown>);
+    get<T>(key: FlowKey<T>): T;
+    find<T>(key: FlowKey<T>): T | undefined;
+    put<T>(key: FlowKey<T>, value: T): void;
+    has(key: FlowKey<unknown>): boolean;
+    snapshot(): Map<string, unknown>;
+    restoreFrom(snapshot: Map<string, unknown>): void;
+}

package/dist/flow-context.js

@@ -0,0 +1,40 @@
+import { FlowError } from './flow-error.js';
+/**
+ * Accumulator for flow data. Keyed by FlowKey — each key appears at most once.
+ *
+ * Use dedicated FlowKey instances as keys (e.g., flowKey<OrderRequest>('OrderRequest')),
+ * not raw strings. Putting the same key twice silently overwrites the previous value.
+ */
+export class FlowContext {
+    flowId;
+    createdAt;
+    attributes;
+    constructor(flowId, createdAt, attributes) {
+        this.flowId = flowId;
+        this.createdAt = createdAt ?? new Date();
+        this.attributes = new Map(attributes ?? []);
+    }
+    get(key) {
+        const value = this.attributes.get(key);
+        if (value === undefined)
+            throw FlowError.missingContext(key);
+        return value;
+    }
+    find(key) {
+        return this.attributes.get(key);
+    }
+    put(key, value) {
+        this.attributes.set(key, value);
+    }
+    has(key) {
+        return this.attributes.has(key);
+    }
+    snapshot() {
+        return new Map(this.attributes);
+    }
+    restoreFrom(snapshot) {
+        this.attributes.clear();
+        for (const [k, v] of snapshot)
+            this.attributes.set(k, v);
+    }
+}

package/dist/flow-definition.d.ts

@@ -0,0 +1,66 @@
+import type { FlowKey } from './flow-key.js';
+import type { StateConfig, Transition, StateProcessor, TransitionGuard, BranchProcessor } from './types.js';
+export declare class FlowDefinition<S extends string> {
+    readonly name: string;
+    readonly stateConfig: Record<S, StateConfig>;
+    readonly ttl: number;
+    readonly maxGuardRetries: number;
+    readonly transitions: Transition<S>[];
+    readonly errorTransitions: Map<S, S>;
+    readonly initialState: S | null;
+    readonly terminalStates: Set<S>;
+    private constructor();
+    transitionsFrom(state: S): Transition<S>[];
+    externalFrom(state: S): Transition<S> | undefined;
+    allStates(): S[];
+    static builder<S extends string>(name: string, stateConfig: Record<S, StateConfig>): Builder<S>;
+}
+export declare class Builder<S extends string> {
+    private readonly name;
+    private readonly stateConfig;
+    private ttl;
+    private maxGuardRetries;
+    private readonly transitions;
+    private readonly errorTransitions;
+    private readonly initiallyAvailableKeys;
+    constructor(name: string, stateConfig: Record<S, StateConfig>);
+    initiallyAvailable(...keys: FlowKey<unknown>[]): this;
+    setTtl(ms: number): this;
+    setMaxGuardRetries(max: number): this;
+    from(state: S): FromBuilder<S>;
+    onError(from: S, to: S): this;
+    onAnyError(errorState: S): this;
+    /** @internal */
+    addTransition(t: Transition<S>): void;
+    build(): FlowDefinition<S>;
+    private validate;
+    private checkReachability;
+    private checkPathToTerminal;
+    private canReachTerminal;
+    private checkDag;
+    private hasCycle;
+    private checkExternalUniqueness;
+    private checkBranchCompleteness;
+    private checkRequiresProduces;
+    private checkRequiresProducesFrom;
+    private checkAutoExternalConflict;
+    private checkTerminalNoOutgoing;
+}
+export declare class FromBuilder<S extends string> {
+    private readonly builder;
+    private readonly fromState;
+    constructor(builder: Builder<S>, fromState: S);
+    auto(to: S, processor: StateProcessor<S>): Builder<S>;
+    external(to: S, guard: TransitionGuard<S>, processor?: StateProcessor<S>): Builder<S>;
+    branch(branch: BranchProcessor<S>): BranchBuilder<S>;
+}
+export declare class BranchBuilder<S extends string> {
+    private readonly builder;
+    private readonly fromState;
+    private readonly branch;
+    private readonly targets;
+    private readonly processors;
+    constructor(builder: Builder<S>, fromState: S, branch: BranchProcessor<S>);
+    to(state: S, label: string, processor?: StateProcessor<S>): this;
+    endBranch(): Builder<S>;
+}

package/dist/flow-definition.js

@@ -0,0 +1,346 @@
+import { FlowError } from './flow-error.js';
+export class FlowDefinition {
+    name;
+    stateConfig;
+    ttl; // milliseconds
+    maxGuardRetries;
+    transitions;
+    errorTransitions;
+    initialState;
+    terminalStates;
+    constructor(name, stateConfig, ttl, maxGuardRetries, transitions, errorTransitions) {
+        this.name = name;
+        this.stateConfig = stateConfig;
+        this.ttl = ttl;
+        this.maxGuardRetries = maxGuardRetries;
+        this.transitions = [...transitions];
+        this.errorTransitions = new Map(errorTransitions);
+        let initial = null;
+        const terminals = new Set();
+        for (const [state, cfg] of Object.entries(stateConfig)) {
+            if (cfg.initial)
+                initial = state;
+            if (cfg.terminal)
+                terminals.add(state);
+        }
+        this.initialState = initial;
+        this.terminalStates = terminals;
+    }
+    transitionsFrom(state) {
+        return this.transitions.filter(t => t.from === state);
+    }
+    externalFrom(state) {
+        return this.transitions.find(t => t.from === state && t.type === 'external');
+    }
+    allStates() {
+        return Object.keys(this.stateConfig);
+    }
+    // ─── Builder ─────────────────────────────────────────────
+    static builder(name, stateConfig) {
+        return new Builder(name, stateConfig);
+    }
+}
+export class Builder {
+    name;
+    stateConfig;
+    ttl = 5 * 60 * 1000; // 5 minutes
+    maxGuardRetries = 3;
+    transitions = [];
+    errorTransitions = new Map();
+    initiallyAvailableKeys = [];
+    constructor(name, stateConfig) {
+        this.name = name;
+        this.stateConfig = stateConfig;
+    }
+    initiallyAvailable(...keys) {
+        for (const k of keys)
+            this.initiallyAvailableKeys.push(k);
+        return this;
+    }
+    setTtl(ms) { this.ttl = ms; return this; }
+    setMaxGuardRetries(max) { this.maxGuardRetries = max; return this; }
+    from(state) {
+        return new FromBuilder(this, state);
+    }
+    onError(from, to) {
+        this.errorTransitions.set(from, to);
+        return this;
+    }
+    onAnyError(errorState) {
+        for (const s of Object.keys(this.stateConfig)) {
+            if (!this.stateConfig[s].terminal)
+                this.errorTransitions.set(s, errorState);
+        }
+        return this;
+    }
+    /** @internal */
+    addTransition(t) { this.transitions.push(t); }
+    build() {
+        const def = FlowDefinition.builder(this.name, this.stateConfig);
+        // Build via private constructor
+        const result = Object.create(FlowDefinition.prototype);
+        Object.assign(result, {
+            name: this.name,
+            stateConfig: this.stateConfig,
+            ttl: this.ttl,
+            maxGuardRetries: this.maxGuardRetries,
+            transitions: [...this.transitions],
+            errorTransitions: new Map(this.errorTransitions),
+        });
+        // Compute initial/terminal
+        let initial = null;
+        const terminals = new Set();
+        for (const [state, cfg] of Object.entries(this.stateConfig)) {
+            if (cfg.initial)
+                initial = state;
+            if (cfg.terminal)
+                terminals.add(state);
+        }
+        result.initialState = initial;
+        result.terminalStates = terminals;
+        this.validate(result);
+        return result;
+    }
+    validate(def) {
+        const errors = [];
+        if (!def.initialState) {
+            errors.push('No initial state found (exactly one state must have initial=true)');
+        }
+        this.checkReachability(def, errors);
+        this.checkPathToTerminal(def, errors);
+        this.checkDag(def, errors);
+        this.checkExternalUniqueness(def, errors);
+        this.checkBranchCompleteness(def, errors);
+        this.checkRequiresProduces(def, errors);
+        this.checkAutoExternalConflict(def, errors);
+        this.checkTerminalNoOutgoing(def, errors);
+        if (errors.length > 0) {
+            throw new FlowError('INVALID_FLOW_DEFINITION', `Flow '${this.name}' has ${errors.length} validation error(s):\n  - ${errors.join('\n  - ')}`);
+        }
+    }
+    checkReachability(def, errors) {
+        if (!def.initialState)
+            return;
+        const visited = new Set();
+        const queue = [def.initialState];
+        visited.add(def.initialState);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            for (const t of def.transitionsFrom(current)) {
+                if (!visited.has(t.to)) {
+                    visited.add(t.to);
+                    queue.push(t.to);
+                }
+            }
+            const errTarget = def.errorTransitions.get(current);
+            if (errTarget && !visited.has(errTarget)) {
+                visited.add(errTarget);
+                queue.push(errTarget);
+            }
+        }
+        for (const s of def.allStates()) {
+            if (!visited.has(s) && !def.stateConfig[s].terminal) {
+                errors.push(`State ${s} is not reachable from ${def.initialState}`);
+            }
+        }
+    }
+    checkPathToTerminal(def, errors) {
+        if (!def.initialState)
+            return;
+        const visited = new Set();
+        if (!this.canReachTerminal(def, def.initialState, visited)) {
+            errors.push(`No path from ${def.initialState} to any terminal state`);
+        }
+    }
+    canReachTerminal(def, state, visited) {
+        if (def.stateConfig[state].terminal)
+            return true;
+        if (visited.has(state))
+            return false;
+        visited.add(state);
+        for (const t of def.transitionsFrom(state)) {
+            if (this.canReachTerminal(def, t.to, visited))
+                return true;
+        }
+        const errTarget = def.errorTransitions.get(state);
+        return errTarget !== undefined && this.canReachTerminal(def, errTarget, visited);
+    }
+    checkDag(def, errors) {
+        const autoGraph = new Map();
+        for (const t of def.transitions) {
+            if (t.type === 'auto' || t.type === 'branch') {
+                if (!autoGraph.has(t.from))
+                    autoGraph.set(t.from, new Set());
+                autoGraph.get(t.from).add(t.to);
+            }
+        }
+        const visited = new Set();
+        const inStack = new Set();
+        for (const s of def.allStates()) {
+            if (!visited.has(s) && this.hasCycle(autoGraph, s, visited, inStack)) {
+                errors.push(`Auto/Branch transitions contain a cycle involving ${s}`);
+                break;
+            }
+        }
+    }
+    hasCycle(graph, node, visited, inStack) {
+        visited.add(node);
+        inStack.add(node);
+        for (const neighbor of graph.get(node) ?? []) {
+            if (inStack.has(neighbor))
+                return true;
+            if (!visited.has(neighbor) && this.hasCycle(graph, neighbor, visited, inStack))
+                return true;
+        }
+        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) {
+            if (t.type === 'branch' && t.branchTargets.size > 0) {
+                for (const [label, target] of t.branchTargets) {
+                    if (!allStates.has(target)) {
+                        errors.push(`Branch target '${label}' -> ${target} is not a valid state`);
+                    }
+                }
+            }
+        }
+    }
+    checkRequiresProduces(def, errors) {
+        if (!def.initialState)
+            return;
+        const stateAvailable = new Map();
+        this.checkRequiresProducesFrom(def, def.initialState, new Set(this.initiallyAvailableKeys), stateAvailable, errors);
+    }
+    checkRequiresProducesFrom(def, state, available, stateAvailable, errors) {
+        if (stateAvailable.has(state)) {
+            const existing = stateAvailable.get(state);
+            let isSubset = true;
+            for (const a of available) {
+                if (!existing.has(a)) {
+                    isSubset = false;
+                    break;
+                }
+            }
+            if (isSubset)
+                return;
+            // intersection
+            for (const a of [...existing]) {
+                if (!available.has(a))
+                    existing.delete(a);
+            }
+        }
+        else {
+            stateAvailable.set(state, new Set(available));
+        }
+        for (const t of def.transitionsFrom(state)) {
+            const newAvailable = new Set(stateAvailable.get(state));
+            if (t.guard) {
+                for (const req of t.guard.requires) {
+                    if (!newAvailable.has(req))
+                        errors.push(`Guard '${t.guard.name}' at ${t.from} requires ${req} but it may not be available`);
+                }
+                for (const p of t.guard.produces)
+                    newAvailable.add(p);
+            }
+            if (t.branch) {
+                for (const req of t.branch.requires) {
+                    if (!newAvailable.has(req))
+                        errors.push(`Branch '${t.branch.name}' at ${t.from} requires ${req} but it may not be available`);
+                }
+            }
+            if (t.processor) {
+                for (const req of t.processor.requires) {
+                    if (!newAvailable.has(req))
+                        errors.push(`Processor '${t.processor.name}' at ${t.from} -> ${t.to} requires ${req} but it may not be available`);
+                }
+                for (const p of t.processor.produces)
+                    newAvailable.add(p);
+            }
+            this.checkRequiresProducesFrom(def, t.to, newAvailable, stateAvailable, errors);
+        }
+    }
+    checkAutoExternalConflict(def, errors) {
+        for (const state of def.allStates()) {
+            const trans = def.transitionsFrom(state);
+            const hasAuto = trans.some(t => t.type === 'auto' || t.type === 'branch');
+            const hasExternal = trans.some(t => t.type === 'external');
+            if (hasAuto && hasExternal) {
+                errors.push(`State ${state} has both auto/branch and external transitions — auto takes priority, making external unreachable`);
+            }
+        }
+    }
+    checkTerminalNoOutgoing(def, errors) {
+        for (const t of def.transitions) {
+            if (def.stateConfig[t.from].terminal) {
+                errors.push(`Terminal state ${t.from} has an outgoing transition to ${t.to}`);
+            }
+        }
+    }
+}
+export class FromBuilder {
+    builder;
+    fromState;
+    constructor(builder, fromState) {
+        this.builder = builder;
+        this.fromState = fromState;
+    }
+    auto(to, processor) {
+        this.builder.addTransition({
+            from: this.fromState, to, type: 'auto', processor,
+            guard: undefined, branch: undefined, branchTargets: new Map(),
+        });
+        return this.builder;
+    }
+    external(to, guard, processor) {
+        this.builder.addTransition({
+            from: this.fromState, to, type: 'external', processor,
+            guard, branch: undefined, branchTargets: new Map(),
+        });
+        return this.builder;
+    }
+    branch(branch) {
+        return new BranchBuilder(this.builder, this.fromState, branch);
+    }
+}
+export class BranchBuilder {
+    builder;
+    fromState;
+    branch;
+    targets = new Map();
+    processors = new Map();
+    constructor(builder, fromState, branch) {
+        this.builder = builder;
+        this.fromState = fromState;
+        this.branch = branch;
+    }
+    to(state, label, processor) {
+        this.targets.set(label, state);
+        if (processor)
+            this.processors.set(label, processor);
+        return this;
+    }
+    endBranch() {
+        for (const [label, target] of this.targets) {
+            this.builder.addTransition({
+                from: this.fromState, to: target, type: 'branch',
+                processor: this.processors.get(label),
+                guard: undefined, branch: this.branch,
+                branchTargets: new Map(this.targets),
+            });
+        }
+        return this.builder;
+    }
+}

package/dist/flow-engine.d.ts

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

package/dist/flow-engine.js

@@ -0,0 +1,161 @@
+import { FlowContext } from './flow-context.js';
+import { FlowInstance } from './flow-instance.js';
+import { FlowError } from './flow-error.js';
+const MAX_CHAIN_DEPTH = 10;
+/**
+ * Generic engine that drives all flow state machines.
+ *
+ * Exceptions:
+ * - FLOW_NOT_FOUND: resumeAndExecute with unknown or completed flowId
+ * - INVALID_TRANSITION: resumeAndExecute when no external transition exists
+ * - MAX_CHAIN_DEPTH: auto-chain exceeded 10 steps
+ * - EXPIRED: flow TTL exceeded at resumeAndExecute entry
+ *
+ * Processor and branch exceptions are caught and routed to error transitions.
+ */
+export class FlowEngine {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async startFlow(definition, sessionId, initialData) {
+        const flowId = crypto.randomUUID();
+        const ctx = new FlowContext(flowId);
+        for (const [key, value] of initialData)
+            ctx.put(key, value);
+        const initial = definition.initialState;
+        if (!initial)
+            throw new FlowError('INVALID_FLOW_DEFINITION', 'No initial state');
+        const expiresAt = new Date(Date.now() + definition.ttl);
+        const flow = new FlowInstance(flowId, sessionId, definition, ctx, initial, expiresAt);
+        this.store.create(flow);
+        await this.executeAutoChain(flow);
+        this.store.save(flow);
+        return flow;
+    }
+    async resumeAndExecute(flowId, definition, externalData) {
+        const flow = this.store.loadForUpdate(flowId);
+        if (!flow)
+            throw new FlowError('FLOW_NOT_FOUND', `Flow ${flowId} not found or already completed`);
+        if (externalData) {
+            for (const [key, value] of externalData)
+                flow.context.put(key, value);
+        }
+        if (new Date() > flow.expiresAt) {
+            flow.complete('EXPIRED');
+            this.store.save(flow);
+            return flow;
+        }
+        const currentState = flow.currentState;
+        const transition = definition.externalFrom(currentState);
+        if (!transition)
+            throw FlowError.invalidTransition(currentState, currentState);
+        const guard = transition.guard;
+        if (guard) {
+            const output = await guard.validate(flow.context);
+            switch (output.type) {
+                case 'accepted': {
+                    const backup = flow.context.snapshot();
+                    if (output.data) {
+                        for (const [key, value] of output.data)
+                            flow.context.put(key, value);
+                    }
+                    try {
+                        if (transition.processor)
+                            await transition.processor.process(flow.context);
+                        const from = flow.currentState;
+                        flow.transitionTo(transition.to);
+                        this.store.recordTransition(flow.id, from, transition.to, guard.name, flow.context);
+                    }
+                    catch {
+                        flow.context.restoreFrom(backup);
+                        this.handleError(flow, currentState);
+                        this.store.save(flow);
+                        return flow;
+                    }
+                    break;
+                }
+                case 'rejected': {
+                    flow.incrementGuardFailure();
+                    if (flow.guardFailureCount >= definition.maxGuardRetries) {
+                        this.handleError(flow, currentState);
+                    }
+                    this.store.save(flow);
+                    return flow;
+                }
+                case 'expired': {
+                    flow.complete('EXPIRED');
+                    this.store.save(flow);
+                    return flow;
+                }
+            }
+        }
+        else {
+            const from = flow.currentState;
+            flow.transitionTo(transition.to);
+            this.store.recordTransition(flow.id, from, transition.to, 'external', flow.context);
+        }
+        await this.executeAutoChain(flow);
+        this.store.save(flow);
+        return flow;
+    }
+    async executeAutoChain(flow) {
+        let depth = 0;
+        while (depth < MAX_CHAIN_DEPTH) {
+            const current = flow.currentState;
+            if (flow.definition.stateConfig[current].terminal) {
+                flow.complete(current);
+                break;
+            }
+            const transitions = flow.definition.transitionsFrom(current);
+            const autoOrBranch = transitions.find(t => t.type === 'auto' || t.type === 'branch');
+            if (!autoOrBranch)
+                break;
+            const backup = flow.context.snapshot();
+            try {
+                if (autoOrBranch.type === 'auto') {
+                    if (autoOrBranch.processor)
+                        await autoOrBranch.processor.process(flow.context);
+                    const from = flow.currentState;
+                    flow.transitionTo(autoOrBranch.to);
+                    this.store.recordTransition(flow.id, from, autoOrBranch.to, autoOrBranch.processor?.name ?? 'auto', flow.context);
+                }
+                else {
+                    const branch = autoOrBranch.branch;
+                    const label = await branch.decide(flow.context);
+                    const target = autoOrBranch.branchTargets.get(label);
+                    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;
+                    if (specific.processor)
+                        await specific.processor.process(flow.context);
+                    const from = flow.currentState;
+                    flow.transitionTo(target);
+                    this.store.recordTransition(flow.id, from, target, `${branch.name}:${label}`, flow.context);
+                }
+            }
+            catch {
+                flow.context.restoreFrom(backup);
+                this.handleError(flow, flow.currentState);
+                return;
+            }
+            depth++;
+        }
+        if (depth >= MAX_CHAIN_DEPTH)
+            throw FlowError.maxChainDepth();
+    }
+    handleError(flow, fromState) {
+        const errorTarget = flow.definition.errorTransitions.get(fromState);
+        if (errorTarget) {
+            const from = flow.currentState;
+            flow.transitionTo(errorTarget);
+            this.store.recordTransition(flow.id, from, errorTarget, 'error', flow.context);
+            if (flow.definition.stateConfig[errorTarget].terminal)
+                flow.complete(errorTarget);
+        }
+        else {
+            flow.complete('TERMINAL_ERROR');
+        }
+    }
+}

package/dist/flow-error.d.ts

@@ -0,0 +1,8 @@
+export declare class FlowError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+    static invalidTransition(from: string, to: string): FlowError;
+    static missingContext(key: string): FlowError;
+    static dagCycle(detail: string): FlowError;
+    static maxChainDepth(): FlowError;
+}

package/dist/flow-error.js

@@ -0,0 +1,20 @@
+export class FlowError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'FlowError';
+    }
+    static invalidTransition(from, to) {
+        return new FlowError('INVALID_TRANSITION', `Invalid transition from ${from} to ${to}`);
+    }
+    static missingContext(key) {
+        return new FlowError('MISSING_CONTEXT', `Missing context key: ${key}`);
+    }
+    static dagCycle(detail) {
+        return new FlowError('DAG_CYCLE', `Auto/Branch transitions contain a cycle: ${detail}`);
+    }
+    static maxChainDepth() {
+        return new FlowError('MAX_CHAIN_DEPTH', 'Auto-chain exceeded maximum depth of 10');
+    }
+}

package/dist/flow-instance.d.ts

@@ -0,0 +1,29 @@
+import type { FlowDefinition } from './flow-definition.js';
+import type { FlowContext } from './flow-context.js';
+export declare class FlowInstance<S extends string> {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly definition: FlowDefinition<S>;
+    readonly context: FlowContext;
+    private _currentState;
+    private _guardFailureCount;
+    private _version;
+    readonly createdAt: Date;
+    readonly expiresAt: Date;
+    private _exitState;
+    constructor(id: string, sessionId: string, definition: FlowDefinition<S>, context: FlowContext, currentState: S, expiresAt: Date);
+    /**
+     * Restore a FlowInstance from persisted state.
+     * Used by FlowStore implementations to reconstruct instances loaded from storage.
+     */
+    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;
+    get version(): number;
+    get exitState(): string | null;
+    get isCompleted(): boolean;
+    /** @internal */ transitionTo(state: S): void;
+    /** @internal */ incrementGuardFailure(): void;
+    /** @internal */ complete(exitState: string): void;
+    /** @internal */ setVersion(version: number): void;
+}

package/dist/flow-instance.js

@@ -0,0 +1,52 @@
+export class FlowInstance {
+    id;
+    sessionId;
+    definition;
+    context;
+    _currentState;
+    _guardFailureCount;
+    _version;
+    createdAt;
+    expiresAt;
+    _exitState;
+    constructor(id, sessionId, definition, context, currentState, expiresAt) {
+        this.id = id;
+        this.sessionId = sessionId;
+        this.definition = definition;
+        this.context = context;
+        this._currentState = currentState;
+        this._guardFailureCount = 0;
+        this._version = 0;
+        this.createdAt = new Date();
+        this.expiresAt = expiresAt;
+        this._exitState = null;
+    }
+    /**
+     * Restore a FlowInstance from persisted state.
+     * Used by FlowStore implementations to reconstruct instances loaded from storage.
+     */
+    static restore(id, sessionId, definition, context, currentState, createdAt, expiresAt, guardFailureCount, version, exitState) {
+        const instance = Object.create(FlowInstance.prototype);
+        // Use defineProperties to set readonly fields
+        Object.defineProperty(instance, 'id', { value: id, writable: false });
+        Object.defineProperty(instance, 'sessionId', { value: sessionId, writable: false });
+        Object.defineProperty(instance, 'definition', { value: definition, writable: false });
+        Object.defineProperty(instance, 'context', { value: context, writable: false });
+        Object.defineProperty(instance, 'createdAt', { value: createdAt, writable: false });
+        Object.defineProperty(instance, 'expiresAt', { value: expiresAt, writable: false });
+        instance._currentState = currentState;
+        instance._guardFailureCount = guardFailureCount;
+        instance._version = version;
+        instance._exitState = exitState;
+        return instance;
+    }
+    get currentState() { return this._currentState; }
+    get guardFailureCount() { return this._guardFailureCount; }
+    get version() { return this._version; }
+    get exitState() { return this._exitState; }
+    get isCompleted() { return this._exitState !== null; }
+    /** @internal */ transitionTo(state) { this._currentState = state; }
+    /** @internal */ incrementGuardFailure() { this._guardFailureCount++; }
+    /** @internal */ complete(exitState) { this._exitState = exitState; }
+    /** @internal */ setVersion(version) { this._version = version; }
+}

package/dist/flow-key.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Branded string type for type-safe FlowContext keys.
+ *
+ * Use dedicated FlowKey instances as keys, not raw strings.
+ * Each key maps to exactly one data type in the context.
+ */
+export type FlowKey<T> = string & {
+    readonly __type: T;
+};
+export declare function flowKey<T>(name: string): FlowKey<T>;

package/dist/flow-key.js

@@ -0,0 +1,3 @@
+export function flowKey(name) {
+    return name;
+}

package/dist/in-memory-flow-store.d.ts

@@ -0,0 +1,18 @@
+import type { FlowContext } from './flow-context.js';
+import type { FlowInstance } from './flow-instance.js';
+export interface TransitionRecord {
+    flowId: string;
+    from: string | null;
+    to: string;
+    trigger: string;
+    timestamp: Date;
+}
+export declare class InMemoryFlowStore {
+    private flows;
+    private _transitionLog;
+    create(flow: FlowInstance<any>): void;
+    loadForUpdate<S extends string>(flowId: string): FlowInstance<S> | undefined;
+    save(flow: FlowInstance<any>): void;
+    recordTransition(flowId: string, from: string | null, to: string, trigger: string, _ctx: FlowContext): void;
+    get transitionLog(): readonly TransitionRecord[];
+}

package/dist/in-memory-flow-store.js

@@ -0,0 +1,22 @@
+export class InMemoryFlowStore {
+    flows = new Map();
+    _transitionLog = [];
+    create(flow) {
+        this.flows.set(flow.id, flow);
+    }
+    loadForUpdate(flowId) {
+        const flow = this.flows.get(flowId);
+        if (!flow || flow.isCompleted)
+            return undefined;
+        return flow;
+    }
+    save(flow) {
+        this.flows.set(flow.id, flow);
+    }
+    recordTransition(flowId, from, to, trigger, _ctx) {
+        this._transitionLog.push({ flowId, from, to, trigger, timestamp: new Date() });
+    }
+    get transitionLog() {
+        return this._transitionLog;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { Tramli } from './tramli.js';
+export { FlowEngine } from './flow-engine.js';
+export { FlowContext } from './flow-context.js';
+export { FlowInstance } from './flow-instance.js';
+export { FlowDefinition, Builder, FromBuilder, BranchBuilder } from './flow-definition.js';
+export { FlowError } from './flow-error.js';
+export { InMemoryFlowStore } from './in-memory-flow-store.js';
+export type { TransitionRecord } from './in-memory-flow-store.js';
+export { MermaidGenerator } from './mermaid-generator.js';
+export { flowKey } from './flow-key.js';
+export type { FlowKey } from './flow-key.js';
+export type { StateConfig, GuardOutput, TransitionType, Transition, StateProcessor, TransitionGuard, BranchProcessor, } from './types.js';

package/dist/index.js

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

package/dist/mermaid-generator.d.ts

@@ -0,0 +1,5 @@
+import type { FlowDefinition } from './flow-definition.js';
+export declare class MermaidGenerator {
+    static generate<S extends string>(def: FlowDefinition<S>): string;
+    private static transitionLabel;
+}

package/dist/mermaid-generator.js

@@ -0,0 +1,36 @@
+export class MermaidGenerator {
+    static generate(def) {
+        const lines = ['stateDiagram-v2'];
+        if (def.initialState)
+            lines.push(`  [*] --> ${def.initialState}`);
+        const seen = new Set();
+        for (const t of def.transitions) {
+            const key = `${t.from}->${t.to}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const label = this.transitionLabel(t);
+            lines.push(label ? `  ${t.from} --> ${t.to}: ${label}` : `  ${t.from} --> ${t.to}`);
+        }
+        for (const [from, to] of def.errorTransitions) {
+            const key = `${from}->${to}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                lines.push(`  ${from} --> ${to}: error`);
+            }
+        }
+        for (const s of def.terminalStates) {
+            lines.push(`  ${s} --> [*]`);
+        }
+        return lines.join('\n') + '\n';
+    }
+    static transitionLabel(t) {
+        if (t.type === 'auto')
+            return t.processor?.name ?? '';
+        if (t.type === 'external')
+            return t.guard ? `[${t.guard.name}]` : '';
+        if (t.type === 'branch')
+            return t.branch?.name ?? '';
+        return '';
+    }
+}

package/dist/tramli.d.ts

@@ -0,0 +1,8 @@
+import type { StateConfig } from './types.js';
+import { Builder } from './flow-definition.js';
+import { FlowEngine } from './flow-engine.js';
+import type { InMemoryFlowStore } from './in-memory-flow-store.js';
+export declare class Tramli {
+    static define<S extends string>(name: string, stateConfig: Record<S, StateConfig>): Builder<S>;
+    static engine(store: InMemoryFlowStore): FlowEngine;
+}

package/dist/tramli.js

@@ -0,0 +1,10 @@
+import { Builder } from './flow-definition.js';
+import { FlowEngine } from './flow-engine.js';
+export class Tramli {
+    static define(name, stateConfig) {
+        return new Builder(name, stateConfig);
+    }
+    static engine(store) {
+        return new FlowEngine(store);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,73 @@
+import type { FlowKey } from './flow-key.js';
+import type { FlowContext } from './flow-context.js';
+/** State configuration: terminal and initial flags for each state. */
+export type StateConfig = {
+    terminal: boolean;
+    initial: boolean;
+};
+/** Guard output — discriminated union (Java: sealed interface GuardOutput). */
+export type GuardOutput = {
+    type: 'accepted';
+    data?: Map<string, unknown>;
+} | {
+    type: 'rejected';
+    reason: string;
+} | {
+    type: 'expired';
+};
+/** Transition types. */
+export type TransitionType = 'auto' | 'external' | 'branch';
+/** A single transition in the flow definition. */
+export interface Transition<S extends string> {
+    from: S;
+    to: S;
+    type: TransitionType;
+    processor?: StateProcessor<S>;
+    guard?: TransitionGuard<S>;
+    branch?: BranchProcessor<S>;
+    branchTargets: Map<string, S>;
+}
+/**
+ * Processes a state transition.
+ *
+ * Processors SHOULD be fast and avoid external I/O.
+ * If a processor throws, the engine restores context and routes to error transition.
+ */
+export interface StateProcessor<S extends string> {
+    name: string;
+    requires: FlowKey<unknown>[];
+    produces: FlowKey<unknown>[];
+    process(ctx: FlowContext): Promise<void> | void;
+}
+/**
+ * Guards an external transition. Pure function — must not mutate FlowContext.
+ *
+ * TTL vs GuardOutput.expired: FlowInstance TTL is checked at resumeAndExecute
+ * entry (flow-level). GuardOutput 'expired' is guard-level for business logic.
+ */
+export interface TransitionGuard<S extends string> {
+    name: string;
+    requires: FlowKey<unknown>[];
+    produces: FlowKey<unknown>[];
+    maxRetries: number;
+    validate(ctx: FlowContext): Promise<GuardOutput> | GuardOutput;
+}
+/** Decides which branch to take based on FlowContext state. */
+export interface BranchProcessor<S extends string> {
+    name: string;
+    requires: FlowKey<unknown>[];
+    decide(ctx: FlowContext): Promise<string> | string;
+}
+/**
+ * Persistence contract for flow instances.
+ *
+ * Threading: FlowEngine assumes single-threaded access per flow instance.
+ * Atomicity: create/save and recordTransition form a logical unit.
+ * If partial writes occur, save is authoritative over the transition log.
+ */
+export interface FlowStore {
+    create(flow: unknown): void | Promise<void>;
+    loadForUpdate<S extends string>(flowId: string): unknown | undefined | Promise<unknown | undefined>;
+    save(flow: unknown): void | Promise<void>;
+    recordTransition(flowId: string, from: string | null, to: string, trigger: string, ctx: FlowContext): void | Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@unlaxer/tramli",
+  "version": "0.1.0",
+  "description": "Constrained flow engine — state machines that prevent invalid transitions at build time",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/opaopa6969/tramli-ts"
+  },
+  "author": "Hisayuki Ookubo <opaopa6969@gmail.com>",
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}