@proophboard/exploration-runtime 0.0.0-stage → 0.1.0

package/dist/playFunction/runtimeFold.js

@@ -0,0 +1,620 @@
+/**
+ * runtimeFold — the pure, environment-independent Exploration fold that executes
+ * AUTHORED play functions (4b), falling back to the built-in defaults (R11) when
+ * an element has no `playFunction`.
+ *
+ * This is deliberately NOT a hook and touches no DOM/worker API, so it is:
+ *   - unit-testable directly (the Web Worker can't be exercised under jsdom), and
+ *   - usable both inside the Worker (handlerWorker.ts) and on the main-thread
+ *     synchronous fast-path (when no element has a playFunction).
+ *
+ * Contract parity: with no authored handlers this reproduces `runReplay`'s exact
+ * default behaviour (so the M1–M3 runtime contract/tests still hold). Authored
+ * handlers extend it with: six handler kinds (interact/decide/apply/read/react/
+ * process), ordered multi-event commands, sequential apply, two-level leaf-replace
+ * merge, non-object Information shapes (via apply), deterministic clock + uuid(),
+ * the per-step cascade budget, and reject().
+ *
+ * Handler sources arrive PRE-TRANSPILED (TS→JS done by the caller/worker), so the
+ * fold stays synchronous. Compilation (`new Function`) is cached per source.
+ */
+import { toClassName } from '../lib/toClassName.js';
+import { getCommandsDrivenByUi, getConnections } from '../lib/connectionRules.js';
+import { deriveRuntimeSteps, mergeProjection, seedState, defaultDecide, } from './runtimeSteps.js';
+import { DeterministicClock } from './clock.js';
+import { CascadeBudget, isCascadeBudgetExceeded, DEFAULT_CASCADE_LIMITS } from './cascadeBudget.js';
+import { compileHandler, runHandler, deepFreeze, isRejectSignal, } from './sandbox.js';
+import { makePlayLogger } from './playLog.js';
+function clone(value) {
+    return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Compiled-handler cache keyed by source (compilation is pure). */
+const compiledCache = new Map();
+function getCompiled(source, kind) {
+    const cacheKey = `${kind}::${source}`;
+    let fn = compiledCache.get(cacheKey);
+    if (!fn) {
+        fn = compileHandler(source, kind);
+        compiledCache.set(cacheKey, fn);
+    }
+    return fn;
+}
+/** Test seam. */
+export function __clearCompiledCache() {
+    compiledCache.clear();
+}
+/** Does any element in the chapter carry an authored play function? */
+export function hasAnyPlayFunction(chapter) {
+    if (!chapter)
+        return false;
+    return chapter.elements.some((e) => typeof e.playFunction === 'string' && e.playFunction.trim().length > 0);
+}
+/**
+ * Run the authored-handler fold. Pure: `(input) → RuntimeResultV2`.
+ */
+export function runFold(input) {
+    const { chapter, steps, scenario, playheadIndex, liveStorage, handlers } = input;
+    const log = makePlayLogger(input.logSource ?? 'PlayWorker');
+    const authoredCount = Object.keys(handlers).length;
+    log('flow', `fold start — playhead=${playheadIndex}, steps=${steps.length}, authoredHandlers=${authoredCount}`);
+    const clock = new DeterministicClock(scenario.clock);
+    const budget = new CascadeBudget(input.cascadeLimits ?? DEFAULT_CASCADE_LIMITS);
+    const errors = [];
+    // Automation-dispatched commands awaiting their slice (deferred execution).
+    const pendingCommands = [];
+    // Pending commands already fired this replay (so we don't fire twice).
+    const firedPending = new Set();
+    // Seed state (reuses the M1 seeder; keys are className-form).
+    const state = seedState(scenario, clock.now());
+    // Captured-input seam (navigation without a command): `state.$input` exposes
+    // the UI storage collected via `storage.save()` / manual capture to all
+    // handlers — notably Information `read(state)`, which can "query" a projection
+    // using a captured value (e.g. find the picked todo by `state.$input.todoId`)
+    // WITHOUT hijacking a command→event flow for pure navigation.
+    //
+    // Shape (Option A — flat, `$`-reserved): the top level mirrors the LAST visible
+    // step's storage (most recent step ≤ playhead that captured input), so
+    // `state.$input.todoId` reads the latest value directly; `$byStep` is a reserved
+    // sibling holding every visible step's storage keyed by step index. It is kept
+    // current as the fold advances, so `read` (computed at the playhead) sees input
+    // from this and all earlier visible steps — never from the future.
+    const inputByStep = {};
+    const refreshInput = () => {
+        // Flatten: last-captured wins at the top level; $byStep preserves history.
+        const stepIdx = Object.keys(inputByStep)
+            .map(Number)
+            .sort((a, b) => a - b);
+        const last = stepIdx.length ? inputByStep[stepIdx[stepIdx.length - 1]] : {};
+        state.$input = { ...last, $byStep: { ...inputByStep } };
+    };
+    refreshInput(); // seed with {} / empty $byStep
+    const handlerFor = (el) => {
+        if (!el)
+            return undefined;
+        const src = handlers[el.id];
+        return src && src.trim().length > 0 ? src : undefined;
+    };
+    // Frozen snapshot of state for handler input (handlers must not mutate it).
+    const frozenState = () => deepFreeze(clone(state));
+    // Event → reacting automation(s), resolved via connection rules (NOT slice
+    // co-membership): the triggering event may sit in the write slice BEFORE the
+    // automation. We index reacting automations by the event's NAME, since the
+    // runtime matches produced events to event elements by name.
+    const reactionsByEventName = new Map();
+    if (chapter) {
+        const connections = getConnections(chapter);
+        for (const conn of connections) {
+            if (conn.type !== 'event')
+                continue;
+            if (conn.fromElement.type !== 'event' || conn.toElement.type !== 'automation')
+                continue;
+            const name = conn.fromElement.name;
+            const list = reactionsByEventName.get(name) ?? [];
+            // Only reaction automations that actually author a `react` participate;
+            // a default (no playFunction) automation reaction is a no-op (R11).
+            list.push(conn.toElement);
+            reactionsByEventName.set(name, list);
+        }
+    }
+    /** Ids of automations that are event-reaction targets (so NOT jobs). */
+    const reactionAutomationIds = new Set();
+    for (const list of reactionsByEventName.values()) {
+        for (const a of list)
+            reactionAutomationIds.add(a.id);
+    }
+    // Command → event element(s) it produces, resolved via connection rules (the
+    // event may be in the command's slice OR a following event-only slice). Used by
+    // the DEFAULT decide so a command without an authored handler emits the right
+    // event(s) even across slices.
+    const eventsByCommandId = new Map();
+    if (chapter) {
+        const connections = getConnections(chapter);
+        for (const conn of connections) {
+            if (conn.type !== 'command')
+                continue;
+            if (conn.fromElement.type !== 'command' || conn.toElement.type !== 'event')
+                continue;
+            const list = eventsByCommandId.get(conn.fromElement.id) ?? [];
+            list.push(conn.toElement);
+            eventsByCommandId.set(conn.fromElement.id, list);
+        }
+    }
+    // Event → Information element(s) it projects into, resolved via connection rules.
+    // In Event Modeling the Information an event writes is frequently drawn in a
+    // FOLLOWING read slice (connected by an event→information edge), NOT co-located
+    // in the event's write slice. Keyed by the event element's NAME (produced events
+    // match event elements by name; the same name may recur across slices). Used by
+    // the DEFAULT apply so a plain event still fills its connected Information.
+    const informationByEventName = new Map();
+    if (chapter) {
+        const connections = getConnections(chapter);
+        for (const conn of connections) {
+            if (conn.type !== 'event')
+                continue;
+            if (conn.fromElement.type !== 'event' || conn.toElement.type !== 'information')
+                continue;
+            const name = conn.fromElement.name;
+            const list = informationByEventName.get(name) ?? [];
+            list.push(conn.toElement);
+            informationByEventName.set(name, list);
+        }
+    }
+    /** Compute Information read() views at the current state (R11a, R21a). */
+    const computeReadViews = (atStep) => {
+        const views = [];
+        if (!chapter)
+            return views;
+        const seen = new Set();
+        for (const el of chapter.elements) {
+            if (el.type !== 'information')
+                continue;
+            const authored = handlerFor(el);
+            if (!authored || seen.has(el.id))
+                continue;
+            seen.add(el.id);
+            const ctxKey = toClassName(el.context || 'App');
+            const elKey = toClassName(el.name);
+            try {
+                const view = runHandler(getCompiled(authored, 'read'), clock.surface(), [frozenState()]);
+                log('read', `read(state) → view for ${el.context || 'App'}.${el.name}`, view);
+                views.push({ elementId: el.id, key: `${ctxKey}.${elKey}`, view });
+            }
+            catch (err) {
+                errors.push({
+                    kind: 'threw',
+                    message: err instanceof Error ? err.message : String(err),
+                    stepIndex: atStep,
+                    elementId: el.id,
+                    elementName: el.name,
+                });
+            }
+        }
+        return views;
+    };
+    if (!chapter || steps.length === 0) {
+        return { events: state.$events, state, errors, readViews: computeReadViews(0), clockISO: clock.now() };
+    }
+    const upto = Math.max(0, Math.min(playheadIndex, steps.length - 1));
+    // Storage per step (live overrides recorded) — same routing as runReplay.
+    const recorded = new Map();
+    for (const entry of scenario.interactions ?? []) {
+        if (entry && typeof entry.stepIndex === 'number')
+            recorded.set(entry.stepIndex, entry.storage ?? {});
+    }
+    const storageForStep = (s) => {
+        const live = liveStorage?.[s];
+        return live !== undefined ? live : recorded.get(s);
+    };
+    /** Emit one runtime event: assign index/timestamp, tick clock, record, apply. */
+    const emitEvent = (step, partial) => {
+        budget.countEvent();
+        const runtimeEvent = {
+            ...partial,
+            payload: partial.payload ?? {},
+            index: state.$events.length,
+            timestamp: clock.now(),
+            sliceId: step.slice.id, // M5 attribution: which slice emitted this event
+        };
+        state.$events.push(runtimeEvent);
+        log('event', `emit #${runtimeEvent.index} ${runtimeEvent.context}.${runtimeEvent.name} @${runtimeEvent.timestamp}`, runtimeEvent.payload);
+        clock.tick(); // auto-tick per produced event (R32-A)
+        // event.apply — authored or default.
+        applyEvent(step, runtimeEvent);
+        // Automation event-reactions (R10 react): fire reacting automations for this
+        // event, bounded by cascade DEPTH. Reactions produce commands that re-enter
+        // decide → events → (possibly) more reactions.
+        fireReactions(step, runtimeEvent);
+        return runtimeEvent;
+    };
+    /** Apply an event into projections: authored apply() or the default merge. */
+    const applyEvent = (step, event) => {
+        // Resolve the event element (for an authored apply) and the target Information.
+        const eventEl = step.events.find((e) => e.name === event.name) ?? step.events[0];
+        const authored = handlerFor(eventEl);
+        if (authored) {
+            try {
+                const patch = runHandler(getCompiled(authored, 'apply'), clock.surface(), [clone(event), frozenState()]);
+                log('apply', `apply(${event.name}, state) → projection patch`, patch);
+                if (isPlainObject(patch)) {
+                    // Two-level leaf-replace merge of { Ctx: { El: {...} } }.
+                    for (const [ctx, elements] of Object.entries(patch)) {
+                        if (!isPlainObject(elements))
+                            continue;
+                        for (const [el, val] of Object.entries(elements)) {
+                            applyLeaf(ctx, el, val);
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                recordError(err, step, eventEl);
+            }
+            return;
+        }
+        // DEFAULT: merge the event payload into the target Information. The target is
+        // the single-object Information in the event's OWN slice if present, else the
+        // Information connected to this event via the Event Modeling edges (typically
+        // a following read slice). Merges into every connected Information (R11, R13).
+        const sameSliceInfo = step.information[0];
+        const targets = sameSliceInfo
+            ? [sameSliceInfo]
+            : (informationByEventName.get(event.name) ?? []);
+        if (targets.length === 0) {
+            log('apply', `default apply(${event.name}) → NO target Information (same-slice none, no event→information connection)`);
+        }
+        for (const targetInfo of targets) {
+            log('apply', `default apply(${event.name}) → merge into ${targetInfo.context || 'App'}.${targetInfo.name}`, event.payload);
+            mergeProjection(state, targetInfo.context || 'App', targetInfo.name, event.payload);
+        }
+    };
+    /** Leaf-replace write honouring the className keying + non-object shapes (R13). */
+    const applyLeaf = (ctxDisplay, elDisplay, value) => {
+        const ctxKey = toClassName(ctxDisplay);
+        const elKey = toClassName(elDisplay);
+        const ctxBucket = isPlainObject(state[ctxKey]) ? state[ctxKey] : {};
+        if (isPlainObject(value)) {
+            const existing = isPlainObject(ctxBucket[elKey]) ? ctxBucket[elKey] : {};
+            ctxBucket[elKey] = { ...existing, ...value }; // leaf-merge for objects
+        }
+        else {
+            ctxBucket[elKey] = clone(value); // lists/scalars: replace wholesale
+        }
+        state[ctxKey] = ctxBucket;
+    };
+    const recordError = (err, step, el) => {
+        const where = el ? `${el.type} ${el.name}` : `step ${step.stepIndex}`;
+        if (isCascadeBudgetExceeded(err)) {
+            log('error', `cascade-exceeded (${err.kind}) at ${where}: ${err.message}`);
+            errors.push({
+                kind: 'cascade-exceeded',
+                message: err.message,
+                stepIndex: step.stepIndex,
+                sliceId: step.slice.id,
+                elementId: el?.id,
+                elementName: el?.name,
+                cascadeKind: err.kind,
+            });
+            throw err; // cascade stops the whole step — rethrow to unwind the fold step
+        }
+        if (isRejectSignal(err)) {
+            log('error', `reject() at ${where}: ${err.reason || 'Command rejected.'}`);
+            errors.push({
+                kind: 'rejected',
+                message: err.reason || 'Command rejected.',
+                stepIndex: step.stepIndex,
+                sliceId: step.slice.id,
+                elementId: el?.id,
+                elementName: el?.name,
+            });
+            return;
+        }
+        const name = err instanceof Error ? err.name : 'Unknown';
+        const firstFrame = err instanceof Error && err.stack ? (err.stack.split('\n')[1]?.trim() ?? '') : '';
+        log('error', `threw at ${where}: [${name}] ${err instanceof Error ? err.message : String(err)}${firstFrame ? ` @ ${firstFrame}` : ''}`);
+        errors.push({
+            kind: 'threw',
+            message: err instanceof Error ? err.message : String(err),
+            stepIndex: step.stepIndex,
+            sliceId: step.slice.id,
+            elementId: el?.id,
+            elementName: el?.name,
+        });
+    };
+    /** Resolve the command element a produced command refers to, by name (+context). */
+    const resolveCommandElement = (command, fallbackStep) => {
+        // Prefer a command element in the current step, else anywhere in the chapter.
+        const inStep = fallbackStep.commands.find((c) => c.name === command.name);
+        if (inStep)
+            return inStep;
+        return chapter.elements.find((e) => e.type === 'command' && e.name === command.name &&
+            (!command.context || (e.context || 'App') === command.context)) ?? chapter.elements.find((e) => e.type === 'command' && e.name === command.name);
+    };
+    /** The step a command element lives in (for its slice events in the default). */
+    const stepForElement = (el, fallback) => {
+        if (!el)
+            return fallback;
+        return steps.find((s) => s.slice.id === el.sliceId) ?? fallback;
+    };
+    /** Run a command through decide (authored or default) → ordered events. */
+    const runCommand = (step, command) => {
+        const cmdEl = resolveCommandElement(command, step);
+        const targetStep = stepForElement(cmdEl, step);
+        const authored = handlerFor(cmdEl);
+        let decided;
+        if (authored) {
+            try {
+                const out = runHandler(getCompiled(authored, 'decide'), clock.surface(), [clone(command), frozenState()]);
+                decided = Array.isArray(out)
+                    ? out.map((e) => {
+                        const ev = e;
+                        return { name: String(ev.name ?? ''), context: ev.context || command.context, payload: ev.payload ?? {} };
+                    })
+                    : [];
+                log('decide', `decide(${command.name}, state) → ${decided.length} event(s): ${decided.map((d) => d.name).join(', ') || '—'}`, command.payload);
+            }
+            catch (err) {
+                recordError(err, step, cmdEl);
+                return; // reject/throw: no events, no state change for this command
+            }
+            for (const ev of decided)
+                emitEvent(targetStep, ev);
+        }
+        else {
+            // DEFAULT decide: emit the command's connected event(s) — which may live in
+            // a following event-only slice — each carrying the command payload (R11).
+            // Emit each event in the STEP that contains its event element, so authored
+            // apply / default-merge resolve against the right slice's Information.
+            const eventEls = cmdEl ? (eventsByCommandId.get(cmdEl.id) ?? []) : [];
+            if (eventEls.length > 0) {
+                log('decide', `default decide(${command.name}) → connected event(s): ${eventEls.map((e) => e.name).join(', ')}`, command.payload);
+                for (const evtEl of eventEls) {
+                    const evtStep = stepForElement(evtEl, targetStep);
+                    emitEvent(evtStep, {
+                        name: evtEl.name,
+                        context: evtEl.context || command.context,
+                        payload: clone(command.payload) ?? {},
+                    });
+                }
+            }
+            else {
+                // Fallback: command's own slice events (M1 single-slice behaviour).
+                log('decide', `default decide(${command.name}) → slice event(s): ${targetStep.events.map((e) => e.name).join(', ') || '—'}`, command.payload);
+                for (const ev of defaultDecide(targetStep, command))
+                    emitEvent(targetStep, ev);
+            }
+        }
+    };
+    /** Build a command object for an element, with the storage that drives it. */
+    const commandFromElement = (cmdEl, storage) => ({
+        name: cmdEl.name,
+        context: cmdEl.context || 'App',
+        payload: storage ? clone(storage) : {},
+    });
+    /**
+     * Fire automation event-reactions for a just-emitted event (R10 react).
+     * Reacting automations are resolved via connection rules (reactionsByEventName).
+     * Each authored `react(event, state)` returns commands which are RECORDED as
+     * PENDING (not run immediately): they fire when the playhead reaches the target
+     * command's slice (draft §4.6), mirroring the UI captured-input → command flow.
+     */
+    const fireReactions = (step, event) => {
+        const reactors = reactionsByEventName.get(event.name);
+        if (!reactors || reactors.length === 0)
+            return;
+        for (const autoEl of reactors) {
+            const authored = handlerFor(autoEl);
+            if (!authored)
+                continue; // default automation reaction is a no-op (R11)
+            try {
+                const out = runHandler(getCompiled(authored, 'react'), clock.surface(), [clone(event), frozenState()]);
+                const cmds = Array.isArray(out) ? out : [];
+                log('react', `react(${event.name}, state) by ${autoEl.name} → ${cmds.length} command(s): ${cmds.map((c) => c?.name).join(', ') || '—'}`);
+                if (Array.isArray(out)) {
+                    for (const c of out) {
+                        const cc = c;
+                        recordPendingCommand(autoEl, {
+                            name: String(cc.name ?? ''),
+                            context: cc.context || (autoEl.context || 'App'),
+                            payload: cc.payload ?? {},
+                        }, event.name);
+                    }
+                }
+            }
+            catch (err) {
+                recordError(err, step, autoEl);
+            }
+        }
+    };
+    /** Record an automation-dispatched command as pending (fires at its slice). */
+    const recordPendingCommand = (autoEl, command, triggeredByEventName) => {
+        const target = chapter.elements.find((e) => e.type === 'command' && e.name === command.name &&
+            (!command.context || (e.context || 'App') === command.context)) ?? chapter.elements.find((e) => e.type === 'command' && e.name === command.name);
+        log('pending', `defer command ${command.context}.${command.name} from ${autoEl.name}${triggeredByEventName ? ` (on ${triggeredByEventName})` : ' (job)'} — ${target ? 'target resolved' : 'UNRESOLVED target'}`, command.payload);
+        pendingCommands.push({
+            commandElementId: target?.id,
+            name: command.name,
+            context: command.context,
+            payload: clone(command.payload) ?? {},
+            sourceAutomationId: autoEl.id,
+            sourceAutomationName: autoEl.name,
+            triggeredByEventName,
+        });
+    };
+    // Connection-aware storage routing (UI may drive a command in a later slice).
+    const storageByCommandId = new Map();
+    for (let s = 0; s <= upto; s++) {
+        const uiStep = steps[s];
+        if (!uiStep.uiElement)
+            continue;
+        const storage = storageForStep(s);
+        if (storage === undefined)
+            continue;
+        for (const cmd of getCommandsDrivenByUi(chapter, uiStep.uiElement)) {
+            storageByCommandId.set(cmd.id, storage);
+        }
+    }
+    // ── Fold steps 0..upto ─────────────────────────────────────────────────────
+    for (let s = 0; s <= upto; s++) {
+        const step = steps[s];
+        try {
+            log('flow', `step ${s}/${upto} — slice "${step.slice.label}"${step.uiElement ? ` ui=${step.uiElement.name}` : ''}${step.commands.length ? ` cmd=${step.commands.map((c) => c.name).join(',')}` : ''}${step.events.length ? ` evt=${step.events.map((e) => e.name).join(',')}` : ''}${step.automationElement ? ` auto=${step.automationElement.name}` : ''}`);
+            // Expose this step's captured input via state.$input BEFORE any handler on
+            // this step runs, so interact/decide/apply (and the end-of-fold read) can
+            // query it. Only UI steps carry input; others leave $input unchanged.
+            if (step.uiElement) {
+                const stepStorage = storageForStep(s);
+                if (stepStorage !== undefined) {
+                    inputByStep[s] = stepStorage;
+                    refreshInput();
+                    log('input', `$input ← step ${s} storage (${step.uiElement.name})`, stepStorage);
+                }
+            }
+            // 1. UI step with an authored interact → commands (authored only; the
+            //    default UI path is handled by storage routing feeding the command).
+            let uiInteractRan = false;
+            if (step.uiElement) {
+                const authored = handlerFor(step.uiElement);
+                if (authored) {
+                    uiInteractRan = true;
+                    const storage = storageForStep(s) ?? {};
+                    try {
+                        const out = runHandler(getCompiled(authored, 'interact'), clock.surface(), [clone(storage), frozenState()]);
+                        const cmds = Array.isArray(out) ? out : [];
+                        log('interact', `interact(storage, state) on ${step.uiElement.name} → ${cmds.length} command(s): ${cmds.map((c) => c?.name).join(', ') || '—'}`, storage);
+                        if (Array.isArray(out)) {
+                            for (const c of out) {
+                                const cc = c;
+                                runCommand(step, {
+                                    name: String(cc.name ?? ''),
+                                    context: cc.context || (step.uiElement.context || 'App'),
+                                    payload: cc.payload ?? {},
+                                });
+                            }
+                        }
+                    }
+                    catch (err) {
+                        recordError(err, step, step.uiElement);
+                    }
+                }
+            }
+            // 2. Commands in the slice. Each command fires from exactly one source,
+            //    checked in order: (a) a PENDING command dispatched earlier by an
+            //    automation whose target is this command; (b) UI storage routed to it;
+            //    (c) the M1 default. Skipped entirely when an authored UI interact ran
+            //    (that interact is the command source for this step).
+            if (!uiInteractRan && step.commands.length > 0) {
+                for (const cmdEl of step.commands) {
+                    // (a) consume pending commands targeting this command element.
+                    let firedFromPending = false;
+                    for (let pi = 0; pi < pendingCommands.length; pi++) {
+                        if (firedPending.has(pi))
+                            continue;
+                        const pc = pendingCommands[pi];
+                        if (pc.commandElementId !== cmdEl.id)
+                            continue;
+                        firedPending.add(pi);
+                        firedFromPending = true;
+                        log('pending', `fire deferred command ${pc.context}.${pc.name} at slice "${step.slice.label}" (from ${pc.sourceAutomationName})`, pc.payload);
+                        runCommand(step, { name: pc.name, context: pc.context, payload: clone(pc.payload) });
+                    }
+                    if (firedFromPending)
+                        continue;
+                    // (b)/(c) storage-routed or default.
+                    const storage = storageByCommandId.get(cmdEl.id);
+                    runCommand(step, commandFromElement(cmdEl, storage));
+                }
+            }
+            else if (!uiInteractRan && step.events.length > 0 && !step.uiElement) {
+                // 3. Hand-drawn events with no command driver: emit directly (empty payload),
+                //    applying authored/default apply. Preserves M1 behaviour.
+                for (const evtEl of step.events) {
+                    emitEvent(step, { name: evtEl.name, context: evtEl.context || 'App', payload: {} });
+                }
+            }
+            // 4. Automation (job) process(state) → commands, when the playhead reaches it.
+            //    An automation is a JOB only if it is NOT an event-reaction target
+            //    (reaction automations fire via fireReactions when their event occurs).
+            if (step.automationElement) {
+                const authored = handlerFor(step.automationElement);
+                const isReaction = reactionAutomationIds.has(step.automationElement.id);
+                if (authored && !isReaction) {
+                    try {
+                        const out = runHandler(getCompiled(authored, 'process'), clock.surface(), [frozenState()]);
+                        const cmds = Array.isArray(out) ? out : [];
+                        log('process', `process(state) on ${step.automationElement.name} → ${cmds.length} command(s): ${cmds.map((c) => c?.name).join(', ') || '—'}`);
+                        if (Array.isArray(out)) {
+                            for (const c of out) {
+                                const cc = c;
+                                // Deferred like a reaction: the job's command fires when the
+                                // playhead reaches its (downstream) slice. Surfaced as pending.
+                                recordPendingCommand(step.automationElement, {
+                                    name: String(cc.name ?? ''),
+                                    context: cc.context || (step.automationElement.context || 'App'),
+                                    payload: cc.payload ?? {},
+                                });
+                            }
+                        }
+                    }
+                    catch (err) {
+                        recordError(err, step, step.automationElement);
+                    }
+                }
+            }
+            // 5. Read-step surfacing: ensure seeded Information buckets appear (M1 parity).
+            if (step.events.length === 0 && step.commands.length === 0 && step.information.length > 0) {
+                for (const info of step.information) {
+                    const ctxKey = toClassName(info.context || 'App');
+                    const elKey = toClassName(info.name);
+                    const ctx = isPlainObject(state[ctxKey]) ? state[ctxKey] : {};
+                    if (!(elKey in ctx)) {
+                        ctx[elKey] = ctx[elKey] ?? {};
+                        state[ctxKey] = ctx;
+                    }
+                }
+            }
+        }
+        catch (err) {
+            // A cascade-exceeded stops THIS step; record it (it may have been thrown
+            // from emitEvent's budget check without passing through recordError) and
+            // continue so the playhead settles with last-good state for earlier steps.
+            if (isCascadeBudgetExceeded(err)) {
+                if (!errors.some((e) => e.kind === 'cascade-exceeded' && e.stepIndex === step.stepIndex)) {
+                    errors.push({
+                        kind: 'cascade-exceeded',
+                        message: err.message,
+                        stepIndex: step.stepIndex,
+                        sliceId: step.slice.id,
+                        cascadeKind: err.kind,
+                    });
+                }
+            }
+            else {
+                recordError(err, step);
+            }
+        }
+    }
+    const unfiredPending = pendingCommands.filter((_pc, i) => !firedPending.has(i));
+    const readViews = computeReadViews(upto);
+    log('flow', `fold done — events=${state.$events.length}, errors=${errors.length}, pending=${unfiredPending.length}, readViews=${readViews.length}, clock=${clock.now()}`);
+    return {
+        events: state.$events,
+        state,
+        errors,
+        readViews,
+        pendingCommands: unfiredPending,
+        clockISO: clock.now(),
+    };
+}
+/** Convenience: derive steps + run the fold in one call (used by the worker). */
+export function foldChapter(chapter, scenario, playheadIndex, handlers, liveStorage, cascadeLimits, logSource) {
+    if (!chapter) {
+        const empty = seedState(scenario, new DeterministicClock(scenario.clock).now());
+        return { events: empty.$events, state: empty, errors: [], readViews: [] };
+    }
+    const steps = deriveRuntimeSteps(chapter);
+    return runFold({ chapter, steps, scenario, playheadIndex, handlers, liveStorage, cascadeLimits, logSource });
+}
+//# sourceMappingURL=runtimeFold.js.map