@agentxm/workspace-operations 0.28.12 → 0.28.13

package/dist/src/index.d.ts

@@ -1,31 +1,32 @@
 /**
  * @agentxm/workspace-operations public API.
  *
- * The workspace-operations kernel: plan vocabulary and execution, the
- * interactive preview/apply orchestration (`previewOrApplyPlan`), operation
- * resolutions and journals, plan readiness and reconciliation gating, and the
- * workspace transaction and transition-lock machinery. The composed workspace
- * layer lives behind `./live`.
+ * The workspace-operations capability: plan vocabulary and execution, the
+ * two-phase candidate orchestration (`prepareExecutionCandidate` then
+ * `resolveExecutionCandidate`), operation resolutions and journals, and plan
+ * readiness and reconciliation gating. Transactions and the transition lock
+ * live in `@agentxm/workspace-transactions`; the composed workspace layer in
+ * `@agentxm/workspace-state/live`.
  *
  * @experimental This API is unstable and may change without notice.
  * @packageDocumentation
  */
 export { BlockingClassSchema, defaultOperationPresentation, operationPresentation, presentationOf, ArtifactMechanismSchema, ConfirmableConsentSchema, OperationPreconditionSchema, PlanPolicyIdSchema, PlanPolicyIds, PlanRiskConditionSchema, } from "./plan/plan.js";
-export type { ArtifactMechanism, BlockingClass, CompletedJobStep, ConfirmableConsent, ErrorJobStep, ExecutedJob, ExecutedPlan, Job, JobStepArtifact, JobStepArtifactSource, JobStepArtifactTarget, JobStepResult, Operation, OperationPrecondition, OperationPresentation, Plan, PlanPolicyId, PlanRiskCondition, PlannedJobStep, ReadyJobStep, RegistryBindingProposal, RegistryLifecycleEvidence, UnitBlocking, WarnJobStep, } from "./plan/plan.js";
+export type { ArtifactMechanism, BlockingClass, CompletedJobStep, ConfirmableConsent, ErrorJobStep, ExecutedJob, ExecutedPlan, Job, JobStepArtifact, JobStepArtifactSource, JobStepArtifactTarget, JobStepResult, Operation, OperationPrecondition, OperationPresentation, Plan, PlanExecutionCapabilities, PlanPolicyId, PlanRiskCondition, PlannedJobStep, ReadyJobStep, RegistryLifecycleEvidence, UnitBlocking, WarnJobStep, } from "./plan/plan.js";
 export { AtomicityClassSchema, OperationOutcomeSchema, OperationPhaseSchema, UnitDispositionSchema, UnitStateSchema, countUnitStates, declaredAtomicity, deriveOperationOutcome, executedUnits, makeOperationResolution, plannedUnits, unitIdOf, unitsByStableIdentity, } from "./plan/operation-resolution.js";
 export type { AtomicityClass, MakeOperationResolutionArgs, OperationAtomicity, OperationBlock, OperationFootprintEntry, OperationInterruption, OperationOutcome, OperationPhase, OperationRecovery, OperationResolution, ResolvedUnit, UnitDisposition, UnitState, UnitStateCounts, } from "./plan/operation-resolution.js";
 export { OperationJournal, appendResolvedUnit, appendStartedUnit, recordJournalPhase, getOperationJournal, makeOperationJournal, recordOperationJournal, updateOperationJournal, type OperationJournalService, type OperationJournalState, } from "./plan/operation-journal.js";
 export { applyPlan, type ApplyPlanOptions, type OperationHandler } from "./plan/apply-plan.js";
 export { CurrentOperationUnit, OperationEventSchema, OperationLifecycle, OperationModeSchema, ProgressUnitSchema, SettledOutcomeSchema, awaitDrained, lifecycleEvents, makeOperationLifecycle, makeThrottledUnitProgress, observeChildUnit, observeUnit, publishOperationEvent, publishPhaseStarted, publishUnitProgress, publishWaitEnded, publishWaiting, settleOperation, subscribeLossless, type ObservedUnit, type OperationEvent, type OperationEventEncoded, type OperationEventInput, type OperationLifecycleService, type OperationMode, type ProgressUnit, type SettledOutcome, } from "./plan/operation-events.js";
 export { ApprovalRecoveryMissing, CandidateFingerprintFailed, OPERATION_ERROR_CATEGORIES, OperationErrorCategorySchema, PlanInteractionFailed, STALE_CANDIDATE_DETAIL, StaleExecutionCandidate, StepFailure, type OperationErrorCategory, } from "./plan/errors.js";
