@unlaxer/tramli-plugins 3.0.0

package/dist/esm/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;
+}

package/dist/esm/hierarchy/hierarchy-code-generator.js

@@ -0,0 +1,44 @@
+/**
+ * Generates TypeScript source from a hierarchical flow spec.
+ * Flattens the hierarchy into a flat state config + builder skeleton.
+ */
+export class HierarchyCodeGenerator {
+    generateStateConfig(spec) {
+        const flatStates = [];
+        this.flatten(spec.rootStates, '', flatStates);
+        const lines = [];
+        lines.push(`// Generated state config for ${spec.flowName}`);
+        lines.push(`import { Tramli } from '@unlaxer/tramli';`);
+        lines.push('');
+        lines.push(`export const ${spec.enumName} = {`);
+        for (const s of flatStates) {
+            lines.push(`  ${s.enumName}: { terminal: ${s.terminal}, initial: ${s.initial} },`);
+        }
+        lines.push('} as const;');
+        lines.push('');
+        lines.push(`export type ${spec.enumName}State = keyof typeof ${spec.enumName};`);
+        return lines.join('\n');
+    }
+    generateBuilderSkeleton(spec) {
+        const lines = [];
+        lines.push(`// Generated builder skeleton for ${spec.flowName}`);
+        lines.push(`import { Tramli } from '@unlaxer/tramli';`);
+        lines.push(`import { ${spec.enumName} } from './${spec.enumName}.js';`);
+        lines.push('');
+        lines.push(`export function build${spec.flowName}() {`);
+        lines.push(`  const b = Tramli.define('${spec.flowName}', ${spec.enumName});`);
+        for (const t of spec.transitions) {
+            lines.push(`  // ${t.trigger}: ${t.from} -> ${t.to} requires [${t.requires.join(', ')}] produces [${t.produces.join(', ')}]`);
+        }
+        lines.push('  return b.build();');
+        lines.push('}');
+        return lines.join('\n');
+    }
+    flatten(states, prefix, out) {
+        for (const state of states) {
+            const flat = (prefix ? `${prefix}_${state.name}` : state.name).toUpperCase();
+            out.push({ enumName: flat, terminal: state.terminal, initial: state.initial });
+            this.flatten(state.children, flat, out);
+        }
+    }
+}

package/dist/esm/hierarchy/hierarchy-generation-plugin.d.ts

@@ -0,0 +1,8 @@
+import type { GenerationPlugin, PluginDescriptor } from '../api/types.js';
+import type { HierarchicalFlowSpec } from './types.js';
+export declare class HierarchyGenerationPlugin implements GenerationPlugin<HierarchicalFlowSpec, Map<string, string>> {
+    private readonly generator;
+    descriptor(): PluginDescriptor;
+    kind(): "GENERATION";
+    generate(input: HierarchicalFlowSpec): Map<string, string>;
+}

package/dist/esm/hierarchy/hierarchy-generation-plugin.js

@@ -0,0 +1,18 @@
+import { HierarchyCodeGenerator } from './hierarchy-code-generator.js';
+export class HierarchyGenerationPlugin {
+    generator = new HierarchyCodeGenerator();
+    descriptor() {
+        return {
+            id: 'hierarchy',
+            displayName: 'Hierarchy Generator',
+            description: 'Compiles hierarchical authoring specs into flat TypeScript state config and builder skeleton.',
+        };
+    }
+    kind() { return 'GENERATION'; }
+    generate(input) {
+        return new Map([
+            [`${input.enumName}.ts`, this.generator.generateStateConfig(input)],
+            [`${input.flowName}Generated.ts`, this.generator.generateBuilderSkeleton(input)],
+        ]);
+    }
+}

package/dist/esm/hierarchy/types.d.ts

