footprintjs 5.0.0 → 6.0.0

package/dist/trace.js

@@ -22,11 +22,14 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.qualityTrace = exports.formatQualityTrace = exports.QualityRecorder = exports.ROOT_SUBFLOW_ID = exports.ROOT_RUNTIME_STAGE_ID = exports.inOutRecorder = exports.InOutRecorder = exports.topologyRecorder = exports.TopologyRecorder = exports.BoundaryStateTracker = exports.SequenceRecorder = exports.KeyedRecorder = exports.CommitRangeIndex = exports.SequenceStore = exports.KeyedStore = exports.BoundaryStateStore = exports.formatCausalChain = exports.flattenCausalDAG = exports.causalChain = exports.findLastWriter = exports.findCommits = exports.findCommit = exports.parseRuntimeStageId = exports.createExecutionCounter = exports.buildRuntimeStageId = void 0;
+exports.qualityTrace = exports.formatQualityTrace = exports.QualityRecorder = exports.ROOT_SUBFLOW_ID = exports.ROOT_RUNTIME_STAGE_ID = exports.inOutRecorder = exports.InOutRecorder = exports.topologyRecorder = exports.TopologyRecorder = exports.BoundaryStateTracker = exports.SequenceRecorder = exports.KeyedRecorder = exports.CommitRangeIndex = exports.SequenceStore = exports.KeyedStore = exports.BoundaryStateStore = exports.formatCausalChain = exports.flattenCausalDAG = exports.causalChain = exports.findLastWriter = exports.findCommits = exports.findCommit = exports.walkSubflowSpec = exports.splitStageId = exports.parseRuntimeStageId = exports.createExecutionCounter = exports.buildRuntimeStageId = void 0;
 var runtimeStageId_js_1 = require("./lib/engine/runtimeStageId.js");
 Object.defineProperty(exports, "buildRuntimeStageId", { enumerable: true, get: function () { return runtimeStageId_js_1.buildRuntimeStageId; } });
 Object.defineProperty(exports, "createExecutionCounter", { enumerable: true, get: function () { return runtimeStageId_js_1.createExecutionCounter; } });
 Object.defineProperty(exports, "parseRuntimeStageId", { enumerable: true, get: function () { return runtimeStageId_js_1.parseRuntimeStageId; } });
+Object.defineProperty(exports, "splitStageId", { enumerable: true, get: function () { return runtimeStageId_js_1.splitStageId; } });
+var walkSubflowSpec_js_1 = require("./lib/engine/walkSubflowSpec.js");
+Object.defineProperty(exports, "walkSubflowSpec", { enumerable: true, get: function () { return walkSubflowSpec_js_1.walkSubflowSpec; } });
 // Commit log queries — typed utilities for backtracking
 var commitLogUtils_js_1 = require("./lib/memory/commitLogUtils.js");
 Object.defineProperty(exports, "findCommit", { enumerable: true, get: function () { return commitLogUtils_js_1.findCommit; } });
