@unlaxer/tramli-plugins 3.0.0

package/dist/cjs/api/plugin-registry.d.ts

@@ -0,0 +1,19 @@
+import type { FlowDefinition, FlowEngine } from '@unlaxer/tramli';
+import type { FlowPlugin } from './types.js';
+import { PluginReport } from './types.js';
+/**
+ * Central registry for tramli plugins.
+ * Manages plugin lifecycle: analyze → wrap store → install engine → bind adapters.
+ */
+export declare class PluginRegistry<S extends string> {
+    private plugins;
+    register(plugin: FlowPlugin): this;
+    /** Run all analysis plugins against a FlowDefinition. */
+    analyzeAll(definition: FlowDefinition<S>): PluginReport;
+    /** Apply all store plugins (wrapping in registration order). */
+    applyStorePlugins(store: any): any;
+    /** Install all engine plugins. */
+    installEnginePlugins(engine: FlowEngine): void;
+    /** Bind all runtime adapter plugins. Returns map of plugin id → bound adapter. */
+    bindRuntimeAdapters(engine: FlowEngine): Map<string, unknown>;
+}

package/dist/cjs/api/plugin-registry.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginRegistry = void 0;
+const types_js_1 = require("./types.js");
+/**
+ * Central registry for tramli plugins.
+ * Manages plugin lifecycle: analyze → wrap store → install engine → bind adapters.
+ */
+class PluginRegistry {
+    plugins = [];
+    register(plugin) {
+        this.plugins.push(plugin);
+        return this;
+    }
+    /** Run all analysis plugins against a FlowDefinition. */
+    analyzeAll(definition) {
+        const report = new types_js_1.PluginReport();
+        for (const p of this.plugins) {
+            if (p.kind() === 'ANALYSIS') {
+                p.analyze(definition, report);
+            }
+        }
+        return report;
+    }
+    /** Apply all store plugins (wrapping in registration order). */
+    applyStorePlugins(store) {
+        let wrapped = store;
+        for (const p of this.plugins) {
+            if (p.kind() === 'STORE') {
+                wrapped = p.wrapStore(wrapped);
+            }
+        }
+        return wrapped;
+    }
+    /** Install all engine plugins. */
+    installEnginePlugins(engine) {
+        for (const p of this.plugins) {
+            if (p.kind() === 'ENGINE') {
+                p.install(engine);
+            }
+        }
+    }
+    /** Bind all runtime adapter plugins. Returns map of plugin id → bound adapter. */
+    bindRuntimeAdapters(engine) {
+        const adapters = new Map();
+        for (const p of this.plugins) {
+            if (p.kind() === 'RUNTIME_ADAPTER') {
+                const adapter = p.bind(engine);
+                adapters.set(p.descriptor().id, adapter);
+            }
+        }
+        return adapters;
+    }
+}
+exports.PluginRegistry = PluginRegistry;

package/dist/cjs/api/types.d.ts

@@ -0,0 +1,51 @@
+import type { FlowDefinition, FlowEngine } from '@unlaxer/tramli';
+/** Plugin kind classification. */
+export type PluginKind = 'ANALYSIS' | 'STORE' | 'ENGINE' | 'RUNTIME_ADAPTER' | 'GENERATION' | 'DOCUMENTATION';
+/** Plugin descriptor. */
+export interface PluginDescriptor {
+    id: string;
+    displayName: string;
+    description: string;
+}
+/** Base plugin interface. */
+export interface FlowPlugin {
+    descriptor(): PluginDescriptor;
+    kind(): PluginKind;
+    id?(): string;
+}
+/** Analysis plugin — static analysis of FlowDefinition. */
+export interface AnalysisPlugin<S extends string> extends FlowPlugin {
+    analyze(definition: FlowDefinition<S>, report: PluginReport): void;
+}
+/** Store plugin — wraps FlowStore with additional behavior. */
+export interface StorePlugin extends FlowPlugin {
+    wrapStore(store: any): any;
+}
+/** Engine plugin — installs hooks on FlowEngine. */
+export interface EnginePlugin extends FlowPlugin {
+    install(engine: FlowEngine): void;
+}
+/** Runtime adapter plugin — binds FlowEngine to return richer API. */
+export interface RuntimeAdapterPlugin<R> extends FlowPlugin {
+    bind(engine: FlowEngine): R;
+}
+/** Generation plugin — generates output from input. */
+export interface GenerationPlugin<I, O> extends FlowPlugin {
+    generate(input: I): O;
+}
+/** Documentation plugin — generates string documentation. */
+export interface DocumentationPlugin<I> extends GenerationPlugin<I, string> {
+}
+/** Plugin report — collects analysis findings. */
+export declare class PluginReport {
+    private entries;
+    add(pluginId: string, severity: string, message: string): void;
+    warn(pluginId: string, message: string): void;
+    error(pluginId: string, message: string): void;
+    asText(): string;
+    findings(): {
+        pluginId: string;
+        severity: string;
+        message: string;
+    }[];
+}

