@unlaxer/tramli 1.5.2 → 1.6.0

package/dist/esm/flow-engine.js

@@ -0,0 +1,240 @@
+import { FlowContext } from './flow-context.js';
+import { FlowInstance } from './flow-instance.js';
+import { FlowError } from './flow-error.js';
+const MAX_CHAIN_DEPTH = 10;
+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, definition);
+        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;
+        }
+        // If actively in a sub-flow, delegate resume
+        if (flow.activeSubFlow) {
+            return this.resumeSubFlow(flow, definition);
+        }
+        const currentState = flow.currentState;
+        const transition = definition.externalFrom(currentState);
+        if (!transition)
+            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 (e) {
+                        flow.context.restoreFrom(backup);
+                        this.handleError(flow, currentState, e instanceof Error ? e : new Error(String(e)));
+                        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);
+            // Check for sub-flow transition
+            const subFlowT = transitions.find(t => t.type === 'sub_flow');
+            if (subFlowT) {
+                const advanced = await this.executeSubFlow(flow, subFlowT);
+                depth += advanced;
+                if (advanced === 0)
+                    break; // sub-flow stopped at external
+                continue;
+            }
+            const autoOrBranch = transitions.find(t => t.type === 'auto' || t.type === 'branch');
+            if (!autoOrBranch)
+                break;
+            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 (e) {
+                flow.context.restoreFrom(backup);
+                this.handleError(flow, flow.currentState, e instanceof Error ? e : new Error(String(e)));
+                return;
+            }
+            depth++;
+        }
+        if (depth >= MAX_CHAIN_DEPTH)
+            throw FlowError.maxChainDepth();
+    }
+    async executeSubFlow(parentFlow, subFlowTransition) {
+        const subDef = subFlowTransition.subFlowDefinition;
+        const exitMappings = subFlowTransition.exitMappings;
+        const subInitial = subDef.initialState;
+        const subFlow = new FlowInstance(parentFlow.id, parentFlow.sessionId, subDef, parentFlow.context, subInitial, parentFlow.expiresAt);
+        parentFlow.setActiveSubFlow(subFlow);
+        await this.executeAutoChain(subFlow);
+        if (subFlow.isCompleted) {
+            parentFlow.setActiveSubFlow(null);
+            const target = exitMappings.get(subFlow.exitState);
+            if (target) {
+                const from = parentFlow.currentState;
+                parentFlow.transitionTo(target);
+                this.store.recordTransition(parentFlow.id, from, target, `subFlow:${subDef.name}/${subFlow.exitState}`, parentFlow.context);
+                return 1;
+            }
+            // Error bubbling: no exit mapping → fall back to parent's error transitions
+            this.handleError(parentFlow, parentFlow.currentState);
+            return 1;
+        }
+        return 0; // sub-flow stopped at external
+    }
+    async resumeSubFlow(parentFlow, parentDef) {
+        const subFlow = parentFlow.activeSubFlow;
+        const subDef = subFlow.definition;
+        const transition = subDef.externalFrom(subFlow.currentState);
+        if (!transition) {
+            throw new FlowError('INVALID_TRANSITION', `No external transition from sub-flow state ${subFlow.currentState}`);
+        }
+        const guard = transition.guard;
+        if (guard) {
+            const output = await guard.validate(parentFlow.context);
+            if (output.type === 'accepted') {
+                if (output.data) {
+                    for (const [key, value] of output.data)
+                        parentFlow.context.put(key, value);
+                }
+                subFlow.transitionTo(transition.to);
+                this.store.recordTransition(parentFlow.id, subFlow.currentState, transition.to, guard.name, parentFlow.context);
+            }
+            else if (output.type === 'rejected') {
+                subFlow.incrementGuardFailure();
+                if (subFlow.guardFailureCount >= subDef.maxGuardRetries) {
+                    subFlow.complete('ERROR');
+                }
+                this.store.save(parentFlow);
+                return parentFlow;
+            }
+            else {
+                parentFlow.complete('EXPIRED');
+                this.store.save(parentFlow);
+                return parentFlow;
+            }
+        }
+        else {
+            subFlow.transitionTo(transition.to);
+        }
+        await this.executeAutoChain(subFlow);
+        if (subFlow.isCompleted) {
+            parentFlow.setActiveSubFlow(null);
+            const subFlowT = parentDef.transitionsFrom(parentFlow.currentState)
+                .find(t => t.type === 'sub_flow');
+            if (subFlowT?.exitMappings) {
+                const target = subFlowT.exitMappings.get(subFlow.exitState);
+                if (target) {
+                    const from = parentFlow.currentState;
+                    parentFlow.transitionTo(target);
+                    this.store.recordTransition(parentFlow.id, from, target, `subFlow:${subDef.name}/${subFlow.exitState}`, parentFlow.context);
+                    await this.executeAutoChain(parentFlow);
+                }
+            }
+        }
+        this.store.save(parentFlow);
+        return parentFlow;
+    }
+    handleError(flow, fromState, cause) {
+        if (cause)
+            flow.setLastError(`${cause.constructor.name}: ${cause.message}`);
+        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/esm/flow-error.d.ts

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

package/dist/esm/flow-error.js

@@ -0,0 +1,30 @@
+export class FlowError extends Error {
+    code;
+    /** Types that were available in context when the error occurred. */
+    availableTypes;
+    /** Types that were expected but missing (if applicable). */
+    missingTypes;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'FlowError';
+    }
+    /** Attach context snapshot to this error. */
+    withContextSnapshot(available, missing) {
+        this.availableTypes = available;
+        this.missingTypes = missing;
+        return this;
+    }
+    static invalidTransition(from, to) {
+        return new FlowError('INVALID_TRANSITION', `Invalid transition from ${from} to ${to}`);
+    }
+    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/esm/flow-instance.d.ts

@@ -0,0 +1,48 @@
+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;
+    private _activeSubFlow;
+    private _lastError;
+    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;
+    get activeSubFlow(): FlowInstance<any> | null;
+    /** Last error message (set when a processor throws and error transition fires). */
+    get lastError(): string | null;
+    /** State path from root to deepest active sub-flow. */
+    statePath(): string[];
+    /** State path as slash-separated string. */
+    statePathString(): string;
+    /** Data types available in context at current state (from data-flow graph). */
+    availableData(): Set<string>;
+    /** Data types that the next transition requires but are not yet in context. */
+    missingFor(): string[];
+    /** Types required by the next external transition (including in active sub-flows). */
+    waitingFor(): string[];
+    /** Return a copy with the given version. For FlowStore optimistic locking. */
+    withVersion(newVersion: number): FlowInstance<S>;
+    /** @internal */ transitionTo(state: S): void;
+    /** @internal */ incrementGuardFailure(): void;
+    /** @internal */ complete(exitState: string): void;
+    /** @internal */ setVersion(version: number): void;
+    /** @internal */ setActiveSubFlow(sub: FlowInstance<any> | null): void;
+    /** @internal */ setLastError(error: string | null): void;
+}

