@agentxm/workspace-operations 0.28.12 → 0.28.13

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

@@ -1,4 +1,44 @@
+/**
+ * The one derivation of an approval mode from what a request carries.
+ *
+ * It lives with plan execution rather than in a transport adapter because the
+ * distinction it draws — between a route that offers preapproval and one that
+ * does not — is what `resolveExecutionCandidate` uses to decide whether an
+ * unattended apply blocks naming interactive approval or names a flag.
+ */
+export const confirmableRiskApproval = (requested) => requested.preapproved === true
+    ? "preapproved"
+    : requested.preapproved === false
+        ? "prompt-if-interactive"
+        : "interactive-only";
 export const previewPlanExecution = { request: { mode: "preview" } };
+/**
+ * The one derivation of a plan execution from what a request carries.
+ *
+ * It lives here for the same reason `confirmableRiskApproval` does: the
+ * preview arm of `PlanExecution` has no field an approval could occupy, so
+ * advance approval accompanying a preview is dropped by this derivation
+ * rather than by a transport adapter's own convention. A preview therefore
+ * cannot spend an approval it never receives, and two requests that differ
+ * only in approval reach `resolveExecutionCandidate` as the same execution.
+ */
+export const requestedPlanExecution = (options) => options.intent.preview
+    ? {
+        ...previewPlanExecution,
+        ...(options.configuredAgentOperations === undefined
+            ? {}
+            : { configuredAgentOperations: options.configuredAgentOperations }),
+    }
+    : applyPlanExecution({
+        approval: confirmableRiskApproval(options.intent.yes === undefined ? {} : { preapproved: options.intent.yes }),
+        ...(options.acceptedPolicies === undefined
+            ? {}
+            : { acceptedPolicies: options.acceptedPolicies }),
+        recovery: options.recovery,
+        ...(options.configuredAgentOperations === undefined
+            ? {}
+            : { configuredAgentOperations: options.configuredAgentOperations }),
+    });
 export const applyPlanExecution = (options) => ({
     request: {
         mode: "apply",

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

@@ -23,7 +23,7 @@ import { type ExtensionType } from "@agentxm/extension-model/unstable/extensions
 import type { ArtifactChange } from "@agentxm/workspace-state";
 import type { ConfiguredAgentOutcome } from "@agentxm/workspace-state";
 import type { DeprecationView } from "@agentxm/extension-model/unstable/extensions/deprecation";
-import type { ReleaseAgeOperationEvidence } from "@agentxm/registry-protocol/unstable/registry/release-age-policy";
+import type { RegistryBindingProposal, ReleaseAgeOperationEvidence } from "@agentxm/extension-resolution";
 import type { SuggestedAction } from "@agentxm/registry-protocol/unstable/suggested-action";
 export declare const PlanPolicyIds: readonly ["ignore-version-constraints", "accept-warnings"];
 export declare const PlanPolicyIdSchema: Schema.Literals<readonly ["ignore-version-constraints", "accept-warnings"]>;
@@ -111,21 +111,6 @@ export interface JobStepArtifactSource {
     readonly directory?: string;
     readonly gitTreeHash?: string;
 }
-/**
- * The Registry identity a step proposes to accept. Trust classification
- * compares it with the accepted resolution for the same configured target,
- * so a change of publisher is identified from structured data rather than
- * from warning text.
- */
-export interface RegistryBindingProposal {
-    readonly extensionType: ExtensionType;
-    /** The configured (local) name whose accepted resolution the step replaces. */
-    readonly target: string;
-    readonly owner: string;
-    readonly packageName: string;
-    readonly version: string;
-    readonly publisherBindingId: string;
-}
 export interface RegistryLifecycleEvidence {
     readonly deprecation: DeprecationView;
 }
@@ -253,9 +238,14 @@ export interface Plan<Requirements = never, Output = never> {
     /** Persisted inputs outside workspace state that materially determine this plan. */
     readonly materialPaths?: ReadonlyArray<string>;
     /** Local plans roll back candidate-wide; remote effects report truthful partial outcomes. */
-    readonly executionCapabilities?: {
-        readonly rollback: "local-atomic" | "non-rollbackable";
-    };
+    readonly executionCapabilities?: PlanExecutionCapabilities;
+}
+/**
+ * What a plan promises about undoing itself. A producer declares this so the
+ * atomicity a result reports is the one the plan's owner decided.
+ */
+export interface PlanExecutionCapabilities {
+    readonly rollback: "local-atomic" | "non-rollbackable";
 }
 export interface ExecutedJob<Output = never> {
     readonly steps: ReadonlyArray<CompletedJobStep<Output>>;

package/dist/src/plan/resolve-plan-interaction.d.ts

@@ -1,7 +1,7 @@
 /**
  * Plan-resolution interaction port.
  *
- * `previewOrApplyPlan` presents candidates and obtains the apply confirmation
+ * `resolveExecutionCandidate` presents candidates and obtains the apply confirmation
  * exclusively through this service. The CLI runtime provides the renderer- and
  * prompt-backed implementation; wording and verbosity gating belong to that
  * implementation, never to the kernel. Progress is not an interaction: the

package/dist/src/plan/resolve-plan-interaction.js

@@ -1,7 +1,7 @@
 /**
  * Plan-resolution interaction port.
  *
- * `previewOrApplyPlan` presents candidates and obtains the apply confirmation
+ * `resolveExecutionCandidate` presents candidates and obtains the apply confirmation
  * exclusively through this service. The CLI runtime provides the renderer- and
  * prompt-backed implementation; wording and verbosity gating belong to that
  * implementation, never to the kernel. Progress is not an interaction: the

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

@@ -1,42 +1,57 @@
 /**
- * Plan preview/apply function.
+ * Candidate preparation and resolution.
  *
- * Orchestrates `augmentPlanWithReconciliation`, `scanPlanReadiness`,
- * and `applyPlan` with the `ResolvePlanInteraction` port, and produces
- * one `OperationResolution` at every termination path. Channels project the
- * returned resolution; presentation and prompting live behind the port, and
- * per-type outcome refinement behind the optional
- * `ConfiguredAgentOutcomesProvider` port.
+ * `prepareExecutionCandidate` turns a plan into the immutable execution
+ * candidate every later step refers to: it augments the plan with lockfile
+ * reconciliation, projects configured-agent outcomes, scans readiness,
+ * assembles the semantic risk conditions, and fingerprints the material
+ * preimages. `resolveExecutionCandidate` presents that candidate, fails
+ * closed on blockers and missing policies, previews or confirms, acquires
+ * the workspace transition, revalidates the same candidate under it, applies
+ * it closure by closure, and produces one `OperationResolution` at every
+ * termination path. Presentation and prompting live behind the
+ * `ResolvePlanInteraction` port; per-type outcome refinement behind the
+ * `ConfiguredAgentOutcomesProvider`.
  *
- * This is a free function, not a method on WorkspaceMutationsService.
  *
  * @experimental This API is unstable and may change without notice.
  */
-import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
 import * as Effect from "effect/Effect";
 import { ApprovalRecoveryMissing, StepFailure } from "./errors.js";
 import { type ExecutionCandidate } from "./execution-candidate.js";
 import type { Plan } from "./plan.js";
 import { type OperationResolution } from "./operation-resolution.js";
-import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { OperationJournal } from "./operation-journal.js";
+import { ConfiguredAgentOutcomesProvider, WorkspaceMutations } from "@agentxm/workspace-state";
+import { FootprintRecorder } from "@agentxm/workspace-transactions";
 import { ResolvePlanInteraction } from "./resolve-plan-interaction.js";
-import { type PlanExecution } from "./plan-execution.js";
+import { type ConfiguredAgentOperation, type PlanExecution } from "./plan-execution.js";
+export interface PrepareExecutionCandidateOptions {
+    /** Operations whose configured-agent outcomes the candidate projects and, after apply, verifies. */
+    readonly configuredAgentOperations?: ReadonlyArray<ConfiguredAgentOperation>;
+}
 /**
- * Preview or apply (display, confirm, and execute) a plan using the workspace read model.
+ * Prepare the immutable execution candidate for a plan: augment with lockfile
+ * reconciliation, project configured-agent outcomes, scan readiness, assemble
+ * risk conditions, and fingerprint every material preimage. Preview,
+ * confirmation, and apply all refer to the candidate this returns.
+ */
+export declare const prepareExecutionCandidate: <Requirements, Output>(plan: Plan<Requirements, Output>, options?: PrepareExecutionCandidateOptions | undefined) => Effect.Effect<ExecutionCandidate<Requirements, Output>, import("./errors.js").CandidateFingerprintFailed | import("@agentxm/workspace-state").LockfileValidationError | import("@agentxm/workspace-state").WorkspaceSettingsReadFailure, Path.Path | import("effect/FileSystem").FileSystem | WorkspaceMutations | ConfiguredAgentOutcomesProvider>;
+export interface ResolveExecutionCandidateOptions<Requirements, Output> {
+    /** A typed pre-apply gate that runs under the transition before revalidation. */
+    readonly beforeApply?: (candidate: ExecutionCandidate<Requirements, Output>) => Effect.Effect<void, StepFailure, Requirements>;
+}
+/**
+ * Preview or apply a prepared candidate.
  *
- * Steps:
- * 1. Augment plan with lockfile reconciliation if needed
- * 2. Scan for errors/warnings
- * 3. Construct and display the exact candidate
- * 4. Fail closed on blockers and missing named policies
- * 5. Preview or approve confirmable semantic risk
- * 6. Revalidate and apply the same candidate
+ * 1. Present the immutable candidate.
+ * 2. Fail closed on blockers and missing named policies.
+ * 3. Preview, or approve confirmable semantic risk.
+ * 4. Acquire the workspace transition, revalidate the same candidate under
+ *    it, and apply it closure by closure.
  *
  * Every termination path resolves to one `OperationResolution`.
  */
-export declare const previewOrApplyPlan: <Requirements, Output>(plan: Plan<Requirements, Output>, options: {
-    execution: PlanExecution;
-    beforeApply?: (candidate: ExecutionCandidate<Requirements, Output>) => Effect.Effect<void, StepFailure, Requirements>;
-}) => Effect.Effect<OperationResolution<Output>, import("./errors.js").CandidateFingerprintFailed | ApprovalRecoveryMissing | import("./errors.js").PlanInteractionFailed | import("@agentxm/workspace-state").WorkspaceTransitionAcquireFailure | import("@agentxm/workspace-state").LockfileValidationError | import("@agentxm/workspace-state").WorkspaceSettingsReadFailure, Path.Path | FileSystem.FileSystem | ResolvePlanInteraction | WorkspaceMutations | Exclude<Requirements, import("effect/Scope").Scope>>;
+export declare const resolveExecutionCandidate: <Requirements, Output>(candidate: ExecutionCandidate<Requirements, Output>, execution: PlanExecution, options?: ResolveExecutionCandidateOptions<Requirements, Output> | undefined) => Effect.Effect<OperationResolution<Output>, ApprovalRecoveryMissing | import("./errors.js").PlanInteractionFailed | import("@agentxm/workspace-state").WorkspaceSettingsReadFailure | import("@agentxm/workspace-transactions").WorkspaceTransitionAcquireFailure, OperationJournal | Path.Path | import("effect/FileSystem").FileSystem | ResolvePlanInteraction | WorkspaceMutations | ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-transactions").WorkspaceTransactionScope | Exclude<Requirements, import("effect/Scope").Scope> | FootprintRecorder>;
 //# sourceMappingURL=resolve-plan.d.ts.map

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

@@ -1,22 +1,24 @@
 /**
- * Plan preview/apply function.
+ * Candidate preparation and resolution.
  *
- * Orchestrates `augmentPlanWithReconciliation`, `scanPlanReadiness`,
- * and `applyPlan` with the `ResolvePlanInteraction` port, and produces
- * one `OperationResolution` at every termination path. Channels project the
- * returned resolution; presentation and prompting live behind the port, and
- * per-type outcome refinement behind the optional
- * `ConfiguredAgentOutcomesProvider` port.
+ * `prepareExecutionCandidate` turns a plan into the immutable execution
+ * candidate every later step refers to: it augments the plan with lockfile
+ * reconciliation, projects configured-agent outcomes, scans readiness,
+ * assembles the semantic risk conditions, and fingerprints the material
+ * preimages. `resolveExecutionCandidate` presents that candidate, fails
+ * closed on blockers and missing policies, previews or confirms, acquires
+ * the workspace transition, revalidates the same candidate under it, applies
+ * it closure by closure, and produces one `OperationResolution` at every
+ * termination path. Presentation and prompting live behind the
+ * `ResolvePlanInteraction` port; per-type outcome refinement behind the
+ * `ConfiguredAgentOutcomesProvider`.
  *
- * This is a free function, not a method on WorkspaceMutationsService.
  *
  * @experimental This API is unstable and may change without notice.
  */
 import * as Cause from "effect/Cause";
-import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
 import * as Effect from "effect/Effect";
-import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Ref from "effect/Ref";
 import { ApprovalRecoveryMissing, STALE_CANDIDATE_DETAIL, StaleExecutionCandidate, StepFailure, } from "./errors.js";
@@ -25,17 +27,13 @@ import { isExecutionCandidateFresh, makeExecutionCandidate, } from "./execution-
 import { augmentPlanWithReconciliation } from "../operations/augment-plan.js";
 import { scanPlanReadiness } from "../operations/scan-plan-readiness.js";
 import { declaredAtomicity, executedUnits, makeOperationResolution, plannedUnits, unitIdOf, } from "./operation-resolution.js";
-import { appendResolvedUnit, appendStartedUnit, recordJournalPhase, recordOperationJournal, } from "./operation-journal.js";
+import { OperationJournal, appendResolvedUnit, appendStartedUnit, recordJournalPhase, recordOperationJournal, } from "./operation-journal.js";
 import { CurrentOperationUnit, observeUnit, publishOperationEvent, publishPhaseStarted, publishWaitEnded, publishWaiting, } from "./operation-events.js";
-import { WorkspaceMutations } from "@agentxm/workspace-state";
-import { readPendingClosureRestorationFailures, WorkspaceRestorationIncomplete, } from "@agentxm/workspace-state";
-import { rollbackWorkspaceClosure, settleWorkspaceClosure, withWorkspaceClosure, } from "../operations/transaction.js";
-import { readFootprint } from "@agentxm/workspace-state";
+import { ConfiguredAgentOutcomesProvider, WorkspaceMutations, configuredAgentLifecycleOutcomes, } from "@agentxm/workspace-state";
+import { FootprintRecorder, WorkspaceRestorationIncomplete, acquireWorkspaceTransition, pendingClosureRestorations, readFootprint, rollbackWorkspaceClosure, runWorkspaceTransaction, settleWorkspaceClosure, withWorkspaceClosure, } from "@agentxm/workspace-transactions";
 import { InterruptionSignalSource } from "./interruption-signal.js";
 import { ResolvePlanInteraction } from "./resolve-plan-interaction.js";
 import { confirmationRecoverySuggestions, namedPolicyRecoverySuggestions, } from "./plan-execution.js";
-import { ConfiguredAgentOutcomesProvider } from "@agentxm/workspace-state";
-import { configuredAgentLifecycleOutcomes } from "@agentxm/workspace-state";
 import { candidateFingerprintFailedToStepFailure, configuredAgentOutcomesUnavailableToStepFailure, restorationIncompleteToStepFailure, workspaceStateReadFailureToStepFailure, workspaceTransactionFailureToStepFailure, } from "./step-failure-conversions.js";
 /** Publish a phase transition to the lifecycle stream and the journal. */
 const enterPhase = (phase) => publishPhaseStarted(phase).pipe(Effect.andThen(recordJournalPhase(phase)));
@@ -87,59 +85,30 @@ const withExecutedAgentOutcomes = (plan, outcomes) => ({
     })),
 });
 /**
- * Preview or apply (display, confirm, and execute) a plan using the workspace read model.
- *
- * Steps:
- * 1. Augment plan with lockfile reconciliation if needed
- * 2. Scan for errors/warnings
- * 3. Construct and display the exact candidate
- * 4. Fail closed on blockers and missing named policies
- * 5. Preview or approve confirmable semantic risk
- * 6. Revalidate and apply the same candidate
- *
- * Every termination path resolves to one `OperationResolution`.
+ * The generic lifecycle outcomes for one operation, refined by the provider's
+ * per-type override when the operation enables the extension.
  */
-export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (plan, options) {
-    const ws = yield* WorkspaceMutations;
-    const interaction = yield* ResolvePlanInteraction;
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const fsLayer = Layer.mergeAll(Layer.succeed(FileSystem.FileSystem, fs), Layer.succeed(Path.Path, path));
-    const mode = options.execution.request.mode;
-    yield* publishPhaseStarted("planning");
-    // Step 1: Lockfile reconciliation, observed as one planning unit.
-    const augmented = yield* observeUnit({ id: "lockfile-reconciliation", label: "lockfile reconciliation" }, augmentPlanWithReconciliation(plan, () => ws.getLockfileState()));
-    const operations = options.execution.configuredAgentOperations ?? [];
-    const configuredAgents = operations.length === 0 ? [] : yield* ws.getConfiguredAgents();
-    const outcomesProvider = yield* Effect.serviceOption(ConfiguredAgentOutcomesProvider);
-    const outcomesOverrideFor = (extensionType) => Option.isSome(outcomesProvider)
-        ? outcomesProvider.value.byExtensionType[extensionType]
-        : undefined;
-    const outcomesFor = (operation, state) => {
-        const generic = configuredAgentLifecycleOutcomes({
-            type: operation.extensionType,
-            name: operation.name,
-            agentIds: configuredAgents,
-            scope: ws.scope,
-            state,
-            targetState: operation.plannedState,
-            installed: state === "projected",
-            observedAgentIds: state === "projected" ? configuredAgents : [],
-        });
-        const override = outcomesOverrideFor(operation.extensionType);
-        if (operation.plannedState === "enabled" && override !== undefined) {
-            return override(state).pipe(Effect.map((outcomes) => outcomes.filter(({ name }) => name === operation.name)), Effect.map((outcomes) => (outcomes.length === 0 ? generic : outcomes)), Effect.catch(() => Effect.succeed(generic)));
-        }
-        return Effect.succeed(generic);
-    };
-    const projectedOutcomes = (yield* Effect.forEach(operations, (operation) => outcomesFor(operation, "projected"))).flat();
-    const augmentedPlan = operations.length === 0
-        ? augmented.plan
-        : withPlannedAgentOutcomes(augmented.plan, projectedOutcomes);
-    // Step 2: Scan readiness and construct semantic risk conditions.
-    const readiness = scanPlanReadiness(augmentedPlan);
-    const declaredConditionIds = new Set((augmentedPlan.riskConditions ?? []).map((condition) => condition.id));
-    const readinessBlockers = augmentedPlan.jobs.flatMap((job) => job.steps.flatMap((step) => step.readiness === "error"
+const outcomesFor = (ws, provider, configuredAgents, operation, state) => {
+    const generic = configuredAgentLifecycleOutcomes({
+        type: operation.extensionType,
+        name: operation.name,
+        agentIds: configuredAgents,
+        scope: ws.scope,
+        state,
+        targetState: operation.plannedState,
+        installed: state === "projected",
+        observedAgentIds: state === "projected" ? configuredAgents : [],
+    });
+    const override = provider.byExtensionType[operation.extensionType];
+    if (operation.plannedState === "enabled" && override !== undefined) {
+        return override(state).pipe(Effect.map((outcomes) => outcomes.filter(({ name }) => name === operation.name)), Effect.map((outcomes) => (outcomes.length === 0 ? generic : outcomes)), Effect.catch(() => Effect.succeed(generic)));
+    }
+    return Effect.succeed(generic);
+};
+/** The readiness blockers a plan's error steps contribute beyond declared conditions. */
+const readinessBlockersOf = (plan) => {
+    const declaredConditionIds = new Set((plan.riskConditions ?? []).map((condition) => condition.id));
+    return plan.jobs.flatMap((job) => job.steps.flatMap((step) => step.readiness === "error"
         ? (step.blockingConditionIds ?? []).length > 0 &&
             (step.blockingConditionIds ?? []).every((id) => declaredConditionIds.has(id))
             ? []
@@ -152,6 +121,27 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
                 },
             ]
         : []));
+};
+/**
+ * Prepare the immutable execution candidate for a plan: augment with lockfile
+ * reconciliation, project configured-agent outcomes, scan readiness, assemble
+ * risk conditions, and fingerprint every material preimage. Preview,
+ * confirmation, and apply all refer to the candidate this returns.
+ */
+export const prepareExecutionCandidate = Effect.fn("prepareExecutionCandidate")(function* (plan, options) {
+    const ws = yield* WorkspaceMutations;
+    const provider = yield* ConfiguredAgentOutcomesProvider;
+    yield* publishPhaseStarted("planning");
+    // Lockfile reconciliation, observed as one planning unit.
+    const augmented = yield* observeUnit({ id: "lockfile-reconciliation", label: "lockfile reconciliation" }, augmentPlanWithReconciliation(plan, () => ws.getLockfileState()));
+    const operations = options?.configuredAgentOperations ?? [];
+    const configuredAgents = operations.length === 0 ? [] : yield* ws.getConfiguredAgents();
+    const projectedOutcomes = (yield* Effect.forEach(operations, (operation) => outcomesFor(ws, provider, configuredAgents, operation, "projected"))).flat();
+    const augmentedPlan = operations.length === 0
+        ? augmented.plan
+        : withPlannedAgentOutcomes(augmented.plan, projectedOutcomes);
+    // Readiness blockers and unmet preconditions join the declared risk
+    // conditions, so the candidate carries every reason it could be refused.
     const preconditionBlockers = (augmentedPlan.preconditions ?? []).flatMap((precondition) => precondition.status === "unmet"
         ? [
             {
@@ -166,18 +156,46 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
         : []);
     const riskConditions = [
         ...(augmentedPlan.riskConditions ?? []),
-        ...readinessBlockers,
+        ...readinessBlockersOf(augmentedPlan),
         ...preconditionBlockers,
     ];
     const candidatePlan = {
         ...augmentedPlan,
         ...(riskConditions.length === 0 ? {} : { riskConditions }),
     };
-    const candidate = yield* makeExecutionCandidate(candidatePlan, {
+    return yield* makeExecutionCandidate(candidatePlan, {
         settingsPath: ws.layout.settingsPath,
         lockPath: ws.layout.lockPath,
         baseDir: ws.baseDir,
-    }).pipe(Effect.provide(fsLayer));
+    }, operations);
+});
+/**
+ * Preview or apply a prepared candidate.
+ *
+ * 1. Present the immutable candidate.
+ * 2. Fail closed on blockers and missing named policies.
+ * 3. Preview, or approve confirmable semantic risk.
+ * 4. Acquire the workspace transition, revalidate the same candidate under
+ *    it, and apply it closure by closure.
+ *
+ * Every termination path resolves to one `OperationResolution`.
+ */
+export const resolveExecutionCandidate = Effect.fn("resolveExecutionCandidate")(function* (candidate, execution, options) {
+    const ws = yield* WorkspaceMutations;
+    const provider = yield* ConfiguredAgentOutcomesProvider;
+    const interaction = yield* ResolvePlanInteraction;
+    const path = yield* Path.Path;
+    // The journal and footprint recorder are requirements of the operation
+    // boundary: the settlement observers below record into them.
+    const journal = yield* OperationJournal;
+    yield* FootprintRecorder;
+    const mode = execution.request.mode;
+    const candidatePlan = candidate.plan;
+    const operations = candidate.configuredAgentOperations;
+    const configuredAgents = operations.length === 0 ? [] : yield* ws.getConfiguredAgents();
+    const readiness = scanPlanReadiness(candidatePlan);
+    const readinessBlockers = readinessBlockersOf(candidatePlan);
+    const riskConditions = candidatePlan.riskConditions ?? [];
     const atomicity = declaredAtomicity(candidatePlan);
     const resolutionBase = {
         name: candidatePlan.name,
@@ -218,13 +236,13 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
         failure: over.failure,
         suggestions: candidatePlan.failureSuggestions,
     });
-    // Step 3: Display the immutable candidate before any policy terminal or effect.
+    // Display the immutable candidate before any policy terminal or effect.
     if (mode === "preview") {
         yield* enterPhase("preview");
     }
     const hasConfirmableRisk = riskConditions.some((condition) => condition.level === "confirmable");
     yield* interaction.presentPlan(candidatePlan, { mode });
-    // Step 4: Hard blockers dominate preview, overrides, and confirmation.
+    // Hard blockers dominate preview, overrides, and confirmation.
     if (readiness.hasErrors) {
         const firstError = readinessBlockers[0];
         return notExecuted({
@@ -250,18 +268,18 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
             },
         });
     }
-    // Step 5: Preview is speculative and never grants approval to a later invocation.
-    if (options.execution.request.mode === "preview") {
+    // Preview is speculative and never grants approval to a later invocation.
+    if (execution.request.mode === "preview") {
         return makeOperationResolution({
             ...resolutionBase,
             atomicity: { declared: atomicity, applied: "closure-atomic" },
             units: plannedUnits(candidatePlan.jobs),
         });
     }
-    if (!("approvalRecovery" in options.execution)) {
+    if (!("approvalRecovery" in execution)) {
         return yield* new ApprovalRecoveryMissing();
     }
-    const applyExecution = options.execution;
+    const applyExecution = execution;
     const overrideConditions = riskConditions.filter((condition) => condition.level === "override-required");
     const missingOverrides = overrideConditions.filter((condition) => !applyExecution.request.acceptedPolicies.has(condition.policy));
     if (missingOverrides.length > 0) {
@@ -281,8 +299,8 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
             suggestions: escapes,
         });
     }
-    // Step 5b: Confirmation. A condition that consents only at a prompt — a
-    // publisher change, or any confirmable condition met by a command with no
+    // Confirmation. A condition that consents only at a prompt — a publisher
+    // change, or any confirmable condition met by a command with no
     // preapprovable confirmation — is never satisfied by preapproval. A
     // preapprovable condition is satisfied by explicit preapproval; otherwise
     // it is asked when a prompt can open and blocks when one cannot, naming
@@ -319,7 +337,7 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
             }
         }
     }
-    // Step 6: Acquire the workspace transition — planning, network acquisition,
+    // Acquire the workspace transition — planning, network acquisition,
     // preview, and confirmation ran without it — then revalidate every material
     // candidate preimage and apply the exact candidate while holding it.
     const totalUnits = candidate.plan.jobs.reduce((count, job) => count + job.steps.length, 0);
@@ -329,16 +347,16 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
         description: candidatePlan.description,
         jobs: [{ concurrency: 1, steps: [step] }],
     }, { restored: false })[0]?.state ?? "committed";