package/dist/cjs/api/types.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginReport = void 0;
+/** Plugin report — collects analysis findings. */
+class PluginReport {
+    entries = [];
+    add(pluginId, severity, message) {
+        this.entries.push({ pluginId, severity, message });
+    }
+    warn(pluginId, message) {
+        this.add(pluginId, 'WARN', message);
+    }
+    error(pluginId, message) {
+        this.add(pluginId, 'ERROR', message);
+    }
+    asText() {
+        if (this.entries.length === 0)
+            return 'No findings.';
+        return this.entries.map(e => `[${e.severity}] ${e.pluginId}: ${e.message}`).join('\n');
+    }
+    findings() { return [...this.entries]; }
+}
+exports.PluginReport = PluginReport;

package/dist/cjs/audit/audit-store-plugin.d.ts

@@ -0,0 +1,7 @@
+import type { StorePlugin, PluginDescriptor } from '../api/types.js';
+import { AuditingFlowStore } from './auditing-flow-store.js';
+export declare class AuditStorePlugin implements StorePlugin {
+    descriptor(): PluginDescriptor;
+    kind(): "STORE";
+    wrapStore(store: any): AuditingFlowStore;
+}

package/dist/cjs/audit/audit-store-plugin.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditStorePlugin = void 0;
+const auditing_flow_store_js_1 = require("./auditing-flow-store.js");
+class AuditStorePlugin {
+    descriptor() {
+        return { id: 'audit', displayName: 'Audit Store', description: 'Captures transition + produced-data diffs' };
+    }
+    kind() { return 'STORE'; }
+    wrapStore(store) {
+        return new auditing_flow_store_js_1.AuditingFlowStore(store);
+    }
+}
+exports.AuditStorePlugin = AuditStorePlugin;

package/dist/cjs/audit/auditing-flow-store.d.ts

@@ -0,0 +1,24 @@
+import type { FlowContext } from '@unlaxer/tramli';
+export interface AuditedTransitionRecord {
+    flowId: string;
+    from: string | null;
+    to: string;
+    trigger: string;
+    timestamp: Date;
+    producedDataSnapshot: Map<string, unknown>;
+}
+/**
+ * FlowStore decorator that captures produced-data snapshots on each transition.
+ */
+export declare class AuditingFlowStore {
+    private readonly delegate;
+    private auditLog;
+    constructor(delegate: any);
+    create(flow: any): void;
+    loadForUpdate<S extends string>(flowId: string, definition?: any): any;
+    save(flow: any): void;
+    recordTransition(flowId: string, from: any, to: string, trigger: string, ctx: FlowContext): void;
+    get auditedTransitions(): readonly AuditedTransitionRecord[];
+    get transitionLog(): any;
+    clear(): void;
+}

