@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/workspace/transaction.js

@@ -0,0 +1,177 @@
+/**
+ * Workspace transaction state: the ambient authority context, the write
+ * registration primitives every workspace writer calls, and the typed
+ * failure vocabulary of the transaction and transition-lock machinery.
+ *
+ * This module owns the ambient transaction/closure references and the
+ * protection primitives (`protectWorkspacePath`, `protectCreatedAncestors`)
+ * that snapshot a path before its first mutation. The transaction runner and
+ * closure settlement mechanics that consume this context live in
+ * `./operations/transaction.ts`; the application error boundary owns the
+ * rendering, codes, and suggestions for every failure declared here.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Semaphore from "effect/Semaphore";
+export const CurrentWorkspaceTransaction = ServiceMap.Reference("@agentxm/workspace-state/workspace/transaction/CurrentWorkspaceTransaction", {
+    defaultValue: () => Option.none(),
+});
+/**
+ * The semantic closure whose mutations are currently executing. Snapshots
+ * taken while a closure is active belong to it: they are dropped when the
+ * closure settles and restored when it — and only it — rolls back. Snapshots
+ * taken outside any closure belong to the operation closure and are restored
+ * by the transaction's own failure handling.
+ */
+export const CurrentWorkspaceClosure = ServiceMap.Reference("@agentxm/workspace-state/workspace/transaction/CurrentWorkspaceClosure", { defaultValue: () => undefined });
+/**
+ * Restoration did not complete: the typed fact the terminal resolution
+ * derives outcome, disposition, and exit status from. The pre-change
+ * snapshots survive in the OS-temporary snapshot directory; nothing about
+ * this failure persists in the workspace, and the next mutation converges
+ * from the current workspace state.
+ */
+export class WorkspaceRestorationIncomplete extends Data.TaggedError("WorkspaceRestorationIncomplete") {
+}
+/**
+ * Registering a path with the active transaction failed: the pre-mutation
+ * preimage could not be taken, so the path was never mutated. `target` is the
+ * path being protected; the `create-store` step's message interpolates
+ * nothing.
+ */
+export class WorkspaceSnapshotError extends Data.TaggedError("WorkspaceSnapshotError") {
+}
+/** Preparing the workspace state directory for a transition failed. */
+export class WorkspaceDirectoryError extends Data.TaggedError("WorkspaceDirectoryError") {
+}
+/**
+ * Workspace transition-lock mechanics failed. `path` carries the fact each
+ * step's message interpolates: the scratch directory for `create-scratch`,
+ * the lock path otherwise. `missing-timestamp` has no underlying cause.
+ */
+export class TransitionLockError extends Data.TaggedError("TransitionLockError") {
+}
+/**
+ * The bounded contention wait elapsed while another invocation held the
+ * workspace transition.
+ */
+export class TransitionLockUnavailable extends Data.TaggedError("TransitionLockUnavailable") {
+}
+/**
+ * The hold is no longer provably owned: ownership could not be confirmed
+ * within the staleness window, so a contender may already have reclaimed the
+ * lock. Any further durable write by the original owner — mutation and
+ * restoration alike — could overwrite a successor's work.
+ */
+export class WorkspaceTransitionCompromised extends Data.TaggedError("WorkspaceTransitionCompromised") {
+}
+/**
+ * One restoration step did not complete or verify. Never a channel failure:
+ * it travels as the `restorationCause` inside
+ * {@link WorkspaceRestorationIncomplete} and the pending closure records.
+ */
+export class WorkspaceRestorationError extends Data.TaggedError("WorkspaceRestorationError") {
+}
+const closureKey = (closure) => closure ?? "";
+/**
+ * Snapshot one target into the active transaction context, deduplicating on
+ * first touch per closure. Shared by the registration primitives below and by
+ * the transaction runner claiming its declared targets.
+ */
+export const protectInContext = (context, target, closure) => context.snapshotSemaphore.withPermits(1)(Effect.gen(function* () {
+    const { fs, path } = context;
+    const normalized = path.resolve(target);
+    // First-touch dedupe is per closure: a later closure touching a target
+    // an earlier closure already committed needs its own — post-commit —
+    // preimage, so restoring it undoes only that closure's work.
+    const key = closureKey(closure);
+    const protectedForClosure = context.protectedTargets.get(key) ?? new Set();
+    if (protectedForClosure.has(normalized))
+        return;
+    const link = yield* fs.readLink(normalized).pipe(Effect.option);
+    let snapshot;
+    if (Option.isSome(link)) {
+        snapshot = { closure, target: normalized, state: "symlink", linkTarget: link.value };
+    }
+    else {
+        const exists = yield* fs
+            .exists(normalized)
+            .pipe(Effect.mapError((cause) => new WorkspaceSnapshotError({ target: normalized, step: "inspect-target", cause })));
+        if (!exists) {
+            snapshot = { closure, target: normalized, state: "absent" };
+        }
+        else {
+            if (context.snapshotStore.dir === undefined) {
+                context.snapshotStore.dir = yield* fs
+                    .makeTempDirectory({ prefix: "axm-rollback-" })
+                    .pipe(Effect.mapError((cause) => new WorkspaceSnapshotError({ target: normalized, step: "create-store", cause })));
+            }
+            const backup = path.join(context.snapshotStore.dir, `${context.snapshotSequence.value++}.snap`);
+            // The pre-change bytes are preserved before the path is first
+            // mutated; a path that cannot be snapshotted is never mutated.
+            yield* fs
+                .copy(normalized, backup, { preserveTimestamps: true })
+                .pipe(Effect.mapError((cause) => new WorkspaceSnapshotError({ target: normalized, step: "copy", cause })));
+            snapshot = { closure, target: normalized, state: "copied", backup };
+        }
+    }
+    protectedForClosure.add(normalized);
+    context.protectedTargets.set(key, protectedForClosure);
+    context.snapshots.push(snapshot);
+}));
+/** Snapshot a path before its first mutation when a workspace transaction is active. */
+export const protectWorkspacePath = (target) => Effect.gen(function* () {
+    const current = yield* CurrentWorkspaceTransaction;
+    if (Option.isNone(current))
+        return;
+    const closure = yield* CurrentWorkspaceClosure;
+    yield* protectInContext(current.value, target, closure);
+});
+/**
+ * Closure rollbacks that could not complete and verify, with the snapshot
+ * store that still preserves their pre-change bytes. Read at the end of a
+ * plan apply so the terminal resolution derives retained state from the
+ * in-memory facts alone. `None` outside a transaction.
+ */
+export const readPendingClosureRestorationFailures = CurrentWorkspaceTransaction.pipe(Effect.map(Option.map((context) => ({
+    failures: [...context.pendingRestorationFailures],
+    snapshotDir: context.snapshotStore.dir,
+}))));
+/**
+ * Protect the first ancestor a recursive directory creation is about to
+ * create, so restoration removes the created directory chain instead of
+ * leaving empty parents behind. No-op outside a transaction or when the
+ * directory already exists.
+ */
+export const protectCreatedAncestors = (fs, path, directory) => CurrentWorkspaceTransaction.pipe(Effect.flatMap(Option.match({
+    onNone: () => Effect.void,
+    onSome: (context) => Effect.gen(function* () {
+        let firstMissing;
+        let current = path.resolve(directory);
+        while (true) {
+            const exists = yield* fs.exists(current).pipe(Effect.mapError((cause) => new WorkspaceSnapshotError({
+                target: current,
+                step: "inspect-ancestor",
+                cause,
+            })));
+            if (exists)
+                break;
+            firstMissing = current;
+            const parent = path.dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+        if (firstMissing !== undefined) {
+            const closure = yield* CurrentWorkspaceClosure;
+            yield* protectInContext(context, firstMissing, closure);
+        }
+    }),
+})));
+//# sourceMappingURL=transaction.js.map

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@agentxm/workspace-state",
+  "version": "0.28.4-bootstrap.0",
+  "description": "AXM workspace state kernel: settings, lockfile, read model, and desired-state vocabulary for the axm CLI. Unstable and unsupported — use the axm.sh CLI.",
+  "type": "module",
+  "license": "FSL-1.1-MIT",
+  "homepage": "https://axm.sh",
+  "bugs": {
+    "url": "https://github.com/agentxm/axm/issues"
+  },
+  "author": "AgentXM <hello@agentxm.ai> (https://agentxm.ai)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentxm/axm.git",
+    "directory": "packages/workspace-state"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./testing": {
+      "types": "./dist/src/testing.d.ts",
+      "default": "./dist/src/testing.js"
+    }
+  },
+  "files": [
+    "dist/src/",
+    "!**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "nx": {
+    "includedScripts": []
+  },
+  "dependencies": {
+    "effect": "4.0.0-rc.112",
+    "jsonc-parser": "^3.3.1",
+    "semver": "^7.8.5",
+    "yaml": "^2.9.0",
+    "@agentxm/registry-protocol": "^0.28.4-bootstrap.0",
+    "@agentxm/extension-model": "^0.28.4-bootstrap.0"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.0-rc.112",
+    "@effect/vitest": "4.0.0-rc.112",
+    "@types/semver": "^7.5.8",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^4.1.10"
+  }
+}