@agentxm/workspace-operations 0.28.12 → 0.28.13

package/dist/src/testing.js

@@ -7,7 +7,29 @@
  * @experimental This API is unstable and may change without notice.
  * @packageDocumentation
  */
+import * as Layer from "effect/Layer";
+import { ConfiguredAgentOutcomesProvider } from "@agentxm/workspace-state";
+import { ConfiguredAgentOutcomesProviderTest } from "@agentxm/workspace-state/testing";
+import { FootprintRecorder, makeFootprintRecorder } from "@agentxm/workspace-transactions";
+import { OperationJournal, makeOperationJournal } 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 const OperationJournalTest = Layer.effect(OperationJournal, makeOperationJournal);
+/** A fresh footprint recorder for one test invocation. */
+export const FootprintRecorderTest = Layer.effect(FootprintRecorder, makeFootprintRecorder);
+/**
+ * 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 const PlanInvocationTest = Layer.mergeAll(OperationJournalTest, FootprintRecorderTest, ConfiguredAgentOutcomesProviderTest);
 export { ResolvePlanInteractionTest, } from "./plan/resolve-plan-interaction.js";
 export { interactiveOnlyPlanExecution, preapprovedPlanExecution, promptablePlanExecution, } from "./plan/plan-execution-fixtures.js";
-export { makeMemoryTransitionLockWorld, } from "./operations/memory-transition-lock.js";
 //# sourceMappingURL=testing.js.map

package/package.json

@@ -4,17 +4,18 @@
     "url": "https://github.com/agentxm/axm/issues"
   },
   "dependencies": {
-    "@agentxm/extension-model": "^0.28.12",
-    "@agentxm/registry-protocol": "^0.28.12",
-    "@agentxm/workspace-state": "^0.28.12",
-    "effect": "4.0.0-rc.112",
-    "proper-lockfile": "^4.1.2"
-  },
-  "description": "AXM workspace operations kernel: plans, execution candidates, operation resolutions, and workspace transactions for the axm CLI. Unstable and unsupported — use the axm.sh CLI.",
+    "@agentxm/extension-model": "^0.28.13",
+    "@agentxm/extension-resolution": "^0.28.13",
+    "@agentxm/registry-protocol": "^0.28.13",
+    "@agentxm/workspace-state": "^0.28.13",
+    "@agentxm/workspace-transactions": "^0.28.13",
+    "effect": "4.0.0-rc.112"
+  },
+  "description": "AXM workspace operations: plans, execution candidates, closure execution, and operation resolutions for the axm CLI. Unstable and unsupported — use the axm.sh CLI.",
   "devDependencies": {
+    "@agentxm/specification-metadata": "^0.28.13",
     "@effect/platform-node": "4.0.0-rc.112",
     "@effect/vitest": "4.0.0-rc.112",
-    "@types/proper-lockfile": "^4.1.4",
     "@typescript/native": "npm:typescript@^7.0.2",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "vitest": "^4.1.10",
@@ -29,11 +30,6 @@
       "default": "./dist/src/index.js",
       "types": "./dist/src/index.d.ts"
     },
-    "./live": {
-      "axm-source": "./src/live.ts",
-      "default": "./dist/src/live.js",
-      "types": "./dist/src/live.d.ts"
-    },
     "./testing": {
       "axm-source": "./src/testing.ts",
       "default": "./dist/src/testing.js",
@@ -54,11 +50,11 @@
     "access": "public"
   },
   "repository": {
-    "directory": "packages/workspace-operations",
+    "directory": "packages/core/workspace-operations",
     "type": "git",
     "url": "https://github.com/agentxm/axm.git"
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.28.12"
-}
+  "version": "0.28.13"
+}

package/dist/src/live.d.ts

@@ -1,13 +0,0 @@
-/**
- * @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

@@ -1,12 +0,0 @@
-/**
- * @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/load-workspace.d.ts

@@ -1,44 +0,0 @@
-/**
- * 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";
-import { type WorkspaceTransitionLock } 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 declare const makeWorkspaceTransactionCapabilities: (lock: WorkspaceTransitionLock) => MakeWorkspaceTransactionCapabilities;
-/**
- * Create workspace mutations effect.
- *
- * Loads an existing workspace from disk.
- *
- * The workspace must already be initialized. Missing or invalid settings and
- * invalid or unsupported lockfiles fail fast with a typed workspace error.
- *
- * @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

@@ -1,80 +0,0 @@
-/**
- * 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 { liveWorkspaceTransitionLock } 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 = (lock) => ({ 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({
-        lock,
-        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) => lock
-        .acquire({
-        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 and
- * invalid or unsupported lockfiles fail fast with a typed workspace error.
- *
- * @param options - WorkspaceMutations layer options
- * @returns Effect yielding WorkspaceMutationsService
- */
-export const loadWorkspace = (options) => makeWorkspaceMutations(options, makeWorkspaceTransactionCapabilities(liveWorkspaceTransitionLock));
-/**
- * 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/memory-transition-lock.d.ts

@@ -1,20 +0,0 @@
-/**
- * Deterministic in-process workspace transition admission for tests.
- *
- * One world owns admission state while each invocation receives an isolated
- * ownership view. Waiting uses Effect time so contention and interruption can
- * be exercised without native timers or lock files.
- *
- * @experimental This API is unstable and may change without notice.
- */
-import type { WorkspaceTransitionLock } from "./transition-lock.js";
-export interface MemoryTransitionLockWorld {
-    readonly counts: () => {
-        readonly acquisitions: number;
-        readonly releases: number;
-    };
-    readonly invocation: () => WorkspaceTransitionLock;
-}
-/** Make one isolated admission world for a deterministic test scenario. */
-export declare const makeMemoryTransitionLockWorld: () => MemoryTransitionLockWorld;
-//# sourceMappingURL=memory-transition-lock.d.ts.map

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