@@ -0,0 +1,27 @@
+export interface HierarchicalStateSpec {
+    name: string;
+    initial: boolean;
+    terminal: boolean;
+    entryProduces: string[];
+    exitProduces: string[];
+    children: HierarchicalStateSpec[];
+}
+export interface HierarchicalTransitionSpec {
+    from: string;
+    to: string;
+    trigger: string;
+    requires: string[];
+    produces: string[];
+}
+export interface HierarchicalFlowSpec {
+    flowName: string;
+    enumName: string;
+    rootStates: HierarchicalStateSpec[];
+    transitions: HierarchicalTransitionSpec[];
+}
+export declare function stateSpec(name: string, opts?: {
+    initial?: boolean;
+    terminal?: boolean;
+}): HierarchicalStateSpec;
+export declare function transitionSpec(from: string, to: string, trigger: string): HierarchicalTransitionSpec;
+export declare function flowSpec(flowName: string, enumName: string): HierarchicalFlowSpec;

package/dist/esm/hierarchy/types.js

@@ -0,0 +1,16 @@
+export function stateSpec(name, opts) {
+    return {
+        name,
+        initial: opts?.initial ?? false,
+        terminal: opts?.terminal ?? false,
+        entryProduces: [],
+        exitProduces: [],
+        children: [],
+    };
+}
+export function transitionSpec(from, to, trigger) {
+    return { from, to, trigger, requires: [], produces: [] };
+}
+export function flowSpec(flowName, enumName) {
+    return { flowName, enumName, rootStates: [], transitions: [] };
+}

package/dist/esm/idempotency/idempotency-runtime-plugin.d.ts

@@ -0,0 +1,11 @@
+import type { FlowEngine } from '@unlaxer/tramli';
+import type { RuntimeAdapterPlugin, PluginDescriptor } from '../api/types.js';
+import type { IdempotencyRegistry } from './types.js';
+import { IdempotentRichResumeExecutor } from './idempotent-rich-resume-executor.js';
+export declare class IdempotencyRuntimePlugin implements RuntimeAdapterPlugin<IdempotentRichResumeExecutor> {
+    private readonly registry;
+    constructor(registry: IdempotencyRegistry);
+    descriptor(): PluginDescriptor;
+    kind(): "RUNTIME_ADAPTER";
+    bind(engine: FlowEngine): IdempotentRichResumeExecutor;
+}

package/dist/esm/idempotency/idempotency-runtime-plugin.js

@@ -0,0 +1,18 @@
+import { IdempotentRichResumeExecutor } from './idempotent-rich-resume-executor.js';
+export class IdempotencyRuntimePlugin {
+    registry;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    descriptor() {
+        return {
+            id: 'idempotency',
+            displayName: 'Idempotency',
+            description: 'Binds a FlowEngine to duplicate-suppression helpers.',
+        };
+    }
+    kind() { return 'RUNTIME_ADAPTER'; }
+    bind(engine) {
+        return new IdempotentRichResumeExecutor(engine, this.registry);
+    }
+}

package/dist/esm/idempotency/idempotent-rich-resume-executor.d.ts

@@ -0,0 +1,9 @@
+import type { FlowEngine, FlowDefinition } from '@unlaxer/tramli';
+import type { IdempotencyRegistry, CommandEnvelope } from './types.js';
+import { type RichResumeResult } from '../resume/rich-resume.js';
+export declare class IdempotentRichResumeExecutor {
+    private readonly registry;
+    private readonly delegate;
+    constructor(engine: FlowEngine, registry: IdempotencyRegistry);
+    resume<S extends string>(flowId: string, definition: FlowDefinition<S>, envelope: CommandEnvelope, knownBeforeState: S): Promise<RichResumeResult<S>>;
+}

package/dist/esm/idempotency/idempotent-rich-resume-executor.js

@@ -0,0 +1,18 @@
+import { RichResumeExecutor } from '../resume/rich-resume.js';
+export class IdempotentRichResumeExecutor {
+    registry;
+    delegate;
+    constructor(engine, registry) {
+        this.registry = registry;
+        this.delegate = new RichResumeExecutor(engine);
+    }
+    async resume(flowId, definition, envelope, knownBeforeState) {
+        if (!this.registry.markIfFirstSeen(flowId, envelope.commandId)) {
+            return {
+                status: 'ALREADY_COMPLETE',
+                error: new Error(`duplicate commandId ${envelope.commandId}`),
+            };
+        }
+        return this.delegate.resume(flowId, definition, envelope.externalData, knownBeforeState);
+    }
+}

