@agentxm/workspace-operations 0.28.4-bootstrap.0

package/dist/src/operations/transition-lock.js

@@ -0,0 +1,291 @@
+// @effect-diagnostics nodeBuiltinImport:off — proper-lockfile requires a callback-style fs; the adapter is confined to the lock path
+/**
+ * Workspace transition lock.
+ *
+ * One cross-process lock serializes mutation-class operations on a workspace.
+ * A plan-family apply acquires it after confirmation — planning, network
+ * acquisition, preview, and the confirmation decision stay lock-free — then
+ * revalidates its candidate and applies while holding it; the workspace
+ * transaction reuses the invocation's hold, or acquires its own when no
+ * plan-family hold exists. A contending invocation waits with a visible
+ * reason up to a bound, then terminates blocked with a machine-readable
+ * reference to the holder.
+ *
+ * Each acquisition records a distinct owner token in the holder metadata.
+ * Ownership is proven only by an exact token match — never inferred from a
+ * pid or from missing or unreadable metadata — and a holder write that fails
+ * releases the acquisition instead of holding anonymously.
+ *
+ * The lock file lives at `.axm/tmp/workspace-transition.lock`; its path is
+ * load-bearing for operational tooling and must not move casually.
+ *
+ * Acquisition is atomic with respect to interruption: the narrow region from
+ * the library granting the hold through finalizer registration is masked, so
+ * an interrupt can never strand a granted lock, while contention waits stay
+ * interruptible. Only the lock-is-held error class is absorbed by the bounded
+ * wait; any other acquisition error surfaces immediately as a typed failure.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as nodeFs from "node:fs";
+import { randomBytes } from "node:crypto";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as lockfile from "proper-lockfile";
+import { TransitionLockError, WorkspaceDirectoryError, WorkspaceTransitionCompromised, } from "@agentxm/workspace-state";
+export const TRANSITION_LOCK_FILENAME = "workspace-transition.lock";
+// Staleness must tolerate a saturated event loop: a heavy apply starves the
+// mtime-update timer, and a slack smaller than the starvation lets a LIVE
+// holder's lock self-declare compromised — after which release refuses and the
+// dir is left for the next invocation to wait out. 25 s of slack covers the
+// longest observed starvation with room; a crashed holder delays a contender
+// at most this long, still inside the 60 s wait bound.
+const LOCK_STALE_MILLIS = 30_000;
+const LOCK_UPDATE_MILLIS = 5_000;
+const WAIT_INTERVAL = Duration.millis(250);
+/** How long a contending invocation serializes behind the holder. */
+export const TRANSITION_WAIT_BOUND_MILLIS = 60_000;
+/**
+ * Held transition locks in this process, keyed by resolved workspace
+ * directory. Owned exclusively by `acquireWorkspaceTransitionLock`, whose
+ * scope finalizer removes the entry, so an entry's lifetime is exactly the
+ * lock's; the workspace transaction consults it to avoid deadlocking on the
+ * invocation's own hold and to observe compromise of that hold.
+ */
+// eslint-disable-next-line no-restricted-syntax -- Owned exclusively by acquireWorkspaceTransitionLock: an entry's lifetime is exactly the lock's, and the acquisition's scope finalizer removes it.
+const heldTransitions = new Map();
+export const isWorkspaceTransitionHeldByThisInvocation = (workspaceDir) => heldTransitions.has(workspaceDir);
+/** The live hold for a workspace this process acquired, when one exists. */
+export const heldWorkspaceTransition = (workspaceDir) => heldTransitions.get(workspaceDir);
+const errorCode = (cause) => typeof cause === "object" && cause !== null && "code" in cause && typeof cause.code === "string"
+    ? cause.code
+    : undefined;
+export const transitionLockPath = (path, workspaceDir) => path.join(workspaceDir, "tmp", TRANSITION_LOCK_FILENAME);
+/**
+ * The filesystem handed to `proper-lockfile`. Identical to the platform fs
+ * except that removing a transition-lock directory first clears the tool's
+ * own holder metadata inside it. The library reclaims a stale lock and
+ * releases a held one with a non-recursive `rmdir`; without this, a lock
+ * directory left by a crashed process — which always still contains
+ * `holder.json` — could never be reclaimed, and every later mutation would
+ * wait out its bound and report a false contention. Removal stays
+ * non-recursive past that one owned name, so foreign content keeps blocking
+ * removal the way it always did.
+ */
+const lockDirectoryFs = {
+    ...nodeFs,
+    rmdir: (target, callback) => {
+        if (typeof target === "string" && target.endsWith(TRANSITION_LOCK_FILENAME)) {
+            nodeFs.unlink(`${target}/holder.json`, () => {
+                nodeFs.rmdir(target, callback);
+            });
+            return;
+        }
+        nodeFs.rmdir(target, callback);
+    },
+    rmdirSync: (target) => {
+        if (typeof target === "string" && target.endsWith(TRANSITION_LOCK_FILENAME)) {
+            try {
+                nodeFs.unlinkSync(`${target}/holder.json`);
+            }
+            catch {
+                // Absent metadata blocks nothing; foreign content still blocks rmdir.
+            }
+        }
+        nodeFs.rmdirSync(target);
+    },
+};
+/**
+ * Acquisition-error classes the bounded contention wait absorbs: the lock is
+ * held (`ELOCKED`), or the attempt raced the holder's own acquire, release,
+ * or staleness sweep (`ENOENT`/`EEXIST` from proper-lockfile's internal
+ * stat-remove-retry). Every other class — permissions, foreign state
+ * squatting the path — is not resolved by waiting and surfaces immediately.
+ */
+const isContentionErrorCode = (code) => code === "ELOCKED" || code === "ENOENT" || code === "EEXIST";
+const readHolder = (fs, path, lockPath) => fs.readFileString(path.join(lockPath, "holder.json")).pipe(Effect.map((content) => {
+    const parsed = JSON.parse(content);
+    if (typeof parsed === "object" &&
+        parsed !== null &&
+        "command" in parsed &&
+        typeof parsed.command === "string" &&
+        "pid" in parsed &&
+        typeof parsed.pid === "number") {
+        return Option.some({
+            command: parsed.command,
+            pid: parsed.pid,
+            ...("candidateId" in parsed && typeof parsed.candidateId === "string"
+                ? { candidateId: parsed.candidateId }
+                : {}),
+            ...("token" in parsed && typeof parsed.token === "string" ? { token: parsed.token } : {}),
+        });
+    }
+    return Option.none();
+}), Effect.catch(() => Effect.succeed(Option.none())));
+const writeHolder = (fs, path, lockPath, holder) => fs
+    .writeFileString(path.join(lockPath, "holder.json"), JSON.stringify(holder))
+    .pipe(Effect.mapError((cause) => new TransitionLockError({ path: lockPath, step: "record-holder", cause })));
+/**
+ * Acquire the workspace transition lock, waiting up to the bound while
+ * another invocation holds it. Resolves `None` when acquired (the release is
+ * a scope finalizer) and `Some(contention)` when the bound elapsed.
+ */
+export const acquireWorkspaceTransitionLock = (args) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const workspaceDir = path.resolve(args.workspaceDir);
+    const scratchDir = path.join(workspaceDir, "tmp");
+    const lockPath = path.join(scratchDir, TRANSITION_LOCK_FILENAME);
+    const waitBound = args.waitBoundMillis ?? TRANSITION_WAIT_BOUND_MILLIS;
+    const workspaceExisted = yield* fs
+        .exists(workspaceDir)
+        .pipe(Effect.mapError((cause) => new WorkspaceDirectoryError({ path: workspaceDir, step: "inspect", cause })));
+    yield* fs
+        .makeDirectory(scratchDir, { recursive: true })
+        .pipe(Effect.mapError((cause) => new TransitionLockError({ path: scratchDir, step: "create-scratch", cause })));
+    const removeEmptyScratch = fs.readDirectory(scratchDir).pipe(Effect.flatMap((entries) => entries.length === 0
+        ? fs.remove(scratchDir, { recursive: true, force: false })
+        : Effect.void), Effect.ignore);
+    const removeNewEmptyWorkspace = workspaceExisted
+        ? Effect.void
+        : fs.readDirectory(workspaceDir).pipe(Effect.flatMap((entries) => entries.length === 0
+            ? fs.remove(workspaceDir, { recursive: true, force: false })
+            : Effect.void), Effect.ignore);
+    const compromisedSignal = Deferred.makeUnsafe();
+    let waitedMillis = 0;
+    let reportedWaiting = false;
+    while (true) {
+        // One attempt is atomic with respect to interruption: from the library
+        // granting the hold through finalizer registration there is no
+        // interruptible gap, so an interrupt requested mid-acquisition defers
+        // until the release finalizer exists and then releases through it. The
+        // mask stays narrow — a single no-retry grant plus local metadata —
+        // and the contention wait below remains interruptible.
+        const attempt = yield* Effect.uninterruptible(Effect.gen(function* () {
+            const granted = yield* Effect.tryPromise({
+                try: () => lockfile.lock(workspaceDir, {
+                    lockfilePath: lockPath,
+                    realpath: false,
+                    retries: 0,
+                    fs: lockDirectoryFs,
+                    stale: args.timingMillis?.stale ?? LOCK_STALE_MILLIS,
+                    update: args.timingMillis?.update ?? LOCK_UPDATE_MILLIS,
+                    // The default handler throws inside a timer: an uncatchable
+                    // crash that sprays raw frames on stderr. Complete the typed
+                    // compromise signal instead — the workspace transaction races
+                    // against it and never continues mutating after ownership is
+                    // lost.
+                    onCompromised: (cause) => {
+                        Deferred.doneUnsafe(compromisedSignal, Effect.fail(new WorkspaceTransitionCompromised({ workspaceDir, lockPath, cause })));
+                    },
+                }),
+                catch: (cause) => ({ cause, code: errorCode(cause) }),
+            }).pipe(Effect.result);
+            if (granted._tag === "Failure") {
+                if (isContentionErrorCode(granted.failure.code)) {
+                    return { _tag: "held" };
+                }
+                return {
+                    _tag: "failed",
+                    error: new TransitionLockError({
+                        path: lockPath,
+                        step: "acquire",
+                        cause: granted.failure.cause,
+                    }),
+                };
+            }
+            const release = granted.success;
+            const token = randomBytes(16).toString("hex");
+            const holderStamped = yield* Effect.gen(function* () {
+                const lockInfo = yield* fs
+                    .stat(lockPath)
+                    .pipe(Effect.mapError((cause) => new TransitionLockError({ path: lockPath, step: "inspect-timestamp", cause })));
+                const lockMtime = yield* Option.match(lockInfo.mtime, {
+                    onNone: () => Effect.fail(new TransitionLockError({ path: lockPath, step: "missing-timestamp" })),
+                    onSome: Effect.succeed,
+                });
+                yield* writeHolder(fs, path, lockPath, {
+                    ...args.holder,
+                    token,
+                });
+                // proper-lockfile proves ownership by comparing the directory's
+                // mtime with the timestamp it recorded at acquisition. Writing
+                // holder.json changes that directory mtime, so restore the exact
+                // acquired value before the first refresh observes it.
+                yield* fs
+                    .utimes(lockPath, lockMtime, lockMtime)
+                    .pipe(Effect.mapError((cause) => new TransitionLockError({ path: lockPath, step: "preserve-timestamp", cause })));
+            }).pipe(Effect.result);
+            if (holderStamped._tag === "Failure") {
+                // The holder metadata is the only ownership evidence this
+                // acquisition will ever have; holding without it would be
+                // indistinguishable from a successor's half-written acquisition.
+                // Release the lock and fail rather than hold anonymously.
+                yield* Effect.tryPromise({
+                    try: () => release(),
+                    catch: (cause) => new TransitionLockError({ path: lockPath, step: "release", cause }),
+                }).pipe(Effect.ignore);
+                return { _tag: "failed", error: holderStamped.failure };
+            }
+            heldTransitions.set(workspaceDir, {
+                compromised: Deferred.await(compromisedSignal),
+                isCompromised: () => Deferred.isDoneUnsafe(compromisedSignal),
+            });
+            yield* Effect.addFinalizer(() => Effect.gen(function* () {
+                heldTransitions.delete(workspaceDir);
+                // Removal requires an exact owner-token match, proven before
+                // release() — which would remove the directory unconditionally.
+                // Absent or unreadable holder metadata is indistinguishable from
+                // a successor that reclaimed the stale hold but has not yet
+                // written its holder file, and is never license to remove; the
+                // unowned in-process bookkeeping self-resolves as compromised on
+                // its next update tick without touching the directory.
+                const residualHolder = yield* readHolder(fs, path, lockPath);
+                const ownsResidual = Option.match(residualHolder, {
+                    onNone: () => false,
+                    onSome: (value) => value.token === token,
+                });
+                if (ownsResidual) {
+                    yield* Effect.tryPromise({
+                        try: () => release(),
+                        catch: (cause) => new TransitionLockError({ path: lockPath, step: "release", cause }),
+                    }).pipe(Effect.ignore);
+                    // A compromised hold makes release() refuse; the directory is
+                    // still ours by exact token match — remove it directly.
+                    yield* fs.remove(lockPath, { recursive: true, force: true }).pipe(Effect.ignore);
+                }
+                yield* removeEmptyScratch;
+                yield* removeNewEmptyWorkspace;
+            }));
+            return { _tag: "acquired" };
+        }));
+        if (attempt._tag === "acquired") {
+            return Option.none();
+        }
+        if (attempt._tag === "failed") {
+            yield* removeEmptyScratch;
+            yield* removeNewEmptyWorkspace;
+            return yield* attempt.error;
+        }
+        // The lock is held: serialize behind the holder with a visible reason,
+        // up to the bound — the loser serializes or times out into a
+        // categorized blocked, never an internal crash.
+        const holder = yield* readHolder(fs, path, lockPath);
+        if (!reportedWaiting && args.onWaiting !== undefined) {
+            reportedWaiting = true;
+            yield* args.onWaiting(holder);
+        }
+        if (waitedMillis >= waitBound) {
+            yield* removeEmptyScratch;
+            yield* removeNewEmptyWorkspace;
+            return Option.some({ holder, waitedMillis });
+        }
+        yield* Effect.sleep(WAIT_INTERVAL);
+        waitedMillis += Duration.toMillis(WAIT_INTERVAL);
+    }
+});
+//# sourceMappingURL=transition-lock.js.map

