@unlaxer/tramli-plugins 3.3.0 → 3.5.0

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

@@ -1,13 +1,26 @@
 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.
+ * Replay service — reconstructs flow state at any version.
+ *
+ * Assumes each TRANSITION event stores a full snapshot of the state.
+ * Returns the latest matching state at or before the requested version.
+ *
+ * If the event log is later changed to store diffs instead of full snapshots,
+ * use {@link ProjectionReplayService} with a fold/reducer instead.
  */
 export declare class ReplayService {
     stateAtVersion(events: readonly VersionedTransitionEvent[], flowId: string, targetVersion: number): string | null;
 }
 /**
- * Projection replay service — custom reducers for materialized views.
+ * Projection replay service — fold/reducer model for custom aggregations.
+ *
+ * Unlike {@link ReplayService} which assumes full snapshots,
+ * this service supports both full-snapshot and diff-based event logs.
+ * `reducer.initialState()` returns the empty starting state,
+ * `reducer.apply(state, event)` accumulates each event.
+ *
+ * Use for custom aggregations (transition count, cumulative metrics)
+ * or when the event log stores diffs rather than full snapshots.
  */
 export declare class ProjectionReplayService {
     stateAtVersion<T>(events: readonly VersionedTransitionEvent[], flowId: string, targetVersion: number, reducer: ProjectionReducer<T>): T;

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

@@ -2,8 +2,13 @@
 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.
+ * Replay service — reconstructs flow state at any version.
+ *
+ * Assumes each TRANSITION event stores a full snapshot of the state.
+ * Returns the latest matching state at or before the requested version.
+ *
+ * If the event log is later changed to store diffs instead of full snapshots,
+ * use {@link ProjectionReplayService} with a fold/reducer instead.
  */
 class ReplayService {
     stateAtVersion(events, flowId, targetVersion) {
@@ -17,7 +22,15 @@ class ReplayService {
 }
 exports.ReplayService = ReplayService;
 /**
- * Projection replay service — custom reducers for materialized views.
+ * Projection replay service — fold/reducer model for custom aggregations.
+ *
+ * Unlike {@link ReplayService} which assumes full snapshots,
+ * this service supports both full-snapshot and diff-based event logs.
+ * `reducer.initialState()` returns the empty starting state,
+ * `reducer.apply(state, event)` accumulates each event.
+ *
+ * Use for custom aggregations (transition count, cumulative metrics)
+ * or when the event log stores diffs rather than full snapshots.
  */
 class ProjectionReplayService {
     stateAtVersion(events, flowId, targetVersion, reducer) {

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

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

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PolicyLintPlugin = void 0;
+const types_js_1 = require("../api/types.js");
 const default_flow_policies_js_1 = require("./default-flow-policies.js");
 class PolicyLintPlugin {
     policies;
@@ -19,9 +20,11 @@ class PolicyLintPlugin {
     }
     kind() { return 'ANALYSIS'; }
     analyze(definition, report) {
+        const r = report ?? new types_js_1.PluginReport();
         for (const policy of this.policies) {
-            policy(definition, report);
+            policy(definition, r);
         }
+        return r;
     }
 }
 exports.PolicyLintPlugin = PolicyLintPlugin;

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

@@ -21,5 +21,7 @@ export declare class ObservabilityEnginePlugin implements EnginePlugin {
     constructor(sink: TelemetrySink);
     descriptor(): PluginDescriptor;
     kind(): "ENGINE";
-    install(engine: FlowEngine): void;
+    install(engine: FlowEngine, options?: {
+        append?: boolean;
+    }): void;
 }

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

@@ -16,18 +16,32 @@ class ObservabilityEnginePlugin {
         return { id: 'observability', displayName: 'Observability', description: 'Telemetry via engine logger hooks' };
     }
     kind() { return 'ENGINE'; }
-    install(engine) {
+    install(engine, options) {
+        const append = options?.append ?? false;
+        const prevTransition = append ? engine.getTransitionLogger() : undefined;
+        const prevError = append ? engine.getErrorLogger() : undefined;
+        const prevGuard = append ? engine.getGuardLogger() : undefined;
         engine.setTransitionLogger(entry => {
+            prevTransition?.(entry);
             this.sink.emit({
-                type: 'transition', flowId: entry.flowId, flowName: '',
-                data: { from: entry.from, to: entry.to, trigger: entry.trigger },
+                type: 'transition', flowId: entry.flowId, flowName: entry.flowName,
+                data: { from: entry.from, to: entry.to, trigger: entry.trigger, durationMicros: entry.durationMicros },
                 timestamp: new Date(),
             });
         });
         engine.setErrorLogger(entry => {
+            prevError?.(entry);
             this.sink.emit({
-                type: 'error', flowId: entry.flowId, flowName: '',
-                data: { from: entry.from, to: entry.to, trigger: entry.trigger, cause: entry.cause?.message },
+                type: 'error', flowId: entry.flowId, flowName: entry.flowName,
+                data: { from: entry.from, to: entry.to, trigger: entry.trigger, cause: entry.cause?.message, durationMicros: entry.durationMicros },
+                timestamp: new Date(),
+            });
+        });
+        engine.setGuardLogger((entry) => {
+            prevGuard?.(entry);
+            this.sink.emit({
+                type: 'guard', flowId: entry.flowId, flowName: entry.flowName,
+                data: { state: entry.state, guardName: entry.guardName, result: entry.result, reason: entry.reason, durationMicros: entry.durationMicros },
                 timestamp: new Date(),
             });
         });

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

@@ -1,13 +1,26 @@
 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.
+ * Replay service — reconstructs flow state at any version.
+ *
+ * Assumes each TRANSITION event stores a full snapshot of the state.
+ * Returns the latest matching state at or before the requested version.
+ *
+ * If the event log is later changed to store diffs instead of full snapshots,
+ * use {@link ProjectionReplayService} with a fold/reducer instead.
  */
 export declare class ReplayService {
     stateAtVersion(events: readonly VersionedTransitionEvent[], flowId: string, targetVersion: number): string | null;
 }
 /**
- * Projection replay service — custom reducers for materialized views.
+ * Projection replay service — fold/reducer model for custom aggregations.
+ *
+ * Unlike {@link ReplayService} which assumes full snapshots,
+ * this service supports both full-snapshot and diff-based event logs.
+ * `reducer.initialState()` returns the empty starting state,
+ * `reducer.apply(state, event)` accumulates each event.
+ *
+ * Use for custom aggregations (transition count, cumulative metrics)
+ * or when the event log stores diffs rather than full snapshots.
  */
 export declare class ProjectionReplayService {
     stateAtVersion<T>(events: readonly VersionedTransitionEvent[], flowId: string, targetVersion: number, reducer: ProjectionReducer<T>): T;

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

@@ -1,6 +1,11 @@
 /**
- * Replay service — stateAtVersion using full-snapshot assumption.
- * If moving to diff-only persistence, this must become a fold/reducer.
+ * Replay service — reconstructs flow state at any version.
+ *
+ * Assumes each TRANSITION event stores a full snapshot of the state.
+ * Returns the latest matching state at or before the requested version.
+ *
+ * If the event log is later changed to store diffs instead of full snapshots,
+ * use {@link ProjectionReplayService} with a fold/reducer instead.
  */
 export class ReplayService {
     stateAtVersion(events, flowId, targetVersion) {
@@ -13,7 +18,15 @@ export class ReplayService {
     }
 }
 /**
- * Projection replay service — custom reducers for materialized views.
+ * Projection replay service — fold/reducer model for custom aggregations.
+ *
+ * Unlike {@link ReplayService} which assumes full snapshots,
+ * this service supports both full-snapshot and diff-based event logs.
+ * `reducer.initialState()` returns the empty starting state,
+ * `reducer.apply(state, event)` accumulates each event.
+ *
+ * Use for custom aggregations (transition count, cumulative metrics)
+ * or when the event log stores diffs rather than full snapshots.
  */
 export class ProjectionReplayService {
     stateAtVersion(events, flowId, targetVersion, reducer) {

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

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

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

@@ -1,3 +1,4 @@
+import { PluginReport } from '../api/types.js';
 import { allDefaultPolicies } from './default-flow-policies.js';
 export class PolicyLintPlugin {
     policies;
@@ -16,8 +17,10 @@ export class PolicyLintPlugin {
     }
     kind() { return 'ANALYSIS'; }
     analyze(definition, report) {
+        const r = report ?? new PluginReport();
         for (const policy of this.policies) {
-            policy(definition, report);
+            policy(definition, r);
         }
+        return r;
     }
 }

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

@@ -21,5 +21,7 @@ export declare class ObservabilityEnginePlugin implements EnginePlugin {
     constructor(sink: TelemetrySink);
     descriptor(): PluginDescriptor;
     kind(): "ENGINE";
-    install(engine: FlowEngine): void;
+    install(engine: FlowEngine, options?: {
+        append?: boolean;
+    }): void;
 }

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

@@ -12,18 +12,32 @@ export class ObservabilityEnginePlugin {
         return { id: 'observability', displayName: 'Observability', description: 'Telemetry via engine logger hooks' };
     }
     kind() { return 'ENGINE'; }
-    install(engine) {
+    install(engine, options) {
+        const append = options?.append ?? false;
+        const prevTransition = append ? engine.getTransitionLogger() : undefined;
+        const prevError = append ? engine.getErrorLogger() : undefined;
+        const prevGuard = append ? engine.getGuardLogger() : undefined;
         engine.setTransitionLogger(entry => {
+            prevTransition?.(entry);
             this.sink.emit({
-                type: 'transition', flowId: entry.flowId, flowName: '',
-                data: { from: entry.from, to: entry.to, trigger: entry.trigger },
+                type: 'transition', flowId: entry.flowId, flowName: entry.flowName,
+                data: { from: entry.from, to: entry.to, trigger: entry.trigger, durationMicros: entry.durationMicros },
                 timestamp: new Date(),
             });
         });
         engine.setErrorLogger(entry => {
+            prevError?.(entry);
             this.sink.emit({
-                type: 'error', flowId: entry.flowId, flowName: '',
-                data: { from: entry.from, to: entry.to, trigger: entry.trigger, cause: entry.cause?.message },
+                type: 'error', flowId: entry.flowId, flowName: entry.flowName,
+                data: { from: entry.from, to: entry.to, trigger: entry.trigger, cause: entry.cause?.message, durationMicros: entry.durationMicros },
+                timestamp: new Date(),
+            });
+        });
+        engine.setGuardLogger((entry) => {
+            prevGuard?.(entry);
+            this.sink.emit({
+                type: 'guard', flowId: entry.flowId, flowName: entry.flowName,
+                data: { state: entry.state, guardName: entry.guardName, result: entry.result, reason: entry.reason, durationMicros: entry.durationMicros },
                 timestamp: new Date(),
             });
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unlaxer/tramli-plugins",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Plugin pack for tramli — audit, eventstore, observability, resume, idempotency, hierarchy, diagram, docs, lint, testing, subflow",
   "type": "module",
   "exports": {