footprintjs 10.0.0 → 10.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +2 -1
- package/CLAUDE.md +43 -7
- package/README.md +136 -312
- package/dist/esm/index.d.ts +60 -2
- package/dist/esm/index.js +13 -6
- package/dist/esm/lib/attempt/anySignal.d.ts +19 -0
- package/dist/esm/lib/attempt/anySignal.js +39 -0
- package/dist/esm/lib/attempt/call.d.ts +88 -0
- package/dist/esm/lib/attempt/call.js +129 -0
- package/dist/esm/lib/attempt/category.d.ts +31 -0
- package/dist/esm/lib/attempt/category.js +107 -0
- package/dist/esm/lib/attempt/correlation.d.ts +95 -0
- package/dist/esm/lib/attempt/correlation.js +178 -0
- package/dist/esm/lib/attempt/deadline.d.ts +44 -0
- package/dist/esm/lib/attempt/deadline.js +101 -0
- package/dist/esm/lib/attempt/decision.d.ts +52 -0
- package/dist/esm/lib/attempt/decision.js +134 -0
- package/dist/esm/lib/attempt/effect.d.ts +76 -0
- package/dist/esm/lib/attempt/effect.js +160 -0
- package/dist/esm/lib/attempt/errors.d.ts +41 -0
- package/dist/esm/lib/attempt/errors.js +44 -0
- package/dist/esm/lib/attempt/index.d.ts +18 -0
- package/dist/esm/lib/attempt/index.js +15 -0
- package/dist/esm/lib/attempt/name.d.ts +21 -0
- package/dist/esm/lib/attempt/name.js +43 -0
- package/dist/esm/lib/attempt/observed.d.ts +66 -0
- package/dist/esm/lib/attempt/observed.js +171 -0
- package/dist/esm/lib/attempt/policy.d.ts +45 -0
- package/dist/esm/lib/attempt/policy.js +83 -0
- package/dist/esm/lib/attempt/record.d.ts +11 -0
- package/dist/esm/lib/attempt/record.js +24 -0
- package/dist/esm/lib/attempt/retryLoopContext.d.ts +18 -0
- package/dist/esm/lib/attempt/retryLoopContext.js +24 -0
- package/dist/esm/lib/attempt/retryLoopTypes.d.ts +18 -0
- package/dist/esm/lib/attempt/retryLoopTypes.js +2 -0
- package/dist/esm/lib/attempt/runner.d.ts +155 -0
- package/dist/esm/lib/attempt/runner.js +503 -0
- package/dist/esm/lib/attempt/standalone.d.ts +47 -0
- package/dist/esm/lib/attempt/standalone.js +126 -0
- package/dist/esm/lib/attempt/types.d.ts +453 -0
- package/dist/esm/lib/attempt/types.js +16 -0
- package/dist/esm/lib/budget/index.d.ts +9 -0
- package/dist/esm/lib/budget/index.js +9 -0
- package/dist/esm/lib/budget/timeBudget.d.ts +136 -0
- package/dist/esm/lib/budget/timeBudget.js +666 -0
- package/dist/esm/lib/builder/FlowChartBuilder.d.ts +88 -3
- package/dist/esm/lib/builder/FlowChartBuilder.js +224 -16
- package/dist/esm/lib/builder/retryLoop.d.ts +56 -0
- package/dist/esm/lib/builder/retryLoop.js +283 -0
- package/dist/esm/lib/builder/types.d.ts +35 -1
- package/dist/esm/lib/builder/types.js +1 -1
- package/dist/esm/lib/decide/decide.js +2 -2
- package/dist/esm/lib/decide/index.d.ts +1 -1
- package/dist/esm/lib/decide/index.js +2 -2
- package/dist/esm/lib/decide/types.d.ts +3 -0
- package/dist/esm/lib/decide/types.js +1 -8
- package/dist/esm/lib/engine/graph/StageNode.d.ts +11 -1
- package/dist/esm/lib/engine/graph/StageNode.js +1 -1
- package/dist/esm/lib/engine/graph/prefixNodeTree.js +5 -1
- package/dist/esm/lib/engine/handlers/ResumeEntry.js +3 -1
- package/dist/esm/lib/engine/handlers/StageRunner.d.ts +8 -1
- package/dist/esm/lib/engine/handlers/StageRunner.js +36 -9
- package/dist/esm/lib/engine/handlers/SubflowExecutor.js +20 -4
- package/dist/esm/lib/engine/handlers/stageError.d.ts +7 -0
- package/dist/esm/lib/engine/handlers/stageError.js +11 -1
- package/dist/esm/lib/engine/index.d.ts +2 -2
- package/dist/esm/lib/engine/index.js +1 -1
- package/dist/esm/lib/engine/narrative/CombinedNarrativeRecorder.d.ts +27 -13
- package/dist/esm/lib/engine/narrative/CombinedNarrativeRecorder.js +68 -40
- package/dist/esm/lib/engine/narrative/FlowRecorderDispatcher.d.ts +2 -0
- package/dist/esm/lib/engine/narrative/FlowRecorderDispatcher.js +14 -1
- package/dist/esm/lib/engine/narrative/NarrativeFlowRecorder.d.ts +22 -3
- package/dist/esm/lib/engine/narrative/NarrativeFlowRecorder.js +61 -9
- package/dist/esm/lib/engine/narrative/NullControlFlowNarrativeGenerator.d.ts +1 -0
- package/dist/esm/lib/engine/narrative/NullControlFlowNarrativeGenerator.js +2 -1
- package/dist/esm/lib/engine/narrative/formatting/sentences.d.ts +23 -0
- package/dist/esm/lib/engine/narrative/formatting/sentences.js +127 -1
- package/dist/esm/lib/engine/narrative/index.d.ts +2 -2
- package/dist/esm/lib/engine/narrative/index.js +1 -1
- package/dist/esm/lib/engine/narrative/narrativeTypes.d.ts +27 -21
- package/dist/esm/lib/engine/narrative/narrativeTypes.js +1 -1
- package/dist/esm/lib/engine/narrative/recorders/ManifestFlowRecorder.d.ts +45 -2
- package/dist/esm/lib/engine/narrative/recorders/ManifestFlowRecorder.js +55 -2
- package/dist/esm/lib/engine/narrative/recorders/index.d.ts +1 -1
- package/dist/esm/lib/engine/narrative/recorders/index.js +1 -1
- package/dist/esm/lib/engine/narrative/types.d.ts +70 -4
- package/dist/esm/lib/engine/narrative/types.js +1 -1
- package/dist/esm/lib/engine/traversal/FlowchartTraverser.d.ts +59 -19
- package/dist/esm/lib/engine/traversal/FlowchartTraverser.js +182 -114
- package/dist/esm/lib/engine/traversalContext.d.ts +7 -2
- package/dist/esm/lib/engine/traversalContext.js +6 -3
- package/dist/esm/lib/engine/types.d.ts +52 -57
- package/dist/esm/lib/engine/types.js +1 -1
- package/dist/esm/lib/{decide → filter}/evaluator.d.ts +7 -2
- package/dist/esm/lib/filter/evaluator.js +135 -0
- package/dist/esm/lib/ids/idempotencyKey.d.ts +14 -0
- package/dist/esm/lib/ids/idempotencyKey.js +24 -0
- package/dist/esm/lib/memory/StageContext.d.ts +109 -3
- package/dist/esm/lib/memory/StageContext.js +214 -4
- package/dist/esm/lib/memory/borrowedMutation.d.ts +8 -0
- package/dist/esm/lib/memory/borrowedMutation.js +14 -1
- package/dist/esm/lib/memory/frameTypes.d.ts +30 -0
- package/dist/esm/lib/memory/frameTypes.js +3 -1
- package/dist/esm/lib/memory/redaction.d.ts +12 -0
- package/dist/esm/lib/memory/redaction.js +54 -5
- package/dist/esm/lib/pause/record.js +10 -1
- package/dist/esm/lib/pause/types.d.ts +19 -0
- package/dist/esm/lib/pause/types.js +17 -1
- package/dist/esm/lib/reactive/createTypedScope.js +3 -1
- package/dist/esm/lib/reactive/types.d.ts +36 -4
- package/dist/esm/lib/reactive/types.js +3 -1
- package/dist/esm/lib/recorder/AttemptRecorder.d.ts +141 -0
- package/dist/esm/lib/recorder/AttemptRecorder.js +412 -0
- package/dist/esm/lib/recorder/ControlDepRecorder.d.ts +22 -2
- package/dist/esm/lib/recorder/ControlDepRecorder.js +33 -2
- package/dist/esm/lib/recorder/EmitRecorder.d.ts +3 -0
- package/dist/esm/lib/recorder/EmitRecorder.js +1 -1
- package/dist/esm/lib/recorder/InOutRecorder.d.ts +37 -1
- package/dist/esm/lib/recorder/InOutRecorder.js +75 -6
- package/dist/esm/lib/recorder/QualityRecorder.d.ts +32 -5
- package/dist/esm/lib/recorder/QualityRecorder.js +87 -29
- package/dist/esm/lib/recorder/TopologyRecorder.d.ts +35 -5
- package/dist/esm/lib/recorder/TopologyRecorder.js +76 -2
- package/dist/esm/lib/recorder/attemptMetricRows.d.ts +11 -0
- package/dist/esm/lib/recorder/attemptMetricRows.js +202 -0
- package/dist/esm/lib/recorder/attemptMetrics.d.ts +7 -0
- package/dist/esm/lib/recorder/attemptMetrics.js +165 -0
- package/dist/esm/lib/recorder/attemptMetricsTypes.d.ts +114 -0
- package/dist/esm/lib/recorder/attemptMetricsTypes.js +2 -0
- package/dist/esm/lib/recorder/attemptOTel.d.ts +78 -0
- package/dist/esm/lib/recorder/attemptOTel.js +107 -0
- package/dist/esm/lib/recorder/attemptSeries.d.ts +81 -0
- package/dist/esm/lib/recorder/attemptSeries.js +103 -0
- package/dist/esm/lib/recorder/hooks.d.ts +9 -0
- package/dist/esm/lib/recorder/hooks.js +4 -1
- package/dist/esm/lib/recorder/qualityTrace.d.ts +4 -1
- package/dist/esm/lib/recorder/qualityTrace.js +14 -6
- package/dist/esm/lib/runner/DeferredObserverTier.js +13 -1
- package/dist/esm/lib/runner/ExecutionRuntime.d.ts +54 -6
- package/dist/esm/lib/runner/ExecutionRuntime.js +57 -5
- package/dist/esm/lib/runner/FlowChartExecutor.d.ts +42 -2
- package/dist/esm/lib/runner/FlowChartExecutor.js +238 -45
- package/dist/esm/lib/runner/RunnableChart.d.ts +6 -0
- package/dist/esm/lib/runner/RunnableChart.js +5 -1
- package/dist/esm/lib/runner/attach.d.ts +2 -1
- package/dist/esm/lib/runner/attach.js +8 -2
- package/dist/esm/lib/runner/checkpoint.js +3 -1
- package/dist/esm/lib/runner/deadline.d.ts +42 -0
- package/dist/esm/lib/runner/deadline.js +90 -0
- package/dist/esm/lib/runner/index.d.ts +3 -1
- package/dist/esm/lib/runner/index.js +2 -1
- package/dist/esm/lib/runner/options.d.ts +17 -0
- package/dist/esm/lib/runner/options.js +3 -1
- package/dist/esm/lib/runner/recordSink.d.ts +128 -0
- package/dist/esm/lib/runner/recordSink.js +296 -0
- package/dist/esm/lib/runner/resume.d.ts +3 -0
- package/dist/esm/lib/runner/resume.js +22 -2
- package/dist/esm/lib/runner/snapshot.d.ts +2 -2
- package/dist/esm/lib/runner/snapshot.js +6 -2
- package/dist/esm/lib/scope/ScopeFacade.d.ts +118 -4
- package/dist/esm/lib/scope/ScopeFacade.js +304 -7
- package/dist/esm/lib/scope/recorders/DebugRecorder.d.ts +17 -3
- package/dist/esm/lib/scope/recorders/DebugRecorder.js +79 -13
- package/dist/esm/lib/scope/recorders/MetricRecorder.d.ts +10 -0
- package/dist/esm/lib/scope/recorders/MetricRecorder.js +15 -2
- package/dist/esm/lib/scope/runtime.d.ts +3 -0
- package/dist/esm/lib/scope/runtime.js +1 -1
- package/dist/esm/lib/scope/types.d.ts +6 -0
- package/dist/esm/lib/scope/types.js +1 -1
- package/dist/esm/lib/sinks/fileSink.d.ts +135 -0
- package/dist/esm/lib/sinks/fileSink.js +387 -0
- package/dist/esm/recorders.d.ts +8 -2
- package/dist/esm/recorders.js +7 -1
- package/dist/esm/sinks.d.ts +23 -0
- package/dist/esm/sinks.js +23 -0
- package/dist/esm/trace.d.ts +2 -2
- package/dist/esm/trace.js +1 -1
- package/dist/index.js +77 -60
- package/dist/lib/attempt/anySignal.js +43 -0
- package/dist/lib/attempt/call.js +134 -0
- package/dist/lib/attempt/category.js +111 -0
- package/dist/lib/attempt/correlation.js +186 -0
- package/dist/lib/attempt/deadline.js +112 -0
- package/dist/lib/attempt/decision.js +139 -0
- package/dist/lib/attempt/effect.js +174 -0
- package/dist/lib/attempt/errors.js +49 -0
- package/dist/lib/attempt/index.js +26 -0
- package/dist/lib/attempt/name.js +48 -0
- package/dist/lib/attempt/observed.js +177 -0
- package/dist/lib/attempt/policy.js +92 -0
- package/dist/lib/attempt/record.js +29 -0
- package/dist/lib/attempt/retryLoopContext.js +31 -0
- package/dist/lib/attempt/retryLoopTypes.js +3 -0
- package/dist/lib/attempt/runner.js +510 -0
- package/dist/lib/attempt/standalone.js +130 -0
- package/dist/lib/attempt/types.js +17 -0
- package/dist/lib/budget/index.js +17 -0
- package/dist/lib/budget/timeBudget.js +674 -0
- package/dist/lib/builder/FlowChartBuilder.js +224 -16
- package/dist/lib/builder/retryLoop.js +287 -0
- package/dist/lib/builder/types.js +1 -1
- package/dist/lib/decide/decide.js +2 -2
- package/dist/lib/decide/index.js +2 -2
- package/dist/lib/decide/types.js +1 -8
- package/dist/lib/engine/graph/StageNode.js +1 -1
- package/dist/lib/engine/graph/prefixNodeTree.js +5 -1
- package/dist/lib/engine/handlers/ResumeEntry.js +3 -1
- package/dist/lib/engine/handlers/StageRunner.js +36 -9
- package/dist/lib/engine/handlers/SubflowExecutor.js +20 -4
- package/dist/lib/engine/handlers/stageError.js +13 -2
- package/dist/lib/engine/index.js +1 -1
- package/dist/lib/engine/narrative/CombinedNarrativeRecorder.js +67 -39
- package/dist/lib/engine/narrative/FlowRecorderDispatcher.js +14 -1
- package/dist/lib/engine/narrative/NarrativeFlowRecorder.js +60 -8
- package/dist/lib/engine/narrative/NullControlFlowNarrativeGenerator.js +2 -1
- package/dist/lib/engine/narrative/formatting/sentences.js +131 -2
- package/dist/lib/engine/narrative/index.js +1 -1
- package/dist/lib/engine/narrative/narrativeTypes.js +1 -1
- package/dist/lib/engine/narrative/recorders/ManifestFlowRecorder.js +55 -2
- package/dist/lib/engine/narrative/recorders/index.js +1 -1
- package/dist/lib/engine/narrative/types.js +1 -1
- package/dist/lib/engine/traversal/FlowchartTraverser.js +181 -113
- package/dist/lib/engine/traversalContext.js +6 -3
- package/dist/lib/engine/types.js +1 -1
- package/dist/lib/filter/evaluator.js +139 -0
- package/dist/lib/ids/idempotencyKey.js +28 -0
- package/dist/lib/memory/StageContext.js +215 -5
- package/dist/lib/memory/borrowedMutation.js +16 -2
- package/dist/lib/memory/frameTypes.js +3 -1
- package/dist/lib/memory/redaction.js +54 -5
- package/dist/lib/pause/record.js +10 -1
- package/dist/lib/pause/types.js +17 -1
- package/dist/lib/reactive/createTypedScope.js +3 -1
- package/dist/lib/reactive/types.js +3 -1
- package/dist/lib/recorder/AttemptRecorder.js +417 -0
- package/dist/lib/recorder/ControlDepRecorder.js +33 -2
- package/dist/lib/recorder/EmitRecorder.js +1 -1
- package/dist/lib/recorder/InOutRecorder.js +75 -6
- package/dist/lib/recorder/QualityRecorder.js +87 -29
- package/dist/lib/recorder/TopologyRecorder.js +76 -2
- package/dist/lib/recorder/attemptMetricRows.js +209 -0
- package/dist/lib/recorder/attemptMetrics.js +174 -0
- package/dist/lib/recorder/attemptMetricsTypes.js +3 -0
- package/dist/lib/recorder/attemptOTel.js +111 -0
- package/dist/lib/recorder/attemptSeries.js +113 -0
- package/dist/lib/recorder/hooks.js +4 -1
- package/dist/lib/recorder/qualityTrace.js +14 -6
- package/dist/lib/runner/DeferredObserverTier.js +13 -1
- package/dist/lib/runner/ExecutionRuntime.js +57 -5
- package/dist/lib/runner/FlowChartExecutor.js +238 -45
- package/dist/lib/runner/RunnableChart.js +5 -1
- package/dist/lib/runner/attach.js +8 -2
- package/dist/lib/runner/checkpoint.js +3 -1
- package/dist/lib/runner/deadline.js +94 -0
- package/dist/lib/runner/index.js +4 -2
- package/dist/lib/runner/options.js +3 -1
- package/dist/lib/runner/recordSink.js +302 -0
- package/dist/lib/runner/resume.js +22 -2
- package/dist/lib/runner/snapshot.js +6 -2
- package/dist/lib/scope/ScopeFacade.js +303 -6
- package/dist/lib/scope/recorders/DebugRecorder.js +79 -13
- package/dist/lib/scope/recorders/MetricRecorder.js +15 -2
- package/dist/lib/scope/runtime.js +1 -1
- package/dist/lib/scope/types.js +1 -1
- package/dist/lib/sinks/fileSink.js +392 -0
- package/dist/recorders.js +10 -2
- package/dist/sinks.js +32 -0
- package/dist/trace.js +1 -1
- package/dist/types/index.d.ts +60 -2
- package/dist/types/lib/attempt/anySignal.d.ts +19 -0
- package/dist/types/lib/attempt/call.d.ts +88 -0
- package/dist/types/lib/attempt/category.d.ts +31 -0
- package/dist/types/lib/attempt/correlation.d.ts +95 -0
- package/dist/types/lib/attempt/deadline.d.ts +44 -0
- package/dist/types/lib/attempt/decision.d.ts +52 -0
- package/dist/types/lib/attempt/effect.d.ts +76 -0
- package/dist/types/lib/attempt/errors.d.ts +41 -0
- package/dist/types/lib/attempt/index.d.ts +18 -0
- package/dist/types/lib/attempt/name.d.ts +21 -0
- package/dist/types/lib/attempt/observed.d.ts +66 -0
- package/dist/types/lib/attempt/policy.d.ts +45 -0
- package/dist/types/lib/attempt/record.d.ts +11 -0
- package/dist/types/lib/attempt/retryLoopContext.d.ts +18 -0
- package/dist/types/lib/attempt/retryLoopTypes.d.ts +18 -0
- package/dist/types/lib/attempt/runner.d.ts +155 -0
- package/dist/types/lib/attempt/standalone.d.ts +47 -0
- package/dist/types/lib/attempt/types.d.ts +453 -0
- package/dist/types/lib/budget/index.d.ts +9 -0
- package/dist/types/lib/budget/timeBudget.d.ts +136 -0
- package/dist/types/lib/builder/FlowChartBuilder.d.ts +88 -3
- package/dist/types/lib/builder/retryLoop.d.ts +56 -0
- package/dist/types/lib/builder/types.d.ts +35 -1
- package/dist/types/lib/decide/index.d.ts +1 -1
- package/dist/types/lib/decide/types.d.ts +3 -0
- package/dist/types/lib/engine/graph/StageNode.d.ts +11 -1
- package/dist/types/lib/engine/handlers/StageRunner.d.ts +8 -1
- package/dist/types/lib/engine/handlers/stageError.d.ts +7 -0
- package/dist/types/lib/engine/index.d.ts +2 -2
- package/dist/types/lib/engine/narrative/CombinedNarrativeRecorder.d.ts +27 -13
- package/dist/types/lib/engine/narrative/FlowRecorderDispatcher.d.ts +2 -0
- package/dist/types/lib/engine/narrative/NarrativeFlowRecorder.d.ts +22 -3
- package/dist/types/lib/engine/narrative/NullControlFlowNarrativeGenerator.d.ts +1 -0
- package/dist/types/lib/engine/narrative/formatting/sentences.d.ts +23 -0
- package/dist/types/lib/engine/narrative/index.d.ts +2 -2
- package/dist/types/lib/engine/narrative/narrativeTypes.d.ts +27 -21
- package/dist/types/lib/engine/narrative/recorders/ManifestFlowRecorder.d.ts +45 -2
- package/dist/types/lib/engine/narrative/recorders/index.d.ts +1 -1
- package/dist/types/lib/engine/narrative/types.d.ts +70 -4
- package/dist/types/lib/engine/traversal/FlowchartTraverser.d.ts +59 -19
- package/dist/types/lib/engine/traversalContext.d.ts +7 -2
- package/dist/types/lib/engine/types.d.ts +52 -57
- package/dist/types/lib/{decide → filter}/evaluator.d.ts +7 -2
- package/dist/types/lib/ids/idempotencyKey.d.ts +14 -0
- package/dist/types/lib/memory/StageContext.d.ts +109 -3
- package/dist/types/lib/memory/borrowedMutation.d.ts +8 -0
- package/dist/types/lib/memory/frameTypes.d.ts +30 -0
- package/dist/types/lib/memory/redaction.d.ts +12 -0
- package/dist/types/lib/pause/types.d.ts +19 -0
- package/dist/types/lib/reactive/types.d.ts +36 -4
- package/dist/types/lib/recorder/AttemptRecorder.d.ts +141 -0
- package/dist/types/lib/recorder/ControlDepRecorder.d.ts +22 -2
- package/dist/types/lib/recorder/EmitRecorder.d.ts +3 -0
- package/dist/types/lib/recorder/InOutRecorder.d.ts +37 -1
- package/dist/types/lib/recorder/QualityRecorder.d.ts +32 -5
- package/dist/types/lib/recorder/TopologyRecorder.d.ts +35 -5
- package/dist/types/lib/recorder/attemptMetricRows.d.ts +11 -0
- package/dist/types/lib/recorder/attemptMetrics.d.ts +7 -0
- package/dist/types/lib/recorder/attemptMetricsTypes.d.ts +114 -0
- package/dist/types/lib/recorder/attemptOTel.d.ts +78 -0
- package/dist/types/lib/recorder/attemptSeries.d.ts +81 -0
- package/dist/types/lib/recorder/hooks.d.ts +9 -0
- package/dist/types/lib/recorder/qualityTrace.d.ts +4 -1
- package/dist/types/lib/runner/ExecutionRuntime.d.ts +54 -6
- package/dist/types/lib/runner/FlowChartExecutor.d.ts +42 -2
- package/dist/types/lib/runner/RunnableChart.d.ts +6 -0
- package/dist/types/lib/runner/attach.d.ts +2 -1
- package/dist/types/lib/runner/deadline.d.ts +42 -0
- package/dist/types/lib/runner/index.d.ts +3 -1
- package/dist/types/lib/runner/options.d.ts +17 -0
- package/dist/types/lib/runner/recordSink.d.ts +128 -0
- package/dist/types/lib/runner/resume.d.ts +3 -0
- package/dist/types/lib/runner/snapshot.d.ts +2 -2
- package/dist/types/lib/scope/ScopeFacade.d.ts +118 -4
- package/dist/types/lib/scope/recorders/DebugRecorder.d.ts +17 -3
- package/dist/types/lib/scope/recorders/MetricRecorder.d.ts +10 -0
- package/dist/types/lib/scope/runtime.d.ts +3 -0
- package/dist/types/lib/scope/types.d.ts +6 -0
- package/dist/types/lib/sinks/fileSink.d.ts +135 -0
- package/dist/types/recorders.d.ts +8 -2
- package/dist/types/sinks.d.ts +23 -0
- package/dist/types/trace.d.ts +2 -2
- package/package.json +17 -3
- package/dist/esm/lib/decide/evaluator.js +0 -130
- package/dist/lib/decide/evaluator.js +0 -134
|
@@ -36,6 +36,7 @@ import type { RedactionPolicy, RedactionReport, ScopeRecorder } from '../scope/t
|
|
|
36
36
|
import type { AttachRecorderOptions, ObserverDrainResult } from './DeferredObserverTier.js';
|
|
37
37
|
import { type RuntimeSnapshot } from './ExecutionRuntime.js';
|
|
38
38
|
import { type FlowChartExecutorOptions } from './options.js';
|
|
39
|
+
import { type RecordFlushResult } from './recordSink.js';
|
|
39
40
|
export declare class FlowChartExecutor<TOut = any, TScope = any> {
|
|
40
41
|
private traverser;
|
|
41
42
|
/** Shared execution counter and per-stage visit counts (loopIteration) — shared BY
|
|
@@ -64,6 +65,12 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
|
|
|
64
65
|
*/
|
|
65
66
|
private _isExecuting;
|
|
66
67
|
private readonly flowChartArgs;
|
|
68
|
+
/**
|
|
69
|
+
* The crash-safe record of the current run (10.1, P6) — the sink every log of the run writes to, its
|
|
70
|
+
* accounting and its failure mode. Fresh per `run()` and per fresh-executor resume; a same-executor resume keeps
|
|
71
|
+
* it, as it keeps the root log. Absent without a `sink` option.
|
|
72
|
+
*/
|
|
73
|
+
private record;
|
|
67
74
|
/**
|
|
68
75
|
* Create a FlowChartExecutor.
|
|
69
76
|
*
|
|
@@ -159,7 +166,7 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
|
|
|
159
166
|
* const result = await executor.resume(restored, { approved: true });
|
|
160
167
|
* ```
|
|
161
168
|
*/
|
|
162
|
-
resume(checkpoint: FlowchartCheckpoint, resumeInput?: unknown, options?: Pick<RunOptions, 'signal' | 'env' | 'maxDepth' | 'maxIterations'>): Promise<ExecutorResult>;
|
|
169
|
+
resume(checkpoint: FlowchartCheckpoint, resumeInput?: unknown, options?: Pick<RunOptions, 'signal' | 'env' | 'maxDepth' | 'maxIterations' | 'deadline' | 'timeoutMs'>): Promise<ExecutorResult>;
|
|
163
170
|
/**
|
|
164
171
|
* The settle of a leg that threw: flush the deferred tier (the OUTERMOST
|
|
165
172
|
* handler — a pause re-throws through subflow traversers without exit
|
|
@@ -168,6 +175,22 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
|
|
|
168
175
|
* is rethrown.
|
|
169
176
|
*/
|
|
170
177
|
private pausedOrThrow;
|
|
178
|
+
/**
|
|
179
|
+
* The settle of a leg that writes its record (10.1, P6) — the 10.0 settle (`run()` / `resume()`), then the root
|
|
180
|
+
* log's closing entry with how the leg ended, then (`flush: 'auto'`) the adapter's flush, all before the leg
|
|
181
|
+
* counts as finished. A leg without a sink never comes here: its settle has no extra await.
|
|
182
|
+
*
|
|
183
|
+
* The leg's own error always wins. A run that finished but lost an entry under `onFailure: 'fail'` rejects with
|
|
184
|
+
* the `RecordSinkError`.
|
|
185
|
+
*/
|
|
186
|
+
private settleRecorded;
|
|
187
|
+
/**
|
|
188
|
+
* What a new root log opens with: names and numbers the run already serves — the run, the chart, the correlation,
|
|
189
|
+
* the deadline, the declared budget, and the run a fresh-executor resume continues. Served by the record.
|
|
190
|
+
*/
|
|
191
|
+
private openingMeta;
|
|
192
|
+
/** The closing entry's error: the run's SERVED form of it, its name, message and code only (never `raw`). */
|
|
193
|
+
private closingError;
|
|
171
194
|
/** The re-entrancy guard: one executor = one in-flight execution. */
|
|
172
195
|
private assertIdle;
|
|
173
196
|
/**
|
|
@@ -273,7 +296,8 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
|
|
|
273
296
|
*
|
|
274
297
|
* @param options `{ input, env }` — `input` is the frozen business input
|
|
275
298
|
* (read in a stage via `scope.$getArgs()`); `env` is infrastructure context
|
|
276
|
-
* like `{ signal, timeoutMs, traceId }` (read via `scope.$getEnv()`)
|
|
299
|
+
* like `{ signal, timeoutMs, traceId }` (read via `scope.$getEnv()`); `deadline` / `timeoutMs` give the run
|
|
300
|
+
* its deadline (`env.deadline`, `scope.$attempt().timeLeftMs()`).
|
|
277
301
|
*
|
|
278
302
|
* After it resolves, read results off the executor:
|
|
279
303
|
* - `getSnapshot()` — full state, commit log, execution tree.
|
|
@@ -294,6 +318,22 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
|
|
|
294
318
|
drainObservers(opts?: {
|
|
295
319
|
timeoutMs?: number;
|
|
296
320
|
}): Promise<ObserverDrainResult>;
|
|
321
|
+
/**
|
|
322
|
+
* Flush the record sink (10.1, P6): await the adapter's `flush()` — for an executor built with
|
|
323
|
+
* `sink: { adapter, flush: 'manual' }`, or before a serverless process freezes. `timeoutMs` bounds the wait; a
|
|
324
|
+
* flush still running then is `pending` (and keeps running). A failed flush is counted on `getSnapshot().sink`.
|
|
325
|
+
* Done at once without a sink, or with an adapter that has no `flush`.
|
|
326
|
+
*
|
|
327
|
+
* @example
|
|
328
|
+
* ```typescript
|
|
329
|
+
* const executor = new FlowChartExecutor(chart, { sink: { adapter: fileSink(path), flush: 'manual' } });
|
|
330
|
+
* await executor.run();
|
|
331
|
+
* await executor.flushRecord({ timeoutMs: 2_000 });
|
|
332
|
+
* ```
|
|
333
|
+
*/
|
|
334
|
+
flushRecord(opts?: {
|
|
335
|
+
timeoutMs?: number;
|
|
336
|
+
}): Promise<RecordFlushResult>;
|
|
297
337
|
/**
|
|
298
338
|
* Returns the runtime snapshot.
|
|
299
339
|
*
|
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
* Called by FlowChartBuilder.build() to enrich the compiled chart with
|
|
6
6
|
* d3-style chainable run methods and self-describing outputs.
|
|
7
7
|
*/
|
|
8
|
+
import { type TimeBudgetOptions, type TimeBudgetReport } from '../budget/index.js';
|
|
8
9
|
import type { FlowChart } from '../builder/types.js';
|
|
9
10
|
import type { JsonSchema } from '../contract/types.js';
|
|
10
11
|
import type { FlowRecorder } from '../engine/narrative/types.js';
|
|
@@ -49,6 +50,11 @@ export interface RunnableFlowChart<TOut = any, TScope = any> extends FlowChart<T
|
|
|
49
50
|
toMCPTool(): MCPToolDescription;
|
|
50
51
|
/** Generate a Mermaid flowchart diagram string from the chart's node graph. */
|
|
51
52
|
toMermaid(): string;
|
|
53
|
+
/**
|
|
54
|
+
* The slowest this chart can take, from its declared retry policies — `timeBudget(chart, options)`. Checks
|
|
55
|
+
* against the chart's declared `.budget(ms)` unless `options.budgetMs` is given.
|
|
56
|
+
*/
|
|
57
|
+
timeBudget(options?: TimeBudgetOptions): TimeBudgetReport;
|
|
52
58
|
}
|
|
53
59
|
/**
|
|
54
60
|
* Enrich a FlowChart with run + describe methods.
|
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
* from the same per-stage list as `onRead`/`onWrite`);
|
|
16
16
|
* - a flow attach turns the narrative on (the flow channel needs it).
|
|
17
17
|
*/
|
|
18
|
+
import type { RunCorrelation } from '../attempt/types.js';
|
|
18
19
|
import type { CombinedNarrativeRecorderOptions } from '../engine/narrative/CombinedNarrativeRecorder.js';
|
|
19
20
|
import { CombinedNarrativeRecorder } from '../engine/narrative/CombinedNarrativeRecorder.js';
|
|
20
21
|
import type { FlowRecorder } from '../engine/narrative/types.js';
|
|
@@ -77,7 +78,7 @@ export declare class RunObservers {
|
|
|
77
78
|
* The marked-keys set is ALWAYS wired (a stage can call
|
|
78
79
|
* `setValue(key, val, true)` for per-call redaction without any policy).
|
|
79
80
|
*/
|
|
80
|
-
composeScopeFactory<TScope>(baseFactory: ScopeFactory<TScope>, redactionPolicy: RedactionPolicy | undefined, sharedRedactedKeys: Set<string
|
|
81
|
+
composeScopeFactory<TScope>(baseFactory: ScopeFactory<TScope>, redactionPolicy: RedactionPolicy | undefined, sharedRedactedKeys: Set<string>, correlation?: RunCorrelation): ScopeFactory<TScope>;
|
|
81
82
|
/**
|
|
82
83
|
* The leg's flow recorders: the narrative recorder (when on), the user's
|
|
83
84
|
* flow recorders, then the deferred tier's flow tap (RFC-001 Block 7) —
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* runner/deadline.ts — `armRun`: the run's ONE effective signal and its deadline (design §3.1, P1b).
|
|
3
|
+
*
|
|
4
|
+
* A run has three ways to be told to stop — `RunOptions.signal`, `env.signal`, and a deadline (`RunOptions.deadline`,
|
|
5
|
+
* `now + RunOptions.timeoutMs`, or `env.deadline`; the earliest wins). Before 10.1 they did not compose: `timeoutMs`
|
|
6
|
+
* was ignored beside a `signal`, and `env.signal` was readable but never raced. `armRun` composes all of them into
|
|
7
|
+
* one signal the traverser races (and hands every subflow), and stamps the env a stage reads:
|
|
8
|
+
*
|
|
9
|
+
* env.deadline = the deadline (epoch ms) env.signal = the one composed signal
|
|
10
|
+
*
|
|
11
|
+
* — but only when there is something to stamp AND somewhere it was already going: a deadline always gives the run
|
|
12
|
+
* an env; a signal is stamped onto an env the caller gave. A run with no deadline and no env keeps no env, so a
|
|
13
|
+
* stage's `$getEnv()` stays `{}` and its commit carries no `'env'` mark — byte-identical to 10.0.
|
|
14
|
+
*
|
|
15
|
+
* At the deadline the signal aborts with a BRANDED reason (`attempt/deadline.ts`) carrying the message a run with
|
|
16
|
+
* `timeoutMs` always rejected with, so the attempt runner reads it as "out of time" (`timeout` / `no-time-left`),
|
|
17
|
+
* never as a cancellation.
|
|
18
|
+
*/
|
|
19
|
+
import type { ExecutionEnv } from '../engine/types.js';
|
|
20
|
+
/** What `armRun` reads — the run's own options. */
|
|
21
|
+
export interface RunTiming {
|
|
22
|
+
readonly signal?: AbortSignal;
|
|
23
|
+
readonly timeoutMs?: number;
|
|
24
|
+
readonly deadline?: number;
|
|
25
|
+
readonly env?: ExecutionEnv;
|
|
26
|
+
/**
|
|
27
|
+
* The executor's own stop (10.1, P6): a record sink with `onFailure: 'fail'` aborts it at the first lost entry,
|
|
28
|
+
* with the `RecordSinkError` as its reason. Composed like the others; absent for every other run.
|
|
29
|
+
*/
|
|
30
|
+
readonly stop?: AbortSignal;
|
|
31
|
+
}
|
|
32
|
+
/** The armed run: the signal the traverser races, the env stages read, and the one call that releases both. */
|
|
33
|
+
export interface ArmedRun {
|
|
34
|
+
readonly signal: AbortSignal | undefined;
|
|
35
|
+
readonly env: ExecutionEnv | undefined;
|
|
36
|
+
/** The run's deadline, epoch ms — absent without one. */
|
|
37
|
+
readonly deadline: number | undefined;
|
|
38
|
+
/** Clear the deadline timer and remove every listener composition added. Idempotent. */
|
|
39
|
+
dispose(): void;
|
|
40
|
+
}
|
|
41
|
+
/** Compose the run's signal and deadline from its options; `now` is the clock (epoch ms). */
|
|
42
|
+
export declare function armRun(timing: RunTiming, now?: () => number): ArmedRun;
|
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
export type { ComposableRunner } from './ComposableRunner.js';
|
|
2
2
|
export type { AttachRecorderOptions, ObserverDelivery, ObserverDrainResult, ObserverStats, } from './DeferredObserverTier.js';
|
|
3
|
-
export type { RecorderSnapshot, RuntimeSnapshot } from './ExecutionRuntime.js';
|
|
3
|
+
export type { RecorderSnapshot, RecordSinkStats, RuntimeSnapshot } from './ExecutionRuntime.js';
|
|
4
4
|
export { ExecutionRuntime } from './ExecutionRuntime.js';
|
|
5
5
|
export { FlowChartExecutor } from './FlowChartExecutor.js';
|
|
6
6
|
export type { SubtreeSnapshot } from './getSubtreeSnapshot.js';
|
|
7
7
|
export { getSubtreeSnapshot, listSubflowPaths } from './getSubtreeSnapshot.js';
|
|
8
8
|
export type { FlowChartExecutorOptions } from './options.js';
|
|
9
|
+
export type { RecordFlushResult, RecordSinkFailureMode, RecordSinkFlushMode, RecordSinkOption, RecordSinkOptions, } from './recordSink.js';
|
|
10
|
+
export { RecordSinkError } from './recordSink.js';
|
|
9
11
|
export type { RunResult } from './RunContext.js';
|
|
10
12
|
export { RunContext } from './RunContext.js';
|
|
11
13
|
export type { RunnableFlowChart } from './RunnableChart.js';
|
|
@@ -9,6 +9,7 @@ import type { FlowChart } from '../builder/types.js';
|
|
|
9
9
|
import type { ScopeFactory, StreamHandlers } from '../engine/types.js';
|
|
10
10
|
import type { RunDials } from '../memory/runPolicy.js';
|
|
11
11
|
import type { ScopeProtectionMode } from '../scope/protection/types.js';
|
|
12
|
+
import { type RecordSinkOption, type ResolvedRecordSink } from './recordSink.js';
|
|
12
13
|
/**
|
|
13
14
|
* Options object for `FlowChartExecutor` — preferred over positional params.
|
|
14
15
|
*
|
|
@@ -44,6 +45,20 @@ export interface FlowChartExecutorOptions<TScope = any> extends RunDials {
|
|
|
44
45
|
initialContext?: unknown;
|
|
45
46
|
/** Read-only input accessible via `scope.getArgs()` — never tracked or written. */
|
|
46
47
|
readOnlyContext?: unknown;
|
|
48
|
+
/**
|
|
49
|
+
* Where the run's record goes AS IT LANDS, so a run that never finishes still leaves it: every log of the run
|
|
50
|
+
* (the root and each subflow mount) hands the sink its `opened` base, each commit, a note per attempt that ended,
|
|
51
|
+
* and its `closed` outcome. `fileSink(path)` (`footprintjs/sinks`, Node) or `memorySink()` (`foottrace/write`);
|
|
52
|
+
* read it back with `readStoredRecord` (`foottrace`). The redaction policy applies before any entry is written.
|
|
53
|
+
* A failing sink never stops the run (`onFailure: 'report'`, the default) — `getSnapshot().sink` counts what was
|
|
54
|
+
* lost. See the guide's "A crash-safe record".
|
|
55
|
+
*
|
|
56
|
+
* @example
|
|
57
|
+
* ```typescript
|
|
58
|
+
* const executor = new FlowChartExecutor(chart, { sink: fileSink('/var/footprint/run.jsonl') });
|
|
59
|
+
* ```
|
|
60
|
+
*/
|
|
61
|
+
sink?: RecordSinkOption;
|
|
47
62
|
/**
|
|
48
63
|
* Custom error classifier for throttling detection. Return `true` if a fork
|
|
49
64
|
* child's error represents a rate-limit or backpressure condition; the
|
|
@@ -70,6 +85,8 @@ export interface ExecutorArgs<TOut, TScope> {
|
|
|
70
85
|
scopeProtectionMode?: ScopeProtectionMode;
|
|
71
86
|
/** The dials as given (absent = default) — the run's policy is built from them per leg. */
|
|
72
87
|
dials: RunDials;
|
|
88
|
+
/** The record sink, resolved and checked at construction (10.1, P6). */
|
|
89
|
+
sink?: ResolvedRecordSink;
|
|
73
90
|
}
|
|
74
91
|
/**
|
|
75
92
|
* Resolve either constructor form. The 2-param form is the options form with
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* runner/recordSink.ts — the run's side of the crash-safe record (design §3.5, packet P6).
|
|
3
|
+
*
|
|
4
|
+
* foottrace owns the port (`RecordSink`, `foottrace/write`): a log built with a sink hands it every entry AS IT
|
|
5
|
+
* LANDS — `opened`, `commit`, `note`, `closed` — and counts what the sink did not take. This file is what the
|
|
6
|
+
* EXECUTOR adds around an app's adapter, one {@link RunRecord} per run:
|
|
7
|
+
*
|
|
8
|
+
* - THE ONE LAW, before any byte leaves: the `opened` base is the run's served form of it (the redaction rule's
|
|
9
|
+
* `retainState`, the mirror's seed — so a policy key seeded by `initialContext` or a checkpoint never reaches
|
|
10
|
+
* the sink), and the `opened` / `closed` meta are boundary records (`retainBoundary`). A commit is the log's own
|
|
11
|
+
* bundle, already scrubbed at commit; an attempt note carries the served `AttemptRecord` (no `raw`).
|
|
12
|
+
* - ACCOUNTING: every entry handed to the adapter is counted, every loss too (`getSnapshot().sink`), with a
|
|
13
|
+
* dev-mode warning on the first loss of a run. The adapter's own `onFailure` hears a dispatched entry's loss
|
|
14
|
+
* with that same served entry and a served error, isolated. A refusal before dispatch is counted without
|
|
15
|
+
* forwarding Foottrace's unserved entry.
|
|
16
|
+
* - THE FAILURE MODE (owner ruling Q3): `'report'` (default) — the run goes on; `'fail'` — the first lost entry
|
|
17
|
+
* aborts the run's signal with a {@link RecordSinkError}, and a run that finished with a loss rejects with it.
|
|
18
|
+
* - FLUSH: `'auto'` (default) — `run()` / `resume()` await the adapter's `flush()` after the closing entry;
|
|
19
|
+
* `'manual'` — the app calls `executor.flushRecord()`.
|
|
20
|
+
*
|
|
21
|
+
* Every adapter method is called synchronously from the log; whatever the adapter throws or rejects with is the
|
|
22
|
+
* log's to count (`EventLog · sinkFailures`), never the run's — so nothing here throws to the engine.
|
|
23
|
+
*/
|
|
24
|
+
import type { Meta } from 'foottrace';
|
|
25
|
+
import type { RecordSink } from 'foottrace/write';
|
|
26
|
+
import type { RedactionRule } from '../memory/redaction.js';
|
|
27
|
+
import type { RecordSinkStats } from './ExecutionRuntime.js';
|
|
28
|
+
/** What a lost entry does to the run: `'report'` counts it and goes on; `'fail'` fails the run. */
|
|
29
|
+
export type RecordSinkFailureMode = 'report' | 'fail';
|
|
30
|
+
/** When the adapter's `flush()` runs: after each run's closing entry (`'auto'`), or when the app asks. */
|
|
31
|
+
export type RecordSinkFlushMode = 'auto' | 'manual';
|
|
32
|
+
/**
|
|
33
|
+
* The executor's `sink` option in its long form. The short form is the adapter itself.
|
|
34
|
+
*
|
|
35
|
+
* @example
|
|
36
|
+
* ```typescript
|
|
37
|
+
* new FlowChartExecutor(chart, { sink: { adapter: fileSink('/var/footprint/run.jsonl'), onFailure: 'fail' } });
|
|
38
|
+
* ```
|
|
39
|
+
*/
|
|
40
|
+
export interface RecordSinkOptions {
|
|
41
|
+
/** Where the entries go — `fileSink(path)` (`footprintjs/sinks`), `memorySink()` (`foottrace/write`), or yours. */
|
|
42
|
+
readonly adapter: RecordSink;
|
|
43
|
+
/** `'report'` (default): a lost entry is counted and the run goes on. `'fail'`: the first one fails the run. */
|
|
44
|
+
readonly onFailure?: RecordSinkFailureMode;
|
|
45
|
+
/** `'auto'` (default): `run()` awaits the adapter's `flush()` after the closing entry. `'manual'`: `flushRecord()`. */
|
|
46
|
+
readonly flush?: RecordSinkFlushMode;
|
|
47
|
+
}
|
|
48
|
+
/** The executor's `sink` option: an adapter, or {@link RecordSinkOptions}. */
|
|
49
|
+
export type RecordSinkOption = RecordSink | RecordSinkOptions;
|
|
50
|
+
/** What `executor.flushRecord()` resolves with — the `drainObservers` shape. */
|
|
51
|
+
export interface RecordFlushResult {
|
|
52
|
+
/** The adapter's flush finished (or there was nothing to flush). */
|
|
53
|
+
readonly done: boolean;
|
|
54
|
+
/** The adapter's flush threw or rejected — counted on `getSnapshot().sink`. */
|
|
55
|
+
readonly failed: boolean;
|
|
56
|
+
/** The flush had not settled when `timeoutMs` ran out. */
|
|
57
|
+
readonly pending: boolean;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* A run with `sink: { onFailure: 'fail' }` lost an entry: the record the app asked to be kept is not whole.
|
|
61
|
+
* `cause` is the adapter's own error.
|
|
62
|
+
*/
|
|
63
|
+
export declare class RecordSinkError extends Error {
|
|
64
|
+
readonly cause: unknown;
|
|
65
|
+
readonly name = "RecordSinkError";
|
|
66
|
+
constructor(message: string, cause: unknown);
|
|
67
|
+
}
|
|
68
|
+
/** The option resolved once, at construction. */
|
|
69
|
+
export interface ResolvedRecordSink {
|
|
70
|
+
readonly adapter: RecordSink;
|
|
71
|
+
readonly onFailure: RecordSinkFailureMode;
|
|
72
|
+
readonly flush: RecordSinkFlushMode;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Resolve the executor's `sink` option, or refuse it with a `TypeError` naming what is wrong — a wiring mistake
|
|
76
|
+
* the app makes once, so it fails at construction, never mid-run.
|
|
77
|
+
*/
|
|
78
|
+
export declare function resolveRecordSink(option: unknown): ResolvedRecordSink | undefined;
|
|
79
|
+
/**
|
|
80
|
+
* One run's record sink: the sink every log of the run writes to (root and mounts), its accounting and its
|
|
81
|
+
* failure mode. A same-executor resume keeps it (the root log goes on); a fresh run makes a new one.
|
|
82
|
+
*/
|
|
83
|
+
export declare class RunRecord {
|
|
84
|
+
private readonly resolved;
|
|
85
|
+
/** Hand this to every `EventLog` of the run. */
|
|
86
|
+
readonly sink: RecordSink;
|
|
87
|
+
private entries;
|
|
88
|
+
private failed;
|
|
89
|
+
private lastError?;
|
|
90
|
+
private warned;
|
|
91
|
+
private rule?;
|
|
92
|
+
/** Aborted at the first loss under `'fail'` — composed into the leg's signal; fresh per leg ({@link beginLeg}). */
|
|
93
|
+
private stopper?;
|
|
94
|
+
private failure?;
|
|
95
|
+
/** Opaque error identities only: no raw entry or adapter error is enumerable on the transport error. */
|
|
96
|
+
private readonly invocationFailures;
|
|
97
|
+
constructor(resolved: ResolvedRecordSink);
|
|
98
|
+
/** Capture the served entry now; an asynchronous failure keeps this leg's rule, not a later resume's rule. */
|
|
99
|
+
private invoke;
|
|
100
|
+
/** A sink error is the diagnostic errors.recordSinkError; raw causes belong only to the caller's exception. */
|
|
101
|
+
private errorView;
|
|
102
|
+
/**
|
|
103
|
+
* A same-executor resume starts a new leg on the same record: the counts go on (one log, one record), but the
|
|
104
|
+
* failure mode is the LEG's — a loss in an earlier leg (which already failed that leg) does not stop this one —
|
|
105
|
+
* and the dev-mode warning may fire again.
|
|
106
|
+
*/
|
|
107
|
+
beginLeg(): void;
|
|
108
|
+
/** The leg's redaction rule — a resume builds a new one; the next `opened` / `closed` is served under it. */
|
|
109
|
+
useRule(rule: RedactionRule | undefined): void;
|
|
110
|
+
/** Aborts at the first loss under `onFailure: 'fail'`; absent otherwise. */
|
|
111
|
+
get stopSignal(): AbortSignal | undefined;
|
|
112
|
+
get flushMode(): RecordSinkFlushMode;
|
|
113
|
+
/** The loss that fails the run under `'fail'`; absent while nothing was lost (and always under `'report'`). */
|
|
114
|
+
get fatal(): RecordSinkError | undefined;
|
|
115
|
+
stats(): RecordSinkStats;
|
|
116
|
+
/**
|
|
117
|
+
* Await the adapter's `flush()`, at most `timeoutMs` when given. A flush that throws or rejects is a loss
|
|
118
|
+
* (counted, and fatal under `'fail'`); one still running at the deadline is `pending` and keeps running — and,
|
|
119
|
+
* with `pendingIsLoss` (the run's own flush), counted as a loss too, so a flush that never settles cannot hold a
|
|
120
|
+
* run open, and cannot pass for one that landed. Nothing here throws: a hostile adapter (a throwing `flush`
|
|
121
|
+
* getter, a promise with its own `then`) is a loss, never the run's error.
|
|
122
|
+
*/
|
|
123
|
+
flush(timeoutMs?: number, pendingIsLoss?: boolean): Promise<RecordFlushResult>;
|
|
124
|
+
/** The meta as served: a boundary record, scrubbed by key name at every depth (an inert rule copies nothing). */
|
|
125
|
+
serve(meta: Meta): Meta;
|
|
126
|
+
/** One loss: counted, warned once per run, told with a safe dispatched entry when available, fatal under 'fail'. */
|
|
127
|
+
private lost;
|
|
128
|
+
}
|
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
* The executor owns the per-run state between the steps (the runId, the
|
|
18
18
|
* runtime, the traverser); this module never holds any.
|
|
19
19
|
*/
|
|
20
|
+
import type { RunCorrelation } from '../attempt/types.js';
|
|
20
21
|
import type { FlowChart } from '../builder/types.js';
|
|
21
22
|
import { ResumeEntry } from '../engine/handlers/ResumeEntry.js';
|
|
22
23
|
import type { StageNode } from '../engine/types.js';
|
|
@@ -70,4 +71,6 @@ export declare function announceResume<TOut, TScope>(plan: ResumePlan<TOut, TSco
|
|
|
70
71
|
readonly runId: string;
|
|
71
72
|
readonly executionCount: number;
|
|
72
73
|
readonly observers: RunObservers;
|
|
74
|
+
/** The RESUMED leg's correlation (from `resume()`'s env) — on both events, like every event of the leg. */
|
|
75
|
+
readonly correlation?: RunCorrelation;
|
|
73
76
|
}): void;
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
*/
|
|
8
8
|
import type { FlowchartTraverser } from '../engine/traversal/FlowchartTraverser.js';
|
|
9
9
|
import type { RunObservers } from './attach.js';
|
|
10
|
-
import type { RecorderSnapshot, RuntimeSnapshot } from './ExecutionRuntime.js';
|
|
10
|
+
import type { RecorderSnapshot, RecordSinkStats, RuntimeSnapshot } from './ExecutionRuntime.js';
|
|
11
11
|
/**
|
|
12
12
|
* The served snapshot. `sharedState` is the LIVE view in production (zero
|
|
13
13
|
* copy); in dev mode it is a deep-frozen CLONE, so a consumer mutation throws
|
|
@@ -15,7 +15,7 @@ import type { RecorderSnapshot, RuntimeSnapshot } from './ExecutionRuntime.js';
|
|
|
15
15
|
*/
|
|
16
16
|
export declare function servedSnapshot(traverser: FlowchartTraverser<any, any>, observers: RunObservers, options?: {
|
|
17
17
|
redact?: boolean;
|
|
18
|
-
}): RuntimeSnapshot;
|
|
18
|
+
}, sink?: RecordSinkStats): RuntimeSnapshot;
|
|
19
19
|
/**
|
|
20
20
|
* Collect `toSnapshot()` bundles from every attached recorder — ONE entry
|
|
21
21
|
* per recorder id, across all channels and both delivery tiers.
|
|
@@ -13,6 +13,9 @@
|
|
|
13
13
|
* }
|
|
14
14
|
* ```
|
|
15
15
|
*/
|
|
16
|
+
import type { AttemptContext, AttemptError, CallOptions, RetryPolicy, RunCorrelation } from '../attempt/types.js';
|
|
17
|
+
import type { FlowChart } from '../builder/types.js';
|
|
18
|
+
import type { DetachDriver, DetachHandle } from '../detach/types.js';
|
|
16
19
|
import type { ExecutionEnv } from '../engine/types.js';
|
|
17
20
|
import { StageContext } from '../memory/StageContext.js';
|
|
18
21
|
import type { CommitEvent, RedactionPolicy, RedactionReport, ScopeRecorder } from './types.js';
|
|
@@ -63,6 +66,28 @@ export declare class ScopeFacade {
|
|
|
63
66
|
* tree and this stays unset; see {@link rule}.
|
|
64
67
|
*/
|
|
65
68
|
private _localRule?;
|
|
69
|
+
/**
|
|
70
|
+
* The run's correlation (10.1), installed by the executor's composed scope factory
|
|
71
|
+
* (`RunObservers · composeScopeFactory`) — stamped LAST on every scope and emit event this facade fires,
|
|
72
|
+
* only when present, so a run without one fires byte-identical events.
|
|
73
|
+
*/
|
|
74
|
+
private _correlation?;
|
|
75
|
+
/**
|
|
76
|
+
* The attempt this facade was built for (P1b) — the runner's, read off the
|
|
77
|
+
* context at construction. A facade is ONE attempt's handle: once that
|
|
78
|
+
* attempt ends without an answer (its cap, the deadline, a cancellation, a
|
|
79
|
+
* throw), the function behind it may still be running, and anything it
|
|
80
|
+
* touches through this facade is refused ({@link refuseIfAttemptEnded}) —
|
|
81
|
+
* a write or an emit is also recorded on the stage. Absent for a stage the
|
|
82
|
+
* runner does not run: nothing is fenced, as before.
|
|
83
|
+
*/
|
|
84
|
+
private readonly _attempt?;
|
|
85
|
+
/** The run's signal, for `$attempt()` of a stage the runner does not run. */
|
|
86
|
+
private readonly _runSignal?;
|
|
87
|
+
/** `$call`s with `of > 1` in flight through this facade — a keyless touching call inside one is refused (P3). */
|
|
88
|
+
private _retryingCalls;
|
|
89
|
+
/** This attempt's observed reports, grouped into series (P2) — made on the first report. */
|
|
90
|
+
private _observedBook?;
|
|
66
91
|
constructor(context: StageContext, stageName: string, readOnlyValues?: unknown, executionEnv?: ExecutionEnv);
|
|
67
92
|
/**
|
|
68
93
|
* The redaction rule this facade decides with — the SAME object its
|
|
@@ -93,6 +118,12 @@ export declare class ScopeFacade {
|
|
|
93
118
|
* @internal
|
|
94
119
|
*/
|
|
95
120
|
useRedactionPolicy(policy: RedactionPolicy): void;
|
|
121
|
+
/**
|
|
122
|
+
* Install the run's correlation — every scope and emit event this facade fires carries it; `undefined` clears
|
|
123
|
+
* it. Engine-only (the composed scope factory calls it once per stage), like `useRedactionPolicy`.
|
|
124
|
+
* @internal
|
|
125
|
+
*/
|
|
126
|
+
useCorrelation(correlation: RunCorrelation | undefined): void;
|
|
96
127
|
/** @internal */
|
|
97
128
|
getRedactionPolicy(): RedactionPolicy | undefined;
|
|
98
129
|
/**
|
|
@@ -119,6 +150,85 @@ export declare class ScopeFacade {
|
|
|
119
150
|
* to the stage that made the write.
|
|
120
151
|
*/
|
|
121
152
|
private assertLive;
|
|
153
|
+
/**
|
|
154
|
+
* The attempt fence (P1b): this facade's attempt has ended, so whatever the
|
|
155
|
+
* abandoned function does now must not reach the stage — not its buffer, its
|
|
156
|
+
* reads, its untracked sources or a recorder. Refused; a write or an emit is
|
|
157
|
+
* recorded on the stage first (`StageSnapshot.lateWrites`, the name only),
|
|
158
|
+
* a read (`channel` undefined) is not.
|
|
159
|
+
*/
|
|
160
|
+
private refuseIfAttemptEnded;
|
|
161
|
+
/**
|
|
162
|
+
* The attempt this stage function runs in — `scope.$attempt()` (design
|
|
163
|
+
* §3.1). Its `signal` aborts when the attempt must stop (its cap, the run's
|
|
164
|
+
* deadline, a cancellation): pass it to `fetch` and SDK calls. Its
|
|
165
|
+
* `timeLeftMs()` reads the run's deadline — time is an input the record
|
|
166
|
+
* cannot replay, so with a deadline the read marks the stage's commit
|
|
167
|
+
* `untrackedSources: ['env']`, as `getEnv()` does.
|
|
168
|
+
*
|
|
169
|
+
* A stage the attempt runner does not run (no retry policy, no `timeoutMs`,
|
|
170
|
+
* no deadline) is attempt 1 of 1, with the run's signal and `Infinity` left.
|
|
171
|
+
*
|
|
172
|
+
* ```typescript
|
|
173
|
+
* const t = scope.$attempt();
|
|
174
|
+
* const res = await fetch(url, { signal: t.signal });
|
|
175
|
+
* if (t.timeLeftMs() < 1_000) scope.summary = 'partial';
|
|
176
|
+
* ```
|
|
177
|
+
*/
|
|
178
|
+
getAttempt(): AttemptContext;
|
|
179
|
+
/**
|
|
180
|
+
* A call to an outside system, made inside this stage — `scope.$call(target, fn, policy?)` (design §3.6, P2).
|
|
181
|
+
* `fn` runs on the attempt runner under `policy` (none = ONE attempt, still recorded: a single call is evidence
|
|
182
|
+
* too), and every attempt is an `AttemptRecord` of kind `'call'` on this stage's execution-tree node and on
|
|
183
|
+
* `onAttempt` — its timing, outcome, failure category and the retry-or-stop decision, its error served under the
|
|
184
|
+
* run's redaction rule.
|
|
185
|
+
*
|
|
186
|
+
* The call lives within this stage attempt: it is capped by the time the attempt has left (its cap, the run's
|
|
187
|
+
* deadline) and `fn`'s `signal` aborts when the attempt does; once the attempt is over nothing of the call lands
|
|
188
|
+
* and no further attempt of it starts (`attempt/call.ts`). `target` is a NAME from code — never a value.
|
|
189
|
+
*
|
|
190
|
+
* ```typescript
|
|
191
|
+
* const quote = await scope.$call('stripe.quotes.create', (t) => stripe.quotes.create(body, { signal: t.signal }),
|
|
192
|
+
* { attempts: 3, timeoutMs: 10_000, backoffMs: (n) => 500 * n });
|
|
193
|
+
* ```
|
|
194
|
+
*
|
|
195
|
+
* A call that CHANGES an outside system declares it (P3): `options.touches` names the system and
|
|
196
|
+
* `options.idempotencyKey` the key every attempt is made under (`t.idempotencyKey`) — a value from the stage's
|
|
197
|
+
* input or state, never from model output. A touching call that may retry without a key is refused here,
|
|
198
|
+
* before anything is sent; each record says what its attempt did (`effect`), and a call that ends without an answer after any attempt left the
|
|
199
|
+
* effect unknown rejects with `UnknownEffectError` — reconcile by the key, do not retry blindly.
|
|
200
|
+
*/
|
|
201
|
+
call<T>(target: string, fn: (attempt: AttemptContext) => Promise<T> | T, policy?: RetryPolicy, options?: CallOptions): Promise<T>;
|
|
202
|
+
/** `runCall` with this stage attempt as its host (`call`). */
|
|
203
|
+
private startCall;
|
|
204
|
+
/** @internal The explicit retry helper owns this state; the normal write path still owns retention/commit. */
|
|
205
|
+
writeRetryLoopState(key: string, state: {
|
|
206
|
+
readonly idempotencyKey: string;
|
|
207
|
+
}): void;
|
|
208
|
+
/** @internal Exactly the existing P3 key-retention law; operational state keeps the real key. */
|
|
209
|
+
serveRetryLoopKey(key: string): string;
|
|
210
|
+
/** @internal Loop state is durable data: never persist the thrown value, stack, cause or payload. */
|
|
211
|
+
serveRetryLoopError(error: unknown): AttemptError;
|
|
212
|
+
/** A touching call's target, its key served for the records (`RedactionRule · retainIdempotencyKey`: by name and by its sources). */
|
|
213
|
+
private callEffect;
|
|
214
|
+
/**
|
|
215
|
+
* A `$call` from an ended attempt, or from a frame that has committed: recorded by name (`lateWrites`, channel
|
|
216
|
+
* `'attempt'`) and refused — before anything reaches outside. The P1b fence first, so its message and record are
|
|
217
|
+
* the same.
|
|
218
|
+
*/
|
|
219
|
+
private refuseLateCall;
|
|
220
|
+
/**
|
|
221
|
+
* An outside attempt an adapter reported — `AttemptContext.observed` on this stage's attempt or on one of its
|
|
222
|
+
* calls' (P2). Read and validated first (a malformed report is the adapter's bug: a `TypeError`, and it never
|
|
223
|
+
* reaches the record). A report that comes after its attempt ended — the call attempt it was made through, this
|
|
224
|
+
* stage attempt, or the frame's commit — is recorded by name (`lateWrites`, channel `'attempt'`) and DROPPED,
|
|
225
|
+
* never thrown: adapters report from an SDK's own callbacks, which may fire after the stage moved on, and an
|
|
226
|
+
* observed attempt never changes control flow — in either direction. Its series opens at this stage attempt's call
|
|
227
|
+
* level: an SDK's call is a call the stage attempt made, so a report made through a `$call` is that call's sibling.
|
|
228
|
+
*/
|
|
229
|
+
private recordObserved;
|
|
230
|
+
/** This facade's attempt has ended — the P1b fence is closed. */
|
|
231
|
+
private attemptHasEnded;
|
|
122
232
|
/** Called by StageContext.commit() observer. Converts tracked writes to CommitEvent format.
|
|
123
233
|
* Errors are caught to prevent recorder issues from aborting the traversal. */
|
|
124
234
|
private _onCommitFired;
|
|
@@ -147,9 +257,9 @@ export declare class ScopeFacade {
|
|
|
147
257
|
*/
|
|
148
258
|
emitEvent(name: string, payload: unknown): void;
|
|
149
259
|
/** See `ScopeMethods.$detachAndJoinLater`. */
|
|
150
|
-
detachAndJoinLater(driver:
|
|
260
|
+
detachAndJoinLater(driver: DetachDriver, child: FlowChart, input?: unknown): DetachHandle;
|
|
151
261
|
/** See `ScopeMethods.$detachAndForget`. */
|
|
152
|
-
detachAndForget(driver:
|
|
262
|
+
detachAndForget(driver: DetachDriver, child: FlowChart, input?: unknown): void;
|
|
153
263
|
/**
|
|
154
264
|
* Build the subflowPath (outer → inner) for event enrichment.
|
|
155
265
|
*
|
|
@@ -251,8 +361,10 @@ export declare class ScopeFacade {
|
|
|
251
361
|
* Returns the execution environment — read-only infrastructure values
|
|
252
362
|
* that propagate through nested executors (like `process.env` for flowcharts).
|
|
253
363
|
*
|
|
254
|
-
* Contains: signal (abort), timeoutMs, traceId
|
|
255
|
-
*
|
|
364
|
+
* Contains: signal (abort — the run's one effective signal), timeoutMs, traceId, operationId, traceparent,
|
|
365
|
+
* deadline (epoch ms) — the run's env as admitted (`attempt/correlation.ts · admitRunEnv`: one own-field
|
|
366
|
+
* snapshot; `traceparent` is the canonical header the run's correlation carries, never the received bytes), then
|
|
367
|
+
* armed (`runner/deadline.ts · armRun`). Frozen at construction time. Inherited by subflows automatically.
|
|
256
368
|
*
|
|
257
369
|
* ```typescript
|
|
258
370
|
* const { signal, traceId } = scope.getEnv();
|
|
@@ -266,6 +378,8 @@ export declare class ScopeFacade {
|
|
|
266
378
|
/** @internal */
|
|
267
379
|
getPipelineId(): string;
|
|
268
380
|
private _invokeHook;
|
|
381
|
+
/** The event as fired: unchanged without a correlation, else with the run's correlation as its last key. */
|
|
382
|
+
private _correlated;
|
|
269
383
|
/**
|
|
270
384
|
* The scope channel's isolation: a recorder's throw becomes an `onError` on every recorder
|
|
271
385
|
* (stamped with this stage), and a throw from `onError` itself is dropped.
|
|
@@ -1,14 +1,27 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* DebugRecorder — Development-focused recorder for detailed debugging
|
|
3
3
|
*
|
|
4
|
-
* Captures errors (always
|
|
5
|
-
*
|
|
4
|
+
* Captures errors (always — a scope recorder's own failure, the scope
|
|
5
|
+
* channel's `onError`; a stage's failure is not one), mutations and reads
|
|
6
|
+
* (in verbose mode), and stage lifecycle events for troubleshooting.
|
|
7
|
+
*
|
|
8
|
+
* Attempts (10.1): one `attempt` row per attempt of a series that retried,
|
|
9
|
+
* gave up or timed out (`recorder/attemptSeries.ts · isRetryEvidence`) — its
|
|
10
|
+
* outcome, category, duration, decision, the cap and time left it ran under
|
|
11
|
+
* (present with a cap or a deadline) and served error — and one `attemptStop`
|
|
12
|
+
* row when the series gave up (exhausted, declined, no time left). Both verbosities: like a
|
|
13
|
+
* pause, an attempt is significant — and for a retried stage these rows are
|
|
14
|
+
* the failure evidence (a stage's error is never an `error` row). They arrive on the FLOW channel
|
|
15
|
+
* (`onAttempt`), so attach with `attachCombinedRecorder` to see them; the
|
|
16
|
+
* flow channel's own `onError` / `onPause` / `onResume` are ignored, so a
|
|
17
|
+
* combined attach never doubles a scope row.
|
|
6
18
|
*/
|
|
19
|
+
import type { FlowAttemptEvent } from '../../engine/narrative/types.js';
|
|
7
20
|
import type { RecorderOperation } from '../../recorder/RecorderOperation.js';
|
|
8
21
|
import type { ErrorEvent, PauseEvent, ReadEvent, ResumeEvent, ScopeRecorder, StageEvent, WriteEvent } from '../types.js';
|
|
9
22
|
export type DebugVerbosity = 'minimal' | 'verbose';
|
|
10
23
|
export interface DebugEntry {
|
|
11
|
-
type: 'read' | 'write' | 'error' | 'stageStart' | 'stageEnd' | 'pause' | 'resume';
|
|
24
|
+
type: 'read' | 'write' | 'error' | 'stageStart' | 'stageEnd' | 'pause' | 'resume' | 'attempt' | 'attemptStop';
|
|
12
25
|
stageName: string;
|
|
13
26
|
timestamp: number;
|
|
14
27
|
data: unknown;
|
|
@@ -48,6 +61,7 @@ export declare class DebugRecorder implements ScopeRecorder {
|
|
|
48
61
|
onStageEnd(event: StageEvent): void;
|
|
49
62
|
onPause(event: PauseEvent): void;
|
|
50
63
|
onResume(event: ResumeEvent): void;
|
|
64
|
+
onAttempt(event: FlowAttemptEvent): void;
|
|
51
65
|
getEntries(): DebugEntry[];
|
|
52
66
|
getErrors(): DebugEntry[];
|
|
53
67
|
getEntriesForStage(stageName: string): DebugEntry[];
|
|
@@ -6,6 +6,14 @@
|
|
|
6
6
|
* (Convention 1 — one purpose per recorder: this is the ScopeRecorder; the store
|
|
7
7
|
* is the storage).
|
|
8
8
|
*
|
|
9
|
+
* Attempts (10.1): a stage with a retry policy runs each attempt in a fresh
|
|
10
|
+
* scope, so this recorder sees one `onStageStart` per attempt. `attempts` is
|
|
11
|
+
* that count, present when it is 2 or more; `duration` spans the whole
|
|
12
|
+
* execution — from the FIRST attempt's start, waits included — never just the
|
|
13
|
+
* attempt that succeeded. An execution that never returned (it gave up) has
|
|
14
|
+
* no `onStageEnd`, so its duration stays `0`, as for any failed stage. A stage
|
|
15
|
+
* that ran once reads exactly as before.
|
|
16
|
+
*
|
|
9
17
|
* @example
|
|
10
18
|
* ```typescript
|
|
11
19
|
* const metric = new MetricRecorder();
|
|
@@ -38,6 +46,8 @@ export interface StepMetrics {
|
|
|
38
46
|
pauseCount: number;
|
|
39
47
|
/** Duration in ms for this invocation. */
|
|
40
48
|
duration: number;
|
|
49
|
+
/** How many attempts the execution made (its `onStageStart` count) — present only when it retried (≥ 2). */
|
|
50
|
+
attempts?: number;
|
|
41
51
|
}
|
|
42
52
|
/** Aggregated metrics across all invocations (backward compatible). */
|
|
43
53
|
export interface AggregatedMetrics {
|
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
* ScopeFacade owns recording, redaction and state access; custom scopes may
|
|
8
8
|
* explicitly supply a smaller port (including `{}` for data-only scopes).
|
|
9
9
|
*/
|
|
10
|
+
import type { RunCorrelation } from '../attempt/types.js';
|
|
10
11
|
import type { RedactionPolicy, ScopeRecorder } from './types.js';
|
|
11
12
|
/** Engine-facing capabilities. Never use a strict user-field proxy as this port. */
|
|
12
13
|
export interface ScopeRuntimeTarget {
|
|
@@ -15,6 +16,8 @@ export interface ScopeRuntimeTarget {
|
|
|
15
16
|
getScopeRecorders?(): ScopeRecorder[];
|
|
16
17
|
useSharedRedactedKeys?(keys: Set<string>): void;
|
|
17
18
|
useRedactionPolicy?(policy: RedactionPolicy): void;
|
|
19
|
+
/** The run's correlation, stamped on every scope and emit event this scope fires (10.1). */
|
|
20
|
+
useCorrelation?(correlation: RunCorrelation | undefined): void;
|
|
18
21
|
getRedactedKeys?(): Set<string>;
|
|
19
22
|
notifyStageStart?(): void;
|
|
20
23
|
notifyStageEnd?(duration?: number): void;
|