package/dist/src/plan/apply-plan.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared plan apply module.
+ *
+ * Iterates over plan jobs and their steps, executing `step.run()` for
+ * ready/warn steps and promoting error steps to error results without
+ * execution. Readiness errors gate the entire plan before any mutation, and
+ * jobs fail fast unless they explicitly opt into best-effort execution.
+ *
+ * This module is the stable kernel home for `applyPlan` and the
+ * `OperationHandler` type. Per-extension handlers live in their owning domain
+ * packages and resolve this shared contract from here.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { StepFailure } from "./errors.js";
+import type { CompletedJobStep, ExecutedPlan, JobStepResult, Plan } from "./plan.js";
+/**
+ * Type for operation handler functions that take an operation and return
+ * an Effect producing a JobStepResult.
+ */
+export type OperationHandler<Op, R = never> = (op: Op) => Effect.Effect<JobStepResult, StepFailure, R>;
+/**
+ * Apply a plan by iterating jobs and executing step run closures.
+ *
+ * Any readiness error gates the complete plan before execution. At runtime,
+ * jobs use ordered fail-fast execution by default. A job may explicitly opt
+ * into best-effort execution for independent siblings; failures still block
+ * all subsequent jobs.
+ *
+ * Never fails — catches StepFailure and converts to error results.
+ */
+/** Identity of a unit whose run closure is starting. */
+export interface StartedJobStep {
+    readonly key?: string;
+    readonly label: string;
+}
+export interface ApplyPlanOptions<Output> {
+    /** Observes each unit as its run closure starts; never controls execution. */
+    readonly onStepStarted?: (step: StartedJobStep) => Effect.Effect<void>;
+    /** Observes each unit the moment it completes; never controls execution. */
+    readonly onStepCompleted?: (step: CompletedJobStep<Output>) => Effect.Effect<void>;
+}
+export declare const applyPlan: <Requirements, Output>(plan: Plan<Requirements, Output>, options?: ApplyPlanOptions<Output>) => Effect.Effect<ExecutedPlan<Output>, never, Requirements>;
+//# sourceMappingURL=apply-plan.d.ts.map