@@ -1,57 +0,0 @@
-/**
- * Deterministic in-process workspace transition admission for tests.
- *
- * One world owns admission state while each invocation receives an isolated
- * ownership view. Waiting uses Effect time so contention and interruption can
- * be exercised without native timers or lock files.
- *
- * @experimental This API is unstable and may change without notice.
- */
-import * as Effect from "effect/Effect";
-import * as Option from "effect/Option";
-import * as Semaphore from "effect/Semaphore";
-/** Make one isolated admission world for a deterministic test scenario. */
-export const makeMemoryTransitionLockWorld = () => {
-    const admission = Semaphore.makeUnsafe(1);
-    let acquisitions = 0;
-    let releases = 0;
-    let holder = Option.none();
-    return {
-        counts: () => ({ acquisitions, releases }),
-        invocation: () => {
-            let held;
-            return {
-                held: (directory) => (held?.directory === directory ? held.lease : undefined),
-                acquire: (args) => Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
-                    let waitedMillis = 0;
-                    let reportedWaiting = false;
-                    while (!(yield* admission.takeIfAvailable(1))) {
-                        if (!reportedWaiting && args.onWaiting !== undefined) {
-                            yield* restore(args.onWaiting(holder));
-                            reportedWaiting = true;
-                        }
-                        if (waitedMillis >= (args.waitBoundMillis ?? 60_000)) {
-                            return Option.some({ holder, waitedMillis });
-                        }
-                        yield* restore(Effect.sleep("250 millis"));
-                        waitedMillis += 250;
-                    }
-                    holder = Option.some(args.holder);
-                    acquisitions += 1;
-                    held = {
-                        directory: args.workspaceDir,
-                        lease: { compromised: Effect.never, isCompromised: () => false },
-                    };
-                    yield* Effect.addFinalizer(() => Effect.gen(function* () {
-                        held = undefined;
-                        holder = Option.none();
-                        releases += 1;
-                        yield* admission.release(1);
-                    }));
-                    return Option.none();
-                })),
-            };
-        },
-    };
-};
-//# sourceMappingURL=memory-transition-lock.js.map

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

@@ -1,60 +0,0 @@
-/**
- * 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";
-import type { WorkspaceTransitionLock } from "./transition-lock.js";
-/** 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 lock: WorkspaceTransitionLock;
-    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