-export { previewOrApplyPlan } from "./plan/resolve-plan.js";
+export { prepareExecutionCandidate, resolveExecutionCandidate, type PrepareExecutionCandidateOptions, type ResolveExecutionCandidateOptions, } from "./plan/resolve-plan.js";
+export { candidateFingerprintFailedToStepFailure, configuredAgentOutcomesUnavailableToStepFailure, restorationIncompleteToStepFailure, workspaceStateReadFailureToStepFailure, workspaceTransactionFailureToStepFailure, } from "./plan/step-failure-conversions.js";
 export { ResolvePlanInteraction, type ApplyConfirmation, type ResolvePlanInteractionService, } from "./plan/resolve-plan-interaction.js";
 export { InterruptionSignalSource, type InterruptionSignalSourceService, } from "./plan/interruption-signal.js";
+export { resolveInterruption, type InterruptedInvocation, type ObservedFootprintEntry, } from "./plan/interruption-resolution.js";
 export { isExecutionCandidateFresh, makeExecutionCandidate, type ExecutionCandidate, } from "./plan/execution-candidate.js";
-export { applyPlanExecution, confirmationRecoverySuggestions, namedPolicyRecoverySuggestions, credentialFreeLocatorRecoveryValue, previewPlanExecution, protectedRecoveryValue, publicRecoveryValue, recoveryOption, recoveryPositional, recoverySwitch, renderConfirmationRecoveryCommand, unclassifiedRecoveryValue, type ConfirmableRiskApproval, type ConfirmationRecovery, type ConfirmationRecoveryArgument, type ConfirmationRecoveryValue, type ConfiguredAgentOperation, type PlanExecution, type PlanExecutionRequest, type RecoveryApproval, } from "./plan/plan-execution.js";
+export { applyPlanExecution, confirmableRiskApproval, confirmationRecoverySuggestions, namedPolicyRecoverySuggestions, credentialFreeLocatorRecoveryValue, previewPlanExecution, protectedRecoveryValue, publicRecoveryValue, recoveryOption, recoveryPositional, recoverySwitch, renderConfirmationRecoveryCommand, requestedPlanExecution, unclassifiedRecoveryValue, type ConfirmableRiskApproval, type ConfirmationRecovery, type ConfirmationRecoveryArgument, type ConfirmationRecoveryValue, type ConfiguredAgentOperation, type PlanExecution, type PlanExecutionRequest, type RecoveryApproval, type RequestedApproval, type RequestedPlanIntent, } from "./plan/plan-execution.js";
 export * from "./plan/job-step-message.js";
 export { scanPlanReadiness, type PlanReadinessReport } from "./operations/scan-plan-readiness.js";
 export { augmentPlanWithReconciliation, type AugmentedPlanResult, type DegradedLockfileState, } from "./operations/augment-plan.js";