package/dist/src/plan/apply-plan.js

@@ -0,0 +1,238 @@
+/**
+ * Shared plan apply module.
+ *
+ * Iterates over plan jobs and their steps, executing `step.run()` for
+ * ready/warn steps and promoting error steps to error results without
+ * execution. Readiness errors gate the entire plan before any mutation, and
+ * jobs fail fast unless they explicitly opt into best-effort execution.
+ *
+ * This module is the stable kernel home for `applyPlan` and the
+ * `OperationHandler` type. Per-extension handlers live in their owning domain
+ * packages and resolve this shared contract from here.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Array from "effect/Array";
+import * as Effect from "effect/Effect";
+import { StepFailure } from "./errors.js";
+// -----------------------------------------------------------------------------
+// Implementation
+// -----------------------------------------------------------------------------
+const appendReadinessWarning = (step, result) => {
+    if (result.result === "error") {
+        return result;
+    }
+    return {
+        ...result,
+        warnings: [...(result.warnings ?? []), step.warnMessage],
+    };
+};
+const errorStepMessage = (error) => `${error.detail} (${error.category})`;
+const stepEvidence = (step) => ({
+    ...(step.registryLifecycle === undefined ? {} : { registryLifecycle: step.registryLifecycle }),
+    ...(step.agentOutcomes === undefined ? {} : { agentOutcomes: step.agentOutcomes }),
+});
+const executeStep = (step) => {
+    switch (step.readiness) {
+        case "error":
+            return Effect.succeed({
+                ...(step.key === undefined ? {} : { key: step.key }),
+                ...stepEvidence(step),
+                label: step.label,
+                result: {
+                    result: "error",
+                    message: step.errorMessage,
+                    error: new StepFailure({
+                        category: "internal",
+                        detail: step.errorMessage,
+                    }),
+                },
+            });
+        case "ready":
+            return step.run.pipe(Effect.map((result) => ({
+                ...(step.key === undefined ? {} : { key: step.key }),
+                ...stepEvidence(step),
+                label: step.label,
+                result,
+            })), Effect.catch((error) => {
+                return Effect.succeed({
+                    ...(step.key === undefined ? {} : { key: step.key }),
+                    ...stepEvidence(step),
+                    label: step.label,
+                    result: {
+                        result: "error",
+                        message: errorStepMessage(error),
+                        error,
+                    },
+                });
+            }));
+        case "warn":
+            return step.run.pipe(Effect.map((result) => ({
+                ...(step.key === undefined ? {} : { key: step.key }),
+                ...stepEvidence(step),
+                label: step.label,
+                result: appendReadinessWarning(step, result),
+            })), Effect.catch((error) => {
+                return Effect.succeed({
+                    ...(step.key === undefined ? {} : { key: step.key }),
+                    ...stepEvidence(step),
+                    label: step.label,
+                    result: {
+                        result: "error",
+                        message: errorStepMessage(error),
+                        error,
+                    },
+                });
+            }));
+    }
+};
+const blockStep = (step, message, blocking, blockedBy) => ({
+    ...(step.key === undefined ? {} : { key: step.key }),
+    ...stepEvidence(step),
+    label: step.label,
+    ...(blockedBy === undefined ? {} : { blockedBy }),
+    result: {
+        result: "error",
+        message,
+        error: new StepFailure({
+            category: "conflict",
+            detail: message,
+        }),
+        blocking,
+    },
+});
+const applyReadinessGate = (plan) => plan.jobs.map((job) => job.steps.map((step) => step.readiness === "error"
+    ? {
+        label: step.label,
+        result: {
+            result: "error",
+            message: step.errorMessage,
+            error: new StepFailure({ category: "conflict", detail: step.errorMessage }),
+        },
+    }
+    : blockStep(step, "blocked by plan readiness error", { class: "precondition-unmet" })));
+/**
+ * Run one unit with its start and settlement observations. The started fact
+ * is recorded before the run begins, and the settlement fact is recorded
+ * before any interruptible boundary follows the run's completion — an
+ * interrupt arriving with the completion can otherwise erase the only
+ * in-memory evidence that the unit's durable effect was committed. The run
+ * itself stays interruptible; the mask covers only the observations.
+ */
+const runStepObserved = (step, observeStart, observeStep) => Effect.uninterruptibleMask((restore) => observeStart(step).pipe(Effect.andThen(restore(executeStep(step))), Effect.tap(observeStep)));
+const executeFailFastJob = (job, observeStart, observeStep) => Effect.gen(function* () {
+    const completed = [];
+    let failed = false;
+    let failedStepId;
+    for (const step of job.steps) {
+        if (failed) {
+            const blocked = blockStep(step, "blocked by earlier step failure", {
+                class: "operation-aborted",
+                ...(failedStepId === undefined ? {} : { reference: failedStepId }),
+            });
+            completed.push(blocked);
+            yield* Effect.uninterruptible(observeStep(blocked));
+            continue;
+        }
+        const result = yield* runStepObserved(step, observeStart, observeStep);
+        completed.push(result);
+        if (result.result.result === "error" && !failed) {
+            failed = true;
+            failedStepId = result.key ?? result.label;
+        }
+    }
+    return completed;
+});
+const executeBestEffortJob = (job, observeStart, observeStep) => Effect.forEach(job.steps, (step) => runStepObserved(step, observeStart, observeStep), {
+    concurrency: job.concurrency,
+});
+const executeDependencyAwareJob = (job, observeStart, observeStep) => Effect.gen(function* () {
+    const stepsByKey = new Map(job.steps.flatMap((step) => (step.key === undefined ? [] : [[step.key, step]])));
+    const completed = new Map();
+    const unkeyed = job.steps.filter((step) => step.key === undefined);
+    for (const step of unkeyed) {
+        const result = yield* runStepObserved(step, observeStart, observeStep);
+        completed.set(`label:${step.label}`, result);
+    }
+    while ([...stepsByKey.keys()].some((key) => !completed.has(key))) {
+        const remaining = [...stepsByKey.entries()].filter(([key]) => !completed.has(key));
+        const blocked = remaining.filter(([, step]) => (step.dependsOn ?? []).some((dependency) => {
+            const result = completed.get(dependency);
+            return result !== undefined && result.result.result === "error";
+        }));
+        for (const [key, step] of blocked) {
+            const blockedBy = (step.dependsOn ?? []).filter((dependency) => {
+                const result = completed.get(dependency);
+                return result !== undefined && result.result.result === "error";
+            });
+            const blocked = blockStep(step, `blocked by failed dependency: ${blockedBy.join(", ")}`, {
+                class: "dependency-failed",
+                ...(blockedBy[0] === undefined ? {} : { reference: blockedBy[0] }),
+            }, blockedBy);
+            completed.set(key, blocked);
+            yield* Effect.uninterruptible(observeStep(blocked));
+        }
+        const ready = remaining.filter(([key, step]) => !completed.has(key) &&
+            (step.dependsOn ?? []).every((dependency) => {
+                const result = completed.get(dependency);
+                return result === undefined
+                    ? !stepsByKey.has(dependency)
+                    : result.result.result !== "error";
+            }));
+        if (ready.length === 0) {
+            for (const [key, step] of remaining) {
+                if (completed.has(key))
+                    continue;
+                completed.set(key, blockStep(step, "blocked by an unresolved dependency cycle", { class: "dependency-cycle" }, step.dependsOn ?? []));
+            }
+            break;
+        }
+        const results = yield* Effect.forEach(ready, ([, step]) => runStepObserved(step, observeStart, observeStep), { concurrency: job.concurrency });
+        for (const result of results) {
+            if (result.key !== undefined)
+                completed.set(result.key, result);
+        }
+    }
+    return job.steps.map((step) => completed.get(step.key ?? `label:${step.label}`) ??
+        blockStep(step, "blocked by an unresolved execution dependency", {
+            class: "dependency-cycle",
+        }));
+});
+export const applyPlan = (plan, options) => Effect.gen(function* () {
+    const observeStep = options?.onStepCompleted ?? (() => Effect.void);
+    const observeStart = options?.onStepStarted ?? (() => Effect.void);
+    const hasReadinessError = plan.jobs.some((job) => job.steps.some((step) => step.readiness === "error"));
+    let blocked = false;
+    const jobResults = hasReadinessError
+        ? applyReadinessGate(plan)
+        : yield* Effect.forEach(plan.jobs, (job) => blocked
+            ? Effect.succeed(job.steps.map((step) => blockStep(step, "blocked by earlier job failure", {
+                class: "operation-aborted",
+            })))
+            : (job.steps.some((step) => (step.dependsOn ?? []).length > 0)
+                ? executeDependencyAwareJob(job, observeStart, observeStep)
+                : job.executionPolicy === "best-effort"
+                    ? executeBestEffortJob(job, observeStart, observeStep)
+                    : executeFailFastJob(job, observeStart, observeStep)).pipe(Effect.tap((steps) => {
+                if (steps.some((step) => step.result.result === "error")) {
+                    blocked = true;
+                }
+                return Effect.void;
+            })), { concurrency: 1 });
+    return {
+        _tag: "ExecutedPlan",
+        name: plan.name,
+        description: plan.description,
+        ...(plan.releaseAge === undefined ? {} : { releaseAge: plan.releaseAge }),
+        ...(plan.preconditions === undefined ? {} : { preconditions: plan.preconditions }),
+        ...(plan.riskConditions === undefined ? {} : { riskConditions: plan.riskConditions }),
+        jobs: Array.map(jobResults, (steps, i) => ({
+            concurrency: plan.jobs[i]?.concurrency ?? 1,
+            ...(plan.jobs[i]?.executionPolicy === undefined
+                ? {}
+                : { executionPolicy: plan.jobs[i].executionPolicy }),
+            steps,
+        })),
+    };
+}).pipe(Effect.withSpan("Plan.applyPlan"));
+//# sourceMappingURL=apply-plan.js.map