-    let startedUnits = 0;
-    let resolvedUnits = 0;
+    const startedUnits = yield* Ref.make(0);
+    const resolvedUnits = yield* Ref.make(0);
     const applyFreshCandidate = Effect.gen(function* () {
         yield* enterPhase("validation");
-        if (!(yield* isExecutionCandidateFresh(candidate).pipe(Effect.provide(fsLayer)))) {
+        if (!(yield* isExecutionCandidateFresh(candidate))) {
             return yield* new StaleExecutionCandidate({ candidate: candidatePlan.name });
         }
-        if (options.beforeApply !== undefined) {
+        if (options?.beforeApply !== undefined) {
             yield* options.beforeApply(candidate);
-            if (!(yield* isExecutionCandidateFresh(candidate).pipe(Effect.provide(fsLayer)))) {
+            if (!(yield* isExecutionCandidateFresh(candidate))) {
                 return yield* new StaleExecutionCandidate({ candidate: candidatePlan.name });
             }
         }
@@ -361,29 +379,29 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
         return yield* applyPlan(closureScopedPlan, {
             // The started fact is journaled before the run's first effect, so an
             // interruption mid-run reports the unit in flight, never not attempted.
-            onStepStarted: (step) => appendStartedUnit(unitIdOf(step)).pipe(Effect.andThen(publishOperationEvent((seq, atMs) => ({
+            onStepStarted: (step) => appendStartedUnit(unitIdOf(step)).pipe(Effect.provideService(OperationJournal, journal), Effect.andThen(Ref.getAndUpdate(startedUnits, (index) => index + 1)), Effect.flatMap((index) => publishOperationEvent((seq, atMs) => ({
                 _tag: "UnitStarted",
                 seq,
                 atMs,
                 unitId: unitIdOf(step),
                 label: step.label,
-                index: startedUnits++,
+                index,
                 total: totalUnits,
             })))),
             // Settlement runs before the next interruptible boundary: the journal
             // fact and the closure's snapshot disposition are recorded together —
             // a settled closure's commits stand, a failed closure restores only
             // itself, and later ready closures continue.
-            onStepCompleted: (step) => appendResolvedUnit(step).pipe(Effect.andThen(step.result.result === "error"
+            onStepCompleted: (step) => appendResolvedUnit(step).pipe(Effect.provideService(OperationJournal, journal), Effect.andThen(step.result.result === "error"
                 ? rollbackWorkspaceClosure(unitIdOf(step))
-                : settleWorkspaceClosure(unitIdOf(step))), Effect.andThen(publishOperationEvent((seq, atMs) => ({
+                : settleWorkspaceClosure(unitIdOf(step))), Effect.andThen(Ref.getAndUpdate(resolvedUnits, (index) => index + 1)), Effect.flatMap((index) => publishOperationEvent((seq, atMs) => ({
                 _tag: "UnitResolved",
                 seq,
                 atMs,
                 unitId: unitIdOf(step),
                 label: step.label,
                 state: resolvedUnitState(step),
-                index: resolvedUnits++,
+                index,
                 total: totalUnits,
             })))),
         });
@@ -402,7 +420,7 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
         // apply-level failure is a closure rollback that did not complete and
         // verify — the typed restoration fact derives the retained truth from
         // the in-memory pending record alone.
-        const pendingRestoration = yield* readPendingClosureRestorationFailures;
+        const pendingRestoration = yield* pendingClosureRestorations;
         if (Option.isSome(pendingRestoration) && pendingRestoration.value.failures.length > 0) {
             const pending = pendingRestoration.value;
             const first = pending.failures[0];
@@ -433,7 +451,7 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
             return { ...result, candidateId: candidate.id };
         }
         const currentOutcomes = (yield* Effect.forEach(operations, (operation) => {
-            const override = outcomesOverrideFor(operation.extensionType);
+            const override = provider.byExtensionType[operation.extensionType];
             return operation.plannedState === "enabled" && override !== undefined
                 ? override("current").pipe(Effect.map((outcomes) => outcomes.filter(({ name }) => name === operation.name)), Effect.mapError(configuredAgentOutcomesUnavailableToStepFailure))
                 : operation.plannedState === "enabled"
@@ -482,11 +500,11 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
         (value.error._tag === "StepFailure" || value.error._tag === "StaleExecutionCandidate");
     const guardedApply = (candidatePlan.executionCapabilities?.rollback === "non-rollbackable"
         ? applyCandidate
-        : ws.runTransaction({
+        : runWorkspaceTransaction({
             targets: [],
             transition: applyCandidate,
             validate: () => Effect.void,
-            onRestorationStarted: enterPhase("restoration"),
+            onRestorationStarted: enterPhase("restoration").pipe(Effect.provideService(OperationJournal, journal)),
             // Closures protect the shared settings and lockfile at their own
             // first touch; claiming them here would let a late failure tear an
             // earlier closure's settled commit out of the shared files.
@@ -514,7 +532,7 @@ export const previewOrApplyPlan = Effect.fn("previewOrApplyPlan")(function* (pla
     const transitionSubject = "workspace-transition";
     const applyResult = yield* Effect.scoped(Effect.gen(function* () {
         const waited = yield* Ref.make(false);
-        const contention = yield* ws.acquireTransition({
+        const contention = yield* acquireWorkspaceTransition({
             command: applyExecution.approvalRecovery.command.join(" "),
             candidateId: candidate.id,
             // Contention is a first-class lifecycle fact: observers render the

package/dist/src/plan/step-failure-conversions.d.ts

@@ -7,7 +7,8 @@
  *
  * @experimental This API is unstable and may change without notice.
  */
-import type { ConfiguredAgentOutcomesUnavailable, WorkspaceRestorationIncomplete, WorkspaceStateReadFailure, WorkspaceTransactionFailure } from "@agentxm/workspace-state";
+import type { ConfiguredAgentOutcomesUnavailable, WorkspaceStateReadFailure } from "@agentxm/workspace-state";
+import type { WorkspaceRestorationIncomplete, WorkspaceTransactionFailure } from "@agentxm/workspace-transactions";
 import { StepFailure, type CandidateFingerprintFailed } from "./errors.js";
 /** Translate a scoped settings- or lockfile-read failure, naming the fix. */
 export declare const workspaceStateReadFailureToStepFailure: (error: WorkspaceStateReadFailure) => StepFailure;

package/dist/src/testing.d.ts

@@ -7,7 +7,28 @@
  * @experimental This API is unstable and may change without notice.
  * @packageDocumentation
  */
+import * as Layer from "effect/Layer";
+import { ConfiguredAgentOutcomesProvider } from "@agentxm/workspace-state";
+import { FootprintRecorder } from "@agentxm/workspace-transactions";
+import { OperationJournal } from "./plan/operation-journal.js";
+/**
+ * An empty journal for one test invocation, standing in for the
+ * per-invocation journal the CLI's operation lifecycle creates around every
+ * command. Provide it wherever a test drives a plan directly instead of
+ * through that lifecycle. A test that asserts on what was recorded should
+ * build the service itself with `makeOperationJournal` and keep the ref.
+ */
+export declare const OperationJournalTest: Layer.Layer<OperationJournal>;
+/** A fresh footprint recorder for one test invocation. */
+export declare const FootprintRecorderTest: Layer.Layer<FootprintRecorder>;
+/**
+ * Every per-invocation service `resolveExecutionCandidate` acquires that the CLI's
+ * operation lifecycle opens around a command: the journal, the footprint
+ * recorder, and a configured-agent outcome provider with no per-type
+ * refinement. A test that drives a plan directly needs all of them, so this
+ * is the layer to reach for rather than assembling the three by hand.
+ */
+export declare const PlanInvocationTest: Layer.Layer<OperationJournal | FootprintRecorder | ConfiguredAgentOutcomesProvider>;
 export { ResolvePlanInteractionTest, type ResolvePlanInteractionTestState, } from "./plan/resolve-plan-interaction.js";
 export { interactiveOnlyPlanExecution, preapprovedPlanExecution, promptablePlanExecution, } from "./plan/plan-execution-fixtures.js";
-export { makeMemoryTransitionLockWorld, type MemoryTransitionLockWorld, } from "./operations/memory-transition-lock.js";
 //# sourceMappingURL=testing.d.ts.map