@smthrs/engine-store 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/PlanScheduler.js

@@ -0,0 +1,1321 @@
+/**
+ * Drives a persisted plan: the node scheduler.
+ *
+ * `@smthrs/plan` makes the plan a value; this makes it run. The scheduler
+ * walks the persisted graph, dispatches ready nodes through the same
+ * `internal/ActionPersistence` seam every action uses — so the shared step
+ * cache, the workspace sandbox's execute→materialize transaction, attempt
+ * rows, and the fenced journal all apply unchanged — and records an
+ * evaluation outcome per node.
+ *
+ * ## What it is, and what it is not
+ *
+ * Skyframe's `AbstractParallelEvaluator` is the prior art for the state
+ * machine (`CHECK_DEPENDENCIES → VERIFIED_CLEAN | NEEDS_REBUILDING →
+ * REBUILDING → DONE`) and `EvaluationProgressReceiver` for the outcome
+ * vocabulary. Two deliberate deviations:
+ *
+ * 1. **No cache-invalidating node visitor.** Content addressing governs
+ *    reuse. Private reverse indexes propagate settled outcomes and readiness,
+ *    never dirty bits. Dispatch-time content measurement still decides
+ *    whether a recorded result can serve the node.
+ * 2. **Completion-driven, without Skyframe restarts.** Skyframe atomically
+ *    signals reverse dependencies when one node settles. Our dependencies are
+ *    declared in the plan before anything runs, so one coordinator can make
+ *    the equivalent decision from the plan, settled state, and scheduling
+ *    permits: every completion is reconciled and immediately opens another
+ *    admission pass. Giving up the wavefront barrier also gives up its
+ *    trivially serialized reconciliation; draining and applying the durable
+ *    deviation journal after each settlement, before reevaluating downstream
+ *    readiness, restores that ordering without holding unrelated ready cones.
+ *    The coordinator is the sole writer of scheduling state, which keeps every
+ *    admission decision deterministic without the `DeterministicHelper` the
+ *    vault rejected.
+ *
+ * ## The three limits
+ *
+ * The same number must never
+ * stand in for graph width, scheduler admission, and provider capacity. This
+ * module owns the middle one only: `concurrency.steps` is the leaf-execution
+ * cap, and `concurrency.agents` is the subset cap an agent node consumes in
+ * addition. Structural width is whatever the plan says; seats belong to
+ * `Agent Adapters` and are not modelled here.
+ *
+ * Under contention, ready work is ordered by effective priority — declared
+ * `priority` plus one point per capacity-constrained admission pass. A ready
+ * node gains a point exactly when a pass considers it but cannot give it the
+ * required permits. Aging is what lets priority change latency without
+ * permitting starvation; equal effective priorities preserve deterministic
+ * plan order.
+ *
+ * ## Observing the world exactly once
+ *
+ * The torn-run rule: never re-observe the
+ * world mid-run. Reads with no preceding writer are **source** inputs; their
+ * digests and glob membership are durably recorded before dispatch and restored
+ * on reopening. Preceding producers' outputs are measured after settlement —
+ * observing our own output, not the world. Later and self-writes are not source
+ * producers. New generations retain prior pins and record new observations.
+ *
+ * @since 0.1.0
+ */
+import { Sha256 } from "@smthrs/crypto";
+import { FlowEngine } from "@smthrs/engine";
+import { Journal } from "@smthrs/journal";
+import { Plan, Scheduling, StepKey } from "@smthrs/plan";
+import { PlanStore } from "@smthrs/plan-store";
+import * as FileSet from "@smthrs/plan/FileSet";
+import { AttemptStore } from "@smthrs/run-store";
+import * as Cause from "effect/Cause";
+import * as Clock from "effect/Clock";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Metric from "effect/Metric";
+import * as Option from "effect/Option";
+import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as EngineStoreMetrics from "./EngineStoreMetrics.js";
+import * as ActionPersistence from "./internal/ActionPersistence.js";
+import * as AttemptAdmission from "./internal/AttemptAdmission.js";
+import * as CacheAgeVerdicts from "./internal/CacheAgeVerdicts.js";
+import * as FileEnumeration from "./internal/FileEnumeration.js";
+import * as JournalRecords from "./internal/JournalRecords.js";
+import { compareText } from "./internal/Ordering.js";
+import * as PlanInputs from "./internal/PlanInputs.js";
+import * as PlanMerges from "./internal/PlanMerges.js";
+import * as RuntimeGraph from "./internal/RuntimeGraph.js";
+import * as PlanInputStore from "./PlanInputStore.js";
+import * as PlanMergeStore from "./PlanMergeStore.js";
+import * as Reconciliation from "./Reconciliation.js";
+import * as ReplayOnly from "./ReplayOnly.js";
+import * as Selection from "./Selection.js";
+import * as StepBoundary from "./StepBoundary.js";
+import * as WorkspaceSandbox from "./WorkspaceSandbox.js";
+/**
+ * Service tag for the node executor.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export class NodeExecutor extends Context.Service()("@smthrs/engine-store/NodeExecutor") {
+}
+/**
+ * Provides a plain {@link Executor} value as the {@link NodeExecutor} service.
+ *
+ * This is the whole wiring story for the scheduler's one open seam: a flow
+ * runtime, a test double, or a remote dispatcher each become a layer by
+ * passing themselves here.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layerExecutor = (executor) => Layer.succeed(NodeExecutor, executor);
+/**
+ * A refusal the scheduler itself raises. A node's own failure is an outcome,
+ * not one of these — the run continues and the report says `failed`.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export class SchedulerError extends Schema.TaggedError()("@smthrs/engine-store/SchedulerError", {
+    code: Schema.Literals([
+        "invalid_plan",
+        "boundary_unavailable",
+        "key_uncomputable",
+        "elaboration_failed",
+        "store_failed"
+    ]),
+    message: Schema.String,
+    cause: Schema.optional(Schema.Unknown),
+    /** Failures while settling siblings after the primary scheduler failure. */
+    cleanupErrors: Schema.optional(Schema.Array(Schema.Unknown))
+}) {
+}
+/**
+ * Service tag for the plan scheduler.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export class PlanScheduler extends Context.Service()("@smthrs/engine-store/PlanScheduler") {
+}
+/**
+ * The declared digest handed to `StepBoundary.prepare` when the scheduler is
+ * *asking* what a path holds rather than asserting it. Prepare measures every
+ * declared read regardless of what the declaration claims, so any placeholder
+ * works; a self-describing one can never be mistaken for a real digest.
+ *
+ * @private
+ */
+/**
+ * The tag a plan node dispatches, when its material names one.
+ *
+ * A material body is opaque to the compiler by design, so this reads it
+ * defensively and answers nothing rather than guessing: a merge node, a body
+ * an elaborator shaped differently, and a node whose tag is not a string all
+ * carry no tag at all. @private
+ */
+const actionOf = (node) => {
+    const body = node.material.body;
+    if (typeof body !== "object" || body === null)
+        return undefined;
+    const fields = body;
+    const named = typeof fields["action"] === "string" ? fields["action"] : fields["flow"];
+    return typeof named === "string" && named !== "" ? named : undefined;
+};
+/**
+ * One node of a plan, as a journal record carries it.
+ *
+ * The same shape the interpreter writes, so a reader folds both executors
+ * with one decoder. `effects` and `key` are the plan's own; there is no
+ * declaration site here, because a plan node is compiled from a draft and the
+ * draft's author frame is not something the compiler keeps. @private
+ */
+const nodeSummary = (node) => {
+    const action = actionOf(node);
+    return {
+        id: node.id,
+        kind: node.kind,
+        dependsOn: node.dependsOn,
+        tier: node.material.kind,
+        key: node.key,
+        generation: node.generation,
+        ...(action === undefined ? {} : { action })
+    };
+};
+const unmeasured = "unmeasured";
+/** @private */
+const isConflict = (cause) => cause.reasons.some((reason) => Cause.isFailReason(reason) && WorkspaceSandbox.isMaterializationConflict(reason.error));
+/** @private */
+const DeviationPayload = Schema.Struct({
+    stepKeyDigest: Schema.NonEmptyString,
+    attempt: Schema.Int,
+    paths: Schema.Array(Schema.String),
+    diffIdentity: Schema.String
+});
+const decodeDeviation = Schema.decodeUnknownOption(DeviationPayload);
+const digestOf = Schema.decodeUnknownEffect(Sha256);
+const storeFailure = (message) => (cause) => new SchedulerError({ code: "store_failed", message, cause });
+const nonNegativeSafeInteger = (name, value) => {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${name} must be a non-negative safe integer`);
+    }
+    return value;
+};
+/**
+ * Constructs a scheduler bound to one run.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const make = (options) => {
+    const admission = AttemptAdmission.makeUnsafe();
+    const cacheAgeVerdict = CacheAgeVerdicts.make(options.runId);
+    const rebaseLimit = nonNegativeSafeInteger("rebaseLimit", options.rebaseLimit ?? 3);
+    const scheduling = Scheduling.make(options.concurrency);
+    // Capture before the first async boundary. Callers can retain and mutate
+    // their options, but cannot change this scheduler's identity after admission.
+    const capturedEnvironment = Result.try(() => Schema.decodeUnknownSync(Schema.UndefinedOr(StepKey.EnvironmentIdentity))(options.environment, { onExcessProperty: "error" }));
+    // Every scheduler record addresses the run's root lineage, so a frame can
+    // reach it (`apps/site/src/content/docs/docs/concepts/time-travel.mdx`).
+    const lineageId = FlowEngine.Lineage.root(options.runId);
+    const source = (suffix) => ({ runId: options.runId, sourceId: `${options.sourceId}/${suffix}`, lineageId });
+    /**
+     * Scheduler records take the journal's durable, owner-fenced channel: a plan
+     * digest binds an approval, so it may never ride the lossy queue. A zombie
+     * that lost the run self-interrupts on `fence_lost`, exactly as
+     * `internal/ActionPersistence` does — a scheduler that kept dispatching
+     * after losing ownership is the failure mode fencing exists to prevent.
+     */
+    const emit = (record) => Effect.flatMap(Journal.Journal, (journal) => journal.emitDurable(record, options.owner)).pipe(Effect.catch((error) => error.code === "fence_lost"
+        ? Effect.interrupt
+        : Effect.fail(storeFailure("the scheduler could not journal a record")(error))));
+    const atomically = (message, effect) => Effect.flatMap(Journal.Journal, (journal) => journal.transact(effect)).pipe(Effect.mapError((error) => error instanceof SchedulerError ? error : storeFailure(message)(error)));
+    const verifyPlan = (candidate) => Plan.verify(candidate).pipe(Effect.mapError((cause) => new SchedulerError({ code: "invalid_plan", message: "the scheduler requires a verified plan", cause })));
+    const record = Effect.fn("PlanScheduler.record")((candidate) => Effect.gen(function* () {
+        const plan = yield* verifyPlan(candidate);
+        yield* Effect.annotateCurrentSpan({
+            runId: options.runId,
+            planId: plan.planId,
+            digest: plan.digest,
+            generation: plan.generation
+        });
+        const store = yield* PlanStore.PlanStore;
+        const now = yield* Clock.currentTimeMillis.pipe(Effect.map(Math.floor));
+        const outcome = yield* atomically("could not atomically record the plan", Effect.gen(function* () {
+            const recorded = yield* store.record(plan, now).pipe(Effect.mapError(storeFailure("could not record the plan")));
+            yield* emit(JournalRecords.planRecorded(source(`plan/${plan.planId}`), {
+                planId: plan.planId,
+                flow: plan.flow,
+                digest: plan.digest,
+                baseDigest: plan.baseDigest,
+                generation: plan.generation,
+                nodes: plan.nodes.length,
+                outcome: recorded._tag,
+                // The graph itself, beside the count it has always carried. A
+                // reader that only knows how MANY nodes ran cannot show which
+                // ones, and the count stays because the CLI's run progress reads
+                // it as a number.
+                graph: { nodes: plan.nodes.map(nodeSummary) }
+            }));
+            return recorded;
+        }));
+        yield* Effect.annotateCurrentSpan({ outcome: outcome._tag });
+        return outcome;
+    }));
+    const append = Effect.fn("PlanScheduler.append")((candidate) => Effect.gen(function* () {
+        const plan = yield* verifyPlan(candidate);
+        yield* Effect.annotateCurrentSpan({
+            runId: options.runId,
+            planId: plan.planId,
+            digest: plan.digest,
+            generation: plan.generation
+        });
+        const store = yield* PlanStore.PlanStore;
+        yield* atomically("could not atomically append the subgraph", Effect.gen(function* () {
+            yield* store.append(plan).pipe(Effect.mapError(storeFailure("could not append the subgraph")));
+            yield* emit(JournalRecords.subgraphAppended(source(`plan/${plan.planId}/${plan.generation}`), {
+                planId: plan.planId,
+                digest: plan.digest,
+                baseDigest: plan.baseDigest,
+                generation: plan.generation,
+                nodeIds: Plan.generationNodes(plan).map((node) => node.id),
+                graph: { nodes: Plan.generationNodes(plan).map(nodeSummary) }
+            }));
+        }));
+        yield* Effect.annotateCurrentSpan({ outcome: "appended" });
+    }));
+    const run = Effect.fn("PlanScheduler.run")((candidate) => Effect.gen(function* () {
+        if (Result.isFailure(capturedEnvironment)) {
+            return yield* Effect.fail(new SchedulerError({
+                code: "key_uncomputable",
+                message: "the scheduler requires a valid execution environment identity"
+            }));
+        }
+        const environment = capturedEnvironment.success;
+        const environmentDigest = yield* StepKey.environmentIdentity(environment).pipe(Effect.mapError((cause) => new SchedulerError({ code: "key_uncomputable", message: "could not bind the execution environment", cause })));
+        const initial = yield* verifyPlan(candidate);
+        yield* Effect.annotateCurrentSpan({
+            runId: options.runId,
+            planId: initial.planId,
+            digest: initial.digest,
+            nodes: initial.nodes.length
+        });
+        const boundaries = yield* StepBoundary.StepBoundary;
+        const fileSystem = yield* Effect.serviceOption(FileSystem.FileSystem);
+        const executor = yield* NodeExecutor;
+        const journal = yield* Journal.Journal;
+        const inputStore = yield* PlanInputStore.PlanInputStore;
+        const mergeStore = yield* PlanMergeStore.PlanMergeStore;
+        const mergeIdentity = {
+            runId: options.runId,
+            planId: initial.planId,
+            baseDigest: initial.baseDigest,
+            environmentDigest
+        };
+        const mergeFailure = (cause) => cause.code === "fence_lost"
+            ? Effect.interrupt :
+            Effect.fail(storeFailure("could not recover or persist the plan's merge decisions")(cause));
+        const recoveredMerges = yield* mergeStore.list(mergeIdentity, options.owner).pipe(Effect.catch(mergeFailure));
+        const reconciler = Option.getOrElse(yield* Effect.serviceOption(Reconciliation.Reconciliation), Reconciliation.makeDefault);
+        const selector = Option.getOrElse(yield* Effect.serviceOption(Selection.Selection), Selection.makeNoop);
+        // A verifier composes the scheduler replay-only, as it does the engine:
+        // a recorded node replays and a node that would run its body stops.
+        const replayOnly = Option.getOrUndefined(yield* Effect.serviceOption(ReplayOnly.ReplayOnly));
+        yield* Effect.logDebug("scheduler run started", {
+            digest: initial.digest,
+            nodes: initial.nodes.length
+        });
+        // Only a coordinator failure makes interrupted siblings terminal here.
+        // Parking, external cancellation and fence loss retain their established
+        // recovery semantics. The flag is set before the child scope closes.
+        let abortedForFailure = false;
+        const cleanupErrors = [];
+        let plan = yield* PlanMerges.recover(initial, recoveredMerges).pipe(Effect.catch(mergeFailure));
+        const graph = RuntimeGraph.make(plan.nodes);
+        const states = graph.states;
+        const results = new Map();
+        const digestMemo = StepKey.makeDigestMemo();
+        const verdicts = [];
+        const appended = [];
+        const digestToNode = new Map();
+        const deviationSignatures = new Map();
+        const writers = new Map();
+        const writerEntries = [];
+        const nodesById = new Map();
+        let cursor = undefined;
+        const events = yield* Queue.unbounded();
+        const stateOf = (node) => states.get(node.id);
+        /**
+         * Reconciliation's first declared owner of each path. Read version
+         * selection is different: only a reader's predecessors produce its
+         * inputs, never the reader itself or an explicitly later writer.
+         */
+        const indexWriters = (nodes) => {
+            for (const node of nodes) {
+                nodesById.set(node.id, node);
+                for (const entry of [...FileSet.expand(node.effects.writes), ...node.effects.removes ?? []]) {
+                    writerEntries.push({ entry, nodeId: node.id });
+                    if (typeof entry === "string" && !writers.has(entry)) {
+                        writers.set(entry, node.id);
+                    }
+                }
+            }
+        };
+        indexWriters(plan.nodes);
+        const writerFor = (path) => writers.get(path) ?? writerEntries.find(({ entry }) => FileSet.overlaps(entry, path))?.nodeId;
+        // One bounded traversal per observation/dispatch, not an eager matrix
+        // of every node's transitive ancestors. Shared ancestors are visited
+        // once, and the temporary set is released after this reader's work.
+        const writerScopesBefore = (node) => {
+            const scopes = [];
+            graph.visitAncestors(node, (predecessor) => {
+                scopes.push(...FileSet.expand(predecessor.effects.writes), ...predecessor.effects.removes ?? []);
+            });
+            return scopes;
+        };
+        const expandReads = (entries, what) => Effect.gen(function* () {
+            const expanded = [];
+            for (const entry of entries) {
+                if (typeof entry === "string") {
+                    expanded.push({ entry, paths: [entry] });
+                    continue;
+                }
+                if (Option.isNone(fileSystem)) {
+                    return yield* Effect.fail(new SchedulerError({
+                        code: "boundary_unavailable",
+                        message: `the host cannot expand ${what} without a FileSystem`
+                    }));
+                }
+                // Through `FileEnumeration`, never the host `glob`: host results
+                // are absolute under the kernel FileSystem and skip dotfiles, so
+                // a workspace-relative pattern silently expanded to nothing.
+                const matches = yield* FileEnumeration.expandGlob(fileSystem.value, entry).pipe(Effect.mapError((cause) => new SchedulerError({
+                    code: "boundary_unavailable",
+                    message: `the host could not expand ${what}`,
+                    cause
+                })));
+                expanded.push({ entry, paths: matches });
+            }
+            return expanded;
+        });
+        const prepare = (paths, what) => boundaries.prepare({
+            readSet: [...new Set(paths)].sort().map((path) => ({ path, digest: unmeasured })),
+            writeSet: [],
+            boundaryMode: "hard"
+        }).pipe(Effect.mapError((cause) => new SchedulerError({
+            code: "boundary_unavailable",
+            message: `the host could not measure ${what}`,
+            cause
+        })));
+        const expandProducedMatches = (glob, writerScopes, what) => Effect.gen(function* () {
+            const scopes = writerScopes.filter((entry) => FileSet.overlaps(glob, entry));
+            if (scopes.length === 0)
+                return [];
+            if (Option.isNone(fileSystem)) {
+                return yield* Effect.fail(new SchedulerError({
+                    code: "boundary_unavailable",
+                    message: `the host cannot expand ${what} without a FileSystem`
+                }));
+            }
+            const paths = new Set();
+            for (const entry of scopes) {
+                if (typeof entry === "string") {
+                    // One host call: `stat` reports both whether the producer's
+                    // output is there yet and what kind of thing it is, so the
+                    // `exists` probe that used to precede it only doubled the cost.
+                    // On the confined host each call is one CPython fork
+                    // (`@smthrs/platform-node/AtomicFileSystem`).
+                    const info = yield* fileSystem.value.stat(entry).pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.succeed(undefined)), Effect.mapError((cause) => new SchedulerError({
+                        code: "boundary_unavailable",
+                        message: `the host could not expand ${what}`,
+                        cause
+                    })));
+                    // Exact writer declarations name files; directory outputs use
+                    // `TreeArtifact`, and only files are members of a read glob. A
+                    // producer that has not written yet is simply not a candidate.
+                    if (info?.type === "File")
+                        paths.add(entry);
+                    continue;
+                }
+                const matches = FileSet.isGlob(entry)
+                    ? yield* FileEnumeration.expandGlob(fileSystem.value, entry).pipe(Effect.mapError((cause) => new SchedulerError({
+                        code: "boundary_unavailable",
+                        message: `the host could not expand ${what}`,
+                        cause
+                    })))
+                    : yield* FileEnumeration.filesUnder(fileSystem.value, entry.path).pipe(Effect.mapError((cause) => new SchedulerError({
+                        code: "boundary_unavailable",
+                        message: `the host could not expand ${what}`,
+                        cause
+                    })));
+                for (const path of matches) {
+                    if (FileSet.matchesGlob(glob, path))
+                        paths.add(path);
+                }
+            }
+            return [...paths].sort();
+        });
+        // A read declaration is observed only when its node enters this run:
+        // generation zero here, or one newly appended generation below. Paths
+        // already pinned by an earlier declaration reuse that digest; measuring
+        // them again would tear the run. A new source path is measured now,
+        // which is its first observation in this run.
+        const pinned = new Map();
+        const observedReads = new Map();
+        const inputFailure = (cause) => cause.code === "fence_lost"
+            ? Effect.interrupt
+            : Effect.fail(storeFailure("could not recover or persist the plan's source observations")(cause));
+        const observeReads = (nodes, generation, what, commit) => Effect.gen(function* () {
+            const address = {
+                runId: options.runId,
+                planId: initial.planId,
+                baseDigest: initial.baseDigest,
+                environmentDigest,
+                generation
+            };
+            const stored = yield* inputStore.get(address, options.owner).pipe(Effect.catch(inputFailure));
+            let snapshot;
+            if (Option.isSome(stored)) {
+                snapshot = stored.value;
+            }
+            else {
+                const unpinned = new Set();
+                const observedNodes = [];
+                for (const node of nodes) {
+                    const observed = [];
+                    const reads = FileSet.expandReads(node.effects.reads);
+                    const writerScopes = reads.length === 0 ? [] : writerScopesBefore(node);
+                    for (const { entry, paths } of yield* expandReads(reads, what)) {
+                        const sourcePaths = paths.filter((path) => !writerScopes.some((scope) => FileSet.overlaps(scope, path)));
+                        for (const path of sourcePaths) {
+                            if (!pinned.has(path))
+                                unpinned.add(path);
+                        }
+                        observed.push({ entry, sourcePaths });
+                    }
+                    observedNodes.push({ id: node.id, key: node.key, reads: observed });
+                }
+                const pins = unpinned.size === 0 ? [] : (yield* prepare([...unpinned], what)).readSnapshot;
+                const measured = {
+                    version: 1,
+                    generation,
+                    nodes: observedNodes,
+                    pins
+                };
+                yield* PlanInputs.validate(measured, nodes, pinned, writerScopesBefore).pipe(Effect.catch(inputFailure));
+                snapshot = commit === undefined
+                    ? yield* inputStore.record(address, measured, options.owner).pipe(Effect.catch(inputFailure))
+                    : measured;
+            }
+            if (commit !== undefined)
+                snapshot = yield* commit(snapshot);
+            // Do not publish speculative measurements. A competing observation
+            // wins durably, and every recovered declaration must still describe
+            // this verified plan before it can influence an execution key.
+            const nextPins = yield* PlanInputs.validate(snapshot, nodes, pinned, writerScopesBefore).pipe(Effect.catch(inputFailure));
+            for (const node of snapshot.nodes)
+                observedReads.set(node.id, node.reads);
+            for (const [path, digest] of nextPins)
+                pinned.set(path, digest);
+        });
+        // Recover each generation before any dispatch. Existing observations
+        // never enumerate or measure the host again, even after process restart.
+        for (let generation = 0; generation <= plan.generation; generation++) {
+            yield* observeReads(plan.nodes.filter((node) => node.generation === generation), generation, "the plan's source inputs");
+        }
+        // A merge intent is authoritative scheduler state, not a failed-action
+        // cache entry or a convention inferred from an arbitrary node's body.
+        for (const { intent } of recoveredMerges) {
+            const state = stateOf(nodesById.get(intent.nodeId));
+            graph.stage(intent.nodeId, "skipped");
+            state.dispatchKey = intent.dispatchKey;
+            state.attempts = intent.attempts;
+            state.rebases = intent.rebases;
+        }
+        graph.reconcile();
+        const measure = (node) => Effect.gen(function* () {
+            const measured = new Map();
+            const produced = new Set();
+            const observed = observedReads.get(node.id);
+            const writerScopes = observed.length === 0 ? [] : writerScopesBefore(node);
+            for (const read of observed) {
+                if (typeof read.entry === "string") {
+                    if (read.sourcePaths.length === 0)
+                        produced.add(read.entry);
+                    else
+                        measured.set(read.entry, pinned.get(read.entry));
+                    continue;
+                }
+                for (const path of read.sourcePaths)
+                    measured.set(path, pinned.get(path));
+                // A glob's source membership is frozen above. Dispatch may only
+                // add paths derived from preceding writer scopes. Neither an
+                // unproduced arrival nor a future writer widens the source world.
+                for (const path of yield* expandProducedMatches(read.entry, writerScopes, `the inputs of ${node.id}`)) {
+                    produced.add(path);
+                }
+            }
+            if (produced.size > 0) {
+                // Produced paths are our own outputs, so measuring them once their
+                // producer has settled is not re-observing the world.
+                const prepared = yield* prepare([...produced], `the inputs of ${node.id}`);
+                for (const entry of prepared.readSnapshot)
+                    measured.set(entry.path, entry.digest);
+            }
+            return {
+                readSet: [...measured].sort(([left], [right]) => compareText(left, right)).map(([path, digest]) => ({
+                    path,
+                    digest
+                })),
+                writeSet: FileSet.expand(node.effects.writes),
+                // Declared removals travel with the boundary: they are what makes
+                // an absent declared output legitimate rather than a defect.
+                ...(node.effects.removes === undefined ? {} : { removes: node.effects.removes }),
+                boundaryMode: node.effects.boundaryMode
+            };
+        });
+        /**
+         * Non-sealed work uses a stable run-local structural scope: it replays
+         * durable attempts but never reuses an effect from another invocation.
+         * For sealed work:
+         *
+         * The key a dispatch is recorded under: the node's own declaration
+         * folded with the CONTENT of everything it consumes — the digests the
+         * host just measured for its files, and the digest of each upstream
+         * node's settled output value.
+         *
+         * Not the plan key. That key folds every upstream key transitively, so
+         * an edit anywhere upstream re-ran everything below it even when the
+         * edited node's output value was byte-identical. Bazel's
+         * `ActionCacheChecker` stops invalidation at unchanged content, and
+         * `StepKey.dispatchIdentity` is how this does.
+         *
+         * The plan key alone could never have been it either: two runs whose
+         * input files differ declare the same graph, and serving one the other's
+         * result is exactly the staleness the boundary exists to prevent.
+         */
+        const dispatchKeyFor = (node, boundary, settledResults) => (node.material.kind === "sealed" ?
+            StepKey.dispatchIdentity({
+                material: node.material,
+                results: Object.fromEntries(node.material.inputs.flatMap((input) => input._tag === "Ref" ? [[input.from, settledResults.get(input.from)]] : [])),
+                digestMemo,
+                environment,
+                hermetic: {
+                    ...boundary,
+                    readSet: StepBoundary.exactReads(boundary)
+                }
+            }) :
+            StepKey.ordinal({
+                runId: options.runId,
+                // Stable structural scope, never admission order. The declaration
+                // fingerprint prevents a changed plan from reusing an old attempt.
+                parentScope: JSON.stringify(["plan-node/v1", initial.planId, node.id, node.key]),
+                ordinal: 0,
+                tier: node.material.kind
+            })).pipe(
+        /* v8 ignore next 3 -- verified plans have serializable material, admission resolves every dependency, and successful upstream values already crossed durable serialization; key derivation still exposes its honest failure channel */
+        Effect.mapError((cause) => new SchedulerError({ code: "key_uncomputable", message: `could not key ${node.id}`, cause })));
+        const runtimeStrategyOf = (node) => node.conflicts.some((conflict) => conflict.runtime === "stop-merge") ? "stop-merge" : node.runtime;
+        const markSettled = (node, outcome) => {
+            graph.stage(node.id, outcome);
+        };
+        const emitSettlement = (node, sourceSeq) => Effect.gen(function* () {
+            const state = stateOf(node);
+            const action = actionOf(node);
+            yield* emit(JournalRecords.nodeSettled({ ...source(`node/${node.id}/settled`), sourceSeq }, {
+                planId: plan.planId,
+                nodeId: node.id,
+                planKey: node.key,
+                dispatchKey: state.dispatchKey,
+                outcome: state.outcome,
+                attempts: state.attempts,
+                rebases: state.rebases,
+                ...(action === undefined ? {} : { action })
+            }));
+            yield* Metric.update(EngineStoreMetrics.node[state.outcome], 1);
+        });
+        const settle = (node, outcome) => {
+            markSettled(node, outcome);
+            graph.reconcile();
+            return emitSettlement(node);
+        };
+        const applyVerdict = (nodeId, verdict, trigger) => Effect.gen(function* () {
+            verdicts.push({ nodeId, verdict });
+            yield* emit(JournalRecords.nodeReconciled(source(`node/${nodeId}/reconciled/${verdicts.length}`), {
+                planId: plan.planId,
+                nodeId,
+                trigger,
+                verdict
+            }));
+            if (verdict._tag === "Fail") {
+                // The scheduler chooses the node it asks about, so a verdict always
+                // names one it is tracking.
+                graph.stage(nodeId, "failed");
+                results.delete(nodeId);
+                return;
+            }
+            if (verdict._tag === "Reorder") {
+                // Re-plan with the discovered dependency made explicit. It binds
+                // work that has not dispatched yet — the deviating node already
+                // ran, and rewriting history is what append-only forbids.
+                // Persisting the edge is the caller's next elaboration; the
+                // verdict is journaled so it can be.
+                graph.reorder(nodeId, verdict.dependsOn);
+            }
+            // `FactorOut` needs no graph surgery: two identical extracted steps
+            // collapse to one key by themselves, so the second is a `clean`.
+        });
+        const dispatch = Effect.fn("PlanScheduler.dispatch")(function* (node, start) {
+            return yield* Effect.gen(function* () {
+                yield* Effect.annotateCurrentSpan({
+                    runId: options.runId,
+                    planId: plan.planId,
+                    nodeId: node.id,
+                    kind: node.kind,
+                    planKey: node.key
+                });
+                // Attempt bookkeeping is local to this fiber. The coordinator owns
+                // the durable scheduler state and applies this progress only when it
+                // processes the terminal event.
+                let dispatchKey = start.dispatchKey;
+                let attempts = start.attempts;
+                let rebases = start.rebases;
+                while (true) {
+                    const boundary = yield* measure(node);
+                    const measuredKey = yield* dispatchKeyFor(node, boundary, start.results);
+                    if (dispatchKey !== "" && dispatchKey !== measuredKey) {
+                        yield* emit(JournalRecords.nodeInvalidated(source(`node/${node.id}/${attempts}/invalidated`), {
+                            planId: plan.planId,
+                            nodeId: node.id,
+                            planKey: node.key,
+                            from: dispatchKey,
+                            to: measuredKey,
+                            reason: "measured-inputs-changed"
+                        }));
+                    }
+                    dispatchKey = measuredKey;
+                    attempts = attempts + 1;
+                    yield* Effect.annotateCurrentSpan({ dispatchKey, attempt: attempts });
+                    const action = actionOf(node);
+                    yield* emit(JournalRecords.nodeScheduled(source(`node/${node.id}/${attempts}`), {
+                        planId: plan.planId,
+                        nodeId: node.id,
+                        kind: node.kind,
+                        planKey: node.key,
+                        dispatchKey,
+                        attempt: attempts,
+                        priority: node.priority,
+                        waited: start.waited,
+                        ...(action === undefined ? {} : { action })
+                    }));
+                    const dispatchDigest = yield* Effect.orDie(digestOf(dispatchKey));
+                    yield* Queue.offer(events, { _tag: "AttemptKeyed", nodeId: node.id, digest: dispatchDigest });
+                    const ran = yield* Ref.make(false);
+                    const exit = yield* ActionPersistence.make({
+                        runId: options.runId,
+                        owner: options.owner,
+                        admission,
+                        cacheAgeVerdict,
+                        replayOnly,
+                        sourceId: `${options.sourceId}/node/${node.id}`,
+                        execute: () => Ref.set(ran, true).pipe(Effect.andThen(executor.execute({ node, attempt: attempts, boundary, inputs: start.inputs })))
+                    })({
+                        action: {},
+                        attempt: attempts,
+                        key: dispatchKey,
+                        tier: node.material.kind,
+                        nondeterministic: node.material.nondeterministic,
+                        metadata: boundary
+                    }).pipe(Effect.onInterrupt(() => abortedForFailure
+                        ? atomically("could not settle a sibling aborted by scheduler failure", Effect.gen(function* () {
+                            const store = yield* AttemptStore.AttemptStore;
+                            const finishedAtMs = yield* Clock.currentTimeMillis.pipe(Effect.map(Math.floor));
+                            const identity = { runId: options.runId, stepKeyDigest: dispatchDigest, attempt: attempts };
+                            const finished = yield* store.finish({
+                                ...identity,
+                                state: "failed",
+                                finishedAtMs,
+                                error: { code: "scheduler_aborted", message: "A scheduler failure interrupted this attempt" }
+                            }, options.owner);
+                            // A terminal attempt or a replacement owner already decides
+                            // the row. Never overwrite it or emit a contradictory fact.
+                            if (finished._tag === "Finished") {
+                                yield* emit(JournalRecords.attemptFinished(source(`node/${node.id}/${attempts}/aborted`), {
+                                    ...identity,
+                                    state: "failed",
+                                    reason: "scheduler_aborted"
+                                }));
+                            }
+                        })).pipe(Effect.catch((cause) => Effect.sync(() => {
+                            cleanupErrors.push(cause);
+                        })))
+                        : Effect.void), Effect.exit);
+                    if (Exit.isSuccess(exit)) {
+                        return {
+                            outcome: (yield* Ref.get(ran)) ? "built" : "clean",
+                            result: exit.value,
+                            dispatchKey,
+                            attempts,
+                            rebases
+                        };
+                    }
+                    // Losing a fence self-interrupts `ActionPersistence`. An
+                    // interrupted dispatch is the run losing ownership, never a node
+                    // failure that the scheduler may report and continue past.
+                    if (Cause.hasInterrupts(exit.cause))
+                        return yield* Effect.interrupt;
+                    // The generic executor supplies no irreversible idempotency or
+                    // reconciliation contract. A conflict is not proof the effect
+                    // never happened; neither a retry nor a freshly keyed merge may
+                    // blindly execute more work after that uncertain result.
+                    if (!isConflict(exit.cause) || node.material.kind === "irreversible") {
+                        return { outcome: "failed", dispatchKey, attempts, rebases };
+                    }
+                    const strategy = runtimeStrategyOf(node);
+                    if (strategy === "delay-rebase" && rebases < rebaseLimit) {
+                        // Hold the dependents — they are not ready while this node is in
+                        // flight — and re-execute against the newly recorded base. The
+                        // next turn of the loop re-measures, which re-keys, which is a
+                        // new attempt rather than a retry of the old identity.
+                        rebases = rebases + 1;
+                        continue;
+                    }
+                    return { outcome: "conflicted", strategy, dispatchKey, attempts, rebases };
+                }
+            }).pipe(Effect.tap((result) => Effect.annotateCurrentSpan({ outcome: result.outcome })));
+        });
+        /**
+         * `stop-merge`: the losing action is stopped and both lanes are routed
+         * through an explicit merge node appended to the SAME plan, as an
+         * ordinary elaboration. The merge critical section uses this module's
+         * restart-or-fail landing contract, so the merge node carries no rebase
+         * budget of its own: it lands, or the run has a failed node. There is no
+         * worktree-lane surface; that design was removed.
+         */
+        const appendMerge = (intent) => Effect.gen(function* () {
+            const node = yield* PlanMerges.validateIntent(plan, intent).pipe(Effect.catch(mergeFailure));
+            const winners = intent.peers.filter((id) => results.has(id));
+            const mergeId = PlanMerges.allocateId(plan, node.id);
+            const parentDigest = plan.digest;
+            const grown = yield* Plan.append(plan, [PlanMerges.draft(node, mergeId, winners)]).pipe(Effect.mapError((cause) => new SchedulerError({
+                code: "elaboration_failed",
+                message: `could not append the merge node for ${node.id}`,
+                cause
+            })));
+            // `appendMerge` copies the stopped node's effects byte-for-byte, so
+            // re-indexing adds no new writer coverage and cannot turn an
+            // already-pinned source path into a producer. The new generation's
+            // read declarations have not themselves been observed, however:
+            // expand them once now and pin only source paths this run has never
+            // measured. Existing pins are always reused.
+            yield* observeReads(Plan.generationNodes(grown), grown.generation, `generation ${grown.generation}'s source inputs`, (snapshot) => atomically("could not atomically commit the merge extension", Effect.gen(function* () {
+                const recorded = yield* inputStore.record({ ...mergeIdentity, generation: grown.generation }, snapshot, options.owner)
+                    .pipe(Effect.catch(inputFailure));
+                yield* append(grown);
+                yield* mergeStore.complete(mergeIdentity, intent.nodeId, {
+                    version: 1,
+                    generation: grown.generation,
+                    parentDigest,
+                    planDigest: grown.digest,
+                    mergeId,
+                    mergeKey: Plan.generationNodes(grown)[0].key,
+                    winners
+                }, options.owner).pipe(Effect.catch(mergeFailure));
+                return recorded;
+            })));
+            // No asynchronous boundary may expose only part of this admission.
+            // Frozen generations preserve the indexed prefix and its state.
+            const suffix = Plan.generationNodes(grown);
+            graph.append(suffix);
+            plan = grown;
+            indexWriters(suffix);
+            appended.push(mergeId);
+        });
+        const pendingSettlements = [];
+        const registerAttempt = (event) => {
+            const dispatchedUnder = digestToNode.get(event.digest);
+            if (dispatchedUnder === undefined) {
+                digestToNode.set(event.digest, [event.nodeId]);
+            }
+            else if (!dispatchedUnder.includes(event.nodeId)) {
+                digestToNode.set(event.digest, [...dispatchedUnder, event.nodeId]);
+            }
+        };
+        /**
+         * Absorbs every report already offered without processing another node's
+         * settlement. Attempt-key reports update attribution state immediately;
+         * terminal reports stay ordered in `pendingSettlements` for the one-at-a-
+         * time coordinator. A deviation can appear in a journal page only after
+         * its attempt-key report was offered, so calling this after each page
+         * closes the journal/queue observation race without a shared mutable map.
+         */
+        const drainReportedEvents = Effect.gen(function* () {
+            while (true) {
+                const next = yield* Queue.poll(events);
+                if (Option.isNone(next))
+                    return;
+                if (next.value._tag === "AttemptKeyed")
+                    registerAttempt(next.value);
+                else
+                    pendingSettlements.push(next.value);
+            }
+        });
+        const nextSettlement = Effect.gen(function* () {
+            const pending = pendingSettlements.shift();
+            if (pending !== undefined)
+                return pending;
+            while (true) {
+                const event = yield* Queue.take(events);
+                if (event._tag === "DispatchSettled")
+                    return event;
+                registerAttempt(event);
+            }
+        });
+        /**
+         * The first consumer `flows.engine.expected-set-deviation` has ever had.
+         * The events are read from the journal rather than from the attempt row
+         * on purpose: a deviation is a durable, replayable fact, and consuming
+         * the fact keeps this seam usable by anything else that reads the
+         * journal.
+         *
+         * Two properties the drain owes the reconciler, both of them about not
+         * letting arrival order decide a verdict:
+         *
+         * 1. **Attribute the whole page before judging any of it.** Deviating on
+         *    the same paths is a *symmetric* fact — two steps that both ran
+         *    `npm install` — so registering each signature as the entry was
+         *    judged answered the same situation two different ways: the first
+         *    node saw no peer and was failed, and only the second was factored
+         *    out. Every deviation on the page is attributed first, so both sides
+         *    of a pair see each other.
+         * 2. **Drain the journal, not one page of it.** Concurrent dispatches can
+         *    journal more records than one page holds, and the final completion
+         *    is the one that matters: nothing follows it to pick up what a single
+         *    page left behind, so a deviation past the cursor would never reach
+         *    the seam.
+         */
+        const pendingDeviations = [];
+        const drainDeviations = Effect.gen(function* () {
+            let hasMore = true;
+            while (hasMore) {
+                const page = yield* journal.entries({
+                    runId: options.runId,
+                    ...(cursor === undefined ? {} : { after: cursor }),
+                    limit: 512
+                }).pipe(Effect.mapError(storeFailure("could not read the run's journal")));
+                // Every deviation in this page causally follows its attempt-key
+                // report. Absorb those reports now, after the journal read, so even
+                // an in-flight sibling can be attributed without dispatch fibers
+                // mutating coordinator state.
+                yield* drainReportedEvents;
+                const attributed = [];
+                for (const entry of page.entries) {
+                    cursor = entry.seq;
+                    if (entry.eventType !== "flows.engine.expected-set-deviation")
+                        continue;
+                    const payload = decodeDeviation(entry.payload);
+                    if (Option.isNone(payload))
+                        continue;
+                    const nodeIds = digestToNode.get(payload.value.stepKeyDigest);
+                    if (nodeIds === undefined)
+                        continue;
+                    // The attempt belongs to an executing node by construction. If
+                    // its built settlement is absent from current bookkeeping — the
+                    // record arrived first, or is being durably replayed into an
+                    // all-clean invocation — preserve first dispatch order.
+                    const nodeId = nodeIds.find((candidate) => states.get(candidate).outcome === "built") ?? nodeIds[0];
+                    const signature = JSON.stringify([
+                        "expected-set-deviation/v1",
+                        [...new Set(payload.value.paths)].sort(compareText)
+                    ]);
+                    deviationSignatures.set(nodeId, signature);
+                    attributed.push({ nodeId, signature, payload: payload.value });
+                }
+                pendingDeviations.push(...attributed);
+                for (let index = 0; index < pendingDeviations.length;) {
+                    const { nodeId, payload, signature } = pendingDeviations[index];
+                    // A concurrent dispatch can durably journal its deviation before
+                    // its terminal event reaches the head of the coordinator queue.
+                    // Its signature participates in symmetric attribution now, but
+                    // its verdict waits until that node's settlement is processed.
+                    if (states.get(nodeId)?.status !== "settled") {
+                        index = index + 1;
+                        continue;
+                    }
+                    const alsoDeviatedBy = [...deviationSignatures.entries()]
+                        .filter(([other, otherSignature]) => other !== nodeId && otherSignature === signature)
+                        .map(([other]) => other);
+                    // Null prototype: a reconciler's lookup of a path named `toString` must miss.
+                    const declaredBy = Object.assign(Object.create(null), Object.fromEntries(payload.paths.flatMap((path) => {
+                        const owner = writerFor(path);
+                        return owner === undefined ? [] : [[path, owner]];
+                    })));
+                    const verdict = yield* reconciler.onDeviation({
+                        nodeId,
+                        keyDigest: payload.stepKeyDigest,
+                        attempt: payload.attempt,
+                        paths: payload.paths,
+                        diffIdentity: payload.diffIdentity,
+                        declaredBy,
+                        alsoDeviatedBy
+                    });
+                    yield* applyVerdict(nodeId, verdict, "deviation");
+                    pendingDeviations.splice(index, 1);
+                }
+                hasMore = page.hasMore;
+            }
+        });
+        /**
+         * The selection consult, once per run, against the initial plan and the
+         * pinned belief snapshot (`docs/guides/defer-work-with-selection.md`). Only sinks,
+         * nodes nothing in the plan depends on,
+         * are offered, because deferring a node something consumes would block
+         * or corrupt its consumers. A verdict may postpone or propose, never
+         * remove: `Admit` is a no-op, a `Defer` marks the sink for the loop
+         * below, a `Propose` is journaled and nothing more (v1 never
+         * auto-appends), and a Defer naming a non-sink — or a Propose naming
+         * anything the plan already accounts for, its flow included — is
+         * ignored and journaled as an inconsistency observation, against the
+         * same `present` set the layer was shown. The `full` override skips
+         * the consult entirely: nothing is deferred and nothing is proposed
+         * under it, and the override record is what makes that visible.
+         * Elaboration cannot
+         * invalidate the marks: an appended merge node depends only on nodes
+         * that produced results, and a deferred node never executes, so a
+         * deferred sink can never gain a dependent mid-run.
+         */
+        const deferrals = new Map();
+        if (options.selection?.full === true) {
+            yield* emit(JournalRecords.selectionOverridden(source("selection/override"), {
+                planId: plan.planId,
+                mode: "full"
+            }));
+        }
+        else {
+            const dependedOn = new Set(plan.nodes.flatMap((node) => node.dependsOn));
+            const sinks = plan.nodes.filter((node) => !dependedOn.has(node.id));
+            const present = new Set([plan.flow, ...plan.nodes.map((node) => node.id)]);
+            const sinkIds = new Set(sinks.map((node) => node.id));
+            const selected = yield* selector.select({
+                changed: options.selection?.changed ?? [],
+                sinks: sinks.map((node) => ({ nodeId: node.id, planKey: node.key })),
+                present: [...present],
+                beliefs: options.selection?.beliefs ?? { pinnedAtMs: 0, edges: [] },
+                policy: options.selection?.policy ?? { deferBelow: 0 }
+            });
+            for (let index = 0; index < selected.length; index++) {
+                const { nodeId, verdict } = selected[index];
+                if (verdict._tag === "Admit")
+                    continue;
+                if (verdict._tag === "Defer" && sinkIds.has(nodeId)) {
+                    deferrals.set(nodeId, { edge: verdict.edge, likelihood: verdict.likelihood });
+                    continue;
+                }
+                if (verdict._tag === "Propose" && !present.has(nodeId)) {
+                    yield* emit(JournalRecords.selectionProposed(source(`selection/proposed/${index}`), {
+                        planId: plan.planId,
+                        flow: verdict.flow,
+                        edge: verdict.edge,
+                        confidence: verdict.confidence
+                    }));
+                    continue;
+                }
+                yield* emit(JournalRecords.selectionInconsistent(source(`selection/inconsistent/${index}`), {
+                    planId: plan.planId,
+                    nodeId,
+                    verdict: verdict._tag,
+                    reason: verdict._tag === "Defer" ? "not-a-deferrable-sink" : "proposes-a-present-node"
+                }));
+            }
+        }
+        const passiveSettlements = Effect.gen(function* () {
+            while (true) {
+                const blocked = graph.blocked();
+                // Halt, not continue-on-failure: a dependent of failed work never
+                // dispatches. Repeating this pass makes the skip cascade settle in
+                // dependency order before any newly exposed work is admitted.
+                for (const node of blocked)
+                    yield* settle(node, "skipped");
+                if (blocked.length > 0)
+                    continue;
+                // A deferral is a postponement, never a removal, and it only takes
+                // effect on work that was genuinely runnable: a marked sink whose
+                // cone failed settled `skipped` above instead, because work that
+                // could not have run is not a debt. The debt record precedes the
+                // settlement so `Selection.debt` reads them in cause-then-effect
+                // order.
+                const ready = graph.ready();
+                const postponed = ready.filter((node) => deferrals.has(node.id));
+                for (const node of postponed) {
+                    const debt = deferrals.get(node.id);
+                    yield* emit(JournalRecords.selectionDeferred(source(`node/${node.id}/selection-deferred`), {
+                        planId: plan.planId,
+                        nodeId: node.id,
+                        planKey: node.key,
+                        edge: debt.edge,
+                        likelihood: debt.likelihood
+                    }));
+                    yield* settle(node, "deferred");
+                }
+                if (postponed.length > 0)
+                    continue;
+                return ready;
+            }
+        });
+        const dispatchStart = (node) => {
+            const state = stateOf(node);
+            const settledResults = new Map();
+            const inputs = [];
+            for (const input of node.material.inputs) {
+                if (input._tag !== "Ref")
+                    continue;
+                const value = results.get(input.from);
+                settledResults.set(input.from, value);
+                // Admission proved every dependency settled successfully; `settle`
+                // records even an `undefined` result in the map, so every material
+                // Ref has a value to project here.
+                inputs.push({ from: input.from, path: input.path, value: StepKey.project(value, input.path) });
+            }
+            return {
+                dispatchKey: state.dispatchKey,
+                attempts: state.attempts,
+                rebases: state.rebases,
+                waited: state.waited,
+                results: settledResults,
+                inputs
+            };
+        };
+        let admissions = 0;
+        yield* Effect.scoped(Effect.gen(function* () {
+            let inFlightSteps = 0;
+            let inFlightAgents = 0;
+            const pendingMerges = recoveredMerges
+                .filter((decision) => decision.completion === undefined).map((decision) => decision.intent);
+            const appendReadyMerges = Effect.gen(function* () {
+                for (let index = 0; index < pendingMerges.length;) {
+                    const pending = pendingMerges[index];
+                    if (pending.peers.some((peer) => states.get(peer)?.status !== "settled")) {
+                        index = index + 1;
+                        continue;
+                    }
+                    yield* appendMerge(pending);
+                    pendingMerges.splice(index, 1);
+                }
+            });
+            // Passive failure/selection propagation can settle the last peer of
+            // a recovered intent without a dispatch event. Recheck merges until
+            // neither propagation nor an append exposes more scheduling work.
+            const advance = Effect.gen(function* () {
+                while (true) {
+                    const ready = yield* passiveSettlements;
+                    const before = plan.generation;
+                    yield* appendReadyMerges;
+                    if (plan.generation === before)
+                        return ready;
+                }
+            });
+            const admit = (ready) => Effect.gen(function* () {
+                const decision = scheduling.admit(graph.candidates(ready), { steps: inFlightSteps, agents: inFlightAgents });
+                const admitted = decision.admitted.map(({ node }) => node);
+                // Event-driven aging: this admission pass considered every ready
+                // node, and only capacity can leave one behind.
+                for (const { node, waited } of decision.deferred) {
+                    stateOf(node).waited = waited;
+                }
+                if (admitted.length > 0) {
+                    admissions = admissions + 1;
+                    yield* Effect.annotateCurrentSpan({ admissions });
+                    yield* Metric.update(EngineStoreMetrics.schedulerAdmissions, 1);
+                    yield* Effect.logDebug("scheduler admission launched", {
+                        admission: admissions,
+                        ready: ready.length,
+                        admitted: admitted.length,
+                        agents: decision.agents,
+                        inFlightSteps,
+                        inFlightAgents
+                    });
+                }
+                const launches = admitted.map((node) => {
+                    const start = dispatchStart(node);
+                    graph.start(node.id);
+                    inFlightSteps = inFlightSteps + 1;
+                    if (node.kind === "agent")
+                        inFlightAgents = inFlightAgents + 1;
+                    return { node, start };
+                });
+                for (const { node, start } of launches) {
+                    yield* dispatch(node, start).pipe(Effect.trackDuration(EngineStoreMetrics.schedulerDispatchDuration), Effect.exit, Effect.flatMap((exit) => Queue.offer(events, { _tag: "DispatchSettled", node, exit })), Effect.asVoid, Effect.forkScoped({ startImmediately: true }));
+                }
+            });
+            // Repair a settlement missing after a crash without appending the
+            // same stopped decision again when its original record survived.
+            for (const { intent } of recoveredMerges)
+                yield* emitSettlement(nodesById.get(intent.nodeId), 0);
+            yield* Effect.flatMap(advance, admit);
+            while (graph.remaining > 0) {
+                // Compiled plans are acyclic, inferred edges refuse cycle closure,
+                // and discovered edges point only from undispatched nodes to the
+                // already-settled node whose verdict added them, so pending work
+                // with nothing in flight cannot have an empty ready set. If an
+                // invariant breaks anyway, fail loudly: returning here would
+                // report unsettled nodes with their initial outcome as success.
+                /* v8 ignore next 7 -- unreachable while the invariants above hold */
+                if (inFlightSteps === 0) {
+                    return yield* Effect.die(new Error(`PlanScheduler invariant broken: ${graph.remaining} nodes are pending and nothing is in flight`));
+                }
+                const event = yield* nextSettlement;
+                if (Exit.isFailure(event.exit))
+                    return yield* Effect.failCause(event.exit.cause);
+                const node = event.node;
+                const result = event.exit.value;
+                const state = stateOf(node);
+                inFlightSteps = inFlightSteps - 1;
+                if (node.kind === "agent")
+                    inFlightAgents = inFlightAgents - 1;
+                state.dispatchKey = result.dispatchKey;
+                state.attempts = result.attempts;
+                state.rebases = result.rebases;
+                switch (result.outcome) {
+                    case "built":
+                    case "clean":
+                        results.set(node.id, result.result);
+                        markSettled(node, result.outcome);
+                        break;
+                    case "failed":
+                        markSettled(node, "failed");
+                        break;
+                    case "conflicted": {
+                        if (result.strategy === "stop-merge") {
+                            const intent = yield* atomically("could not persist the stopped-attempt decision", Effect.gen(function* () {
+                                const intent = yield* mergeStore.intend(mergeIdentity, {
+                                    version: 1,
+                                    nodeId: node.id,
+                                    nodeKey: node.key,
+                                    dispatchKey: state.dispatchKey,
+                                    attempts: state.attempts,
+                                    rebases: state.rebases,
+                                    peers: node.conflicts.map((conflict) => conflict.with)
+                                        .filter((peer) => states.get(peer)?.status === "running" || results.has(peer))
+                                }, options.owner).pipe(Effect.catch(mergeFailure));
+                                yield* PlanMerges.validateIntent(plan, intent).pipe(Effect.catch(mergeFailure));
+                                return intent;
+                            }));
+                            markSettled(node, "skipped");
+                            // The former dispatch barrier guaranteed that every
+                            // conflicting sibling admitted beside this node had reported
+                            // its result before `appendMerge` selected winners. Preserve
+                            // that semantic boundary only for those already-running
+                            // peers; unrelated work never holds the merge cone.
+                            state.dispatchKey = intent.dispatchKey;
+                            state.attempts = intent.attempts;
+                            state.rebases = intent.rebases;
+                            pendingMerges.push(intent);
+                            break;
+                        }
+                        const verdict = yield* reconciler.onConflict({
+                            nodeId: node.id,
+                            keyDigest: state.dispatchKey,
+                            attempt: state.attempts,
+                            rebases: state.rebases,
+                            strategy: result.strategy,
+                            conflictsWith: node.conflicts.map((conflict) => conflict.with)
+                        });
+                        markSettled(node, "failed");
+                        yield* applyVerdict(node.id, verdict, "materialization-conflict");
+                        break;
+                    }
+                }
+                yield* appendReadyMerges;
+                // The dispatch durably journalled every deviation before its event.
+                // Apply those verdicts before consulting downstream readiness.
+                yield* drainDeviations;
+                // A dispatch outcome is provisional until its deviations have been
+                // reconciled. Persist exactly one terminal fact, after a Fail
+                // verdict has had the chance to replace built with failed.
+                yield* emitSettlement(node);
+                graph.reconcile();
+                // Process terminal events already observed by the journal drain
+                // before opening more permits. This preserves fail-fast behavior for
+                // an already-failed sibling while still admitting immediately when
+                // unrelated work is genuinely still in flight.
+                const ready = yield* advance;
+                if (pendingSettlements.length === 0)
+                    yield* admit(ready);
+            }
+        }).pipe(Effect.onError((cause) => Effect.sync(() => {
+            abortedForFailure = cause.reasons.some((reason) => reason._tag === "Fail");
+        })))).pipe(Effect.catch((error) => Effect.fail(cleanupErrors.length === 0 ? error : new SchedulerError({
+            code: error.code,
+            message: error.message,
+            cause: error.cause,
+            cleanupErrors
+        }))));
+        const settlements = plan.nodes.map((node) => {
+            const state = stateOf(node);
+            return {
+                nodeId: node.id,
+                planKey: node.key,
+                dispatchKey: state.dispatchKey,
+                outcome: state.outcome,
+                attempts: state.attempts,
+                rebases: state.rebases
+            };
+        });
+        yield* Effect.logDebug("scheduler run completed", {
+            admissions,
+            built: settlements.filter((settlement) => settlement.outcome === "built").length,
+            clean: settlements.filter((settlement) => settlement.outcome === "clean").length,
+            failed: settlements.filter((settlement) => settlement.outcome === "failed").length,
+            skipped: settlements.filter((settlement) => settlement.outcome === "skipped").length,
+            deferred: settlements.filter((settlement) => settlement.outcome === "deferred").length
+        });
+        return {
+            planId: plan.planId,
+            digest: plan.digest,
+            settlements,
+            results: Object.fromEntries(results),
+            verdicts,
+            appended
+        };
+    }).pipe(Effect.annotateSpans({ runId: options.runId }), Effect.annotateLogs({ runId: options.runId }), Effect.onExit((exit) => Effect.annotateCurrentSpan({ outcome: EngineStoreMetrics.exitTag(exit).toLowerCase() }))));
+    return { record, append, run };
+};
+/**
+ * Provides a scheduler bound to one run.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layer = (options) => Layer.succeed(PlanScheduler, make(options));
+/**
+ * The recertification driver: re-drives a compiled plan under a fresh,
+ * caller-supplied run with the `full` selection override — guess-free by
+ * construction — then reports the deferring run's remaining debt via
+ * `Selection.debt(deferringRunId, { repaidBy: [options.runId] })`.
+ *
+ * The design draft placed this beside the other Selection helpers; it lives
+ * here because it constructs a scheduler, and `Selection` must stay
+ * type-only toward this module to keep the dependency graph acyclic. The
+ * deferring run's journal is never written — repayment is a read-side join.
+ * Scheduling the cadence (nightly, per-merge) stays a product concern; this
+ * is only the primitive one pass runs.
+ *
+ * @since 0.1.0
+ * @category combinators
+ */
+export const recertify = Effect.fn("PlanScheduler.recertify")((input) => Effect.gen(function* () {
+    const scheduler = make({
+        ...input.options,
+        selection: { ...input.options.selection, full: true }
+    });
+    const report = yield* scheduler.run(input.plan);
+    const remaining = yield* Selection.debt(input.deferringRunId, { repaidBy: [input.options.runId] });
+    return { runId: input.options.runId, report, remaining };
+}));
+//# sourceMappingURL=PlanScheduler.js.map