package/dist/src/plan/errors.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Error category vocabulary for serialized plan and step data.
+ *
+ * The categories are the same strings as the CLI's `AppErrorCode` so machine
+ * output stays byte-identical across the package boundary; the conversion
+ * boundary beside the CLI error vocabulary asserts the parity at compile
+ * time. The kernel owns the vocabulary because plans, journals, and machine
+ * output serialize it; it never owns titles, exit codes, or rendering.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+/** Every category a plan, step result, or risk condition may serialize. */
+export declare const OPERATION_ERROR_CATEGORIES: readonly ["issues", "usage", "not_found", "auth", "forbidden", "conflict", "rate_limit", "network", "validation", "internal", "unavailable", "quota", "auth_required", "auth_expired", "auth_denied", "timeout"];
+export declare const OperationErrorCategorySchema: Schema.Literals<readonly ["issues", "usage", "not_found", "auth", "forbidden", "conflict", "rate_limit", "network", "validation", "internal", "unavailable", "quota", "auth_required", "auth_expired", "auth_denied", "timeout"]>;
+export type OperationErrorCategory = (typeof OPERATION_ERROR_CATEGORIES)[number];
+declare const StepFailure_base: Schema.Class<StepFailure, Schema.TaggedStruct<"StepFailure", {
+    readonly category: Schema.Literals<readonly ["issues", "usage", "not_found", "auth", "forbidden", "conflict", "rate_limit", "network", "validation", "internal", "unavailable", "quota", "auth_required", "auth_expired", "auth_denied", "timeout"]>;
+    readonly detail: Schema.String;
+    readonly suggestions: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly description: Schema.String;
+        readonly cmd: Schema.optional<Schema.String>;
+        readonly url: Schema.optional<Schema.String>;
+    }>>>;
+    readonly cause: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The one serializable failure a plan step settles with. Step authors own the
+ * category choice and the user-facing detail sentence; `suggestions` carries
+ * only display data the boundary cannot reconstruct from fields, and `cause`
+ * carries the typed feature error or raw cause for diagnostic chains. The CLI
+ * boundary owns rendering, exit codes, and the AppError envelope.
+ */
+export declare class StepFailure extends StepFailure_base {
+}
+/**
+ * Detail sentence for a stale execution candidate; the CLI conversion emits
+ * it verbatim so blocked output stays byte-identical.
+ */
+export declare const STALE_CANDIDATE_DETAIL = "The execution candidate became stale before apply.";
+declare const StaleExecutionCandidate_base: Schema.Class<StaleExecutionCandidate, Schema.TaggedStruct<"StaleExecutionCandidate", {
+    /** The plan name of the candidate that went stale. */
+    readonly candidate: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The frozen execution candidate's material preimages changed between
+ * validation and apply. Detected by tag, never by detail-string comparison.
+ */
+export declare class StaleExecutionCandidate extends StaleExecutionCandidate_base {
+}
+declare const CandidateFingerprintFailed_base: Schema.Class<CandidateFingerprintFailed, Schema.TaggedStruct<"CandidateFingerprintFailed", {
+    /** The material path whose preimage could not be read. */
+    readonly target: Schema.String;
+    readonly cause: Schema.Unknown;
+}>, import("effect/Cause").YieldableError>;
+/** Fingerprinting one execution-material path failed. */
+export declare class CandidateFingerprintFailed extends CandidateFingerprintFailed_base {
+}
+declare const ApprovalRecoveryMissing_base: Schema.Class<ApprovalRecoveryMissing, Schema.TaggedStruct<"ApprovalRecoveryMissing", {}>, import("effect/Cause").YieldableError>;
+/**
+ * An apply-mode execution reached the plan pipeline without approval
+ * recovery metadata: a caller violated the `PlanExecution` contract. The CLI
+ * boundary owns the rendering.
+ */
+export declare class ApprovalRecoveryMissing extends ApprovalRecoveryMissing_base {
+}
+declare const PlanInteractionFailed_base: Schema.Class<PlanInteractionFailed, Schema.TaggedStruct<"PlanInteractionFailed", {
+    readonly category: Schema.Literals<readonly ["issues", "usage", "not_found", "auth", "forbidden", "conflict", "rate_limit", "network", "validation", "internal", "unavailable", "quota", "auth_required", "auth_expired", "auth_denied", "timeout"]>;
+    readonly detail: Schema.String;
+    readonly suggestions: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly description: Schema.String;
+        readonly cmd: Schema.optional<Schema.String>;
+        readonly url: Schema.optional<Schema.String>;
+    }>>>;
+    readonly cause: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The plan interaction implementation could not complete a presentation or
+ * confirmation exchange. The implementation owns wording and category choice;
+ * the kernel only transports the failure to the boundary that renders it.
+ */
+export declare class PlanInteractionFailed extends PlanInteractionFailed_base {
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map