package/dist/cjs/audit/auditing-flow-store.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditingFlowStore = void 0;
+/**
+ * FlowStore decorator that captures produced-data snapshots on each transition.
+ */
+class AuditingFlowStore {
+    delegate;
+    auditLog = [];
+    constructor(delegate) {
+        this.delegate = delegate;
+    }
+    create(flow) { this.delegate.create(flow); }
+    loadForUpdate(flowId, definition) {
+        return this.delegate.loadForUpdate(flowId, definition);
+    }
+    save(flow) { this.delegate.save(flow); }
+    recordTransition(flowId, from, to, trigger, ctx) {
+        this.delegate.recordTransition(flowId, from, to, trigger, ctx);
+        const snapshot = new Map();
+        for (const [k, v] of ctx.snapshot()) {
+            snapshot.set(k, v);
+        }
+        this.auditLog.push({
+            flowId, from: from?.toString() ?? null, to, trigger,
+            timestamp: new Date(), producedDataSnapshot: snapshot,
+        });
+    }
+    get auditedTransitions() { return this.auditLog; }
+    get transitionLog() { return this.delegate.transitionLog; }
+    clear() { this.delegate.clear?.(); this.auditLog = []; }
+}
+exports.AuditingFlowStore = AuditingFlowStore;

package/dist/cjs/diagram/diagram-generation-plugin.d.ts

@@ -0,0 +1,9 @@
+import type { FlowDefinition } from '@unlaxer/tramli';
+import type { GenerationPlugin, PluginDescriptor } from '../api/types.js';
+import type { DiagramBundle } from './types.js';
+export declare class DiagramGenerationPlugin<S extends string> implements GenerationPlugin<FlowDefinition<S>, DiagramBundle> {
+    private readonly delegate;
+    descriptor(): PluginDescriptor;
+    kind(): "GENERATION";
+    generate(input: FlowDefinition<S>): DiagramBundle;
+}

package/dist/cjs/diagram/diagram-generation-plugin.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiagramGenerationPlugin = void 0;
+const diagram_plugin_js_1 = require("./diagram-plugin.js");
+class DiagramGenerationPlugin {
+    delegate = new diagram_plugin_js_1.DiagramPlugin();
+    descriptor() {
+        return {
+            id: 'diagram',
+            displayName: 'Diagram Generator',
+            description: 'Generates Mermaid and data-flow bundles from a flow definition.',
+        };
+    }
+    kind() { return 'GENERATION'; }
+    generate(input) {
+        return this.delegate.generate(input);
+    }
+}
+exports.DiagramGenerationPlugin = DiagramGenerationPlugin;

package/dist/cjs/diagram/diagram-plugin.d.ts

@@ -0,0 +1,5 @@
+import type { FlowDefinition } from '@unlaxer/tramli';
+import type { DiagramBundle } from './types.js';
+export declare class DiagramPlugin {
+    generate<S extends string>(definition: FlowDefinition<S>): DiagramBundle;
+}

package/dist/cjs/diagram/diagram-plugin.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiagramPlugin = void 0;
+const tramli_1 = require("@unlaxer/tramli");
+class DiagramPlugin {
+    generate(definition) {
+        const mermaid = tramli_1.MermaidGenerator.generate(definition);
+        const json = definition.dataFlowGraph?.toJson() ?? '{}';
+        const md = `# ${definition.name}\n\n` +
+            `- initial: \`${definition.initialState}\`\n` +
+            `- states: \`${definition.allStates().length}\`\n` +
+            `- transitions: \`${definition.transitions.length}\`\n`;
+        return { mermaid, dataFlowJson: json, markdownSummary: md };
+    }
+}
+exports.DiagramPlugin = DiagramPlugin;

package/dist/cjs/diagram/types.d.ts

@@ -0,0 +1,5 @@
+export interface DiagramBundle {
+    mermaid: string;
+    dataFlowJson: string;
+    markdownSummary: string;
+}

package/dist/cjs/diagram/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/docs/documentation-plugin.d.ts

@@ -0,0 +1,7 @@
+import type { FlowDefinition } from '@unlaxer/tramli';
+/**
+ * Generates a markdown flow catalog from a flow definition.
+ */
+export declare class DocumentationPlugin {
+    toMarkdown<S extends string>(definition: FlowDefinition<S>): string;
+}

