@unlaxer/tramli-plugins 3.0.0

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

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HierarchyCodeGenerator = void 0;
+/**
+ * Generates TypeScript source from a hierarchical flow spec.
+ * Flattens the hierarchy into a flat state config + builder skeleton.
+ */
+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);
+        }
+    }
+}
+exports.HierarchyCodeGenerator = HierarchyCodeGenerator;

package/dist/cjs/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/cjs/hierarchy/hierarchy-generation-plugin.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HierarchyGenerationPlugin = void 0;
+const hierarchy_code_generator_js_1 = require("./hierarchy-code-generator.js");
+class HierarchyGenerationPlugin {
+    generator = new hierarchy_code_generator_js_1.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)],
+        ]);
+    }
+}
+exports.HierarchyGenerationPlugin = HierarchyGenerationPlugin;

package/dist/cjs/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/cjs/hierarchy/types.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stateSpec = stateSpec;
+exports.transitionSpec = transitionSpec;
+exports.flowSpec = flowSpec;
+function stateSpec(name, opts) {
+    return {
+        name,
+        initial: opts?.initial ?? false,
+        terminal: opts?.terminal ?? false,
+        entryProduces: [],
+        exitProduces: [],
+        children: [],
+    };
+}
+function transitionSpec(from, to, trigger) {
+    return { from, to, trigger, requires: [], produces: [] };
+}
+function flowSpec(flowName, enumName) {
+    return { flowName, enumName, rootStates: [], transitions: [] };
+}

package/dist/cjs/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/cjs/idempotency/idempotency-runtime-plugin.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdempotencyRuntimePlugin = void 0;
+const idempotent_rich_resume_executor_js_1 = require("./idempotent-rich-resume-executor.js");
+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 idempotent_rich_resume_executor_js_1.IdempotentRichResumeExecutor(engine, this.registry);
+    }
+}
+exports.IdempotencyRuntimePlugin = IdempotencyRuntimePlugin;

package/dist/cjs/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/cjs/idempotency/idempotent-rich-resume-executor.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdempotentRichResumeExecutor = void 0;
+const rich_resume_js_1 = require("../resume/rich-resume.js");
+class IdempotentRichResumeExecutor {
+    registry;
+    delegate;
+    constructor(engine, registry) {
+        this.registry = registry;
+        this.delegate = new rich_resume_js_1.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);
+    }
+}
+exports.IdempotentRichResumeExecutor = IdempotentRichResumeExecutor;

package/dist/cjs/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/cjs/idempotency/in-memory-idempotency-registry.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryIdempotencyRegistry = void 0;
+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;
+    }
+}
+exports.InMemoryIdempotencyRegistry = InMemoryIdempotencyRegistry;

package/dist/cjs/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/cjs/idempotency/types.js

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