-export { rollbackWorkspaceClosure, runWorkspaceTransaction, settleWorkspaceClosure, withWorkspaceClosure, type WorkspaceTransactionArgs, } from "./operations/transaction.js";
-export { liveWorkspaceTransitionLock, type WorkspaceTransitionLock, TRANSITION_WAIT_BOUND_MILLIS, acquireWorkspaceTransitionLock, heldWorkspaceTransition, isWorkspaceTransitionHeldByThisInvocation, transitionLockPath, type HeldWorkspaceTransition, } from "./operations/transition-lock.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -1,11 +1,12 @@
 /**
  * @agentxm/workspace-operations public API.
  *
- * The workspace-operations kernel: plan vocabulary and execution, the
- * interactive preview/apply orchestration (`previewOrApplyPlan`), operation
- * resolutions and journals, plan readiness and reconciliation gating, and the
- * workspace transaction and transition-lock machinery. The composed workspace
- * layer lives behind `./live`.
+ * The workspace-operations capability: plan vocabulary and execution, the
+ * two-phase candidate orchestration (`prepareExecutionCandidate` then
+ * `resolveExecutionCandidate`), operation resolutions and journals, and plan
+ * readiness and reconciliation gating. Transactions and the transition lock
+ * live in `@agentxm/workspace-transactions`; the composed workspace layer in
+ * `@agentxm/workspace-state/live`.
  *
  * @experimental This API is unstable and may change without notice.
  * @packageDocumentation
@@ -23,21 +24,24 @@ export { applyPlan } from "./plan/apply-plan.js";
 export { CurrentOperationUnit, OperationEventSchema, OperationLifecycle, OperationModeSchema, ProgressUnitSchema, SettledOutcomeSchema, awaitDrained, lifecycleEvents, makeOperationLifecycle, makeThrottledUnitProgress, observeChildUnit, observeUnit, publishOperationEvent, publishPhaseStarted, publishUnitProgress, publishWaitEnded, publishWaiting, settleOperation, subscribeLossless, } from "./plan/operation-events.js";
 // Serialized error vocabulary and the plan-family tagged errors.
 export { ApprovalRecoveryMissing, CandidateFingerprintFailed, OPERATION_ERROR_CATEGORIES, OperationErrorCategorySchema, PlanInteractionFailed, STALE_CANDIDATE_DETAIL, StaleExecutionCandidate, StepFailure, } from "./plan/errors.js";
-// Interactive preview/apply orchestration over the workspace read model.
-export { previewOrApplyPlan } from "./plan/resolve-plan.js";
+// Candidate preparation and interactive preview/apply resolution over the
+// workspace read model: preview, confirmation and apply share one candidate,
+// so what a person reads and what is applied are the same decision.
+export { prepareExecutionCandidate, resolveExecutionCandidate, } from "./plan/resolve-plan.js";
+// Conversions from the kernel families a step can surface into the
+// serialized step vocabulary, so a producer serializes them identically
+// wherever the step was assembled.
+export { candidateFingerprintFailedToStepFailure, configuredAgentOutcomesUnavailableToStepFailure, restorationIncompleteToStepFailure, workspaceStateReadFailureToStepFailure, workspaceTransactionFailureToStepFailure, } from "./plan/step-failure-conversions.js";
 // Interaction port for preview/apply presentation, progress, and confirmation.
 // The CLI runtime provides the Live implementation.
 export { ResolvePlanInteraction, } from "./plan/resolve-plan-interaction.js";
 export { InterruptionSignalSource, } from "./plan/interruption-signal.js";
+export { resolveInterruption, } from "./plan/interruption-resolution.js";
 export { isExecutionCandidateFresh, makeExecutionCandidate, } from "./plan/execution-candidate.js";
-export { applyPlanExecution, confirmationRecoverySuggestions, namedPolicyRecoverySuggestions, credentialFreeLocatorRecoveryValue, previewPlanExecution, protectedRecoveryValue, publicRecoveryValue, recoveryOption, recoveryPositional, recoverySwitch, renderConfirmationRecoveryCommand, unclassifiedRecoveryValue, } from "./plan/plan-execution.js";
+export { applyPlanExecution, confirmableRiskApproval, confirmationRecoverySuggestions, namedPolicyRecoverySuggestions, credentialFreeLocatorRecoveryValue, previewPlanExecution, protectedRecoveryValue, publicRecoveryValue, recoveryOption, recoveryPositional, recoverySwitch, renderConfirmationRecoveryCommand, requestedPlanExecution, unclassifiedRecoveryValue, } from "./plan/plan-execution.js";
 // Job step messaging
 export * from "./plan/job-step-message.js";
 // Plan readiness and reconciliation gating
 export { scanPlanReadiness } from "./operations/scan-plan-readiness.js";
 export { augmentPlanWithReconciliation, } from "./operations/augment-plan.js";
-// Workspace transaction runner and closure lifecycle
-export { rollbackWorkspaceClosure, runWorkspaceTransaction, settleWorkspaceClosure, withWorkspaceClosure, } from "./operations/transaction.js";
-// Transition lock runtime
-export { liveWorkspaceTransitionLock, TRANSITION_WAIT_BOUND_MILLIS, acquireWorkspaceTransitionLock, heldWorkspaceTransition, isWorkspaceTransitionHeldByThisInvocation, transitionLockPath, } from "./operations/transition-lock.js";
 //# sourceMappingURL=index.js.map

package/dist/src/operations/scan-plan-readiness.d.ts

@@ -1,7 +1,7 @@
 /**
  * Pure function to scan a plan's steps and collect readiness statistics.
  *
- * Extracts from the inline logic in `previewOrApplyPlan` so it can be tested
+ * Extracts from the inline logic in `resolveExecutionCandidate` so it can be tested
  * independently and reused from core without CLI dependencies.
  *
  * @experimental This API is unstable and may change without notice.

package/dist/src/operations/scan-plan-readiness.js

@@ -1,7 +1,7 @@
 /**
  * Pure function to scan a plan's steps and collect readiness statistics.
  *
- * Extracts from the inline logic in `previewOrApplyPlan` so it can be tested
+ * Extracts from the inline logic in `resolveExecutionCandidate` so it can be tested
  * independently and reused from core without CLI dependencies.
  *
  * @experimental This API is unstable and may change without notice.

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

@@ -14,6 +14,7 @@
  */
 import * as Array from "effect/Array";
 import * as Effect from "effect/Effect";