package/dist/esm/flow-instance.js

@@ -0,0 +1,104 @@
+export class FlowInstance {
+    id;
+    sessionId;
+    definition;
+    context;
+    _currentState;
+    _guardFailureCount;
+    _version;
+    createdAt;
+    expiresAt;
+    _exitState;
+    _activeSubFlow = null;
+    _lastError = null;
+    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; }
+    get activeSubFlow() { return this._activeSubFlow; }
+    /** Last error message (set when a processor throws and error transition fires). */
+    get lastError() { return this._lastError; }
+    /** State path from root to deepest active sub-flow. */
+    statePath() {
+        const path = [this._currentState];
+        if (this._activeSubFlow)
+            path.push(...this._activeSubFlow.statePath());
+        return path;
+    }
+    /** State path as slash-separated string. */
+    statePathString() { return this.statePath().join('/'); }
+    /** Data types available in context at current state (from data-flow graph). */
+    availableData() {
+        return this.definition.dataFlowGraph?.availableAt(this._currentState) ?? new Set();
+    }
+    /** Data types that the next transition requires but are not yet in context. */
+    missingFor() {
+        const missing = [];
+        for (const t of this.definition.transitionsFrom(this._currentState)) {
+            if (t.guard)
+                for (const r of t.guard.requires) {
+                    if (!this.context.has(r))
+                        missing.push(r);
+                }
+            if (t.processor)
+                for (const r of t.processor.requires) {
+                    if (!this.context.has(r))
+                        missing.push(r);
+                }
+        }
+        return [...new Set(missing)];
+    }
+    /** Types required by the next external transition (including in active sub-flows). */
+    waitingFor() {
+        if (this._activeSubFlow)
+            return this._activeSubFlow.waitingFor();
+        const ext = this.definition.externalFrom(this._currentState);
+        if (!ext?.guard)
+            return [];
+        return [...ext.guard.requires];
+    }
+    /** Return a copy with the given version. For FlowStore optimistic locking. */
+    withVersion(newVersion) {
+        const copy = FlowInstance.restore(this.id, this.sessionId, this.definition, this.context, this._currentState, this.createdAt, this.expiresAt, this._guardFailureCount, newVersion, this._exitState);
+        copy.setActiveSubFlow(this._activeSubFlow);
+        return copy;
+    }
+    /** @internal */ transitionTo(state) { this._currentState = state; }
+    /** @internal */ incrementGuardFailure() { this._guardFailureCount++; }
+    /** @internal */ complete(exitState) { this._exitState = exitState; }
+    /** @internal */ setVersion(version) { this._version = version; }
+    /** @internal */ setActiveSubFlow(sub) { this._activeSubFlow = sub; }
+    /** @internal */ setLastError(error) { this._lastError = error; }
+}

package/dist/esm/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/esm/flow-key.js

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

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

