@agentxm/workspace-operations 0.28.4-bootstrap.0

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2025-2026 AgentXM, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,12 @@
+# @agentxm/workspace-operations
+
+The AXM workspace-operations kernel: plan vocabulary and execution, operation
+resolutions and journals, plan readiness and reconciliation gating, and the
+workspace transaction and transition-lock machinery.
+
+The package root is the public API; the composed workspace layer lives behind
+`./live`, and deterministic in-memory test layers behind `./testing`. The
+surface is unsupported and may change in any release. Ordinary users should
+use the [`axm` CLI](https://axm.sh) instead.
+
+Part of the [AgentXM](https://agentxm.ai) toolchain.

package/dist/src/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @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`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export { BlockingClassSchema, defaultOperationPresentation, operationPresentation, presentationOf, ArtifactMechanismSchema, OperationPreconditionSchema, PlanPolicyIdSchema, PlanPolicyIds, PlanRiskConditionSchema, } from "./plan/plan.js";
+export type { ArtifactMechanism, BlockingClass, CompletedJobStep, ErrorJobStep, ExecutedJob, ExecutedPlan, Job, JobStepArtifact, JobStepArtifactSource, JobStepArtifactTarget, JobStepResult, Operation, OperationPrecondition, OperationPresentation, Plan, 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 { OperationLifecycle, makeOperationLifecycle, publishLifecycleEvent, publishPhaseStarted, subscribeToLifecycle, type OperationLifecycleEvent, type OperationLifecycleService, } 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 { ResolvePlanInteraction, type ApplyConfirmation, type ResolvePlanInteractionService, } from "./plan/resolve-plan-interaction.js";
+export { InterruptionSignalSource, type InterruptionSignalSourceService, } from "./plan/interruption-signal.js";
+export { isExecutionCandidateFresh, makeExecutionCandidate, type ExecutionCandidate, } from "./plan/execution-candidate.js";
+export { applyPlanExecution, confirmationRecoverySuggestions, namedPolicyRecoverySuggestions, credentialFreeLocatorRecoveryValue, preapprovedPlanExecution, promptablePlanExecution, previewPlanExecution, protectedRecoveryValue, publicRecoveryValue, recoveryOption, recoveryPositional, recoverySwitch, renderConfirmationRecoveryCommand, unclassifiedRecoveryValue, type ConfirmationRecovery, type ConfirmationRecoveryArgument, type ConfirmationRecoveryValue, type ConfiguredAgentOperation, type PlanExecution, type PlanExecutionRequest, } 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 { 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

@@ -0,0 +1,42 @@
+/**
+ * @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`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+// Plan types
+export { BlockingClassSchema, defaultOperationPresentation, operationPresentation, presentationOf, ArtifactMechanismSchema, OperationPreconditionSchema, PlanPolicyIdSchema, PlanPolicyIds, PlanRiskConditionSchema, } from "./plan/plan.js";
+// Operation resolution — the single value every plan-family command
+// terminates with, with its pure outcome derivations.
+export { AtomicityClassSchema, OperationOutcomeSchema, OperationPhaseSchema, UnitDispositionSchema, UnitStateSchema, countUnitStates, declaredAtomicity, deriveOperationOutcome, executedUnits, makeOperationResolution, plannedUnits, unitIdOf, unitsByStableIdentity, } from "./plan/operation-resolution.js";
+// Operation journal — invocation-scoped progress record for interruption.
+export { OperationJournal, appendResolvedUnit, appendStartedUnit, recordJournalPhase, getOperationJournal, makeOperationJournal, recordOperationJournal, updateOperationJournal, } from "./plan/operation-journal.js";
+// Apply plan + operation handler registry
+export { applyPlan } from "./plan/apply-plan.js";
+export { OperationLifecycle, makeOperationLifecycle, publishLifecycleEvent, publishPhaseStarted, subscribeToLifecycle, } 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";
+// 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 { isExecutionCandidateFresh, makeExecutionCandidate, } from "./plan/execution-candidate.js";
+export { applyPlanExecution, confirmationRecoverySuggestions, namedPolicyRecoverySuggestions, credentialFreeLocatorRecoveryValue, preapprovedPlanExecution, promptablePlanExecution, previewPlanExecution, protectedRecoveryValue, publicRecoveryValue, recoveryOption, recoveryPositional, recoverySwitch, renderConfirmationRecoveryCommand, 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 { TRANSITION_WAIT_BOUND_MILLIS, acquireWorkspaceTransitionLock, heldWorkspaceTransition, isWorkspaceTransitionHeldByThisInvocation, transitionLockPath, } from "./operations/transition-lock.js";
+//# sourceMappingURL=index.js.map

package/dist/src/live.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @agentxm/workspace-operations environment-backed composition.
+ *
+ * The composed workspace layer every entry point provides. Only application
+ * composition roots import this module; feature logic keeps
+ * `WorkspaceMutations` in its Effect environment.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export { layer, loadWorkspace, makeWorkspaceTransactionCapabilities, } from "./operations/load-workspace.js";
+export type { WorkspaceLayerOptions } from "@agentxm/workspace-state";
+//# sourceMappingURL=live.d.ts.map

package/dist/src/live.js

@@ -0,0 +1,12 @@
+/**
+ * @agentxm/workspace-operations environment-backed composition.
+ *
+ * The composed workspace layer every entry point provides. Only application
+ * composition roots import this module; feature logic keeps
+ * `WorkspaceMutations` in its Effect environment.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export { layer, loadWorkspace, makeWorkspaceTransactionCapabilities, } from "./operations/load-workspace.js";
+//# sourceMappingURL=live.js.map

package/dist/src/operations/augment-plan.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Gate a plan on authoritative lockfile health.
+ *
+ * A missing lockfile is an absent accepted-resolution set: the already-resolved
+ * lifecycle plan may establish needed rows atomically. An invalid lockfile is
+ * authoritative but unreadable, so execution blocks without reconstructing it
+ * from canonical content, manifests, or observation.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import type { Plan } from "../plan/plan.js";
+import type { LockfileState } from "@agentxm/workspace-state";
+export type DegradedLockfileState = Exclude<LockfileState, "ok">;
+export interface AugmentedPlanResult<Requirements = never, Output = never> {
+    readonly plan: Plan<Requirements, Output>;
+    readonly reconciliationTriggered: boolean;
+    readonly reason?: DegradedLockfileState;
+}
+/**
+ * Return the plan unchanged when authority is readable or absent. Replace it
+ * with one explicit blocker when the authoritative file is unreadable.
+ */
+export declare const augmentPlanWithReconciliation: <Requirements, Output, LoadError>(plan: Plan<Requirements, Output>, getLockfileState: () => Effect.Effect<LockfileState, LoadError>) => Effect.Effect<AugmentedPlanResult<Requirements, Output>, LoadError>;
+//# sourceMappingURL=augment-plan.d.ts.map

package/dist/src/operations/augment-plan.js

@@ -0,0 +1,51 @@
+/**
+ * Gate a plan on authoritative lockfile health.
+ *
+ * A missing lockfile is an absent accepted-resolution set: the already-resolved
+ * lifecycle plan may establish needed rows atomically. An invalid lockfile is
+ * authoritative but unreadable, so execution blocks without reconstructing it
+ * from canonical content, manifests, or observation.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+// -----------------------------------------------------------------------------
+// Implementation
+// -----------------------------------------------------------------------------
+/**
+ * Return the plan unchanged when authority is readable or absent. Replace it
+ * with one explicit blocker when the authoritative file is unreadable.
+ */
+export const augmentPlanWithReconciliation = (plan, getLockfileState) => Effect.gen(function* () {
+    const lockfileState = yield* getLockfileState();
+    if (lockfileState !== "invalid") {
+        return {
+            plan,
+            reconciliationTriggered: lockfileState === "missing",
+            ...(lockfileState === "missing" ? { reason: "missing" } : {}),
+        };
+    }
+    return {
+        plan: {
+            _tag: "Plan",
+            name: plan.name,
+            description: plan.description,
+            jobs: [
+                {
+                    concurrency: 1,
+                    steps: [
+                        {
+                            key: "workspace:lockfile-invalid",
+                            readiness: "error",
+                            label: "Read accepted external resolutions",
+                            errorMessage: "The authoritative lockfile is invalid and cannot be reconstructed from workspace observation.",
+                        },
+                    ],
+                },
+            ],
+        },
+        reconciliationTriggered: true,
+        reason: "invalid",
+    };
+});
+//# sourceMappingURL=augment-plan.js.map

package/dist/src/operations/load-workspace.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Live workspace composition: the one seam that needs both the workspace
+ * state facade and the operations-side transaction machinery. Supplies the
+ * transaction capabilities to `makeWorkspaceMutations` and publishes the
+ * `loadWorkspace` effect and `layer` every entry point composes.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import { WorkspaceMutations, type MakeWorkspaceTransactionCapabilities, type WorkspaceLayerOptions, type WorkspaceMutationsError, type WorkspaceMutationsService } from "@agentxm/workspace-state";
+/**
+ * The live transaction capabilities: the runner claims the shared settings
+ * and lockfile targets by default, and both members eliminate FileSystem and
+ * Path so the facade's methods stay `R = never` for callers.
+ */
+export declare const makeWorkspaceTransactionCapabilities: MakeWorkspaceTransactionCapabilities;
+/**
+ * Create workspace mutations effect.
+ *
+ * Loads an existing workspace from disk.
+ *
+ * The workspace must already be initialized. Missing or invalid settings fail
+ * fast with an `AppError`.
+ *
+ * @param options - WorkspaceMutations layer options
+ * @returns Effect yielding WorkspaceMutationsService
+ */
+export declare const loadWorkspace: (options: WorkspaceLayerOptions) => Effect.Effect<WorkspaceMutationsService, WorkspaceMutationsError, FileSystem.FileSystem | Path.Path>;
+/**
+ * Create a layer that loads workspace read model from disk.
+ *
+ * The workspace must already be initialized.
+ *
+ * @param options - WorkspaceMutations layer options
+ * @returns Layer providing WorkspaceMutations
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const layer: (options: WorkspaceLayerOptions) => Layer.Layer<WorkspaceMutations, WorkspaceMutationsError, Path.Path | FileSystem.FileSystem>;
+//# sourceMappingURL=load-workspace.d.ts.map

package/dist/src/operations/load-workspace.js

@@ -0,0 +1,77 @@
+/**
+ * Live workspace composition: the one seam that needs both the workspace
+ * state facade and the operations-side transaction machinery. Supplies the
+ * transaction capabilities to `makeWorkspaceMutations` and publishes the
+ * `loadWorkspace` effect and `layer` every entry point composes.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Semaphore from "effect/Semaphore";
+import { WorkspaceMutations, makeWorkspaceMutations, } from "@agentxm/workspace-state";
+import { runWorkspaceTransaction } from "./transaction.js";
+import { acquireWorkspaceTransitionLock } from "./transition-lock.js";
+/**
+ * The live transaction capabilities: the runner claims the shared settings
+ * and lockfile targets by default, and both members eliminate FileSystem and
+ * Path so the facade's methods stay `R = never` for callers.
+ */
+export const makeWorkspaceTransactionCapabilities = ({ workspaceDir, settingsPath, lockPath, }) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    // Transaction admission must be distinct from the facade's mutation
+    // mutex: a transaction calls the same service's mutation methods while
+    // it owns the outer admission permit.
+    const transactionSemaphore = yield* Semaphore.make(1);
+    const fsLayer = Layer.mergeAll(Layer.succeed(FileSystem.FileSystem, fs), Layer.succeed(Path.Path, path));
+    const runTransaction = (args) => runWorkspaceTransaction({
+        workspaceDir,
+        semaphore: transactionSemaphore,
+        targets: [
+            ...(args.claimDefaultTargets === false ? [] : [settingsPath, lockPath]),
+            ...(args.targets ?? []),
+        ],
+        transition: args.transition,
+        validate: args.validate,
+        ...(args.onRestorationStarted === undefined
+            ? {}
+            : { onRestorationStarted: args.onRestorationStarted }),
+    }).pipe(Effect.provide(fsLayer));
+    const acquireTransition = (request) => acquireWorkspaceTransitionLock({
+        workspaceDir,
+        holder: {
+            command: request.command,
+            pid: process.pid,
+            ...(request.candidateId === undefined ? {} : { candidateId: request.candidateId }),
+        },
+        ...(request.onWaiting === undefined ? {} : { onWaiting: request.onWaiting }),
+    }).pipe(Effect.provide(fsLayer));
+    return { runTransaction, acquireTransition };
+});
+/**
+ * Create workspace mutations effect.
+ *
+ * Loads an existing workspace from disk.
+ *
+ * The workspace must already be initialized. Missing or invalid settings fail
+ * fast with an `AppError`.
+ *
+ * @param options - WorkspaceMutations layer options
+ * @returns Effect yielding WorkspaceMutationsService
+ */
+export const loadWorkspace = (options) => makeWorkspaceMutations(options, makeWorkspaceTransactionCapabilities);
+/**
+ * Create a layer that loads workspace read model from disk.
+ *
+ * The workspace must already be initialized.
+ *
+ * @param options - WorkspaceMutations layer options
+ * @returns Layer providing WorkspaceMutations
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const layer = (options) => Layer.effect(WorkspaceMutations, loadWorkspace(options));
+//# sourceMappingURL=load-workspace.js.map

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

@@ -0,0 +1,22 @@
+/**
+ * Pure function to scan a plan's steps and collect readiness statistics.
+ *
+ * Extracts from the inline logic in `previewOrApplyPlan` so it can be tested
+ * independently and reused from core without CLI dependencies.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { Plan } from "../plan/plan.js";
+export interface PlanReadinessReport {
+    readonly hasErrors: boolean;
+    readonly hasWarnings: boolean;
+    readonly errorMessages: ReadonlyArray<string>;
+    readonly warnMessages: ReadonlyArray<string>;
+}
+/**
+ * Scan all steps in a plan and collect readiness statistics.
+ *
+ * Pure function: no side effects, no service dependencies.
+ */
+export declare const scanPlanReadiness: (plan: Plan<unknown, unknown>) => PlanReadinessReport;
+//# sourceMappingURL=scan-plan-readiness.d.ts.map

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

@@ -0,0 +1,41 @@
+/**
+ * Pure function to scan a plan's steps and collect readiness statistics.
+ *
+ * Extracts from the inline logic in `previewOrApplyPlan` so it can be tested
+ * independently and reused from core without CLI dependencies.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+// -----------------------------------------------------------------------------
+// Implementation
+// -----------------------------------------------------------------------------
+/**
+ * Scan all steps in a plan and collect readiness statistics.
+ *
+ * Pure function: no side effects, no service dependencies.
+ */
+export const scanPlanReadiness = (plan) => {
+    const errorMessages = [];
+    const warnMessages = [];
+    for (const job of plan.jobs) {
+        for (const step of job.steps) {
+            switch (step.readiness) {
+                case "error":
+                    errorMessages.push(`${step.label}: ${step.errorMessage}`);
+                    break;
+                case "warn":
+                    warnMessages.push(`${step.label}: ${step.warnMessage}`);
+                    break;
+                case "ready":
+                    break;
+            }
+        }
+    }
+    return {
+        hasErrors: errorMessages.length > 0,
+        hasWarnings: warnMessages.length > 0,
+        errorMessages,
+        warnMessages,
+    };
+};
+//# sourceMappingURL=scan-plan-readiness.js.map

package/dist/src/operations/transaction.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Workspace transaction mechanics: the snapshot/restore/validate/rollback
+ * runner and the closure settlement operations, implemented against the
+ * ambient authority context declared in `../transaction.ts`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Semaphore from "effect/Semaphore";
+import { WorkspaceRestorationIncomplete, type WorkspaceTransactionFailure } from "@agentxm/workspace-state";
+/** Run one semantic closure's mutations under its closure identity. */
+export declare const withWorkspaceClosure: (closureId: string) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+export interface WorkspaceTransactionArgs<A, E, R> {
+    readonly workspaceDir: string;
+    /** In-process admission owned by the workspace service instance. */
+    readonly semaphore: Semaphore.Semaphore;
+    /** Authoritative files or directories that the transition may mutate. */
+    readonly targets: ReadonlyArray<string>;
+    /** Desired, lock, canonical, projection, and native-configuration mutation. */
+    readonly transition: Effect.Effect<A, E, R>;
+    /** Confirms the complete durable postcondition before the transaction commits. */
+    readonly validate: (value: A) => Effect.Effect<void, E, R>;
+    /** Observes the start of rollback restoration; never controls it. */
+    readonly onRestorationStarted?: Effect.Effect<void>;
+}
+/**
+ * Settle one closure: its commits stand, so its snapshots leave the
+ * restoration set and a later closure touching the same target takes a fresh
+ * post-commit preimage. No-op outside a transaction.
+ */
+export declare const settleWorkspaceClosure: (closureId: string) => Effect.Effect<void>;
+/**
+ * Roll back one failed closure: restore and verify exactly its snapshots, in
+ * reverse order, leaving every other closure's work in place. A restoration
+ * that does not complete and verify records a pending typed failure the
+ * transaction surfaces at its end — the truth travels in memory, never
+ * through a later workspace write. No-op outside a transaction.
+ */
+export declare const rollbackWorkspaceClosure: (closureId: string) => Effect.Effect<void>;
+/**
+ * Run one coupled workspace mutation under the workspace transition lock.
+ *
+ * Every authoritative target is snapshotted into a uniquely prefixed
+ * OS-temporary directory before the transition begins. A failed transition or
+ * postcondition check restores and verifies the exact pre-operation paths and
+ * removes the snapshots; a restoration that does not complete and verify
+ * fails with the typed {@link WorkspaceRestorationIncomplete}, preserving the
+ * snapshot directory for manual inspection. Nothing about a failure persists
+ * in the workspace: the next mutation plans from the current workspace state.
+ *
+ * The invocation-level transition hold is reused when a plan-family apply
+ * already acquired it; otherwise this transaction acquires its own for the
+ * duration of the mutation.
+ */
+export declare const runWorkspaceTransaction: <A, E, R>(args: WorkspaceTransactionArgs<A, E, R>) => Effect.Effect<A, WorkspaceTransactionFailure | WorkspaceRestorationIncomplete | E, R | FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=transaction.d.ts.map