+import * as Ref from "effect/Ref";
 import { StepFailure } from "./errors.js";
 // -----------------------------------------------------------------------------
 // Implementation
@@ -202,10 +203,12 @@ 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;
+    // Any job with an error blocks every later job; the fact travels in a
+    // `Ref` because it crosses the job traversal's iteration boundary.
+    const blocked = yield* Ref.make(false);
     const jobResults = hasReadinessError
         ? applyReadinessGate(plan)
-        : yield* Effect.forEach(plan.jobs, (job) => blocked
+        : yield* Effect.forEach(plan.jobs, (job) => Effect.flatMap(Ref.get(blocked), (isBlocked) => isBlocked
             ? Effect.succeed(job.steps.map((step) => blockStep(step, "blocked by earlier job failure", {
                 class: "operation-aborted",
             })))
@@ -213,12 +216,9 @@ export const applyPlan = (plan, options) => Effect.gen(function* () {
                 ? 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 });
+                    : executeFailFastJob(job, observeStart, observeStep)).pipe(Effect.tap((steps) => steps.some((step) => step.result.result === "error")
+                ? Ref.set(blocked, true)
+                : Effect.void))), { concurrency: 1 });
     return {
         _tag: "ExecutedPlan",
         name: plan.name,

package/dist/src/plan/execution-candidate.d.ts

@@ -3,6 +3,7 @@ import * as Path from "effect/Path";
 import * as Effect from "effect/Effect";
 import { CandidateFingerprintFailed } from "./errors.js";
 import type { Plan } from "./plan.js";
+import type { ConfiguredAgentOperation } from "./plan-execution.js";
 export interface ExecutionCandidate<Requirements = never, Output = never> {
     readonly id: string;
     readonly plan: Plan<Requirements, Output>;
@@ -10,11 +11,16 @@ export interface ExecutionCandidate<Requirements = never, Output = never> {
     readonly materialFingerprint: string;
     /** Base the material fingerprint is relative to; freshness recomputes against it. */
     readonly baseDir: string;
+    /**
+     * Configured-agent operations whose outcomes the candidate projected into
+     * its steps and verifies after apply.
+     */
+    readonly configuredAgentOperations: ReadonlyArray<ConfiguredAgentOperation>;
 }
 export declare const makeExecutionCandidate: <Requirements, Output>(plan: Plan<Requirements, Output>, paths: {
     readonly settingsPath: string;
     readonly lockPath: string;
     readonly baseDir: string;
-}) => Effect.Effect<ExecutionCandidate<Requirements, Output>, CandidateFingerprintFailed, FileSystem.FileSystem | Path.Path>;
+}, configuredAgentOperations?: ReadonlyArray<ConfiguredAgentOperation>) => Effect.Effect<ExecutionCandidate<Requirements, Output>, CandidateFingerprintFailed, FileSystem.FileSystem | Path.Path>;
 export declare const isExecutionCandidateFresh: (candidate: ExecutionCandidate<unknown, unknown>) => Effect.Effect<boolean, CandidateFingerprintFailed, FileSystem.FileSystem | Path.Path>;
 //# sourceMappingURL=execution-candidate.d.ts.map

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

@@ -73,7 +73,7 @@ const planIdentity = (plan, baseDir, path) => JSON.stringify({
         ? path.relative(baseDir, value)
         : value;
 });