@@ -0,0 +1,19 @@
+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;
+    subFlow: string | null;
+    timestamp: Date;
+}
+export declare class InMemoryFlowStore {
+    private flows;
+    private _transitionLog;
+    create(flow: FlowInstance<any>): void;
+    loadForUpdate<S extends string>(flowId: string, _definition?: any): 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/esm/in-memory-flow-store.js

@@ -0,0 +1,23 @@
+export class InMemoryFlowStore {
+    flows = new Map();
+    _transitionLog = [];
+    create(flow) {
+        this.flows.set(flow.id, flow);
+    }
+    loadForUpdate(flowId, _definition) {
+        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) {
+        const subFlow = trigger.startsWith('subFlow:') ? trigger.substring(8, trigger.indexOf('/')) : null;
+        this._transitionLog.push({ flowId, from, to, trigger, subFlow, timestamp: new Date() });
+    }
+    get transitionLog() {
+        return this._transitionLog;
+    }
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,16 @@
+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, SubFlowBuilder } from './flow-definition.js';
+export { FlowError } from './flow-error.js';
+export { InMemoryFlowStore } from './in-memory-flow-store.js';
+export type { TransitionRecord } from './in-memory-flow-store.js';
+export { MermaidGenerator } from './mermaid-generator.js';
+export { SkeletonGenerator } from './skeleton-generator.js';
+export type { TargetLanguage } from './skeleton-generator.js';
+export { DataFlowGraph } from './data-flow-graph.js';
+export type { NodeInfo } from './data-flow-graph.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/esm/index.js

@@ -0,0 +1,11 @@
+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, SubFlowBuilder } from './flow-definition.js';
+export { FlowError } from './flow-error.js';
+export { InMemoryFlowStore } from './in-memory-flow-store.js';
+export { MermaidGenerator } from './mermaid-generator.js';
+export { SkeletonGenerator } from './skeleton-generator.js';
+export { DataFlowGraph } from './data-flow-graph.js';
+export { flowKey } from './flow-key.js';

package/dist/esm/mermaid-generator.d.ts

@@ -0,0 +1,9 @@
+import type { FlowDefinition } from './flow-definition.js';
+export declare class MermaidGenerator {
+    static generate<S extends string>(def: FlowDefinition<S>): string;
+    /** Generate Mermaid diagram highlighting external transitions and their data contracts. */
+    static generateExternalContract<S extends string>(def: FlowDefinition<S>): string;
+    /** Generate Mermaid data-flow diagram from requires/produces declarations. */
+    static generateDataFlow<S extends string>(def: FlowDefinition<S>): string;
+    private static transitionLabel;
+}

package/dist/esm/mermaid-generator.js

@@ -0,0 +1,76 @@
+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) {
+            if (t.type === 'sub_flow' && t.subFlowDefinition) {
+                const subDef = t.subFlowDefinition;
+                lines.push(`  state ${t.from} {`);
+                if (subDef.initialState)
+                    lines.push(`    [*] --> ${subDef.initialState}`);
+                for (const st of subDef.transitions) {
+                    const sLabel = this.transitionLabel(st);
+                    lines.push(sLabel ? `    ${st.from} --> ${st.to}: ${sLabel}` : `    ${st.from} --> ${st.to}`);
+                }
+                for (const term of subDef.terminalStates)
+                    lines.push(`    ${term} --> [*]`);
+                lines.push('  }');
+                if (t.exitMappings) {
+                    for (const [exitName, target] of t.exitMappings) {
+                        lines.push(`  ${t.from} --> ${target}: ${exitName}`);
+                    }
+                }
+                continue;
+            }
+            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';
+    }
+    /** Generate Mermaid diagram highlighting external transitions and their data contracts. */
+    static generateExternalContract(def) {
+        const lines = ['flowchart LR'];
+        for (const t of def.transitions) {
+            if (t.type !== 'external' || !t.guard)
+                continue;
+            lines.push(`    subgraph ${t.from}_to_${t.to}`);
+            lines.push('        direction TB');
+            lines.push(`        ${t.guard.name}{"[${t.guard.name}]"}`);
+            for (const req of t.guard.requires)
+                lines.push(`        ${req} -->|client sends| ${t.guard.name}`);
+            for (const prod of t.guard.produces)
+                lines.push(`        ${t.guard.name} -->|returns| ${prod}`);
+            lines.push('    end');
+        }
+        return lines.join('\n') + '\n';
+    }
+    /** Generate Mermaid data-flow diagram from requires/produces declarations. */
+    static generateDataFlow(def) {
+        return def.dataFlowGraph?.toMermaid() ?? '';
+    }
+    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/esm/skeleton-generator.d.ts

@@ -0,0 +1,10 @@
+import type { FlowDefinition } from './flow-definition.js';
+export type TargetLanguage = 'java' | 'typescript' | 'rust';
+/**
+ * Generates Processor skeleton code from a FlowDefinition's requires/produces contracts.
+ */
+export declare class SkeletonGenerator {
+    static generate<S extends string>(def: FlowDefinition<S>, lang: TargetLanguage): string;
+    private static genProcessor;
+    private static genGuard;
+}