package/dist/cjs/docs/documentation-plugin.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentationPlugin = void 0;
+/**
+ * Generates a markdown flow catalog from a flow definition.
+ */
+class DocumentationPlugin {
+    toMarkdown(definition) {
+        const lines = [];
+        lines.push(`# Flow Catalog: ${definition.name}`);
+        lines.push('');
+        lines.push('## States');
+        lines.push('');
+        for (const state of definition.allStates()) {
+            const config = definition.stateConfig[state];
+            let suffix = '';
+            if (config?.initial)
+                suffix += ' (initial)';
+            if (config?.terminal)
+                suffix += ' (terminal)';
+            lines.push(`- \`${state}\`${suffix}`);
+        }
+        lines.push('');
+        lines.push('## Transitions');
+        lines.push('');
+        for (const t of definition.transitions) {
+            const via = t.processor?.name ?? t.guard?.name ?? t.branch?.name ?? t.type;
+            lines.push(`- \`${t.from} -> ${t.to}\` via \`${via}\``);
+        }
+        return lines.join('\n');
+    }
+}
+exports.DocumentationPlugin = DocumentationPlugin;

package/dist/cjs/docs/flow-documentation-plugin.d.ts

@@ -0,0 +1,8 @@
+import type { FlowDefinition } from '@unlaxer/tramli';
+import type { DocumentationPlugin as DocPluginSPI, PluginDescriptor } from '../api/types.js';
+export declare class FlowDocumentationPlugin<S extends string> implements DocPluginSPI<FlowDefinition<S>> {
+    private readonly delegate;
+    descriptor(): PluginDescriptor;
+    kind(): "DOCUMENTATION";
+    generate(input: FlowDefinition<S>): string;
+}

package/dist/cjs/docs/flow-documentation-plugin.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowDocumentationPlugin = void 0;
+const documentation_plugin_js_1 = require("./documentation-plugin.js");
+class FlowDocumentationPlugin {
+    delegate = new documentation_plugin_js_1.DocumentationPlugin();
+    descriptor() {
+        return {
+            id: 'docs',
+            displayName: 'Documentation Generator',
+            description: 'Renders a markdown flow catalog from a flow definition.',
+        };
+    }
+    kind() { return 'DOCUMENTATION'; }
+    generate(input) {
+        return this.delegate.toMarkdown(input);
+    }
+}
+exports.FlowDocumentationPlugin = FlowDocumentationPlugin;

package/dist/cjs/eventstore/compensation-service.d.ts

@@ -0,0 +1,11 @@
+import type { VersionedTransitionEvent, CompensationResolver } from './types.js';
+import type { EventLogStoreDecorator } from './event-log-store-decorator.js';
+/**
+ * Compensation service — records compensation events for failed transitions.
+ */
+export declare class CompensationService {
+    private readonly resolver;
+    private readonly eventLog;
+    constructor(resolver: CompensationResolver, eventLog: EventLogStoreDecorator);
+    compensate(event: VersionedTransitionEvent, cause: Error): boolean;
+}

package/dist/cjs/eventstore/compensation-service.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompensationService = void 0;
+/**
+ * Compensation service — records compensation events for failed transitions.
+ */
+class CompensationService {
+    resolver;
+    eventLog;
+    constructor(resolver, eventLog) {
+        this.resolver = resolver;
+        this.eventLog = eventLog;
+    }
+    compensate(event, cause) {
+        const plan = this.resolver(event, cause);
+        if (!plan)
+            return false;
+        this.eventLog.appendCompensation(event.flowId, plan.action, JSON.stringify(plan.metadata));
+        return true;
+    }
+}
+exports.CompensationService = CompensationService;

package/dist/cjs/eventstore/event-log-store-decorator.d.ts

@@ -0,0 +1,24 @@
+import type { FlowContext } from '@unlaxer/tramli';
+import type { VersionedTransitionEvent } from './types.js';
+/**
+ * FlowStore decorator that maintains an append-only event log.
+ * Tenure-lite: not full event sourcing, intentionally lighter.
+ */
+export declare class EventLogStoreDecorator {
+    private readonly delegate;
+    private eventLog;
+    private versionCounters;
+    constructor(delegate: any);
+    create(flow: any): void;
+    loadForUpdate<S extends string>(flowId: string, definition?: any): any;
+    save(flow: any): void;
+    recordTransition(flowId: string, from: any, to: string, trigger: string, ctx: FlowContext): void;
+    /** All events across all flows. */
+    events(): readonly VersionedTransitionEvent[];
+    /** Events for a specific flow. */
+    eventsForFlow(flowId: string): VersionedTransitionEvent[];
+    /** Append a compensation event. */
+    appendCompensation(flowId: string, trigger: string, metadata: string): void;
+    get transitionLog(): any;
+    clear(): void;
+}