package/dist/cjs/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/cjs/index.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuaranteedSubflowValidator = exports.ScenarioGenerationPlugin = exports.ScenarioTestPlugin = exports.allDefaultPolicies = exports.PolicyLintPlugin = exports.FlowDocumentationPlugin = exports.DocumentationPlugin = exports.DiagramGenerationPlugin = exports.DiagramPlugin = exports.flowSpec = exports.transitionSpec = exports.stateSpec = exports.HierarchyGenerationPlugin = exports.HierarchyCodeGenerator = exports.EntryExitCompiler = exports.IdempotencyRuntimePlugin = exports.IdempotentRichResumeExecutor = exports.InMemoryIdempotencyRegistry = exports.RichResumeRuntimePlugin = exports.RichResumeExecutor = exports.InMemoryTelemetrySink = exports.ObservabilityEnginePlugin = exports.CompensationService = exports.ProjectionReplayService = exports.ReplayService = exports.EventLogStoreDecorator = exports.EventLogStorePlugin = exports.AuditingFlowStore = exports.AuditStorePlugin = exports.PluginRegistry = exports.PluginReport = void 0;
+// ── API framework ──
+var types_js_1 = require("./api/types.js");
+Object.defineProperty(exports, "PluginReport", { enumerable: true, get: function () { return types_js_1.PluginReport; } });
+var plugin_registry_js_1 = require("./api/plugin-registry.js");
+Object.defineProperty(exports, "PluginRegistry", { enumerable: true, get: function () { return plugin_registry_js_1.PluginRegistry; } });
+// ── Audit ──
+var audit_store_plugin_js_1 = require("./audit/audit-store-plugin.js");
+Object.defineProperty(exports, "AuditStorePlugin", { enumerable: true, get: function () { return audit_store_plugin_js_1.AuditStorePlugin; } });
+var auditing_flow_store_js_1 = require("./audit/auditing-flow-store.js");
+Object.defineProperty(exports, "AuditingFlowStore", { enumerable: true, get: function () { return auditing_flow_store_js_1.AuditingFlowStore; } });
+// ── Event Store ──
+var event_log_store_plugin_js_1 = require("./eventstore/event-log-store-plugin.js");
+Object.defineProperty(exports, "EventLogStorePlugin", { enumerable: true, get: function () { return event_log_store_plugin_js_1.EventLogStorePlugin; } });
+var event_log_store_decorator_js_1 = require("./eventstore/event-log-store-decorator.js");
+Object.defineProperty(exports, "EventLogStoreDecorator", { enumerable: true, get: function () { return event_log_store_decorator_js_1.EventLogStoreDecorator; } });
+var replay_service_js_1 = require("./eventstore/replay-service.js");
+Object.defineProperty(exports, "ReplayService", { enumerable: true, get: function () { return replay_service_js_1.ReplayService; } });
+Object.defineProperty(exports, "ProjectionReplayService", { enumerable: true, get: function () { return replay_service_js_1.ProjectionReplayService; } });
+var compensation_service_js_1 = require("./eventstore/compensation-service.js");
+Object.defineProperty(exports, "CompensationService", { enumerable: true, get: function () { return compensation_service_js_1.CompensationService; } });
+// ── Observability ──
+var observability_plugin_js_1 = require("./observability/observability-plugin.js");
+Object.defineProperty(exports, "ObservabilityEnginePlugin", { enumerable: true, get: function () { return observability_plugin_js_1.ObservabilityEnginePlugin; } });
+Object.defineProperty(exports, "InMemoryTelemetrySink", { enumerable: true, get: function () { return observability_plugin_js_1.InMemoryTelemetrySink; } });
+// ── Rich Resume ──
+var rich_resume_js_1 = require("./resume/rich-resume.js");
+Object.defineProperty(exports, "RichResumeExecutor", { enumerable: true, get: function () { return rich_resume_js_1.RichResumeExecutor; } });
+Object.defineProperty(exports, "RichResumeRuntimePlugin", { enumerable: true, get: function () { return rich_resume_js_1.RichResumeRuntimePlugin; } });
+// ── Idempotency ──
+var in_memory_idempotency_registry_js_1 = require("./idempotency/in-memory-idempotency-registry.js");
+Object.defineProperty(exports, "InMemoryIdempotencyRegistry", { enumerable: true, get: function () { return in_memory_idempotency_registry_js_1.InMemoryIdempotencyRegistry; } });
+var idempotent_rich_resume_executor_js_1 = require("./idempotency/idempotent-rich-resume-executor.js");
+Object.defineProperty(exports, "IdempotentRichResumeExecutor", { enumerable: true, get: function () { return idempotent_rich_resume_executor_js_1.IdempotentRichResumeExecutor; } });
+var idempotency_runtime_plugin_js_1 = require("./idempotency/idempotency-runtime-plugin.js");
+Object.defineProperty(exports, "IdempotencyRuntimePlugin", { enumerable: true, get: function () { return idempotency_runtime_plugin_js_1.IdempotencyRuntimePlugin; } });
+// ── Hierarchy ──
+var entry_exit_compiler_js_1 = require("./hierarchy/entry-exit-compiler.js");
+Object.defineProperty(exports, "EntryExitCompiler", { enumerable: true, get: function () { return entry_exit_compiler_js_1.EntryExitCompiler; } });
+var hierarchy_code_generator_js_1 = require("./hierarchy/hierarchy-code-generator.js");
+Object.defineProperty(exports, "HierarchyCodeGenerator", { enumerable: true, get: function () { return hierarchy_code_generator_js_1.HierarchyCodeGenerator; } });
+var hierarchy_generation_plugin_js_1 = require("./hierarchy/hierarchy-generation-plugin.js");
+Object.defineProperty(exports, "HierarchyGenerationPlugin", { enumerable: true, get: function () { return hierarchy_generation_plugin_js_1.HierarchyGenerationPlugin; } });
+var types_js_2 = require("./hierarchy/types.js");
+Object.defineProperty(exports, "stateSpec", { enumerable: true, get: function () { return types_js_2.stateSpec; } });
+Object.defineProperty(exports, "transitionSpec", { enumerable: true, get: function () { return types_js_2.transitionSpec; } });
+Object.defineProperty(exports, "flowSpec", { enumerable: true, get: function () { return types_js_2.flowSpec; } });
+// ── Diagram ──
+var diagram_plugin_js_1 = require("./diagram/diagram-plugin.js");
+Object.defineProperty(exports, "DiagramPlugin", { enumerable: true, get: function () { return diagram_plugin_js_1.DiagramPlugin; } });
+var diagram_generation_plugin_js_1 = require("./diagram/diagram-generation-plugin.js");
+Object.defineProperty(exports, "DiagramGenerationPlugin", { enumerable: true, get: function () { return diagram_generation_plugin_js_1.DiagramGenerationPlugin; } });
+// ── Documentation ──
+var documentation_plugin_js_1 = require("./docs/documentation-plugin.js");
+Object.defineProperty(exports, "DocumentationPlugin", { enumerable: true, get: function () { return documentation_plugin_js_1.DocumentationPlugin; } });
+var flow_documentation_plugin_js_1 = require("./docs/flow-documentation-plugin.js");
+Object.defineProperty(exports, "FlowDocumentationPlugin", { enumerable: true, get: function () { return flow_documentation_plugin_js_1.FlowDocumentationPlugin; } });
+// ── Lint ──
+var policy_lint_plugin_js_1 = require("./lint/policy-lint-plugin.js");
+Object.defineProperty(exports, "PolicyLintPlugin", { enumerable: true, get: function () { return policy_lint_plugin_js_1.PolicyLintPlugin; } });
+var default_flow_policies_js_1 = require("./lint/default-flow-policies.js");
+Object.defineProperty(exports, "allDefaultPolicies", { enumerable: true, get: function () { return default_flow_policies_js_1.allDefaultPolicies; } });
+// ── Testing ──
+var scenario_test_plugin_js_1 = require("./testing/scenario-test-plugin.js");
+Object.defineProperty(exports, "ScenarioTestPlugin", { enumerable: true, get: function () { return scenario_test_plugin_js_1.ScenarioTestPlugin; } });
+var scenario_generation_plugin_js_1 = require("./testing/scenario-generation-plugin.js");
+Object.defineProperty(exports, "ScenarioGenerationPlugin", { enumerable: true, get: function () { return scenario_generation_plugin_js_1.ScenarioGenerationPlugin; } });
+// ── SubFlow ──
+var guaranteed_subflow_validator_js_1 = require("./subflow/guaranteed-subflow-validator.js");
+Object.defineProperty(exports, "GuaranteedSubflowValidator", { enumerable: true, get: function () { return guaranteed_subflow_validator_js_1.GuaranteedSubflowValidator; } });