package/dist/esm/idempotency/in-memory-idempotency-registry.d.ts

@@ -0,0 +1,5 @@
+import type { IdempotencyRegistry } from './types.js';
+export declare class InMemoryIdempotencyRegistry implements IdempotencyRegistry {
+    private readonly seen;
+    markIfFirstSeen(flowId: string, commandId: string): boolean;
+}

package/dist/esm/idempotency/in-memory-idempotency-registry.js

@@ -0,0 +1,10 @@
+export class InMemoryIdempotencyRegistry {
+    seen = new Set();
+    markIfFirstSeen(flowId, commandId) {
+        const key = `${flowId}::${commandId}`;
+        if (this.seen.has(key))
+            return false;
+        this.seen.add(key);
+        return true;
+    }
+}

package/dist/esm/idempotency/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Command envelope — wraps external data with a unique command ID for dedup.
+ */
+export interface CommandEnvelope {
+    commandId: string;
+    externalData: Map<string, unknown>;
+}
+/**
+ * Idempotency registry — tracks which commands have already been processed.
+ */
+export interface IdempotencyRegistry {
+    markIfFirstSeen(flowId: string, commandId: string): boolean;
+}

package/dist/esm/idempotency/types.js

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

package/dist/esm/index.d.ts

@@ -0,0 +1,36 @@
+export { PluginReport } from './api/types.js';
+export type { PluginKind, PluginDescriptor, FlowPlugin, AnalysisPlugin, StorePlugin, EnginePlugin, RuntimeAdapterPlugin, GenerationPlugin, DocumentationPlugin as DocumentationPluginSPI, } from './api/types.js';
+export { PluginRegistry } from './api/plugin-registry.js';
+export { AuditStorePlugin } from './audit/audit-store-plugin.js';
+export { AuditingFlowStore } from './audit/auditing-flow-store.js';
+export type { AuditedTransitionRecord } from './audit/auditing-flow-store.js';
+export { EventLogStorePlugin } from './eventstore/event-log-store-plugin.js';
+export { EventLogStoreDecorator } from './eventstore/event-log-store-decorator.js';
+export { ReplayService, ProjectionReplayService } from './eventstore/replay-service.js';
+export { CompensationService } from './eventstore/compensation-service.js';
+export type { VersionedTransitionEvent, CompensationPlan, CompensationResolver, ProjectionReducer, } from './eventstore/types.js';
+export { ObservabilityEnginePlugin, InMemoryTelemetrySink } from './observability/observability-plugin.js';
+export type { TelemetryEvent, TelemetrySink } from './observability/observability-plugin.js';
+export { RichResumeExecutor, RichResumeRuntimePlugin } from './resume/rich-resume.js';
+export type { RichResumeStatus, RichResumeResult } from './resume/rich-resume.js';
+export { InMemoryIdempotencyRegistry } from './idempotency/in-memory-idempotency-registry.js';
+export { IdempotentRichResumeExecutor } from './idempotency/idempotent-rich-resume-executor.js';
+export { IdempotencyRuntimePlugin } from './idempotency/idempotency-runtime-plugin.js';
+export type { CommandEnvelope, IdempotencyRegistry } from './idempotency/types.js';
+export { EntryExitCompiler } from './hierarchy/entry-exit-compiler.js';
+export { HierarchyCodeGenerator } from './hierarchy/hierarchy-code-generator.js';
+export { HierarchyGenerationPlugin } from './hierarchy/hierarchy-generation-plugin.js';
+export type { HierarchicalStateSpec, HierarchicalTransitionSpec, HierarchicalFlowSpec, } from './hierarchy/types.js';
+export { stateSpec, transitionSpec, flowSpec } from './hierarchy/types.js';
+export { DiagramPlugin } from './diagram/diagram-plugin.js';
+export { DiagramGenerationPlugin } from './diagram/diagram-generation-plugin.js';
+export type { DiagramBundle } from './diagram/types.js';
+export { DocumentationPlugin } from './docs/documentation-plugin.js';
+export { FlowDocumentationPlugin } from './docs/flow-documentation-plugin.js';
+export { PolicyLintPlugin } from './lint/policy-lint-plugin.js';
+export { allDefaultPolicies } from './lint/default-flow-policies.js';
+export type { FlowPolicy } from './lint/types.js';
+export { ScenarioTestPlugin } from './testing/scenario-test-plugin.js';
+export { ScenarioGenerationPlugin } from './testing/scenario-generation-plugin.js';
+export type { FlowScenario, FlowTestPlan } from './testing/types.js';
+export { GuaranteedSubflowValidator } from './subflow/guaranteed-subflow-validator.js';