@@ -75,4 +78,4 @@ Object.defineProperty(exports, "QualityRecorder", { enumerable: true, get: funct
 var qualityTrace_js_1 = require("./lib/recorder/qualityTrace.js");
 Object.defineProperty(exports, "formatQualityTrace", { enumerable: true, get: function () { return qualityTrace_js_1.formatQualityTrace; } });
 Object.defineProperty(exports, "qualityTrace", { enumerable: true, get: function () { return qualityTrace_js_1.qualityTrace; } });
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHJhY2UuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvdHJhY2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FxQkc7OztBQUlILG9FQUFrSDtBQUF6Ryx3SEFBQSxtQkFBbUIsT0FBQTtBQUFFLDJIQUFBLHNCQUFzQixPQUFBO0FBQUUsd0hBQUEsbUJBQW1CLE9BQUE7QUFFekUsd0RBQXdEO0FBQ3hELG9FQUF5RjtBQUFoRiwrR0FBQSxVQUFVLE9BQUE7QUFBRSxnSEFBQSxXQUFXLE9BQUE7QUFBRSxtSEFBQSxjQUFjLE9BQUE7QUFJaEQsMERBQTZGO0FBQXBGLDJHQUFBLFdBQVcsT0FBQTtBQUFFLGdIQUFBLGdCQUFnQixPQUFBO0FBQUUsaUhBQUEsaUJBQWlCLE9BQUE7QUFFekQsbUVBQW1FO0FBQ25FLGlFQUFpRTtBQUNqRSxpRUFBaUU7QUFDakUsNENBQTRDO0FBQzVDLDhFQUEwRTtBQUFqRSwySEFBQSxrQkFBa0IsT0FBQTtBQUMzQiw4REFBMEQ7QUFBakQsMkdBQUEsVUFBVSxPQUFBO0FBQ25CLG9FQUFnRTtBQUF2RCxpSEFBQSxhQUFhLE9BQUE7QUFTdEIsMEVBQXNFO0FBQTdELHVIQUFBLGdCQUFnQixPQUFBO0FBRXpCLG9FQUFvRTtBQUNwRSwrREFBK0Q7QUFDL0QsZ0VBQWdFO0FBQ2hFLHdEQUF3RDtBQUN4RCx5REFBeUQ7QUFDekQsb0VBQWdFO0FBQXZELGlIQUFBLGFBQWEsT0FBQTtBQUV0QixvRkFBb0Y7QUFDcEYsMEVBQXNFO0FBQTdELHVIQUFBLGdCQUFnQixPQUFBO0FBRXpCLHVFQUF1RTtBQUN2RSw2RUFBNkU7QUFDN0Usa0ZBQThFO0FBQXJFLCtIQUFBLG9CQUFvQixPQUFBO0FBVTdCLDBFQUF3RjtBQUEvRSx1SEFBQSxnQkFBZ0IsT0FBQTtBQUFFLHVIQUFBLGdCQUFnQixPQUFBO0FBSzNDLG9FQUF1SDtBQUE5RyxpSEFBQSxhQUFhLE9BQUE7QUFBRSxpSEFBQSxhQUFhLE9BQUE7QUFBRSx5SEFBQSxxQkFBcUIsT0FBQTtBQUFFLG1IQUFBLGVBQWUsT0FBQTtBQUk3RSx3RUFBb0U7QUFBM0QscUhBQUEsZUFBZSxPQUFBO0FBSXhCLGtFQUFrRjtBQUF6RSxxSEFBQSxrQkFBa0IsT0FBQTtBQUFFLCtHQUFBLFlBQVksT0FBQSIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogZm9vdHByaW50anMvdHJhY2Ug4oCUIEV4ZWN1dGlvbiB0cmFjaW5nLCBkZWJ1Z2dpbmcsIGFuZCBiYWNrdHJhY2tpbmcgdXRpbGl0aWVzLlxuICpcbiAqIFJ1bnRpbWUgc3RhZ2UgSURzLCBjb21taXQgbG9nIHF1ZXJpZXMsIGFuZCByZWNvcmRlciBiYXNlIGNsYXNzZXMuXG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGltcG9ydCB7IHBhcnNlUnVudGltZVN0YWdlSWQsIGZpbmRMYXN0V3JpdGVyLCBLZXllZFJlY29yZGVyLCBTZXF1ZW5jZVJlY29yZGVyIH0gZnJvbSAnZm9vdHByaW50anMvdHJhY2UnO1xuICpcbiAqIC8vIFBhcnNlIGEgcnVudGltZVN0YWdlSWRcbiAqIGNvbnN0IHsgc3RhZ2VJZCwgZXhlY3V0aW9uSW5kZXggfSA9IHBhcnNlUnVudGltZVN0YWdlSWQoJ2NhbGwtbGxtIzUnKTtcbiAqXG4gKiAvLyBCYWNrdHJhY2s6IHdobyB3cm90ZSAnc3lzdGVtUHJvbXB0JyBiZWZvcmUgc3RhZ2UgYXQgaWR4IDg/XG4gKiBjb25zdCB3cml0ZXIgPSBmaW5kTGFzdFdyaXRlcihjb21taXRMb2csICdzeXN0ZW1Qcm9tcHQnLCA4KTtcbiAqXG4gKiAvLyBCdWlsZCBhIGtleWVkIHJlY29yZGVyICgxOjEg4oCUIG9uZSBlbnRyeSBwZXIgc3RlcClcbiAqIGNsYXNzIE15UmVjb3JkZXIgZXh0ZW5kcyBLZXllZFJlY29yZGVyPE15RW50cnk+IHsgLi4uIH1cbiAqXG4gKiAvLyBCdWlsZCBhIHNlcXVlbmNlIHJlY29yZGVyICgxOk4g4oCUIG11bHRpcGxlIGVudHJpZXMgcGVyIHN0ZXAsIG9yZGVyaW5nIG1hdHRlcnMpXG4gKiBjbGFzcyBBdWRpdFJlY29yZGVyIGV4dGVuZHMgU2VxdWVuY2VSZWNvcmRlcjxBdWRpdEVudHJ5PiB7IC4uLiB9XG4gKiBgYGBcbiAqL1xuXG4vLyBSdW50aW1lIHN0YWdlIElEIOKAlCB1bmlxdWUgZXhlY3V0aW9uIHN0ZXAgaWRlbnRpZmllcnNcbmV4cG9ydCB0eXBlIHsgRXhlY3V0aW9uQ291bnRlciB9IGZyb20gJy4vbGliL2VuZ2luZS9ydW50aW1lU3RhZ2VJZC5qcyc7XG5leHBvcnQgeyBidWlsZFJ1bnRpbWVTdGFnZUlkLCBjcmVhdGVFeGVjdXRpb25Db3VudGVyLCBwYXJzZVJ1bnRpbWVTdGFnZUlkIH0gZnJvbSAnLi9saWIvZW5naW5lL3J1bnRpbWVTdGFnZUlkLmpzJztcblxuLy8gQ29tbWl0IGxvZyBxdWVyaWVzIOKAlCB0eXBlZCB1dGlsaXRpZXMgZm9yIGJhY2t0cmFja2luZ1xuZXhwb3J0IHsgZmluZENvbW1pdCwgZmluZENvbW1pdHMsIGZpbmRMYXN0V3JpdGVyIH0gZnJvbSAnLi9saWIvbWVtb3J5L2NvbW1pdExvZ1V0aWxzLmpzJztcblxuLy8gQ2F1c2FsIGNoYWluIOKAlCBiYWNrd2FyZCBwcm9ncmFtIHNsaWNpbmcgb24gY29tbWl0IGxvZyAoREFHKVxuZXhwb3J0IHR5cGUgeyBDYXVzYWxDaGFpbk9wdGlvbnMsIENhdXNhbE5vZGUsIEtleXNSZWFkTG9va3VwIH0gZnJvbSAnLi9saWIvbWVtb3J5L2JhY2t0cmFjay5qcyc7XG5leHBvcnQgeyBjYXVzYWxDaGFpbiwgZmxhdHRlbkNhdXNhbERBRywgZm9ybWF0Q2F1c2FsQ2hhaW4gfSBmcm9tICcuL2xpYi9tZW1vcnkvYmFja3RyYWNrLmpzJztcblxuLy8g4pSA4pSAIHY1IFN0b3JlcyAoY29uY3JldGUsIGNvbXBvc2FibGUg4oCUIHByaW1hcnkgcmVjb3JkZXIgQVBJKSDilIDilIDilIDilIDilIBcbi8vIENvbXBvc2UgdGhlc2UgdmlhIGBuZXcgU3RvcmU8VD4oKWAgYXMgYSBmaWVsZCBvbiB5b3VyIHJlY29yZGVyXG4vLyBjbGFzcy4gT25lIHB1cnBvc2UgcGVyIHJlY29yZGVyOiBzdG9yZXMgYXJlIHN0b3JhZ2U7IHJlY29yZGVyc1xuLy8gYXJlIGV2ZW50LWhvb2sgaW50ZXJmYWNlIGltcGxlbWVudGF0aW9ucy5cbmV4cG9ydCB7IEJvdW5kYXJ5U3RhdGVTdG9yZSB9IGZyb20gJy4vbGliL3JlY29yZGVyL0JvdW5kYXJ5U3RhdGVTdG9yZS5qcyc7XG5leHBvcnQgeyBLZXllZFN0b3JlIH0gZnJvbSAnLi9saWIvcmVjb3JkZXIvS2V5ZWRTdG9yZS5qcyc7XG5leHBvcnQgeyBTZXF1ZW5jZVN0b3JlIH0gZnJvbSAnLi9saWIvcmVjb3JkZXIvU2VxdWVuY2VTdG9yZS5qcyc7XG5cbi8vIOKUgOKUgCB2NS4xIENvbW1pdCBncm91cGluZyBwcmltaXRpdmUg4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSA4pSAXG4vLyBJbnRlcnZhbCBpbmRleCBvdmVyIGNvbW1pdCBpbmRpY2VzLiBCdWlsdCBpbmNyZW1lbnRhbGx5IGR1cmluZ1xuLy8gdHJhdmVyc2FsOiBvcGVuKCkgb24gYm91bmRhcnkgZW50cnksIGNsb3NlKCkgb24gZXhpdC4gUXVlcnkgYXQgYW55XG4vLyBjb21taXQgcG9zaXRpb24gd2l0aCBlbmNsb3NpbmcoKS9vdmVybGFwcGluZygpLiBHZW5lcmljIG92ZXIgVExhYmVsXG4vLyDigJQgZm9vdHByaW50anMgb3ducyBaRVJPIGtub3dsZWRnZSBvZiB3aGF0IGNvbnN1bWVycyB1c2UgYXMgbGFiZWxzLlxuLy8gU2VlIGRvY3MvZGVzaWduL2NvbW1pdC1yYW5nZS1pbmRleC5tZCBmb3IgdGhlIGZ1bGwgY29udHJhY3QuXG5leHBvcnQgdHlwZSB7IFJhbmdlRW50cnksIFJhbmdlVG9rZW4gfSBmcm9tICcuL2xpYi9yZWNvcmRlci9Db21taXRSYW5nZUluZGV4LmpzJztcbmV4cG9ydCB7IENvbW1pdFJhbmdlSW5kZXggfSBmcm9tICcuL2xpYi9yZWNvcmRlci9Db21taXRSYW5nZUluZGV4LmpzJztcblxuLy8g4pSA4pSAIEFic3RyYWN0IGJhc2VzIChERVBSRUNBVEVEIGluIHY1IOKAlCBzbGF0ZWQgZm9yIHJlbW92YWwpIOKUgOKUgOKUgOKUgOKUgOKUgOKUgFxuLy8gS2VwdCBkdXJpbmcgdGhlIHY1IG1pZ3JhdGlvbiB3aW5kb3cgZm9yIGRvd25zdHJlYW0gY29uc3VtZXJzXG4vLyAoYWdlbnRmb290cHJpbnQsIGFnZW50Zm9vdHByaW50LWxlbnMsIGV0Yy4pIHRoYXQgc3RpbGwgZXh0ZW5kXG4vLyB0aGVtLiBNaWdyYXRlIHRvIHRoZSBjb3JyZXNwb25kaW5nIFN0b3JlIGNsYXNzIGFib3ZlLlxuLy8gS2V5ZWRSZWNvcmRlciDigJQgYmFzZSBjbGFzcyBmb3IgMToxIE1hcC1iYXNlZCByZWNvcmRlcnNcbmV4cG9ydCB7IEtleWVkUmVjb3JkZXIgfSBmcm9tICcuL2xpYi9yZWNvcmRlci9LZXllZFJlY29yZGVyLmpzJztcblxuLy8gU2VxdWVuY2VSZWNvcmRlciDigJQgYmFzZSBjbGFzcyBmb3IgMTpOIG9yZGVyZWQgc2VxdWVuY2UgcmVjb3JkZXJzIHdpdGgga2V5ZWQgaW5kZXhcbmV4cG9ydCB7IFNlcXVlbmNlUmVjb3JkZXIgfSBmcm9tICcuL2xpYi9yZWNvcmRlci9TZXF1ZW5jZVJlY29yZGVyLmpzJztcblxuLy8gQm91bmRhcnlTdGF0ZVRyYWNrZXIg4oCUIGJhc2UgY2xhc3MgZm9yIHRyYW5zaWVudCBicmFja2V0LXNjb3BlZCBzdGF0ZVxuLy8gKGxpdmUgc3RhdGUgRFVSSU5HIGEgbWF0Y2hlZCBbc3RhcnQsIHN0b3BdIGV2ZW50IGludGVydmFsOyBjbGVhcnMgb24gc3RvcClcbmV4cG9ydCB7IEJvdW5kYXJ5U3RhdGVUcmFja2VyIH0gZnJvbSAnLi9saWIvcmVjb3JkZXIvQm91bmRhcnlTdGF0ZVRyYWNrZXIuanMnO1xuXG4vLyBUb3BvbG9neVJlY29yZGVyIOKAlCBjb21wb3NpdGlvbiBncmFwaCBhY2N1bXVsYXRvciAoc3ViZmxvd3MgKyBjb250cm9sLWZsb3cgZWRnZXMpXG5leHBvcnQgdHlwZSB7XG4gIFRvcG9sb2d5LFxuICBUb3BvbG9neUVkZ2UsXG4gIFRvcG9sb2d5SW5jb21pbmdLaW5kLFxuICBUb3BvbG9neU5vZGUsXG4gIFRvcG9sb2d5UmVjb3JkZXJPcHRpb25zLFxufSBmcm9tICcuL2xpYi9yZWNvcmRlci9Ub3BvbG9neVJlY29yZGVyLmpzJztcbmV4cG9ydCB7IFRvcG9sb2d5UmVjb3JkZXIsIHRvcG9sb2d5UmVjb3JkZXIgfSBmcm9tICcuL2xpYi9yZWNvcmRlci9Ub3BvbG9neVJlY29yZGVyLmpzJztcblxuLy8gSW5PdXRSZWNvcmRlciDigJQgY2hhcnQgaW4vb3V0IHN0cmVhbSAoZW50cnkvZXhpdCBwYWlycyBhdCBldmVyeSBjaGFydCBib3VuZGFyeSxcbi8vIGluY2x1ZGluZyB0aGUgdG9wLWxldmVsIHJ1biBhbmQgZXZlcnkgc3ViZmxvdylcbmV4cG9ydCB0eXBlIHsgSW5PdXRFbnRyeSwgSW5PdXRQaGFzZSwgSW5PdXRSZWNvcmRlck9wdGlvbnMgfSBmcm9tICcuL2xpYi9yZWNvcmRlci9Jbk91dFJlY29yZGVyLmpzJztcbmV4cG9ydCB7IEluT3V0UmVjb3JkZXIsIGluT3V0UmVjb3JkZXIsIFJPT1RfUlVOVElNRV9TVEFHRV9JRCwgUk9PVF9TVUJGTE9XX0lEIH0gZnJvbSAnLi9saWIvcmVjb3JkZXIvSW5PdXRSZWNvcmRlci5qcyc7XG5cbi8vIFF1YWxpdHlSZWNvcmRlciDigJQgcGVyLXN0ZXAgcXVhbGl0eSBzY29yaW5nIHdpdGggYmFja3RyYWNraW5nXG5leHBvcnQgdHlwZSB7IFF1YWxpdHlFbnRyeSwgUXVhbGl0eVJlY29yZGVyT3B0aW9ucywgUXVhbGl0eVNjb3JpbmdGbiB9IGZyb20gJy4vbGliL3JlY29yZGVyL1F1YWxpdHlSZWNvcmRlci5qcyc7XG5leHBvcnQgeyBRdWFsaXR5UmVjb3JkZXIgfSBmcm9tICcuL2xpYi9yZWNvcmRlci9RdWFsaXR5UmVjb3JkZXIuanMnO1xuXG4vLyBxdWFsaXR5VHJhY2Ug4oCUIFF1YWxpdHkgU3RhY2sgVHJhY2UgKGJhY2t0cmFjayBmcm9tIGxvdy1zY29yaW5nIHN0ZXBzKVxuZXhwb3J0IHR5cGUgeyBRdWFsaXR5RnJhbWUsIFF1YWxpdHlTdGFja1RyYWNlIH0gZnJvbSAnLi9saWIvcmVjb3JkZXIvcXVhbGl0eVRyYWNlLmpzJztcbmV4cG9ydCB7IGZvcm1hdFF1YWxpdHlUcmFjZSwgcXVhbGl0eVRyYWNlIH0gZnJvbSAnLi9saWIvcmVjb3JkZXIvcXVhbGl0eVRyYWNlLmpzJztcbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHJhY2UuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvdHJhY2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FxQkc7OztBQUlILG9FQUt3QztBQUp0Qyx3SEFBQSxtQkFBbUIsT0FBQTtBQUNuQiwySEFBQSxzQkFBc0IsT0FBQTtBQUN0Qix3SEFBQSxtQkFBbUIsT0FBQTtBQUNuQixpSEFBQSxZQUFZLE9BQUE7QUFNZCxzRUFBa0U7QUFBekQscUhBQUEsZUFBZSxPQUFBO0FBRXhCLHdEQUF3RDtBQUN4RCxvRUFBeUY7QUFBaEYsK0dBQUEsVUFBVSxPQUFBO0FBQUUsZ0hBQUEsV0FBVyxPQUFBO0FBQUUsbUhBQUEsY0FBYyxPQUFBO0FBSWhELDBEQUE2RjtBQUFwRiwyR0FBQSxXQUFXLE9BQUE7QUFBRSxnSEFBQSxnQkFBZ0IsT0FBQTtBQUFFLGlIQUFBLGlCQUFpQixPQUFBO0FBRXpELG1FQUFtRTtBQUNuRSxpRUFBaUU7QUFDakUsaUVBQWlFO0FBQ2pFLDRDQUE0QztBQUM1Qyw4RUFBMEU7QUFBakUsMkhBQUEsa0JBQWtCLE9BQUE7QUFDM0IsOERBQTBEO0FBQWpELDJHQUFBLFVBQVUsT0FBQTtBQUNuQixvRUFBZ0U7QUFBdkQsaUhBQUEsYUFBYSxPQUFBO0FBU3RCLDBFQUFzRTtBQUE3RCx1SEFBQSxnQkFBZ0IsT0FBQTtBQUV6QixvRUFBb0U7QUFDcEUsK0RBQStEO0FBQy9ELGdFQUFnRTtBQUNoRSx3REFBd0Q7QUFDeEQseURBQXlEO0FBQ3pELG9FQUFnRTtBQUF2RCxpSEFBQSxhQUFhLE9BQUE7QUFFdEIsb0ZBQW9GO0FBQ3BGLDBFQUFzRTtBQUE3RCx1SEFBQSxnQkFBZ0IsT0FBQTtBQUV6Qix1RUFBdUU7QUFDdkUsNkVBQTZFO0FBQzdFLGtGQUE4RTtBQUFyRSwrSEFBQSxvQkFBb0IsT0FBQTtBQVU3QiwwRUFBd0Y7QUFBL0UsdUhBQUEsZ0JBQWdCLE9BQUE7QUFBRSx1SEFBQSxnQkFBZ0IsT0FBQTtBQUszQyxvRUFBdUg7QUFBOUcsaUhBQUEsYUFBYSxPQUFBO0FBQUUsaUhBQUEsYUFBYSxPQUFBO0FBQUUseUhBQUEscUJBQXFCLE9BQUE7QUFBRSxtSEFBQSxlQUFlLE9BQUE7QUFJN0Usd0VBQW9FO0FBQTNELHFIQUFBLGVBQWUsT0FBQTtBQUl4QixrRUFBa0Y7QUFBekUscUhBQUEsa0JBQWtCLE9BQUE7QUFBRSwrR0FBQSxZQUFZLE9BQUEiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIGZvb3RwcmludGpzL3RyYWNlIOKAlCBFeGVjdXRpb24gdHJhY2luZywgZGVidWdnaW5nLCBhbmQgYmFja3RyYWNraW5nIHV0aWxpdGllcy5cbiAqXG4gKiBSdW50aW1lIHN0YWdlIElEcywgY29tbWl0IGxvZyBxdWVyaWVzLCBhbmQgcmVjb3JkZXIgYmFzZSBjbGFzc2VzLlxuICpcbiAqIEBleGFtcGxlXG4gKiBgYGB0eXBlc2NyaXB0XG4gKiBpbXBvcnQgeyBwYXJzZVJ1bnRpbWVTdGFnZUlkLCBmaW5kTGFzdFdyaXRlciwgS2V5ZWRSZWNvcmRlciwgU2VxdWVuY2VSZWNvcmRlciB9IGZyb20gJ2Zvb3RwcmludGpzL3RyYWNlJztcbiAqXG4gKiAvLyBQYXJzZSBhIHJ1bnRpbWVTdGFnZUlkXG4gKiBjb25zdCB7IHN0YWdlSWQsIGV4ZWN1dGlvbkluZGV4IH0gPSBwYXJzZVJ1bnRpbWVTdGFnZUlkKCdjYWxsLWxsbSM1Jyk7XG4gKlxuICogLy8gQmFja3RyYWNrOiB3aG8gd3JvdGUgJ3N5c3RlbVByb21wdCcgYmVmb3JlIHN0YWdlIGF0IGlkeCA4P1xuICogY29uc3Qgd3JpdGVyID0gZmluZExhc3RXcml0ZXIoY29tbWl0TG9nLCAnc3lzdGVtUHJvbXB0JywgOCk7XG4gKlxuICogLy8gQnVpbGQgYSBrZXllZCByZWNvcmRlciAoMToxIOKAlCBvbmUgZW50cnkgcGVyIHN0ZXApXG4gKiBjbGFzcyBNeVJlY29yZGVyIGV4dGVuZHMgS2V5ZWRSZWNvcmRlcjxNeUVudHJ5PiB7IC4uLiB9XG4gKlxuICogLy8gQnVpbGQgYSBzZXF1ZW5jZSByZWNvcmRlciAoMTpOIOKAlCBtdWx0aXBsZSBlbnRyaWVzIHBlciBzdGVwLCBvcmRlcmluZyBtYXR0ZXJzKVxuICogY2xhc3MgQXVkaXRSZWNvcmRlciBleHRlbmRzIFNlcXVlbmNlUmVjb3JkZXI8QXVkaXRFbnRyeT4geyAuLi4gfVxuICogYGBgXG4gKi9cblxuLy8gUnVudGltZSBzdGFnZSBJRCDigJQgdW5pcXVlIGV4ZWN1dGlvbiBzdGVwIGlkZW50aWZpZXJzXG5leHBvcnQgdHlwZSB7IEV4ZWN1dGlvbkNvdW50ZXIgfSBmcm9tICcuL2xpYi9lbmdpbmUvcnVudGltZVN0YWdlSWQuanMnO1xuZXhwb3J0IHtcbiAgYnVpbGRSdW50aW1lU3RhZ2VJZCxcbiAgY3JlYXRlRXhlY3V0aW9uQ291bnRlcixcbiAgcGFyc2VSdW50aW1lU3RhZ2VJZCxcbiAgc3BsaXRTdGFnZUlkLFxufSBmcm9tICcuL2xpYi9lbmdpbmUvcnVudGltZVN0YWdlSWQuanMnO1xuXG4vLyB3YWxrU3ViZmxvd1NwZWMg4oCUIGZsYXQgb3JkZXJlZCB0cmF2ZXJzYWwgb2YgYSBzdWJmbG93J3Mgc3RydWN0dXJlXG4vLyAoY29uc3VtZSB2aWEgU3RydWN0dXJlUmVjb3JkZXIub25TdWJmbG93TW91bnRlZCdzIHN1YmZsb3dTcGVjIHBheWxvYWQpXG5leHBvcnQgdHlwZSB7IFdhbGtlckl0ZW0sIFdhbGtlck9wdGlvbnMgfSBmcm9tICcuL2xpYi9lbmdpbmUvd2Fsa1N1YmZsb3dTcGVjLmpzJztcbmV4cG9ydCB7IHdhbGtTdWJmbG93U3BlYyB9IGZyb20gJy4vbGliL2VuZ2luZS93YWxrU3ViZmxvd1NwZWMuanMnO1xuXG4vLyBDb21taXQgbG9nIHF1ZXJpZXMg4oCUIHR5cGVkIHV0aWxpdGllcyBmb3IgYmFja3RyYWNraW5nXG5leHBvcnQgeyBmaW5kQ29tbWl0LCBmaW5kQ29tbWl0cywgZmluZExhc3RXcml0ZXIgfSBmcm9tICcuL2xpYi9tZW1vcnkvY29tbWl0TG9nVXRpbHMuanMnO1xuXG4vLyBDYXVzYWwgY2hhaW4g4oCUIGJhY2t3YXJkIHByb2dyYW0gc2xpY2luZyBvbiBjb21taXQgbG9nIChEQUcpXG5leHBvcnQgdHlwZSB7IENhdXNhbENoYWluT3B0aW9ucywgQ2F1c2FsTm9kZSwgS2V5c1JlYWRMb29rdXAgfSBmcm9tICcuL2xpYi9tZW1vcnkvYmFja3RyYWNrLmpzJztcbmV4cG9ydCB7IGNhdXNhbENoYWluLCBmbGF0dGVuQ2F1c2FsREFHLCBmb3JtYXRDYXVzYWxDaGFpbiB9IGZyb20gJy4vbGliL21lbW9yeS9iYWNrdHJhY2suanMnO1xuXG4vLyDilIDilIAgdjUgU3RvcmVzIChjb25jcmV0ZSwgY29tcG9zYWJsZSDigJQgcHJpbWFyeSByZWNvcmRlciBBUEkpIOKUgOKUgOKUgOKUgOKUgFxuLy8gQ29tcG9zZSB0aGVzZSB2aWEgYG5ldyBTdG9yZTxUPigpYCBhcyBhIGZpZWxkIG9uIHlvdXIgcmVjb3JkZXJcbi8vIGNsYXNzLiBPbmUgcHVycG9zZSBwZXIgcmVjb3JkZXI6IHN0b3JlcyBhcmUgc3RvcmFnZTsgcmVjb3JkZXJzXG4vLyBhcmUgZXZlbnQtaG9vayBpbnRlcmZhY2UgaW1wbGVtZW50YXRpb25zLlxuZXhwb3J0IHsgQm91bmRhcnlTdGF0ZVN0b3JlIH0gZnJvbSAnLi9saWIvcmVjb3JkZXIvQm91bmRhcnlTdGF0ZVN0b3JlLmpzJztcbmV4cG9ydCB7IEtleWVkU3RvcmUgfSBmcm9tICcuL2xpYi9yZWNvcmRlci9LZXllZFN0b3JlLmpzJztcbmV4cG9ydCB7IFNlcXVlbmNlU3RvcmUgfSBmcm9tICcuL2xpYi9yZWNvcmRlci9TZXF1ZW5jZVN0b3JlLmpzJztcblxuLy8g4pSA4pSAIHY1LjEgQ29tbWl0IGdyb3VwaW5nIHByaW1pdGl2ZSDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIDilIBcbi8vIEludGVydmFsIGluZGV4IG92ZXIgY29tbWl0IGluZGljZXMuIEJ1aWx0IGluY3JlbWVudGFsbHkgZHVyaW5nXG4vLyB0cmF2ZXJzYWw6IG9wZW4oKSBvbiBib3VuZGFyeSBlbnRyeSwgY2xvc2UoKSBvbiBleGl0LiBRdWVyeSBhdCBhbnlcbi8vIGNvbW1pdCBwb3NpdGlvbiB3aXRoIGVuY2xvc2luZygpL292ZXJsYXBwaW5nKCkuIEdlbmVyaWMgb3ZlciBUTGFiZWxcbi8vIOKAlCBmb290cHJpbnRqcyBvd25zIFpFUk8ga25vd2xlZGdlIG9mIHdoYXQgY29uc3VtZXJzIHVzZSBhcyBsYWJlbHMuXG4vLyBTZWUgZG9jcy9kZXNpZ24vY29tbWl0LXJhbmdlLWluZGV4Lm1kIGZvciB0aGUgZnVsbCBjb250cmFjdC5cbmV4cG9ydCB0eXBlIHsgUmFuZ2VFbnRyeSwgUmFuZ2VUb2tlbiB9IGZyb20gJy4vbGliL3JlY29yZGVyL0NvbW1pdFJhbmdlSW5kZXguanMnO1xuZXhwb3J0IHsgQ29tbWl0UmFuZ2VJbmRleCB9IGZyb20gJy4vbGliL3JlY29yZGVyL0NvbW1pdFJhbmdlSW5kZXguanMnO1xuXG4vLyDilIDilIAgQWJzdHJhY3QgYmFzZXMgKERFUFJFQ0FURUQgaW4gdjUg4oCUIHNsYXRlZCBmb3IgcmVtb3ZhbCkg4pSA4pSA4pSA4pSA4pSA4pSA4pSAXG4vLyBLZXB0IGR1cmluZyB0aGUgdjUgbWlncmF0aW9uIHdpbmRvdyBmb3IgZG93bnN0cmVhbSBjb25zdW1lcnNcbi8vIChhZ2VudGZvb3RwcmludCwgYWdlbnRmb290cHJpbnQtbGVucywgZXRjLikgdGhhdCBzdGlsbCBleHRlbmRcbi8vIHRoZW0uIE1pZ3JhdGUgdG8gdGhlIGNvcnJlc3BvbmRpbmcgU3RvcmUgY2xhc3MgYWJvdmUuXG4vLyBLZXllZFJlY29yZGVyIOKAlCBiYXNlIGNsYXNzIGZvciAxOjEgTWFwLWJhc2VkIHJlY29yZGVyc1xuZXhwb3J0IHsgS2V5ZWRSZWNvcmRlciB9IGZyb20gJy4vbGliL3JlY29yZGVyL0tleWVkUmVjb3JkZXIuanMnO1xuXG4vLyBTZXF1ZW5jZVJlY29yZGVyIOKAlCBiYXNlIGNsYXNzIGZvciAxOk4gb3JkZXJlZCBzZXF1ZW5jZSByZWNvcmRlcnMgd2l0aCBrZXllZCBpbmRleFxuZXhwb3J0IHsgU2VxdWVuY2VSZWNvcmRlciB9IGZyb20gJy4vbGliL3JlY29yZGVyL1NlcXVlbmNlUmVjb3JkZXIuanMnO1xuXG4vLyBCb3VuZGFyeVN0YXRlVHJhY2tlciDigJQgYmFzZSBjbGFzcyBmb3IgdHJhbnNpZW50IGJyYWNrZXQtc2NvcGVkIHN0YXRlXG4vLyAobGl2ZSBzdGF0ZSBEVVJJTkcgYSBtYXRjaGVkIFtzdGFydCwgc3RvcF0gZXZlbnQgaW50ZXJ2YWw7IGNsZWFycyBvbiBzdG9wKVxuZXhwb3J0IHsgQm91bmRhcnlTdGF0ZVRyYWNrZXIgfSBmcm9tICcuL2xpYi9yZWNvcmRlci9Cb3VuZGFyeVN0YXRlVHJhY2tlci5qcyc7XG5cbi8vIFRvcG9sb2d5UmVjb3JkZXIg4oCUIGNvbXBvc2l0aW9uIGdyYXBoIGFjY3VtdWxhdG9yIChzdWJmbG93cyArIGNvbnRyb2wtZmxvdyBlZGdlcylcbmV4cG9ydCB0eXBlIHtcbiAgVG9wb2xvZ3ksXG4gIFRvcG9sb2d5RWRnZSxcbiAgVG9wb2xvZ3lJbmNvbWluZ0tpbmQsXG4gIFRvcG9sb2d5Tm9kZSxcbiAgVG9wb2xvZ3lSZWNvcmRlck9wdGlvbnMsXG59IGZyb20gJy4vbGliL3JlY29yZGVyL1RvcG9sb2d5UmVjb3JkZXIuanMnO1xuZXhwb3J0IHsgVG9wb2xvZ3lSZWNvcmRlciwgdG9wb2xvZ3lSZWNvcmRlciB9IGZyb20gJy4vbGliL3JlY29yZGVyL1RvcG9sb2d5UmVjb3JkZXIuanMnO1xuXG4vLyBJbk91dFJlY29yZGVyIOKAlCBjaGFydCBpbi9vdXQgc3RyZWFtIChlbnRyeS9leGl0IHBhaXJzIGF0IGV2ZXJ5IGNoYXJ0IGJvdW5kYXJ5LFxuLy8gaW5jbHVkaW5nIHRoZSB0b3AtbGV2ZWwgcnVuIGFuZCBldmVyeSBzdWJmbG93KVxuZXhwb3J0IHR5cGUgeyBJbk91dEVudHJ5LCBJbk91dFBoYXNlLCBJbk91dFJlY29yZGVyT3B0aW9ucyB9IGZyb20gJy4vbGliL3JlY29yZGVyL0luT3V0UmVjb3JkZXIuanMnO1xuZXhwb3J0IHsgSW5PdXRSZWNvcmRlciwgaW5PdXRSZWNvcmRlciwgUk9PVF9SVU5USU1FX1NUQUdFX0lELCBST09UX1NVQkZMT1dfSUQgfSBmcm9tICcuL2xpYi9yZWNvcmRlci9Jbk91dFJlY29yZGVyLmpzJztcblxuLy8gUXVhbGl0eVJlY29yZGVyIOKAlCBwZXItc3RlcCBxdWFsaXR5IHNjb3Jpbmcgd2l0aCBiYWNrdHJhY2tpbmdcbmV4cG9ydCB0eXBlIHsgUXVhbGl0eUVudHJ5LCBRdWFsaXR5UmVjb3JkZXJPcHRpb25zLCBRdWFsaXR5U2NvcmluZ0ZuIH0gZnJvbSAnLi9saWIvcmVjb3JkZXIvUXVhbGl0eVJlY29yZGVyLmpzJztcbmV4cG9ydCB7IFF1YWxpdHlSZWNvcmRlciB9IGZyb20gJy4vbGliL3JlY29yZGVyL1F1YWxpdHlSZWNvcmRlci5qcyc7XG5cbi8vIHF1YWxpdHlUcmFjZSDigJQgUXVhbGl0eSBTdGFjayBUcmFjZSAoYmFja3RyYWNrIGZyb20gbG93LXNjb3Jpbmcgc3RlcHMpXG5leHBvcnQgdHlwZSB7IFF1YWxpdHlGcmFtZSwgUXVhbGl0eVN0YWNrVHJhY2UgfSBmcm9tICcuL2xpYi9yZWNvcmRlci9xdWFsaXR5VHJhY2UuanMnO1xuZXhwb3J0IHsgZm9ybWF0UXVhbGl0eVRyYWNlLCBxdWFsaXR5VHJhY2UgfSBmcm9tICcuL2xpYi9yZWNvcmRlci9xdWFsaXR5VHJhY2UuanMnO1xuIl19

package/dist/types/advanced.d.ts

@@ -26,7 +26,7 @@ export { EventLog } from './lib/memory/index.js';
 export { TransactionBuffer } from './lib/memory/index.js';
 export { DiagnosticCollector } from './lib/memory/index.js';
 export { applySmartMerge, deepSmartMerge, getNestedValue, getRunAndGlobalPaths, normalisePath, redactPatch, setNestedValue, updateNestedValue, updateValue, } from './lib/memory/index.js';
-export type { BuildTimeExtractor, BuildTimeNodeMetadata, ExecOptions, FlowChartSpec, ILogger, ScopeProtectionMode, SerializedPipelineStructure, SimplifiedParallelSpec, StageFn, StageNode, StreamCallback, StreamLifecycleHandler, StreamTokenHandler, SubflowMountOptions, SubflowRef, } from './lib/builder/index.js';
+export type { ExecOptions, FlowChartOptions, FlowChartSpec, ILogger, ScopeProtectionMode, SerializedPipelineStructure, SimplifiedParallelSpec, StageFn, StageNode, StreamCallback, StreamLifecycleHandler, StreamTokenHandler, SubflowMountOptions, SubflowRef, } from './lib/builder/index.js';
 export { ArrayMergeMode, DeciderList, SelectorFnList, specToStageNode } from './lib/builder/index.js';
 export { createTypedScopeFactory } from './lib/builder/typedFlowChart.js';
 export type { ProviderResolver, ResolveOptions, ScopeProvider, StageContextLike, StrictMode, } from './lib/scope/index.js';
@@ -44,10 +44,10 @@ export { FlowchartTraverser } from './lib/engine/index.js';
 export { isStageNodeReturn } from './lib/engine/index.js';
 export type { IControlFlowNarrative } from './lib/engine/index.js';
 export type { CombinedNarrativeEntry, CombinedNarrativeOptions } from './lib/engine/index.js';
-export type { BranchResult, BranchResults, SerializedPipelineStructure as EngineSerializedPipelineStructure, StageSnapshot as EngineStageSnapshot, ExtractorError, HandlerDeps, IExecutionRuntime, NodeResultType, RuntimeStructureMetadata, ScopeFactory, SerializedPipelineNode, StageFunction, SubflowResult, TraversalExtractor, TraversalResult, } from './lib/engine/index.js';
+export type { BranchResult, BranchResults, SerializedPipelineStructure as EngineSerializedPipelineStructure, HandlerDeps, IExecutionRuntime, NodeResultType, RuntimeStructureMetadata, ScopeFactory, SerializedPipelineNode, StageFunction, SubflowResult, TraversalResult, } from './lib/engine/index.js';
 export { NullControlFlowNarrativeGenerator } from './lib/engine/index.js';
-export type { CallExtractorFn, ExecuteNodeFn, GetStagePathFn, RunStageFn } from './lib/engine/index.js';
-export { applyOutputMapping, ChildrenExecutor, computeNodeType, ContinuationResolver, createSubflowHandlerDeps, DeciderHandler, DEFAULT_MAX_ITERATIONS, ExtractorRunner, extractParentScopeValues, getInitialScopeValues, NodeResolver, RuntimeStructureManager, seedSubflowGlobalStore, SelectorHandler, StageRunner, SubflowExecutor, } from './lib/engine/index.js';
+export type { ExecuteNodeFn, RunStageFn } from './lib/engine/index.js';
+export { applyOutputMapping, ChildrenExecutor, computeNodeType, ContinuationResolver, createSubflowHandlerDeps, DeciderHandler, DEFAULT_MAX_ITERATIONS, extractParentScopeValues, getInitialScopeValues, NodeResolver, RuntimeStructureManager, seedSubflowGlobalStore, SelectorHandler, StageRunner, SubflowExecutor, } from './lib/engine/index.js';
 export type { ExecutionCounter } from './lib/engine/runtimeStageId.js';
 export { buildRuntimeStageId, createExecutionCounter, parseRuntimeStageId } from './lib/engine/runtimeStageId.js';
 export { findCommit, findCommits, findLastWriter } from './lib/memory/commitLogUtils.js';

package/dist/types/index.d.ts

@@ -17,6 +17,8 @@
 export type { FlowChart, StageFunction as StageHandler, StreamHandlers } from './lib/builder/index.js';
 /** @category Quick Start */
 export { flowChart, FlowChartBuilder } from './lib/builder/index.js';
+/** @category Quick Start — build-time observer (twin of FlowRecorder) */
+export type { StructureDeciderCompleteEvent, StructureEdgeAddedEvent, StructureEdgeKind, StructureLoopEdgeAddedEvent, StructureRecorder, StructureStageAddedEvent, StructureSubflowMountedEvent, } from './lib/builder/index.js';
 /** @category Quick Start */
 export type { TypedStageFunction } from './lib/builder/typedFlowChart.js';
 /** @category Quick Start */

package/dist/types/lib/builder/FlowChartBuilder.d.ts

@@ -15,8 +15,10 @@ import type { ScopeFactory } from '../engine/types.js';
 import type { PausableHandler } from '../pause/types.js';
 import type { TypedScope } from '../reactive/types.js';
 import { type RunnableFlowChart } from '../runner/RunnableChart.js';
+import type { StructureEdgeKind, StructureRecorder } from './structure/StructureRecorder.js';
+import { StructureRecorderDispatcher } from './structure/StructureRecorderDispatcher.js';
 import { type TypedStageFunction } from './typedFlowChart.js';
-import type { BuildTimeExtractor, FlowChart, FlowChartSpec, ILogger, SerializedPipelineStructure, SimplifiedParallelSpec, StageFunction, StageNode, StreamLifecycleHandler, StreamTokenHandler, SubflowMountOptions, TraversalExtractor } from './types.js';
+import type { FlowChart, FlowChartOptions, FlowChartSpec, ILogger, SerializedPipelineStructure, SimplifiedParallelSpec, StageFunction, StageNode, StreamLifecycleHandler, StreamTokenHandler, SubflowMountOptions } from './types.js';
 /**
  * Fluent helper returned by addDeciderFunction to add branches.
  * `end()` sets `deciderFn = true` — the fn IS the decider.
@@ -92,9 +94,22 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
         root: StageNode<TOut, TScope>;
     }>;
     private _streamHandlers;
-    private _extractor?;
-    private _buildTimeExtractor?;
-    private _buildTimeExtractorErrors;
+    /**
+     * L7.3 — Build-time observer fan-out. Owned by the builder so every
+     * `addX()` method can fire `StructureRecorder` events at the natural
+     * moment of the corresponding mutation. Dispatcher is allocated
+     * lazily on first attach to keep the zero-recorder path allocation-
+     * free.
+     */
+    private _structureDispatcher?;
+    /**
+     * L7.3 — Sealed-after-build flag (Panel 2 phase invariant). Flips
+     * to `true` when `.build()` returns; subsequent `attachStructureRecorder`
+     * throws. Prevents the footgun where a consumer attaches a recorder
+     * mid-execution and gets partial structure data (missed every event
+     * already fired during construction).
+     */
+    private _sealed;
     private _enableNarrative;
     private _logger?;
     private _descriptionParts;
@@ -106,7 +121,90 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
     private _outputSchema?;
     private _outputMapper?;
     private _scopeFactory?;
-    constructor(buildTimeExtractor?: BuildTimeExtractor<any>);
+    /**
+     * Attach a `StructureRecorder` for build-phase observation. Multiple
+     * recorders coexist (same id allowed; iteration order = attach
+     * order). Throws if called after `.build()` — the chart is sealed at
+     * that point and any recorder attached late would miss every event
+     * fired during construction.
+     *
+     * **Seed replay**: when this is called AFTER `start()` has already
+     * fired (i.e., after the `flowChart()` factory returns), the
+     * just-attached recorder receives a one-time `onStageAdded` for the
+     * root stage so it observes the seed. Only the new recorder sees
+     * the replay; already-attached recorders are not re-fired.
+     *
+     * **Mid-chain attach caveat**: a recorder attached AFTER one or more
+     * `addX()` calls receives the seed replay but MISSES every
+     * intermediate event. Attach BEFORE the first `addX()` for complete
+     * capture.
+     *
+     * Public for now to enable direct attach in tests + early consumers.
+     * L7.4 will wire `flowChart(..., { structureRecorders: [...] })` as
+     * an additional registration site; this method will remain.
+     */
+    attachStructureRecorder(recorder: StructureRecorder): this;
+    /**
+     * Inspect accumulated `StructureBuildError`s. Returns empty array
+     * when no recorders attached OR no errors occurred. Returns a
+     * defensive copy — caller mutations do not affect subsequent calls.
+     *
+     * **Call on the BUILDER, not the chart returned by `.build()`.**
+     * Capture the builder reference before `.build()` if you need
+     * post-build access:
+     * ```ts
+     * const builder = flowChart(...).attachStructureRecorder(rec);
+     * const chart = builder.build();
+     * const errors = builder.getStructureBuildErrors();
+     * ```
+     */
+    getStructureBuildErrors(): ReturnType<StructureRecorderDispatcher['getErrors']>;
+    private _fireStageAdded;
+    private _fireEdgeAdded;
+    private _fireLoopEdgeAdded;
+    /**
+     * Fire the `next` edge(s) from a parent spec to a freshly-added
+     * node — with convergence expansion when the parent is a
+     * fork / decider / selector with branches.
+     *
+     * A fork at `parent` is semantically `parent ──fork-branch──► child[i]`
+     * for each child, and the chained `.addFunction(X)` continues
+     * AFTER the fork converges. The runtime semantics are that each
+     * child INDEPENDENTLY feeds `X` (parallel completion → join). The
+     * literal "edge from parent to X" would misrepresent this —
+     * visualizers and topological algorithms would see one edge where
+     * there should be N convergence edges.
+     *
+     * Fix: when `parentSpec` has branch children (fork or branched
+     * decider/selector), fire one `next` edge from EACH child to the
+     * target. Otherwise fire the single edge from `parentSpec` itself.
+     *
+     * Loop-reference children (synthetic spec nodes created by
+     * `.loopTo()`) are excluded — they're back-edge markers, not
+     * convergence sources.
+     *
+     * Call ORDER constraint: must be called BEFORE the cursor advances
+     * to the new target. The caller passes the PRE-ADVANCE parent spec.
+     */
+    private _fireNextEdgeFromParent;
+    private _fireDeciderComplete;
+    private _fireSubflowMounted;
+    /** Sub-builder access (`.b._fireXxx`) is needed by DeciderList /
+     *  SelectorFnList; expose the dispatcher through internal helpers
+     *  that go through the same no-op-when-absent guard.
+     *
+     *  @internal — these methods are exposed because TypeScript `private`
+     *  doesn't traverse class boundaries. Consumer code MUST NOT call
+     *  them; calling them post-construction lets a hostile caller
+     *  fabricate structure events and corrupt downstream visualizations
+     *  or audit trails. The `_` prefix is intentional convention. */
+    _fireEdgeAddedFromSubBuilder(from: string, to: string, kind: StructureEdgeKind, label?: string): void;
+    /** @internal — see `_fireEdgeAddedFromSubBuilder`. */
+    _fireStageAddedFromSubBuilder(spec: SerializedPipelineStructure): void;
+    /** @internal — see `_fireEdgeAddedFromSubBuilder`. */
+    _fireDeciderCompleteFromSubBuilder(decider: string, type: 'decider' | 'selector', branchIds: string[], defaultBranch?: string): void;
+    /** @internal — see `_fireEdgeAddedFromSubBuilder`. */
+    _fireSubflowMountedFromSubBuilder(subflowId: string, subflowName: string, rootStageId: string, isLazy?: boolean, subflowSpec?: SerializedPipelineStructure, subflowPath?: string): void;
     private _appendDescriptionLine;
     private _appendSubflowDescription;
     setLogger(logger: ILogger): this;
@@ -240,12 +338,6 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
     onStream(handler: StreamTokenHandler): this;
     onStreamStart(handler: StreamLifecycleHandler): this;
     onStreamEnd(handler: StreamLifecycleHandler): this;
-    addTraversalExtractor<TResult = unknown>(extractor: TraversalExtractor<TResult>): this;
-    addBuildTimeExtractor<TResult = FlowChartSpec>(extractor: BuildTimeExtractor<TResult>): this;
-    getBuildTimeExtractorErrors(): Array<{
-        message: string;
-        error: unknown;
-    }>;
     build(): RunnableFlowChart<TOut, TScope>;
     /** Override the scope factory. Rarely needed — auto-embeds TypedScope by default. */
     setScopeFactory(factory: ScopeFactory<TScope>): this;
@@ -253,7 +345,11 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
     toMermaid(): string;
     private _needCursor;
     private _needCursorSpec;
-    _applyExtractorToNode(spec: SerializedPipelineStructure): SerializedPipelineStructure;
+    /**
+     * Advance the spec cursor. Retained as a method so call sites stay
+     * one-liners and future cursor-related side effects have a hook.
+     */
+    private _advanceCursorSpec;
     _stageMapHas(key: string): boolean;
     _addToMap(id: string, fn: StageFunction<TOut, TScope>): void;
     _mergeStageMap(other: Map<string, StageFunction<TOut, TScope>>, prefix?: string): void;
@@ -262,6 +358,6 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
         root: StageNode<TOut, TScope>;
     }> | undefined, prefix: string): void;
 }