package/dist/cjs/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/cjs/lint/default-flow-policies.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allDefaultPolicies = allDefaultPolicies;
+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`);
+        }
+    }
+}
+function allDefaultPolicies() {
+    return [
+        warnTerminalWithOutgoing,
+        warnTooManyExternals,
+        warnDeadProducedData,
+        warnOverwideProcessors,
+    ];
+}

package/dist/cjs/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/cjs/lint/policy-lint-plugin.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyLintPlugin = void 0;
+const default_flow_policies_js_1 = require("./default-flow-policies.js");
+class PolicyLintPlugin {
+    policies;
+    constructor(policies) {
+        this.policies = policies;
+    }
+    static defaults() {
+        return new PolicyLintPlugin((0, default_flow_policies_js_1.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);
+        }
+    }
+}
+exports.PolicyLintPlugin = PolicyLintPlugin;

package/dist/cjs/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/cjs/lint/types.js

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

package/dist/cjs/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/cjs/observability/observability-plugin.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObservabilityEnginePlugin = exports.InMemoryTelemetrySink = void 0;
+class InMemoryTelemetrySink {
+    log = [];
+    emit(event) { this.log.push(event); }
+    events() { return this.log; }
+}
+exports.InMemoryTelemetrySink = InMemoryTelemetrySink;
+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(),
+            });
+        });
+    }
+}
+exports.ObservabilityEnginePlugin = ObservabilityEnginePlugin;

package/dist/cjs/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/cjs/resume/rich-resume.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RichResumeRuntimePlugin = exports.RichResumeExecutor = void 0;
+/**
+ * Enhanced resumeAndExecute with explicit status classification.
+ */
+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 };
+        }
+    }
+}
+exports.RichResumeExecutor = RichResumeExecutor;
+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);
+    }
+}
+exports.RichResumeRuntimePlugin = RichResumeRuntimePlugin;

package/dist/cjs/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/cjs/subflow/guaranteed-subflow-validator.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuaranteedSubflowValidator = void 0;
+/**
+ * Validates that a subflow's entry requirements are satisfied
+ * by the parent flow's available data at a given state plus any guaranteed types.
+ */
+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(', ')}]`);
+        }
+    }
+}
+exports.GuaranteedSubflowValidator = GuaranteedSubflowValidator;

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