package/dist/esm/index.js

@@ -0,0 +1,38 @@
+// ── API framework ──
+export { PluginReport } from './api/types.js';
+export { PluginRegistry } from './api/plugin-registry.js';
+// ── Audit ──
+export { AuditStorePlugin } from './audit/audit-store-plugin.js';
+export { AuditingFlowStore } from './audit/auditing-flow-store.js';
+// ── Event Store ──
+export { EventLogStorePlugin } from './eventstore/event-log-store-plugin.js';
+export { EventLogStoreDecorator } from './eventstore/event-log-store-decorator.js';
+export { ReplayService, ProjectionReplayService } from './eventstore/replay-service.js';
+export { CompensationService } from './eventstore/compensation-service.js';
+// ── Observability ──
+export { ObservabilityEnginePlugin, InMemoryTelemetrySink } from './observability/observability-plugin.js';
+// ── Rich Resume ──
+export { RichResumeExecutor, RichResumeRuntimePlugin } from './resume/rich-resume.js';
+// ── Idempotency ──
+export { InMemoryIdempotencyRegistry } from './idempotency/in-memory-idempotency-registry.js';
+export { IdempotentRichResumeExecutor } from './idempotency/idempotent-rich-resume-executor.js';
+export { IdempotencyRuntimePlugin } from './idempotency/idempotency-runtime-plugin.js';
+// ── Hierarchy ──
+export { EntryExitCompiler } from './hierarchy/entry-exit-compiler.js';
+export { HierarchyCodeGenerator } from './hierarchy/hierarchy-code-generator.js';
+export { HierarchyGenerationPlugin } from './hierarchy/hierarchy-generation-plugin.js';
+export { stateSpec, transitionSpec, flowSpec } from './hierarchy/types.js';
+// ── Diagram ──
+export { DiagramPlugin } from './diagram/diagram-plugin.js';
+export { DiagramGenerationPlugin } from './diagram/diagram-generation-plugin.js';
+// ── Documentation ──
+export { DocumentationPlugin } from './docs/documentation-plugin.js';
+export { FlowDocumentationPlugin } from './docs/flow-documentation-plugin.js';
+// ── Lint ──
+export { PolicyLintPlugin } from './lint/policy-lint-plugin.js';
+export { allDefaultPolicies } from './lint/default-flow-policies.js';
+// ── Testing ──
+export { ScenarioTestPlugin } from './testing/scenario-test-plugin.js';
+export { ScenarioGenerationPlugin } from './testing/scenario-generation-plugin.js';
+// ── SubFlow ──
+export { GuaranteedSubflowValidator } from './subflow/guaranteed-subflow-validator.js';

package/dist/esm/lint/default-flow-policies.d.ts

@@ -0,0 +1,2 @@
+import type { FlowPolicy } from './types.js';
+export declare function allDefaultPolicies<S extends string>(): FlowPolicy<S>[];

package/dist/esm/lint/default-flow-policies.js