package/dist/cjs/eventstore/event-log-store-decorator.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventLogStoreDecorator = void 0;
+/**
+ * FlowStore decorator that maintains an append-only event log.
+ * Tenure-lite: not full event sourcing, intentionally lighter.
+ */
+class EventLogStoreDecorator {
+    delegate;
+    eventLog = [];
+    versionCounters = new Map();
+    constructor(delegate) {
+        this.delegate = delegate;
+    }
+    create(flow) { this.delegate.create(flow); }
+    loadForUpdate(flowId, definition) {
+        return this.delegate.loadForUpdate(flowId, definition);
+    }
+    save(flow) { this.delegate.save(flow); }
+    recordTransition(flowId, from, to, trigger, ctx) {
+        this.delegate.recordTransition(flowId, from, to, trigger, ctx);
+        const version = (this.versionCounters.get(flowId) ?? 0) + 1;
+        this.versionCounters.set(flowId, version);
+        this.eventLog.push({
+            flowId, version, type: 'TRANSITION',
+            from: from?.toString() ?? null, to, trigger,
+            timestamp: new Date(),
+            stateSnapshot: JSON.stringify(Object.fromEntries(ctx.snapshot())),
+        });
+    }
+    /** All events across all flows. */
+    events() { return this.eventLog; }
+    /** Events for a specific flow. */
+    eventsForFlow(flowId) {
+        return this.eventLog.filter(e => e.flowId === flowId);
+    }
+    /** Append a compensation event. */
+    appendCompensation(flowId, trigger, metadata) {
+        const version = (this.versionCounters.get(flowId) ?? 0) + 1;
+        this.versionCounters.set(flowId, version);
+        this.eventLog.push({
+            flowId, version, type: 'COMPENSATION',
+            from: null, to: 'COMPENSATED', trigger,
+            timestamp: new Date(), stateSnapshot: metadata,
+        });
+    }
+    get transitionLog() { return this.delegate.transitionLog; }
+    clear() { this.delegate.clear?.(); this.eventLog = []; this.versionCounters.clear(); }
+}
+exports.EventLogStoreDecorator = EventLogStoreDecorator;

package/dist/cjs/eventstore/event-log-store-plugin.d.ts

@@ -0,0 +1,7 @@
+import type { StorePlugin, PluginDescriptor } from '../api/types.js';
+import { EventLogStoreDecorator } from './event-log-store-decorator.js';
+export declare class EventLogStorePlugin implements StorePlugin {
+    descriptor(): PluginDescriptor;
+    kind(): "STORE";
+    wrapStore(store: any): EventLogStoreDecorator;
+}

package/dist/cjs/eventstore/event-log-store-plugin.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventLogStorePlugin = void 0;
+const event_log_store_decorator_js_1 = require("./event-log-store-decorator.js");
+class EventLogStorePlugin {
+    descriptor() {
+        return { id: 'eventstore', displayName: 'Event Log Store', description: 'Tenure-lite: append-only transition log with replay' };
+    }
+    kind() { return 'STORE'; }
+    wrapStore(store) {
+        return new event_log_store_decorator_js_1.EventLogStoreDecorator(store);
+    }
+}
+exports.EventLogStorePlugin = EventLogStorePlugin;

package/dist/cjs/eventstore/replay-service.d.ts

@@ -0,0 +1,14 @@
+import type { VersionedTransitionEvent, ProjectionReducer } from './types.js';
+/**
+ * Replay service — stateAtVersion using full-snapshot assumption.
+ * If moving to diff-only persistence, this must become a fold/reducer.
+ */
+export declare class ReplayService {
+    stateAtVersion(events: readonly VersionedTransitionEvent[], flowId: string, targetVersion: number): string | null;
+}
+/**
+ * Projection replay service — custom reducers for materialized views.
+ */
+export declare class ProjectionReplayService {
+    stateAtVersion<T>(events: readonly VersionedTransitionEvent[], flowId: string, targetVersion: number, reducer: ProjectionReducer<T>): T;
+}

