@agentxm/workspace-operations 0.28.12 → 0.28.13

package/dist/src/operations/transaction.js

@@ -1,358 +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 { createHash, randomBytes } from "node:crypto";
-import * as Cause from "effect/Cause";
-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";
-import { recordFootprint } from "@agentxm/workspace-state";
-import { CurrentWorkspaceClosure, CurrentWorkspaceTransaction, protectInContext, TransitionLockUnavailable, WorkspaceDirectoryError, WorkspaceRestorationError, WorkspaceRestorationIncomplete, WorkspaceTransitionCompromised, } from "@agentxm/workspace-state";
-/** Run one semantic closure's mutations under its closure identity. */
-export const withWorkspaceClosure = (closureId) => (effect) => effect.pipe(Effect.provideService(CurrentWorkspaceClosure, closureId));
-const normalizedTargets = (path, targets) => {
-    const sorted = Array.from(new Set(targets.map((target) => path.resolve(target)))).sort((left, right) => left.length - right.length || left.localeCompare(right));
-    const retained = [];
-    for (const target of sorted) {
-        if (retained.some((parent) => target === parent || target.startsWith(`${parent}${path.sep}`))) {
-            continue;
-        }
-        retained.push(target);
-    }
-    return retained;
-};
-const workspaceRelative = (path, workspaceDir, target) => {
-    const relative = path.relative(path.dirname(workspaceDir), target);
-    return relative.startsWith("..") ? target : relative;
-};
-const sha256 = (input) => createHash("sha256").update(input).digest("hex");
-/**
- * Deterministic content hash of a path's current state: file bytes, symlink
- * target, recursive directory listing, or the literal `absent`.
- */
-const hashPathState = (fs, path, target) => Effect.gen(function* () {
-    const link = yield* fs.readLink(target).pipe(Effect.option);
-    if (Option.isSome(link))
-        return sha256(`symlink:${link.value}`);
-    const exists = yield* fs.exists(target);
-    if (!exists)
-        return "absent";
-    const info = yield* fs.stat(target);
-    if (info.type === "Directory") {
-        const entries = [...(yield* fs.readDirectory(target))].sort();
-        const parts = [];
-        for (const entry of entries) {
-            const child = yield* hashPathState(fs, path, path.join(target, entry));
-            parts.push(`${entry}:${child}`);
-        }
-        return sha256(`dir:${parts.join("\n")}`);
-    }
-    const bytes = yield* fs.readFile(target);
-    return sha256(bytes);
-}).pipe(Effect.catch(() => Effect.succeed("unhashable")));
-const dropClosureSnapshots = (context, closureId) => {
-    let index = context.snapshots.length;
-    while (index > 0) {
-        index -= 1;
-        if (context.snapshots[index]?.closure === closureId) {
-            context.snapshots.splice(index, 1);
-        }
-    }
-    context.protectedTargets.delete(closureId);
-};
-/**
- * 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 const settleWorkspaceClosure = (closureId) => CurrentWorkspaceTransaction.pipe(Effect.flatMap(Option.match({
-    onNone: () => Effect.void,
-    onSome: (context) => context.snapshotSemaphore.withPermits(1)(Effect.sync(() => {
-        dropClosureSnapshots(context, closureId);
-    })),
-})));
-/**
- * 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 const rollbackWorkspaceClosure = (closureId) => CurrentWorkspaceTransaction.pipe(Effect.flatMap(Option.match({
-    onNone: () => Effect.void,
-    onSome: (context) => context.snapshotSemaphore.withPermits(1)(Effect.gen(function* () {
-        const { fs, path } = context;
-        const owned = context.snapshots.filter((snapshot) => snapshot.closure === closureId);
-        if (owned.length === 0) {
-            dropClosureSnapshots(context, closureId);
-            return;
-        }
-        const transitionCompromised = context.isTransitionCompromised;
-        yield* restoreAll(fs, path, owned, transitionCompromised).pipe(Effect.andThen(verifySnapshots(fs, path, owned)), Effect.matchEffect({
-            onFailure: (restorationCause) => Effect.sync(() => {
-                context.pendingRestorationFailures.push({
-                    closureId,
-                    restorationCause,
-                    retained: owned.map((snapshot) => workspaceRelative(path, context.workspaceDir, snapshot.target)),
-                });
-            }),
-            onSuccess: () => Effect.void,
-        }));
-        dropClosureSnapshots(context, closureId);
-    })),
-})));
-/** Whether anything occupies the path: a file, directory, or (broken) symlink. */
-const pathPresent = (fs, target) => fs.readLink(target).pipe(Effect.map(() => true), Effect.catch(() => fs.exists(target)));
-/**
- * Restore one snapshot through validated staging and atomic publication.
- * The restored content is fully staged and validated in an owned
- * `<target>.tmp.<unique>` sibling before a rename publishes it, so abrupt
- * termination — including a forced process exit — can never expose a
- * partially restored target: the authoritative path holds the failure-time
- * content, the restored content, or (for a directory swap only, between two
- * renames) nothing, never a partial tree. The target path itself is never
- * removed; only owned `.tmp.` siblings are.
- */
-const restoreSnapshot = (fs, path, snapshot) => Effect.gen(function* () {
-    if (snapshot.state === "absent") {
-        if (!(yield* pathPresent(fs, snapshot.target)))
-            return;
-        // Publishing absence is one rename: the mutated tree leaves the
-        // authoritative path atomically, then the owned trash is removed.
-        const trash = `${snapshot.target}.tmp.${randomBytes(6).toString("hex")}`;
-        yield* fs.rename(snapshot.target, trash);
-        yield* fs.remove(trash, { recursive: true, force: true }).pipe(Effect.ignore);
-        return;
-    }
-    yield* fs.makeDirectory(path.dirname(snapshot.target), { recursive: true });
-    const staging = `${snapshot.target}.tmp.${randomBytes(6).toString("hex")}`;
-    yield* Effect.gen(function* () {
-        if (snapshot.state === "symlink") {
-            yield* fs.symlink(snapshot.linkTarget, staging);
-            const staged = yield* fs.readLink(staging);
-            if (staged !== snapshot.linkTarget) {
-                return yield* new WorkspaceRestorationError({
-                    target: snapshot.target,
-                    step: "stage",
-                    cause: { staged, expected: snapshot.linkTarget },
-                });
-            }
-        }
-        else {
-            yield* fs.copy(snapshot.backup, staging, { preserveTimestamps: true });
-            const stagedHash = yield* hashPathState(fs, path, staging);
-            const backupHash = yield* hashPathState(fs, path, snapshot.backup);
-            if (stagedHash !== backupHash || stagedHash === "unhashable") {
-                return yield* new WorkspaceRestorationError({
-                    target: snapshot.target,
-                    step: "stage",
-                    cause: { stagedHash, backupHash },
-                });
-            }
-        }
-        const targetLink = yield* fs.readLink(snapshot.target).pipe(Effect.option);
-        const targetInfo = Option.isSome(targetLink)
-            ? Option.none()
-            : yield* fs.stat(snapshot.target).pipe(Effect.option);
-        const targetPresent = Option.isSome(targetLink) || Option.isSome(targetInfo);
-        const targetIsDirectory = Option.exists(targetInfo, (info) => info.type === "Directory");
-        const stagedIsDirectory = snapshot.state === "copied" && (yield* fs.stat(staging)).type === "Directory";
-        if (!targetPresent || (!targetIsDirectory && !stagedIsDirectory)) {
-            // rename atomically replaces a file or symlink target.
-            yield* fs.rename(staging, snapshot.target);
-            return;
-        }
-        // A directory is swapped through two renames of owned names; the
-        // moved-aside content is intact in the trash sibling until removal.
-        const trash = `${snapshot.target}.tmp.${randomBytes(6).toString("hex")}`;
-        yield* fs.rename(snapshot.target, trash);
-        yield* fs.rename(staging, snapshot.target);
-        yield* fs.remove(trash, { recursive: true, force: true }).pipe(Effect.ignore);
-    }).pipe(Effect.onError(() => fs.remove(staging, { recursive: true, force: true }).pipe(Effect.ignore)));
-});
-const restoreAll = (fs, path, snapshots, transitionCompromised) => Effect.forEach([...snapshots].reverse(), (snapshot) => Effect.suspend(() => 
-// Restoration is a durable write like any other: once lock ownership
-// is lost it must stop, or it could overwrite a successor's work.
-transitionCompromised()
-    ? Effect.fail(new WorkspaceRestorationError({
-        target: snapshot.target,
-        step: "stopped",
-        cause: undefined,
-    }))
-    : restoreSnapshot(fs, path, snapshot).pipe(Effect.andThen(recordFootprint({ path: snapshot.target, change: "restored" })))), {
-    discard: true,
-});
-const verifySnapshots = (fs, path, snapshots) => Effect.forEach(snapshots, (snapshot) => Effect.gen(function* () {
-    const verified = yield* Effect.gen(function* () {
-        if (snapshot.state === "absent") {
-            return !(yield* fs.exists(snapshot.target));
-        }
-        if (snapshot.state === "symlink") {
-            const link = yield* fs.readLink(snapshot.target).pipe(Effect.option);
-            return Option.exists(link, (value) => value === snapshot.linkTarget);
-        }
-        const restored = yield* hashPathState(fs, path, snapshot.target);
-        const backup = yield* hashPathState(fs, path, snapshot.backup);
-        return restored === backup && restored !== "unhashable";
-    }).pipe(Effect.catch(() => Effect.succeed(false)));
-    if (!verified) {
-        return yield* new WorkspaceRestorationError({
-            target: snapshot.target,
-            step: "verify",
-            cause: { state: snapshot.state },
-        });
-    }
-}), { discard: true });
-/**
- * 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 const runWorkspaceTransaction = (args) => Effect.gen(function* () {
-    const current = yield* CurrentWorkspaceTransaction;
-    if (Option.isSome(current)) {
-        const activeClosure = yield* CurrentWorkspaceClosure;
-        yield* Effect.forEach(normalizedTargets(current.value.path, args.targets), (target) => protectInContext(current.value, target, activeClosure), { discard: true });
-        const value = yield* args.transition;
-        yield* args.validate(value);
-        return value;
-    }
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const workspaceDir = path.resolve(args.workspaceDir);
-    const missingWorkspaceAncestors = [];
-    let ancestor = workspaceDir;
-    while (true) {
-        const exists = yield* fs
-            .exists(ancestor)
-            .pipe(Effect.mapError((cause) => new WorkspaceDirectoryError({ path: ancestor, step: "inspect", cause })));
-        if (exists)
-            break;
-        missingWorkspaceAncestors.push(ancestor);
-        const parent = path.dirname(ancestor);
-        if (parent === ancestor)
-            break;
-        ancestor = parent;
-    }
-    return yield* args.semaphore.withPermits(1)(Effect.gen(function* () {
-        yield* fs
-            .makeDirectory(workspaceDir, { recursive: true })
-            .pipe(Effect.mapError((cause) => new WorkspaceDirectoryError({ path: workspaceDir, step: "create", cause })));
-        const scratchDir = path.join(workspaceDir, "tmp");
-        const removeEmptyScratch = fs.readDirectory(scratchDir).pipe(Effect.flatMap((entries) => entries.length === 0
-            ? fs.remove(scratchDir, { recursive: true, force: false })
-            : Effect.void), Effect.ignore);
-        const removeNewEmptyWorkspace = Effect.forEach(missingWorkspaceAncestors, (directory) => fs.readDirectory(directory).pipe(Effect.flatMap((entries) => entries.length === 0
-            ? fs.remove(directory, { recursive: true, force: false })
-            : Effect.void), Effect.ignore), { concurrency: 1, discard: true });
-        return yield* Effect.scoped(Effect.gen(function* () {
-            // The invocation-level transition hold already provides
-            // cross-process exclusion; acquiring here again would deadlock on
-            // our own lock.
-            if (args.lock.held(workspaceDir) === undefined) {
-                const contention = yield* args.lock.acquire({
-                    workspaceDir,
-                    holder: { command: "workspace-transaction", pid: process.pid },
-                });
-                if (Option.isSome(contention)) {
-                    return yield* new TransitionLockUnavailable({
-                        holder: Option.getOrUndefined(contention.value.holder),
-                        waitedMillis: contention.value.waitedMillis,
-                    });
-                }
-            }
-            const held = args.lock.held(workspaceDir);
-            const context = {
-                isTransitionCompromised: held?.isCompromised ?? (() => false),
-                fs,
-                path,
-                workspaceDir,
-                snapshotStore: { dir: undefined },
-                protectedTargets: new Map(),
-                snapshots: [],
-                snapshotSemaphore: Semaphore.makeUnsafe(1),
-                pendingRestorationFailures: [],
-                snapshotSequence: { value: 0 },
-            };
-            // The store is removed only when nothing in it is still needed:
-            // a closure whose rollback failed leaves its pre-change
-            // snapshots preserved for manual recovery, and the typed
-            // restoration fact names this directory.
-            const removeSnapshotStore = Effect.suspend(() => context.snapshotStore.dir === undefined ||
-                context.pendingRestorationFailures.length > 0
-                ? Effect.void
-                : fs
-                    .remove(context.snapshotStore.dir, { recursive: true, force: true })
-                    .pipe(Effect.ignore));
-            // The compromise signal of the hold serializing this mutation:
-            // the invocation-level hold when one exists, else the one just
-            // acquired above. Mutation races against it and stops when
-            // ownership is lost.
-            // Interruptible like the business side: the race runs inside the
-            // uninterruptible rollback guard, and its loser must be
-            // interruptible for the race to settle.
-            const compromiseSignal = (held === undefined ? Effect.never : held.compromised).pipe(Effect.interruptible);
-            const transitionCompromised = held === undefined ? () => false : held.isCompromised;
-            const business = Effect.gen(function* () {
-                // The transaction's own declared targets belong to the
-                // operation closure: no semantic closure is active yet.
-                yield* Effect.forEach(normalizedTargets(path, args.targets), (target) => protectInContext(context, target, undefined), { discard: true });
-                const value = yield* args.transition;
-                yield* args.validate(value);
-                return value;
-            }).pipe(Effect.provideService(CurrentWorkspaceTransaction, Option.some(context)), Effect.interruptible);
-            const retainAll = (cause, restorationCause) => Effect.gen(function* () {
-                const interruption = Cause.hasInterruptsOnly(cause);
-                return yield* new WorkspaceRestorationIncomplete({
-                    terminationCause: interruption ? "interruption" : "failure",
-                    transitionCause: cause,
-                    restorationCause,
-                    snapshotDir: context.snapshotStore.dir,
-                    retained: context.snapshots.map((snapshot) => workspaceRelative(path, workspaceDir, snapshot.target)),
-                });
-            });
-            // The mask/restore shape is load-bearing: the business runs in
-            // the restored (interruptible) region so an external termination
-            // request reaches it, while the settlement handlers — rollback,
-            // verification, and the typed retain path — run uninterruptibly
-            // and observe the interruption as a cause. A blanket mask would
-            // never deliver the interrupt to the parked business and the
-            // invocation could not stop.
-            return yield* Effect.uninterruptibleMask((restoreInterruptibility) => restoreInterruptibility(Effect.raceFirst(business, compromiseSignal)).pipe(Effect.matchCauseEffect({
-                onFailure: (cause) => {
-                    const raceError = Option.getOrUndefined(Cause.findErrorOption(cause));
-                    if (raceError instanceof WorkspaceTransitionCompromised) {
-                        // Ownership is lost: restoring now could overwrite a
-                        // successor's work. Retain everything the failure left,
-                        // keep the snapshots, and fail typed.
-                        return retainAll(cause, raceError);
-                    }
-                    return (args.onRestorationStarted ?? Effect.void)
-                        .pipe(Effect.andThen(restoreAll(fs, path, context.snapshots, transitionCompromised)), Effect.andThen(verifySnapshots(fs, path, context.snapshots)))
-                        .pipe(Effect.matchEffect({
-                        onFailure: (restorationCause) => retainAll(cause, restorationCause),
-                        onSuccess: () => removeSnapshotStore.pipe(Effect.andThen(Effect.failCause(cause))),
-                    }));
-                },
-                onSuccess: (value) => removeSnapshotStore.pipe(Effect.as(value)),
-            })));
-        })).pipe(Effect.ensuring(removeEmptyScratch), Effect.ensuring(removeNewEmptyWorkspace));
-    }));
-});
-//# sourceMappingURL=transaction.js.map

package/dist/src/operations/transition-lock.d.ts

@@ -1,72 +0,0 @@
-/**
- * Workspace transition lock.
- *
- * One cross-process lock serializes mutation-class operations on a workspace.
- * A plan-family apply acquires it after confirmation — planning, network
- * acquisition, preview, and the confirmation decision stay lock-free — then
- * revalidates its candidate and applies while holding it; the workspace
- * transaction reuses the invocation's hold, or acquires its own when no
- * plan-family hold exists. A contending invocation waits with a visible
- * reason up to a bound, then terminates blocked with a machine-readable
- * reference to the holder.
- *
- * Each acquisition records a distinct owner token in the holder metadata.
- * Ownership is proven only by an exact token match — never inferred from a
- * pid or from missing or unreadable metadata — and a holder write that fails
- * releases the acquisition instead of holding anonymously.
- *
- * The lock file lives at `.axm/tmp/workspace-transition.lock`; its path is
- * load-bearing for operational tooling and must not move casually.
- *
- * Acquisition is atomic with respect to interruption: the narrow region from
- * the library granting the hold through finalizer registration is masked, so
- * an interrupt can never strand a granted lock, while contention waits stay
- * interruptible. Only the lock-is-held error class is absorbed by the bounded
- * wait; any other acquisition error surfaces immediately as a typed failure.
- *
- * @experimental This API is unstable and may change without notice.
- */
-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 type * as Scope from "effect/Scope";
-import { WorkspaceTransitionCompromised, type TransitionContention, type TransitionLockHolder, type WorkspaceTransitionAcquireFailure } from "@agentxm/workspace-state";
-export declare const TRANSITION_LOCK_FILENAME = "workspace-transition.lock";
-/** How long a contending invocation serializes behind the holder. */
-export declare const TRANSITION_WAIT_BOUND_MILLIS = 60000;
-/** The live view of one acquisition this process currently holds. */
-export interface HeldWorkspaceTransition {
-    /** Fails when the hold is compromised; never succeeds and never ends otherwise. */
-    readonly compromised: Effect.Effect<never, WorkspaceTransitionCompromised>;
-    /** Synchronous probe for boundaries that cannot race, such as restoration. */
-    readonly isCompromised: () => boolean;
-}
-export declare const isWorkspaceTransitionHeldByThisInvocation: (workspaceDir: string) => boolean;
-/** The live hold for a workspace this process acquired, when one exists. */
-export declare const heldWorkspaceTransition: (workspaceDir: string) => HeldWorkspaceTransition | undefined;
-export declare const transitionLockPath: (path: Path.Path, workspaceDir: string) => string;
-/**
- * Acquire the workspace transition lock, waiting up to the bound while
- * another invocation holds it. Resolves `None` when acquired (the release is
- * a scope finalizer) and `Some(contention)` when the bound elapsed.
- */
-export declare const acquireWorkspaceTransitionLock: (args: {
-    readonly workspaceDir: string;
-    readonly holder: TransitionLockHolder;
-    readonly waitBoundMillis?: number;
-    /** Called once when the invocation starts waiting on another holder. */
-    readonly onWaiting?: (holder: Option.Option<TransitionLockHolder>) => Effect.Effect<void>;
-    /** Staleness/refresh override for deterministic compromise tests only. */
-    readonly timingMillis?: {
-        readonly stale: number;
-        readonly update: number;
-    };
-}) => Effect.Effect<Option.Option<TransitionContention>, WorkspaceTransitionAcquireFailure, FileSystem.FileSystem | Path.Path | Scope.Scope>;
-/** One invocation's view of transition admission and ownership. */
-export interface WorkspaceTransitionLock {
-    readonly acquire: typeof acquireWorkspaceTransitionLock;
-    readonly held: typeof heldWorkspaceTransition;
-}
-export declare const liveWorkspaceTransitionLock: WorkspaceTransitionLock;
-//# sourceMappingURL=transition-lock.d.ts.map