@@ -0,0 +1,38 @@
+function warnTerminalWithOutgoing(def, report) {
+    for (const state of def.terminalStates) {
+        if (def.transitionsFrom(state).length > 0) {
+            report.warn('policy/terminal-outgoing', `terminal state ${state} has outgoing transitions`);
+        }
+    }
+}
+function warnTooManyExternals(def, report) {
+    for (const state of def.allStates()) {
+        const externals = def.transitionsFrom(state).filter(t => t.type === 'external');
+        if (externals.length > 3) {
+            report.warn('policy/external-count', `state ${state} has ${externals.length} external transitions`);
+        }
+    }
+}
+function warnDeadProducedData(def, report) {
+    if (!def.dataFlowGraph)
+        return;
+    const dead = def.dataFlowGraph.deadData();
+    for (const key of dead) {
+        report.warn('policy/dead-data', `produced but never consumed: ${key}`);
+    }
+}
+function warnOverwideProcessors(def, report) {
+    for (const t of def.transitions) {
+        if (t.processor && t.processor.produces.length > 3) {
+            report.warn('policy/overwide-processor', `${t.processor.name} produces ${t.processor.produces.length} types; consider splitting it`);
+        }
+    }
+}
+export function allDefaultPolicies() {
+    return [
+        warnTerminalWithOutgoing,
+        warnTooManyExternals,
+        warnDeadProducedData,
+        warnOverwideProcessors,
+    ];
+}

package/dist/esm/lint/policy-lint-plugin.d.ts

@@ -0,0 +1,11 @@
+import type { FlowDefinition } from '@unlaxer/tramli';
+import type { AnalysisPlugin, PluginDescriptor, PluginReport } from '../api/types.js';
+import type { FlowPolicy } from './types.js';
+export declare class PolicyLintPlugin<S extends string> implements AnalysisPlugin<S> {
+    private readonly policies;
+    constructor(policies: FlowPolicy<S>[]);
+    static defaults<S extends string>(): PolicyLintPlugin<S>;
+    descriptor(): PluginDescriptor;
+    kind(): "ANALYSIS";
+    analyze(definition: FlowDefinition<S>, report: PluginReport): void;
+}

package/dist/esm/lint/policy-lint-plugin.js

@@ -0,0 +1,23 @@
+import { allDefaultPolicies } from './default-flow-policies.js';
+export class PolicyLintPlugin {
+    policies;
+    constructor(policies) {
+        this.policies = policies;
+    }
+    static defaults() {
+        return new PolicyLintPlugin(allDefaultPolicies());
+    }
+    descriptor() {
+        return {
+            id: 'policy-lint',
+            displayName: 'Policy Lint',
+            description: 'Applies design-time lint policies to a flow definition.',
+        };
+    }
+    kind() { return 'ANALYSIS'; }
+    analyze(definition, report) {
+        for (const policy of this.policies) {
+            policy(definition, report);
+        }
+    }
+}

package/dist/esm/lint/types.d.ts

@@ -0,0 +1,5 @@
+import type { FlowDefinition } from '@unlaxer/tramli';
+import type { PluginReport } from '../api/types.js';
+export interface FlowPolicy<S extends string> {
+    (definition: FlowDefinition<S>, report: PluginReport): void;
+}

package/dist/esm/lint/types.js

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

package/dist/esm/observability/observability-plugin.d.ts

@@ -0,0 +1,25 @@
+import type { FlowEngine } from '@unlaxer/tramli';
+import type { EnginePlugin, PluginDescriptor } from '../api/types.js';
+export interface TelemetryEvent {
+    type: 'transition' | 'guard' | 'error' | 'state';
+    flowId: string;
+    flowName: string;
+    data: Record<string, unknown>;
+    timestamp: Date;
+}
+export interface TelemetrySink {
+    emit(event: TelemetryEvent): void;
+    events(): readonly TelemetryEvent[];
+}
+export declare class InMemoryTelemetrySink implements TelemetrySink {
+    private log;
+    emit(event: TelemetryEvent): void;
+    events(): readonly TelemetryEvent[];
+}
+export declare class ObservabilityEnginePlugin implements EnginePlugin {
+    private readonly sink;
+    constructor(sink: TelemetrySink);
+    descriptor(): PluginDescriptor;
+    kind(): "ENGINE";
+    install(engine: FlowEngine): void;
+}

package/dist/esm/observability/observability-plugin.js