package/dist/cjs/eventstore/replay-service.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProjectionReplayService = exports.ReplayService = void 0;
+/**
+ * Replay service — stateAtVersion using full-snapshot assumption.
+ * If moving to diff-only persistence, this must become a fold/reducer.
+ */
+class ReplayService {
+    stateAtVersion(events, flowId, targetVersion) {
+        const flowEvents = events
+            .filter(e => e.flowId === flowId && e.type === 'TRANSITION' && e.version <= targetVersion)
+            .sort((a, b) => a.version - b.version);
+        if (flowEvents.length === 0)
+            return null;
+        return flowEvents[flowEvents.length - 1].to;
+    }
+}
+exports.ReplayService = ReplayService;
+/**
+ * Projection replay service — custom reducers for materialized views.
+ */
+class ProjectionReplayService {
+    stateAtVersion(events, flowId, targetVersion, reducer) {
+        let state = reducer.initialState();
+        for (const event of events) {
+            if (event.flowId === flowId && event.version <= targetVersion) {
+                state = reducer.apply(state, event);
+            }
+        }
+        return state;
+    }
+}
+exports.ProjectionReplayService = ProjectionReplayService;

package/dist/cjs/eventstore/types.d.ts

@@ -0,0 +1,19 @@
+export interface VersionedTransitionEvent {
+    flowId: string;
+    version: number;
+    type: 'TRANSITION' | 'COMPENSATION';
+    from: string | null;
+    to: string;
+    trigger: string;
+    timestamp: Date;
+    stateSnapshot: string;
+}
+export interface CompensationPlan {
+    action: string;
+    metadata: Record<string, string>;
+}
+export type CompensationResolver = (event: VersionedTransitionEvent, cause: Error) => CompensationPlan | null;
+export interface ProjectionReducer<T> {
+    initialState(): T;
+    apply(current: T, event: VersionedTransitionEvent): T;
+}

package/dist/cjs/eventstore/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/hierarchy/entry-exit-compiler.d.ts

@@ -0,0 +1,8 @@
+import type { HierarchicalFlowSpec, HierarchicalTransitionSpec } from './types.js';
+/**
+ * Synthesizes entry/exit transitions from hierarchical state specs.
+ */
+export declare class EntryExitCompiler {
+    synthesize(spec: HierarchicalFlowSpec): HierarchicalTransitionSpec[];
+    private walk;
+}

package/dist/cjs/hierarchy/entry-exit-compiler.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntryExitCompiler = void 0;
+/**
+ * Synthesizes entry/exit transitions from hierarchical state specs.
+ */
+class EntryExitCompiler {
+    synthesize(spec) {
+        const generated = [];
+        for (const state of spec.rootStates) {
+            this.walk(state, generated, null);
+        }
+        return generated;
+    }
+    walk(state, out, parentName) {
+        if (state.entryProduces.length > 0) {
+            out.push({
+                from: parentName ?? `${state.name}__ENTRY_START`,
+                to: state.name,
+                trigger: `__entry__${state.name}`,
+                requires: [],
+                produces: [...state.entryProduces],
+            });
+        }
+        if (state.exitProduces.length > 0) {
+            out.push({
+                from: state.name,
+                to: `${state.name}__EXIT_END`,
+                trigger: `__exit__${state.name}`,
+                requires: [],
+                produces: [...state.exitProduces],
+            });
+        }
+        for (const child of state.children) {
+            this.walk(child, out, state.name);
+        }
+    }
+}
+exports.EntryExitCompiler = EntryExitCompiler;

package/dist/cjs/hierarchy/hierarchy-code-generator.d.ts

@@ -0,0 +1,10 @@
+import type { HierarchicalFlowSpec } from './types.js';
+/**
+ * Generates TypeScript source from a hierarchical flow spec.
+ * Flattens the hierarchy into a flat state config + builder skeleton.
+ */
+export declare class HierarchyCodeGenerator {
+    generateStateConfig(spec: HierarchicalFlowSpec): string;
+    generateBuilderSkeleton(spec: HierarchicalFlowSpec): string;
+    private flatten;
+}