-export declare function flowChart<TState extends object>(name: string, fn: TypedStageFunction<TState> | PausableHandler<TypedScope<TState>>, id: string, buildTimeExtractor?: BuildTimeExtractor<any>, description?: string): FlowChartBuilder<any, TypedScope<TState>>;
-export declare function flowChart<TOut = any, TScope = any>(name: string, fn: StageFunction<TOut, TScope> | PausableHandler<TScope>, id: string, buildTimeExtractor?: BuildTimeExtractor<any>, description?: string): FlowChartBuilder<TOut, TScope>;
+export declare function flowChart<TState extends object>(name: string, fn: TypedStageFunction<TState> | PausableHandler<TypedScope<TState>>, id: string, options?: FlowChartOptions): FlowChartBuilder<any, TypedScope<TState>>;
+export declare function flowChart<TOut = any, TScope = any>(name: string, fn: StageFunction<TOut, TScope> | PausableHandler<TScope>, id: string, options?: FlowChartOptions): FlowChartBuilder<TOut, TScope>;
 export declare function specToStageNode(spec: FlowChartSpec): StageNode<any, any>;

package/dist/types/lib/builder/index.d.ts

@@ -6,5 +6,6 @@
  */
 export { DeciderList, FlowChartBuilder, SelectorFnList } from './FlowChartBuilder.js';
 export { flowChart, specToStageNode } from './FlowChartBuilder.js';