@@ -0,0 +1,31 @@
+export class InMemoryTelemetrySink {
+    log = [];
+    emit(event) { this.log.push(event); }
+    events() { return this.log; }
+}
+export class ObservabilityEnginePlugin {
+    sink;
+    constructor(sink) {
+        this.sink = sink;
+    }
+    descriptor() {
+        return { id: 'observability', displayName: 'Observability', description: 'Telemetry via engine logger hooks' };
+    }
+    kind() { return 'ENGINE'; }
+    install(engine) {
+        engine.setTransitionLogger(entry => {
+            this.sink.emit({
+                type: 'transition', flowId: entry.flowId, flowName: '',
+                data: { from: entry.from, to: entry.to, trigger: entry.trigger },
+                timestamp: new Date(),
+            });
+        });
+        engine.setErrorLogger(entry => {
+            this.sink.emit({
+                type: 'error', flowId: entry.flowId, flowName: '',
+                data: { from: entry.from, to: entry.to, trigger: entry.trigger, cause: entry.cause?.message },
+                timestamp: new Date(),
+            });
+        });
+    }
+}

package/dist/esm/resume/rich-resume.d.ts

@@ -0,0 +1,21 @@
+import type { FlowEngine, FlowDefinition, FlowInstance } from '@unlaxer/tramli';
+import type { RuntimeAdapterPlugin, PluginDescriptor } from '../api/types.js';
+export type RichResumeStatus = 'TRANSITIONED' | 'ALREADY_COMPLETE' | 'NO_APPLICABLE_TRANSITION' | 'REJECTED' | 'EXCEPTION_ROUTED';
+export interface RichResumeResult<S extends string> {
+    status: RichResumeStatus;
+    flow?: FlowInstance<S>;
+    error?: Error;
+}
+/**
+ * Enhanced resumeAndExecute with explicit status classification.
+ */
+export declare class RichResumeExecutor {
+    private readonly engine;
+    constructor(engine: FlowEngine);
+    resume<S extends string>(flowId: string, definition: FlowDefinition<S>, externalData: Map<string, unknown>, previousState: S): Promise<RichResumeResult<S>>;
+}
+export declare class RichResumeRuntimePlugin implements RuntimeAdapterPlugin<RichResumeExecutor> {
+    descriptor(): PluginDescriptor;
+    kind(): "RUNTIME_ADAPTER";
+    bind(engine: FlowEngine): RichResumeExecutor;
+}

package/dist/esm/resume/rich-resume.js

@@ -0,0 +1,42 @@
+/**
+ * Enhanced resumeAndExecute with explicit status classification.
+ */
+export class RichResumeExecutor {
+    engine;
+    constructor(engine) {
+        this.engine = engine;
+    }
+    async resume(flowId, definition, externalData, previousState) {
+        try {
+            const flow = await this.engine.resumeAndExecute(flowId, definition, externalData);
+            if (flow.isCompleted && flow.currentState === previousState) {
+                return { status: 'ALREADY_COMPLETE', flow };
+            }
+            if (flow.currentState === previousState && !flow.isCompleted) {
+                return { status: 'REJECTED', flow };
+            }
+            return { status: 'TRANSITIONED', flow };
+        }
+        catch (e) {
+            if (e.code === 'FLOW_ALREADY_COMPLETED') {
+                return { status: 'ALREADY_COMPLETE', error: e };
+            }
+            if (e.code === 'FLOW_NOT_FOUND') {
+                return { status: 'NO_APPLICABLE_TRANSITION', error: e };
+            }
+            if (e.code === 'INVALID_TRANSITION') {
+                return { status: 'NO_APPLICABLE_TRANSITION', error: e };
+            }
+            return { status: 'EXCEPTION_ROUTED', error: e };
+        }
+    }
+}
+export class RichResumeRuntimePlugin {
+    descriptor() {
+        return { id: 'rich-resume', displayName: 'Rich Resume', description: 'Enhanced resume with status classification' };
+    }
+    kind() { return 'RUNTIME_ADAPTER'; }
+    bind(engine) {
+        return new RichResumeExecutor(engine);
+    }
+}

package/dist/esm/subflow/guaranteed-subflow-validator.d.ts