-export const makeExecutionCandidate = (plan, paths) => Effect.gen(function* () {
+export const makeExecutionCandidate = (plan, paths, configuredAgentOperations = []) => Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
     const materialPaths = resolveMaterialPaths(plan, paths.settingsPath, paths.lockPath, paths.baseDir, path);
@@ -84,7 +84,14 @@ export const makeExecutionCandidate = (plan, paths) => Effect.gen(function* () {
         .update("\0")
         .update(materialFingerprint)
         .digest("hex");
-    return { id, plan, materialPaths, materialFingerprint, baseDir: paths.baseDir };
+    return {
+        id,
+        plan,
+        materialPaths,
+        materialFingerprint,
+        baseDir: paths.baseDir,
+        configuredAgentOperations,
+    };
 });
 export const isExecutionCandidateFresh = (candidate) => Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;

package/dist/src/plan/interruption-resolution.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The terminal resolution of an interrupted operation.
+ *
+ * Interruption is the one lifecycle fact the operation body cannot settle for
+ * itself: the signal arrives from outside it. Turning the operation journal
+ * into a contract-valid resolution — which closures settled, which were in
+ * flight, what durable state is retained, and which atomicity class actually
+ * held — is execution semantics, so it lives beside closure execution rather
+ * than in a transport adapter. The caller supplies only the resume command it
+ * would print, because how an operator re-runs a request is a property of the
+ * surface that accepted it.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type * as Option from "effect/Option";
+import { type AtomicityClass, type OperationResolution } from "./operation-resolution.js";
+import type { OperationPresentation } from "./plan.js";
+import type { OperationJournalState } from "./operation-journal.js";
+/** What the invoking surface knows about a request the signal cut short. */
+export interface InterruptedInvocation {
+    /** Operation name for a resolution produced before planning completed. */
+    readonly planName: string;
+    readonly mode: "preview" | "apply";
+    /**
+     * The command family's statically declared atomicity, for a resolution
+     * produced before the journal exists. Defaults to `closure-atomic`.
+     */
+    readonly declaredAtomicity?: AtomicityClass;
+    readonly presentation?: OperationPresentation;
+    /** The command an operator re-runs to continue; the surface renders it. */
+    readonly replayCommand: string;
+}
+/** One durable path the footprint recorder observed before the signal landed. */
+export interface ObservedFootprintEntry {
+    readonly path: string;
+    readonly change: "created" | "modified" | "removed" | "restored";
+}
+/**
+ * Derive the terminal resolution for an externally interrupted invocation.
+ *
+ * Before the journal exists nothing was planned or attempted: the resolution
+ * carries the requested mode and the command family's declared atomicity,
+ * never a hardcoded apply/closure-atomic claim. Once apply has begun, settled
+ * closures keep their settlement — a commit stands as retained durable state,
+ * and a failure of a restoring apply had already rolled back only its own
+ * closure — while a unit that started without a settlement fact is reported
+ * `interrupted`, never as not attempted.
+ */
+export declare const resolveInterruption: (invocation: InterruptedInvocation, journal: Option.Option<OperationJournalState>, signal: "SIGINT" | "SIGTERM", footprint: ReadonlyArray<ObservedFootprintEntry>) => OperationResolution<unknown>;
+//# sourceMappingURL=interruption-resolution.d.ts.map

package/dist/src/plan/interruption-resolution.js

@@ -0,0 +1,158 @@
+/**
+ * The terminal resolution of an interrupted operation.
+ *
+ * Interruption is the one lifecycle fact the operation body cannot settle for
+ * itself: the signal arrives from outside it. Turning the operation journal
+ * into a contract-valid resolution — which closures settled, which were in
+ * flight, what durable state is retained, and which atomicity class actually
+ * held — is execution semantics, so it lives beside closure execution rather
+ * than in a transport adapter. The caller supplies only the resume command it
+ * would print, because how an operator re-runs a request is a property of the
+ * surface that accepted it.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as OptionModule from "effect/Option";
+import { executedUnits, makeOperationResolution, unitIdOf, } from "./operation-resolution.js";
+/**
+ * Derive the terminal resolution for an externally interrupted invocation.
+ *
+ * Before the journal exists nothing was planned or attempted: the resolution
+ * carries the requested mode and the command family's declared atomicity,
+ * never a hardcoded apply/closure-atomic claim. Once apply has begun, settled
+ * closures keep their settlement — a commit stands as retained durable state,
+ * and a failure of a restoring apply had already rolled back only its own
+ * closure — while a unit that started without a settlement fact is reported
+ * `interrupted`, never as not attempted.
+ */
+export const resolveInterruption = (invocation, journal, signal, footprint) => {
+    const observedFootprint = footprint.length === 0 ? {} : { footprint };
+    if (OptionModule.isNone(journal)) {
+        return makeOperationResolution({
+            name: invocation.planName,
+            description: OptionModule.none(),
+            mode: invocation.mode,
+            atomicity: {
+                declared: invocation.declaredAtomicity ?? "closure-atomic",
+                // Nothing was attempted, so no durable effect was made or retained.
+                applied: "closure-atomic",
+            },
+            units: [],
+            presentation: invocation.presentation,
+            interruption: { signal, disposition: "none" },
+            ...observedFootprint,
+        });
+    }
+    const state = journal.value;
+    const applying = state.phase === "apply" || state.phase === "restoration";
+    if (!applying) {
+        // Planning, preview, confirmation, or validation: nothing was attempted
+        // and the planned units stand as planned.
+        return makeOperationResolution({
+            name: state.name,
+            description: state.description,
+            mode: state.mode,
+            candidateId: state.candidateId,
+            atomicity: { declared: state.atomicity.declared, applied: "closure-atomic" },
+            units: state.plannedUnits,
+            presentation: state.presentation ?? invocation.presentation,
+            releaseAge: state.releaseAge,
+            preconditions: state.preconditions,
+            riskConditions: state.riskConditions,
+            interruption: { signal, disposition: "none" },
+            ...observedFootprint,
+        });
+    }
+    const resolvedUnits = executedUnits({
+        _tag: "ExecutedPlan",
+        name: state.name,
+        description: state.description,
+        jobs: [{ concurrency: 1, steps: state.resolved }],
+    });
+    // Closures settle independently: a settled commit stands as retained
+    // durable state regardless of the interruption, and a settled failure of a
+    // restoring apply had already rolled back only its own closure.
+    const settledUnits = resolvedUnits.map((unit) => unit.state === "committed"
+        ? { ...unit, disposition: "retained" }
+        : unit.state === "failed" && state.restoresOnFailure
+            ? { ...unit, disposition: "restored" }
+            : unit);
+    const resolvedIds = new Set(state.resolved.map((step) => unitIdOf(step)));
+    const startedIds = new Set(state.startedUnitIds);
+    // A started unit missing a settlement fact was in flight at the stopping
+    // point: its effects were restored by the closure's rollback, or their
+    // settlement was simply not observed — never "not attempted".
+    const inFlight = state.plannedUnits
+        .filter((unit) => startedIds.has(unit.id) && !resolvedIds.has(unit.id))
+        .map((unit) => ({
+        ...unit,
+        state: "interrupted",
+        disposition: state.restoresOnFailure ? "restored" : "unknown",
+        message: state.restoresOnFailure
+            ? "interrupted while in flight; effects were restored"
+            : "interrupted while in flight; settlement was not observed",
+    }));
+    const notStarted = state.plannedUnits
+        .filter((unit) => !startedIds.has(unit.id) && !resolvedIds.has(unit.id))
+        .map((unit) => ({
+        ...unit,
+        state: "blocked",
+        message: "not attempted: the operation was interrupted",
+        blocking: {
+            class: "operation-aborted",
+            subject: unit.id,
+            phase: "apply",
+            detail: "not attempted: the operation was interrupted",
+            reference: "interruption",
+        },
+    }));
+    const units = [...settledUnits, ...inFlight, ...notStarted];
+    const committed = settledUnits.filter((unit) => unit.state === "committed");
+    // Unknown dominates — durable state may exist beyond what settled. With
+    // everything settled or restored, retained commits are the headline;
+    // restored in-flight work without commits reports restored.
+    const disposition = inFlight.length > 0 && !state.restoresOnFailure
+        ? "unknown"
+        : committed.length > 0
+            ? "retained"
+            : inFlight.length > 0 || (state.resolved.length > 0 && state.restoresOnFailure)
+                ? "restored"
+                : "none";
+    const recovery = disposition === "retained" || disposition === "unknown"
+        ? {
+            retained: committed.flatMap((unit) => unit.artifact === undefined ? [unit.id] : [unit.artifact.path]),
+            actions: [
+                {
+                    description: "Re-run the command to continue the remaining units.",
+                    cmd: invocation.replayCommand,
+                },
+            ],
+        }
+        : undefined;
+    return makeOperationResolution({
+        name: state.name,
+        description: state.description,
+        mode: state.mode,
+        candidateId: state.candidateId,
+        atomicity: {
+            declared: state.atomicity.declared,
+            // A restoring apply keeps its closure-atomic promise: settled commits
+            // stand and everything else was restored. Only unobserved settlement
+            // or non-rollbackable retention downgrade the applied class.
+            applied: state.restoresOnFailure
+                ? "closure-atomic"
+                : disposition === "retained" || disposition === "unknown"
+                    ? "non-rollbackable"
+                    : "closure-atomic",
+        },
+        units,
+        presentation: state.presentation ?? invocation.presentation,
+        releaseAge: state.releaseAge,
+        preconditions: state.preconditions,
+        riskConditions: state.riskConditions,
+        interruption: { signal, disposition },
+        recovery,
+        ...observedFootprint,
+    });
+};
+//# sourceMappingURL=interruption-resolution.js.map

package/dist/src/plan/operation-journal.d.ts

@@ -18,7 +18,7 @@ import * as Option from "effect/Option";
 import * as Ref from "effect/Ref";
 import * as ServiceMap from "effect/Context";
 import type { CompletedJobStep, OperationPresentation, PlanRiskCondition } from "./plan.js";
-import type { ReleaseAgeOperationEvidence } from "@agentxm/registry-protocol/unstable/registry/release-age-policy";
+import type { ReleaseAgeOperationEvidence } from "@agentxm/extension-resolution";
 import type { OperationPrecondition } from "./plan.js";
 import type { OperationAtomicity, OperationPhase, ResolvedUnit } from "./operation-resolution.js";
 export interface OperationJournalState {
@@ -53,17 +53,17 @@ export interface OperationJournalService {
 declare const OperationJournal_base: ServiceMap.ServiceClass<OperationJournal, "@agentxm/workspace-operations/plan/operation-journal/OperationJournal", OperationJournalService>;
 export declare class OperationJournal extends OperationJournal_base {
 }
-/** Record the operation's frozen facts. No-op when no journal is provided. */
-export declare const recordOperationJournal: (state: OperationJournalState) => Effect.Effect<void>;
-/** Merge updates onto the recorded state. No-op when nothing was recorded. */
-export declare const updateOperationJournal: (update: (state: OperationJournalState) => OperationJournalState) => Effect.Effect<void>;
+/** Record the operation's frozen facts. */
+export declare const recordOperationJournal: (state: OperationJournalState) => Effect.Effect<void, never, OperationJournal>;
+/** Merge updates onto the recorded state. No-op when nothing was recorded yet. */
+export declare const updateOperationJournal: (update: (state: OperationJournalState) => OperationJournalState) => Effect.Effect<void, never, OperationJournal>;
 /** Record the lifecycle phase the invocation has entered. */
-export declare const recordJournalPhase: (phase: OperationPhase) => Effect.Effect<void>;
+export declare const recordJournalPhase: (phase: OperationPhase) => Effect.Effect<void, never, OperationJournal>;
 /** Record that a unit's run began. */
-export declare const appendStartedUnit: (unitId: string) => Effect.Effect<void>;
+export declare const appendStartedUnit: (unitId: string) => Effect.Effect<void, never, OperationJournal>;
 /** Record one unit's settlement fact. */
-export declare const appendResolvedUnit: (step: CompletedJobStep<unknown>) => Effect.Effect<void>;
-export declare const getOperationJournal: Effect.Effect<Option.Option<OperationJournalState>>;
+export declare const appendResolvedUnit: (step: CompletedJobStep<unknown>) => Effect.Effect<void, never, OperationJournal>;
+export declare const getOperationJournal: Effect.Effect<Option.Option<OperationJournalState>, never, OperationJournal>;
 export declare const makeOperationJournal: Effect.Effect<OperationJournalService>;
 export {};
 //# sourceMappingURL=operation-journal.d.ts.map

package/dist/src/plan/operation-journal.js

@@ -19,20 +19,10 @@ import * as Ref from "effect/Ref";
 import * as ServiceMap from "effect/Context";
 export class OperationJournal extends ServiceMap.Service()("@agentxm/workspace-operations/plan/operation-journal/OperationJournal") {
 }
-/** Record the operation's frozen facts. No-op when no journal is provided. */
-export const recordOperationJournal = (state) => Effect.gen(function* () {
-    const service = yield* Effect.serviceOption(OperationJournal);
-    if (Option.isNone(service))
-        return;
-    yield* Ref.set(service.value.ref, Option.some(state));
-});
-/** Merge updates onto the recorded state. No-op when nothing was recorded. */
-export const updateOperationJournal = (update) => Effect.gen(function* () {
-    const service = yield* Effect.serviceOption(OperationJournal);
-    if (Option.isNone(service))
-        return;
-    yield* Ref.update(service.value.ref, Option.map(update));
-});
+/** Record the operation's frozen facts. */
+export const recordOperationJournal = (state) => Effect.flatMap(OperationJournal, (service) => Ref.set(service.ref, Option.some(state)));
+/** Merge updates onto the recorded state. No-op when nothing was recorded yet. */
+export const updateOperationJournal = (update) => Effect.flatMap(OperationJournal, (service) => Ref.update(service.ref, Option.map(update)));
 /** Record the lifecycle phase the invocation has entered. */
 export const recordJournalPhase = (phase) => updateOperationJournal((state) => ({ ...state, phase }));
 /** Record that a unit's run began. */
@@ -42,11 +32,6 @@ export const appendStartedUnit = (unitId) => updateOperationJournal((state) => (
 }));
 /** Record one unit's settlement fact. */
 export const appendResolvedUnit = (step) => updateOperationJournal((state) => ({ ...state, resolved: [...state.resolved, step] }));
-export const getOperationJournal = Effect.gen(function* () {
-    const service = yield* Effect.serviceOption(OperationJournal);
-    if (Option.isNone(service))
-        return Option.none();
-    return yield* Ref.get(service.value.ref);
-});
+export const getOperationJournal = Effect.flatMap(OperationJournal, (service) => Ref.get(service.ref));
 export const makeOperationJournal = Ref.make(Option.none()).pipe(Effect.map((ref) => ({ ref })));
 //# sourceMappingURL=operation-journal.js.map

package/dist/src/plan/operation-resolution.d.ts

@@ -15,7 +15,7 @@
 import type * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 import type { OperationErrorCategory, StepFailure } from "./errors.js";
-import type { ReleaseAgeOperationEvidence } from "@agentxm/registry-protocol/unstable/registry/release-age-policy";
+import type { ReleaseAgeOperationEvidence } from "@agentxm/extension-resolution";
 import type { SuggestedAction } from "@agentxm/registry-protocol/unstable/suggested-action";
 import type { BlockingClass, ExecutedPlan, Job, JobStepArtifact, OperationPrecondition, OperationPresentation, PlanRiskCondition, RegistryLifecycleEvidence } from "./plan.js";
 import type { ConfiguredAgentOutcome } from "@agentxm/workspace-state";

package/dist/src/plan/plan-execution-fixtures.d.ts

@@ -2,8 +2,8 @@
  * Plan-execution fixtures for tests and executable specifications.
  *
  * Production commands convert their parsed intent into a `PlanExecution` at
- * the CLI boundary; these constants let kernel and handler tests drive
- * `previewOrApplyPlan` with an already-decoded approval decision. Production
+ * the CLI boundary; these constants let kernel and handler tests resolve
+ * an execution candidate with an already-decoded approval decision. Production
  * source never imports this module.
  *
  * @experimental This API is unstable and may change without notice.

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

@@ -2,8 +2,8 @@
  * Plan-execution fixtures for tests and executable specifications.
  *
  * Production commands convert their parsed intent into a `PlanExecution` at
- * the CLI boundary; these constants let kernel and handler tests drive
- * `previewOrApplyPlan` with an already-decoded approval decision. Production
+ * the CLI boundary; these constants let kernel and handler tests resolve
+ * an execution candidate with an already-decoded approval decision. Production
  * source never imports this module.
  *
  * @experimental This API is unstable and may change without notice.

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

@@ -44,6 +44,27 @@ export interface ConfirmationRecovery {
  *   approval, never a preapproval flag the command does not accept.
  */
 export type ConfirmableRiskApproval = "preapproved" | "prompt-if-interactive" | "interactive-only";
+/**
+ * What an invoking surface parsed about the approval a request carries.
+ *
+ * `preapproved` is present only on the routes whose capabilities declare a
+ * preapprovable confirmation; every other route omits it. The absence of the
+ * field is therefore a fact about the route, not a missing answer, and it is
+ * what separates "the person declined to preapprove" from "this request could
+ * never have been preapproved".
+ */
+export interface RequestedApproval {
+    readonly preapproved?: boolean;
+}
+/**
+ * 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 declare const confirmableRiskApproval: (requested: RequestedApproval) => ConfirmableRiskApproval;
 export type PlanExecutionRequest = {
     readonly mode: "preview";
 } | {
@@ -65,6 +86,33 @@ export type PlanExecution = {
     readonly configuredAgentOperations?: ReadonlyArray<ConfiguredAgentOperation>;
 };
 export declare const previewPlanExecution: PlanExecution;
+/**
+ * What a command parsed about its own invocation before any plan exists.
+ *
+ * `yes` is present only on the routes whose capabilities declare a
+ * preapprovable confirmation; every other route omits it, exactly as
+ * `RequestedApproval` describes.
+ */
+export interface RequestedPlanIntent {
+    readonly preview: boolean;
+    readonly yes?: boolean;
+}
+/**
+ * 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 declare const requestedPlanExecution: (options: {
+    readonly intent: RequestedPlanIntent;
+    readonly recovery: ConfirmationRecovery;
+    readonly acceptedPolicies?: ReadonlySet<PlanPolicyId>;
+    readonly configuredAgentOperations?: ReadonlyArray<ConfiguredAgentOperation>;
+}) => PlanExecution;
 export declare const applyPlanExecution: (options: {
     readonly approval: ConfirmableRiskApproval;
     readonly acceptedPolicies?: ReadonlySet<PlanPolicyId>;