-export type { BuildTimeExtractor, BuildTimeNodeMetadata, ExecOptions, FlowChart, FlowChartSpec, ILogger, ScopeProtectionMode, SerializedPipelineStructure, SimplifiedParallelSpec, StageFn, StageFunction, StageNode, StreamCallback, StreamHandlers, StreamLifecycleHandler, StreamTokenHandler, SubflowMountOptions, SubflowRef, TraversalExtractor, } from './types.js';
+export type { ExecOptions, FlowChart, FlowChartOptions, FlowChartSpec, ILogger, ScopeProtectionMode, SerializedPipelineStructure, SimplifiedParallelSpec, StageFn, StageFunction, StageNode, StreamCallback, StreamHandlers, StreamLifecycleHandler, StreamTokenHandler, SubflowMountOptions, SubflowRef, } from './types.js';
 export { ArrayMergeMode } from './types.js';
+export type { StructureDeciderCompleteEvent, StructureEdgeAddedEvent, StructureEdgeKind, StructureLoopEdgeAddedEvent, StructureRecorder, StructureStageAddedEvent, StructureSubflowMountedEvent, } from './structure/StructureRecorder.js';

package/dist/types/lib/builder/structure/StructureRecorder.d.ts

@@ -0,0 +1,349 @@
+/**
+ * StructureRecorder — passive observer of BUILD-TIME chart construction events.
+ *
+ * The build-time twin of `FlowRecorder`. Where `FlowRecorder` observes
+ * RUNTIME control-flow transitions (per-execution `runtimeStageId`,
+ * iteration counts, errors, pauses), `StructureRecorder` observes
+ * STATIC chart shape as it's assembled by the builder — every spec
+ * node added, every outgoing edge wired, every decider closed.
+ *
+ * Why two interfaces, not one
+ * ───────────────────────────
+ *   Build and runtime events have different INVARIANTS, not just
+ *   different timing:
+ *
+ *     - Runtime events carry `runtimeStageId` (`[subflowPath/]stageId#N`),
+ *       `iteration`, `traversalContext` — load-bearing for time-travel
+ *       UIs, commit-log indices, and `SequenceRecorder<T>` consumers.
+ *       NONE of these exist at build time.
+ *
+ *     - Build events carry only `stageId` + structural fields. No
+ *       execution index, no iteration, no snapshot.
+ *
+ *     - Some events have no analog across phases: `onPause` /
+ *       `onResume` / `onError` / `onRunStart` are runtime-only;
+ *       `onDeciderComplete` / `onStageAdded` are build-only.
+ *
+ *   A single `FlowRecorder` with `phase: 'static' | 'dynamic'`
+ *   discriminator would force every consumer to write
+ *   `if (e.phase === 'static') ...` branches and would erase the
+ *   least-privilege boundary (a static-only consumer should NOT
+ *   accidentally observe runtime data — e.g., a public docs site
+ *   rendering chart topology must not see scope values).
+ *
+ *   Two interfaces, same mental model, clean separation. Two
+ *   registration sites ship today (pick whichever fits your call
+ *   site):
+ *
+ *     1. **Options-bag** (preferred when the recorder set is known
+ *        at construction time — registers BEFORE `start()` so even
+ *        the seed event fires through the normal dispatcher fan-out):
+ *        ```ts
+ *        flowChart('seed', fn, 'seed', { structureRecorders: [rec] })
+ *          .addFunction('a', fnA, 'a').build();
+ *        ```
+ *
+ *     2. **Fluent** (preferred when attach is conditional, late, or
+ *        in a chain builder — the just-attached recorder gets a
+ *        one-time seed replay so it observes the root stage):
+ *        ```ts
+ *        flowChart('seed', fn, 'seed')
+ *          .attachStructureRecorder(rec)
+ *          .addFunction('a', fnA, 'a').build();
+ *        ```
+ *
+ *   Both deliver the same event stream to the same recorder. See the
+ *   `@example` block below for a fully-fleshed-out implementation.
+ *
+ * Lifecycle + ordering invariants
+ * ───────────────────────────────
+ *   - Fires SYNCHRONOUSLY during builder chain calls (and during
+ *     `.build()` for the terminal node) at the natural moment each
+ *     spec mutation completes.
+ *   - `onStageAdded(A)` and `onStageAdded(B)` fire BEFORE any
+ *     `onEdgeAdded({from: A, to: B})` — endpoint registration
+ *     happens before edge wiring.
+ *   - `onDeciderComplete(D)` fires at sub-builder `.end()` time, AFTER
+ *     every child's `onStageAdded` and every `onEdgeAdded({from: D,
+ *     to: child})`. Marks the decider as no-further-mutation.
+ *   - `onSubflowMounted({subflowId})` fires once per mount.
+ *     **MOUNT-ONLY**: parent recorders do NOT receive a replay of
+ *     the subflow's own internal structure events (those fired
+ *     during the subflow's own `.build()`). Matches the runtime
+ *     `onSubflowEntry` semantics — composition over replay.
+ *
+ * Error isolation (matches FlowRecorder contract)
+ * ───────────────────────────────────────────────
+ *   - A throwing handler is caught, logged via `isDevMode()` warning,
+ *     and accumulated on `builder.getStructureBuildErrors()` for
+ *     post-hoc inspection.
+ *   - Subsequent recorders + subsequent events fire normally; one
+ *     misbehaving recorder cannot THROW its way into blocking
+ *     construction.
+ *   - The errors[] accumulator is soft-capped (~100 entries) with a
+ *     `__truncated__` sentinel record once the cap is hit, to prevent
+ *     unbounded growth on chatty broken recorders.
+ *   - Note: throw isolation does NOT defend against a handler that
+ *     succeeds at runtime but mutates `event.spec` to corrupt the
+ *     chart. See "Spec mutation" below.
+ *
+ * Spec mutation — readonly-by-contract (NOT runtime-enforced)
+ * ────────────────────────────────────────────────────────────
+ *   - Event payloads pass spec references where useful (e.g., `spec`
+ *     on `onStageAdded`). Every field on every event payload is
+ *     marked `readonly` in TypeScript — the type system signals
+ *     consumer intent at author time.
+ *   - There is NO runtime freeze. The builder fires `onStageAdded`
+ *     IMMEDIATELY when a spec node is added, BEFORE the builder
+ *     wires that node's `.next`/`.children`/`.loopTarget` in the
+ *     subsequent `addX` call. Freezing here would break the
+ *     builder's own subsequent mutation.
+ *   - Handler mutation of `event.spec` is DOCUMENTED UNDEFINED
+ *     BEHAVIOR — it will succeed at runtime, but is not supported
+ *     and downstream consumers may break. Specifically, mutating
+ *     `event.spec.fn`, `event.spec.id`, or `event.spec.children`
+ *     can corrupt subsequent runtime behavior of the chart.
+ *   - **Trust model**: attach ONLY recorders from trusted code paths.
+ *     A hostile or buggy recorder can effectively substitute stage
+ *     functions or rewire the chart structure. The `readonly`
+ *     markers cannot defend against intentional mutation.
+ *
+ * @example
+ * ```ts
+ * class TraceStructureRecorder implements StructureRecorder {
+ *   readonly id = 'trace-static';
+ *   nodes: XyflowNode[] = [];
+ *   edges: XyflowEdge[] = [];
+ *
+ *   onStageAdded(e) {
+ *     // Node role: 'stage' is the initial type. If outgoing edges
+ *     // arrive with kind 'fork-branch' / 'decision-branch' the node
+ *     // is functioning as a fork/decider — derive the visual style
+ *     // from those edges, not from `e.type` alone.
+ *     this.nodes.push({ id: e.stageId, type: 'lensStage', data: { label: e.name } });
+ *   }
+ *   onEdgeAdded(e) {
+ *     this.edges.push({ id: `${e.from}->${e.to}`, source: e.from, target: e.to });
+ *   }
+ *   onSubflowMounted(e) {
+ *     this.nodes.push({ id: e.subflowId, type: 'subflow', data: { label: e.subflowName } });
+ *   }
+ *   onDeciderComplete(e) {
+ *     // Optional: finalize node styling now that branch list is sealed.
+ *   }
+ * }
+ *
+ * // Registration option A — options-bag (preferred when recorders
+ * // are known up front; attaches BEFORE the seed event fires):
+ * const rec = new TraceStructureRecorder();
+ * const builder = flowChart('seed', fn, 'seed', {
+ *   structureRecorders: [rec],
+ * }).addFunction('a', fnA, 'a');
+ * const chart = builder.build();
+ *
+ * // Registration option B — fluent chain (preferred for conditional
+ * // or late attach; the just-attached recorder gets a seed replay):
+ * const rec2 = new TraceStructureRecorder();
+ * const builder2 = flowChart('seed', fn, 'seed')
+ *   .attachStructureRecorder(rec2)
+ *   .addFunction('a', fnA, 'a');
+ *
+ * // Inspect any recorder errors (call on the BUILDER, not the chart):
+ * const errors = builder.getStructureBuildErrors();
+ *
+ * <ReactFlow nodes={rec.nodes} edges={rec.edges} />
+ * ```
+ */
+import type { FlowChartSpec, SerializedPipelineStructure } from '../types.js';
+/**
+ * Event payload for `StructureRecorder.onStageAdded`. Fires for every
+ * spec node added to the chart, including the seed (added via
+ * `flowChart()` factory) and subflow mount nodes. Excludes synthetic
+ * loop-reference nodes (those carry `isLoopReference: true` on the
+ * spec; consumers see them via the separate `onLoopEdgeAdded` event
+ * instead of as fresh stages).
+ */
+export interface StructureStageAddedEvent {
+    /**
+     * Stable identifier for this node. AT EVENT FIRE TIME this is the
+     * builder's LOCAL form (no subflow prefix — the prefix is applied
+     * later by `_prefixNodeTree` when this builder is mounted as a
+     * subflow into a parent).
+     *
+     * Note: `spec.id` is a LIVE reference. If you read it AFTER this
+     * chart has been mounted as a subflow, it may have been rewritten
+     * to the FULL prefixed form. Use `splitStageId(spec.id)` from
+     * `footprintjs/trace` to decompose it back into local + subflowPath.
+     *
+     * Correlating with runtime events:
+     *   - Same builder (no mount) →
+     *     `event.stageId === parseRuntimeStageId(runtime).stageId`
+     *   - This builder mounted as subflow → use `splitStageId` on the
+     *     prefixed form (or `parseRuntimeStageId` on the full
+     *     runtimeStageId) before comparing.
+     */
+    readonly stageId: string;
+    /** Human-readable label for the node. */
+    readonly name: string;
+    /** Spec node `type`. Lets recorders branch on stage vs decider vs
+     *  fork vs subflow without re-deriving from other fields. */
+    readonly type: NonNullable<FlowChartSpec['type']>;
+    /** True for nodes added via `addPausableFunction()` — useful for
+     *  visualisers that want to mark stages that can pause execution. */
+    readonly isPausable?: boolean;
+    /** Live reference to the full spec node, for handlers that want
+     *  details beyond the discriminator fields above. MUST NOT be
+     *  mutated by the handler — readonly is type-level intent; no
+     *  runtime freeze. See "Spec mutation" in the file header for the
+     *  trust-model caveats. */
+    readonly spec: FlowChartSpec;
+}
+/** Edge kinds the builder produces at structural time. Matches the
+ *  footprintjs control-flow vocabulary used at runtime.
+ *
+ *  Why no `subflow-entry` here: subflow mounts use the lifecycle
+ *  event `onSubflowMounted` (not an edge event). If a future use case
+ *  needs the parent→subflow-root edge as a distinct kind, it'll be
+ *  added then — YAGNI now (Panel 3, L7.2 review). */
+export type StructureEdgeKind = 'next' | 'fork-branch' | 'decision-branch';
+/**
+ * Event payload for `StructureRecorder.onEdgeAdded`. Fires whenever
+ * the builder wires an outgoing edge from one node to another. Both
+ * endpoints have already been announced via `onStageAdded` by the
+ * time this fires.
+ *
+ * Loop back-edges have their OWN event (`onLoopEdgeAdded`) so
+ * consumers can theme them distinctly and so build-time events stay
+ * free of the runtime-only `iteration` field.
+ */
+export interface StructureEdgeAddedEvent {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: StructureEdgeKind;
+    /** Optional human-readable label — used today for decider branch
+     *  keys (e.g., `'low'`, `'high'`, `'high (default)'`) and parallel
+     *  branch ids. */
+    readonly label?: string;
+}
+/**
+ * Event payload for `StructureRecorder.onLoopEdgeAdded`. Fires when
+ * `.loopTo(target)` installs a back-edge. Distinct from
+ * `onEdgeAdded` so consumers can theme back-edges differently and
+ * because runtime `onLoop` carries `iteration: number` which has no
+ * build-time meaning — keeping the events separated avoids forcing
+ * an `iteration?: number` lie into the structural shape.
+ */
+export interface StructureLoopEdgeAddedEvent {
+    readonly from: string;
+    readonly to: string;
+}
+/**
+ * Event payload for `StructureRecorder.onDeciderComplete`. Fires
+ * when a decider / selector sub-builder closes via `.end()`. By the
+ * time this fires every branch has been announced and the
+ * `defaultBranch` (if set via `.setDefault()`) is final. Lets
+ * recorders treat the decider as no-further-mutation and snapshot
+ * its branch list as final.
+ */
+export interface StructureDeciderCompleteEvent {
+    /** Decider / selector stage id. */
+    readonly decider: string;
+    /** Spec type (`'decider'` vs `'selector'`) — exposed so consumers
+     *  don't need to look up the original `onStageAdded` event. */
+    readonly type: 'decider' | 'selector';
+    /** Branch member ids in declaration order. */
+    readonly branchIds: readonly string[];
+    /** Default branch id when set via `.setDefault()`; undefined when
+     *  no default is configured (e.g., selectors). */
+    readonly defaultBranch?: string;
+}
+/**
+ * Event payload for `StructureRecorder.onSubflowMounted`. Fires once
+ * per subflow mount (`addSubFlowChart` / `addSubFlowChartNext` and
+ * their lazy variants).
+ *
+ * **MOUNT-ONLY semantics** — the subflow's OWN structure events
+ * (every `onStageAdded` / `onEdgeAdded` inside the subflow) fired
+ * during the subflow's own `.build()`, before the mount. Parent
+ * recorders do NOT receive a replay. Instead, this event delivers
+ * the subflow's full structure via `subflowSpec`, and consumers can
+ * walk it via `walkSubflowSpec` from `footprintjs/trace`.
+ *
+ * This matches `FlowRecorder.onSubflowEntry` semantics at runtime
+ * (parents see the boundary, not a replay of internals) and
+ * preserves the "one purpose per recorder" convention.
+ */
+export interface StructureSubflowMountedEvent {
+    /** Subflow identifier the parent assigned at mount. */
+    readonly subflowId: string;
+    /** Human-readable subflow name. */
+    readonly subflowName: string;
+    /** Mount node id in the parent's chart. */
+    readonly rootStageId: string;
+    /** True when the mount uses lazy resolution (deferred subflow
+     *  resolution until execution). */
+    readonly isLazy?: boolean;
+    /**
+     * The mounted subflow's complete spec — the SAME OBJECT
+     * (=== reference equality) reachable via `subflow.buildTimeStructure`
+     * for the FlowChart the consumer passed to `addSubFlowChartBranch` /
+     * `addSubFlowChart` / `addSubFlowChartNext`.
+     *
+     * UNDEFINED for lazy mounts at build time (`isLazy: true`) — the
+     * subflow's structure hasn't been resolved yet. Consumers waiting on
+     * lazy subflows handle the runtime `onSubflowEntry` event instead.
+     *
+     * Immutable post-build; consumers MUST NOT mutate.
+     *
+     * @internal `SerializedPipelineStructure` is library-internal.
+     *           Use `walkSubflowSpec` from `footprintjs/trace` for the
+     *           stable public contract.
+     */
+    readonly subflowSpec?: SerializedPipelineStructure;
+    /**
+     * Local mount id of this subflow within its parent — equal to
+     * `subflowId` for top-level mounts (e.g. `'auth'`), composed
+     * (`'auth/verify'`) for nested mounts whose recorder is attached
+     * to the grandparent. Matches runtime `traversalContext.subflowPath`
+     * semantics — NEVER prefixed with `__root__/`.
+     */
+    readonly subflowPath: string;
+}
+/**
+ * Pluggable observer for BUILD-TIME chart construction events.
+ *
+ * All methods are optional — implement only the hooks you need.
+ * Handlers fire SYNCHRONOUSLY during builder operations and `.build()`.
+ * A throwing handler is caught (see "Error isolation" in the file
+ * header); subsequent dispatch continues.
+ *
+ * Lifecycle: each `StructureRecorder` instance is registered via
+ * EITHER the `flowChart()` options bag (`{ structureRecorders: [rec] }`)
+ * OR the fluent `.attachStructureRecorder(rec)` chain — see the file
+ * header for the trade-offs. Registration after `.build()` is
+ * rejected (chart is sealed).
+ */
+export interface StructureRecorder {
+    /**
+     * Stable identifier — used by the dispatcher to scope error
+     * messages and to support `detach(id)` lookup.
+     *
+     * Convention (matches `FlowRecorder.id` from CLAUDE.md):
+     *   - domain-prefixed kebab-case (`'lens-structure'`,
+     *     `'agentfootprint-composition'`, `'trace-explainable'`)
+     *   - same id → multiple recorders coexist (NOT deduplicated by
+     *     id; the dispatcher fires every attached recorder regardless)
+     *   - `detach(id)` removes EVERY recorder with that id — be
+     *     intentional about reuse if you rely on selective detach
+     *
+     * Choose a stable id at module load and don't randomise it across
+     * runs — it lands in `StructureBuildError.recorderId` so debug
+     * output is greppable.
+     */
+    readonly id: string;
+    onStageAdded?(event: StructureStageAddedEvent): void;
+    onEdgeAdded?(event: StructureEdgeAddedEvent): void;
+    onLoopEdgeAdded?(event: StructureLoopEdgeAddedEvent): void;
+    onDeciderComplete?(event: StructureDeciderCompleteEvent): void;
+    onSubflowMounted?(event: StructureSubflowMountedEvent): void;
+}