@@ -0,0 +1,8 @@
+import type { FlowDefinition } from '@unlaxer/tramli';
+/**
+ * Validates that a subflow's entry requirements are satisfied
+ * by the parent flow's available data at a given state plus any guaranteed types.
+ */
+export declare class GuaranteedSubflowValidator {
+    validate<S extends string, T extends string>(parent: FlowDefinition<S>, parentState: S, subflow: FlowDefinition<T>, guaranteedTypes: Set<string>): void;
+}

package/dist/esm/subflow/guaranteed-subflow-validator.js

@@ -0,0 +1,27 @@
+/**
+ * Validates that a subflow's entry requirements are satisfied
+ * by the parent flow's available data at a given state plus any guaranteed types.
+ */
+export class GuaranteedSubflowValidator {
+    validate(parent, parentState, subflow, guaranteedTypes) {
+        if (!parent.dataFlowGraph || !subflow.dataFlowGraph) {
+            throw new Error('DataFlowGraph is required for subflow validation');
+        }
+        const available = new Set(parent.dataFlowGraph.availableAt(parentState));
+        for (const t of guaranteedTypes)
+            available.add(t);
+        const initialState = subflow.initialState;
+        if (initialState == null) {
+            throw new Error(`Subflow ${subflow.name} has no initial state`);
+        }
+        const requiredAtEntry = subflow.dataFlowGraph.availableAt(initialState);
+        const missing = [];
+        for (const req of requiredAtEntry) {
+            if (!available.has(req))
+                missing.push(req);
+        }
+        if (missing.length > 0) {
+            throw new Error(`Subflow ${subflow.name} is missing guaranteed types at entry: [${missing.join(', ')}]`);
+        }
+    }
+}

package/dist/esm/testing/scenario-generation-plugin.d.ts

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

package/dist/esm/testing/scenario-generation-plugin.js

@@ -0,0 +1,15 @@
+import { ScenarioTestPlugin } from './scenario-test-plugin.js';
+export class ScenarioGenerationPlugin {
+    delegate = new ScenarioTestPlugin();
+    descriptor() {
+        return {
+            id: 'scenario-tests',
+            displayName: 'Scenario Test Generator',
+            description: 'Produces scenario-oriented test plans from a flow definition.',
+        };
+    }
+    kind() { return 'GENERATION'; }
+    generate(input) {
+        return this.delegate.generate(input);
+    }
+}

package/dist/esm/testing/scenario-test-plugin.d.ts

@@ -0,0 +1,8 @@
+import type { FlowDefinition } from '@unlaxer/tramli';
+import type { FlowTestPlan } from './types.js';
+/**
+ * Generates BDD-style test scenarios from a flow definition.
+ */
+export declare class ScenarioTestPlugin {
+    generate<S extends string>(definition: FlowDefinition<S>): FlowTestPlan;
+}

package/dist/esm/testing/scenario-test-plugin.js

@@ -0,0 +1,24 @@
+/**
+ * Generates BDD-style test scenarios from a flow definition.
+ */
+export class ScenarioTestPlugin {
+    generate(definition) {
+        const scenarios = [];
+        for (const t of definition.transitions) {
+            const steps = [];
+            steps.push(`given flow in ${t.from}`);
+            if (t.type === 'external' && t.guard) {
+                steps.push(`when external data satisfies guard ${t.guard.name}`);
+            }
+            if (t.type === 'auto' && t.processor) {
+                steps.push(`when auto processor ${t.processor.name} runs`);
+            }
+            if (t.type === 'branch' && t.branch) {
+                steps.push(`when branch ${t.branch.name} selects a route`);
+            }
+            steps.push(`then flow reaches ${t.to}`);
+            scenarios.push({ name: `${t.from}_to_${t.to}`, steps });
+        }
+        return { scenarios };
+    }
+}

package/dist/esm/testing/types.d.ts

@@ -0,0 +1,7 @@
+export interface FlowScenario {
+    name: string;
+    steps: string[];
+}
+export interface FlowTestPlan {
+    scenarios: readonly FlowScenario[];
+}

package/dist/esm/testing/types.js

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