@agentxm/workspace-transactions 0.28.14-preview.1789139351.5cd4595aa

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,15 @@
+# @agentxm/workspace-transactions
+
+The AXM workspace transaction capability: the cross-process workspace
+transition lock, the per-closure snapshot ledger with restoration and
+verification, atomic single-file publication, and footprint observation. Every
+workspace writer registers its target here before the first mutation, and
+`workspace-operations` settles or rolls back each semantic closure through the
+closure API this package exports for it alone.
+
+The package root is the public API; deterministic in-memory admission and the
+fault-injection hooks live 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/atomic-write.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared atomic single-file replacement: write a uniquely named temp file in
+ * the target's directory, then rename it over the target.
+ *
+ * The temp file lives next to the target so the rename stays on one
+ * filesystem (and therefore atomic), and is removed on any failure or
+ * interruption. Temp names follow `<target>.tmp.<unique>`; sweepers that
+ * clean stale temps (e.g. the lockfile writer) rely on that prefix.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { PlatformError } from "effect/PlatformError";
+/**
+ * Step at which an atomic write failed. `check-target` and `read-target` can
+ * only occur with `skipIfUnchanged: "fail-on-read-error"`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type AtomicWriteStep = "check-target" | "read-target" | "write-temp" | "rename";
+/**
+ * Failure passed to `mapError` so each call site keeps its own error shape.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface AtomicWriteFailure {
+    readonly step: AtomicWriteStep;
+    readonly targetPath: string;
+    readonly tempPath: string;
+    readonly cause: PlatformError;
+}
+/**
+ * Content-equality short-circuit mode: `fail-on-read-error` surfaces
+ * check/read failures via `mapError`; `ignore-read-errors` treats an
+ * unreadable target as changed and proceeds to write.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type SkipIfUnchanged = "fail-on-read-error" | "ignore-read-errors";
+/**
+ * Options for `writeFileAtomic`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface WriteFileAtomicOptions<E> {
+    readonly targetPath: string;
+    readonly content: string | Uint8Array;
+    /** When set, leave the target untouched if it already has this content. */
+    readonly skipIfUnchanged?: SkipIfUnchanged;
+    /** Best-effort remove of the target before rename (Windows cannot always rename over an existing file). */
+    readonly removeTargetBeforeRename?: boolean;
+    readonly mapError: (failure: AtomicWriteFailure) => E;
+}
+export declare const atomicWriteTempPrefix: (targetPath: string) => string;
+/** Remove only stale temp siblings belonging to one atomic-write target. */
+export declare const sweepStaleAtomicWriteTemps: (fs: FileSystem.FileSystem, targetPath: string) => Effect.Effect<void, never, Path.Path>;
+/**
+ * Atomically replace `targetPath` with `content` via a same-directory temp
+ * file and rename. Failures at each step are mapped by the caller, so error
+ * codes, details, and suggestions stay call-site specific.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const writeFileAtomic: <E>(fs: FileSystem.FileSystem, options: WriteFileAtomicOptions<E>) => Effect.Effect<"written" | "skipped", E>;
+//# sourceMappingURL=atomic-write.d.ts.map

package/dist/src/atomic-write.js

@@ -0,0 +1,71 @@
+/**
+ * Shared atomic single-file replacement: write a uniquely named temp file in
+ * the target's directory, then rename it over the target.
+ *
+ * The temp file lives next to the target so the rename stays on one
+ * filesystem (and therefore atomic), and is removed on any failure or
+ * interruption. Temp names follow `<target>.tmp.<unique>`; sweepers that
+ * clean stale temps (e.g. the lockfile writer) rely on that prefix.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+/** In-process sequence so concurrent fibers never share a temp path. */
+let tempSequence = 0;
+export const atomicWriteTempPrefix = (targetPath) => `${targetPath}.tmp.`;
+/** Remove only stale temp siblings belonging to one atomic-write target. */
+export const sweepStaleAtomicWriteTemps = (fs, targetPath) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const parent = path.dirname(targetPath);
+    const filenamePrefix = `${path.basename(targetPath)}.tmp.`;
+    const entries = yield* fs.readDirectory(parent).pipe(Effect.orElseSucceed(() => []));
+    yield* Effect.forEach(entries.filter((entry) => entry.startsWith(filenamePrefix)), (entry) => fs.remove(path.join(parent, entry), { force: true }).pipe(Effect.ignore), { discard: true });
+});
+const makeTempPath = (targetPath) => {
+    tempSequence += 1;
+    const pid = typeof process === "object" ? process.pid.toString(36) : "x";
+    const random = Math.random().toString(36).slice(2, 8);
+    return `${atomicWriteTempPrefix(targetPath)}${pid}.${tempSequence.toString(36)}.${random}`;
+};
+const bytesEqual = (a, b) => a.length === b.length && a.every((value, index) => value === b[index]);
+const targetHasContent = (fs, targetPath, content) => typeof content === "string"
+    ? Effect.map(fs.readFileString(targetPath), (current) => current === content)
+    : Effect.map(fs.readFile(targetPath), (current) => bytesEqual(current, content));
+/**
+ * Atomically replace `targetPath` with `content` via a same-directory temp
+ * file and rename. Failures at each step are mapped by the caller, so error
+ * codes, details, and suggestions stay call-site specific.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const writeFileAtomic = (fs, options) => Effect.gen(function* () {
+    const { content, mapError, targetPath } = options;
+    const tempPath = makeTempPath(targetPath);
+    const fail = (step) => (cause) => mapError({ step, targetPath, tempPath, cause });
+    if (options.skipIfUnchanged === "fail-on-read-error") {
+        const exists = yield* fs.exists(targetPath).pipe(Effect.mapError(fail("check-target")));
+        if (exists) {
+            const unchanged = yield* targetHasContent(fs, targetPath, content).pipe(Effect.mapError(fail("read-target")));
+            if (unchanged)
+                return "skipped";
+        }
+    }
+    else if (options.skipIfUnchanged === "ignore-read-errors") {
+        const unchanged = yield* targetHasContent(fs, targetPath, content).pipe(Effect.option);
+        if (Option.isSome(unchanged) && unchanged.value)
+            return "skipped";
+    }
+    yield* Effect.gen(function* () {
+        yield* (typeof content === "string"
+            ? fs.writeFileString(tempPath, content)
+            : fs.writeFile(tempPath, content)).pipe(Effect.mapError(fail("write-temp")));
+        if (options.removeTargetBeforeRename === true) {
+            yield* fs.remove(targetPath).pipe(Effect.ignore);
+        }
+        yield* fs.rename(tempPath, targetPath).pipe(Effect.mapError(fail("rename")));
+    }).pipe(Effect.ensuring(fs.remove(tempPath, { force: true }).pipe(Effect.ignore)));
+    return "written";
+});
+//# sourceMappingURL=atomic-write.js.map

package/dist/src/context.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The ambient transaction context and the write registration primitives
+ * every workspace writer calls.
+ *
+ * `protectWorkspacePath` and `protectCreatedAncestors` snapshot a path before
+ * its first mutation within the active closure. The context itself — the
+ * ledger reference and the two ambient references that carry it — is
+ * package-private: the transaction runner in `./transaction.ts` constructs
+ * and provides it, and nothing outside this package can reach the ledger.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+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 SynchronizedRef from "effect/SynchronizedRef";
+import { WorkspaceSnapshotError } from "./errors.js";
+import { type TransactionLedger } from "./ledger.js";
+export interface WorkspaceTransactionContext {
+    readonly isTransitionCompromised: () => boolean;
+    readonly fs: FileSystem.FileSystem;
+    readonly path: Path.Path;
+    readonly workspaceDir: string;
+    /** The one serialized record of preimages, closures, and pending restorations. */
+    readonly ledger: SynchronizedRef.SynchronizedRef<TransactionLedger>;
+}
+/** The active transaction, when one is running on this fiber's context. */
+export declare const CurrentWorkspaceTransaction: ServiceMap.Reference<Option.Option<WorkspaceTransactionContext>>;
+/**
+ * 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 declare const CurrentWorkspaceClosure: ServiceMap.Reference<string | undefined>;
+/**
+ * Take one target's preimage into the ledger, deduplicating on first touch
+ * per closure. One serialized ledger transition: the snapshot store is
+ * created, the backup name allocated, and the bytes copied while the ledger
+ * is held, so no concurrent registration or rollback observes a half-taken
+ * snapshot.
+ */
+export declare const protectInContext: (context: WorkspaceTransactionContext, target: string, closure: string | undefined) => Effect.Effect<void, WorkspaceSnapshotError>;
+/** Snapshot a path before its first mutation when a workspace transaction is active. */
+export declare const protectWorkspacePath: (target: string) => Effect.Effect<void, WorkspaceSnapshotError>;
+/**
+ * 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 declare const protectCreatedAncestors: (fs: FileSystem.FileSystem, path: Path.Path, directory: string) => Effect.Effect<void, WorkspaceSnapshotError>;
+//# sourceMappingURL=context.d.ts.map

package/dist/src/context.js

@@ -0,0 +1,115 @@
+/**
+ * The ambient transaction context and the write registration primitives
+ * every workspace writer calls.
+ *
+ * `protectWorkspacePath` and `protectCreatedAncestors` snapshot a path before
+ * its first mutation within the active closure. The context itself — the
+ * ledger reference and the two ambient references that carry it — is
+ * package-private: the transaction runner in `./transaction.ts` constructs
+ * and provides it, and nothing outside this package can reach the ledger.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as ServiceMap from "effect/Context";
+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 SynchronizedRef from "effect/SynchronizedRef";
+import { WorkspaceSnapshotError } from "./errors.js";
+import { isProtected, withSnapshot } from "./ledger.js";
+/** The active transaction, when one is running on this fiber's context. */
+export const CurrentWorkspaceTransaction = ServiceMap.Reference("@agentxm/workspace-transactions/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-transactions/CurrentWorkspaceClosure", { defaultValue: () => undefined });
+/**
+ * Take one target's preimage into the ledger, deduplicating on first touch
+ * per closure. One serialized ledger transition: the snapshot store is
+ * created, the backup name allocated, and the bytes copied while the ledger
+ * is held, so no concurrent registration or rollback observes a half-taken
+ * snapshot.
+ */
+export const protectInContext = (context, target, closure) => SynchronizedRef.updateEffect(context.ledger, (ledger) => 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.
+    if (isProtected(ledger, closure, normalized))
+        return ledger;
+    const link = yield* fs.readLink(normalized).pipe(Effect.option);
+    if (Option.isSome(link)) {
+        const snapshot = {
+            closure,
+            target: normalized,
+            state: "symlink",
+            linkTarget: link.value,
+        };
+        return withSnapshot(ledger, snapshot, ledger);
+    }
+    const exists = yield* fs
+        .exists(normalized)
+        .pipe(Effect.mapError((cause) => new WorkspaceSnapshotError({ target: normalized, step: "inspect-target", cause })));
+    if (!exists) {
+        return withSnapshot(ledger, { closure, target: normalized, state: "absent" }, ledger);
+    }
+    const snapshotDir = ledger.snapshotDir ??
+        (yield* fs
+            .makeTempDirectory({ prefix: "axm-rollback-" })
+            .pipe(Effect.mapError((cause) => new WorkspaceSnapshotError({ target: normalized, step: "create-store", cause }))));
+    const backup = path.join(snapshotDir, `${ledger.snapshotSequence}.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 })));
+    return withSnapshot(ledger, { closure, target: normalized, state: "copied", backup }, { snapshotDir, snapshotSequence: ledger.snapshotSequence + 1 });
+}));
+/** 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);
+});
+/**
+ * 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=context.js.map

package/dist/src/errors.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Typed failure vocabulary of the workspace transaction and transition-lock
+ * machinery, plus the holder and contention facts the lock records. The
+ * application error boundary owns rendering, codes, and suggestions for every
+ * failure declared here.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type * as Cause from "effect/Cause";
+import type * as Option from "effect/Option";
+/** Identity an invocation records while it holds the workspace transition. */
+export interface TransitionLockHolder {
+    readonly command: string;
+    readonly pid: number;
+    readonly candidateId?: string;
+}
+export interface TransitionContention {
+    /** The holder recorded by the invocation that owns the lock, when readable. */
+    readonly holder: Option.Option<TransitionLockHolder>;
+    readonly waitedMillis: number;
+}
+declare const WorkspaceRestorationIncomplete_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "WorkspaceRestorationIncomplete";
+} & Readonly<A>;
+/**
+ * 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 declare class WorkspaceRestorationIncomplete extends WorkspaceRestorationIncomplete_base<{
+    readonly terminationCause: "failure" | "interruption";
+    readonly transitionCause: Cause.Cause<unknown>;
+    readonly restorationCause: unknown;
+    /** OS-temporary directory preserving the pre-change snapshots, when any were taken. */
+    readonly snapshotDir: string | undefined;
+    /** Protected paths, workspace-root-relative where possible, left as the failure left them. */
+    readonly retained: ReadonlyArray<string>;
+    /** Closures whose rollback did not complete, when closure-scoped. */
+    readonly closureIds?: ReadonlyArray<string>;
+}> {
+}
+declare const WorkspaceSnapshotError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "WorkspaceSnapshotError";
+} & Readonly<A>;
+/**
+ * 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 declare class WorkspaceSnapshotError extends WorkspaceSnapshotError_base<{
+    readonly target: string;
+    readonly step: "inspect-target" | "create-store" | "copy" | "inspect-ancestor";
+    readonly cause: unknown;
+}> {
+}
+declare const WorkspaceDirectoryError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "WorkspaceDirectoryError";
+} & Readonly<A>;
+/** Preparing the workspace state directory for a transition failed. */
+export declare class WorkspaceDirectoryError extends WorkspaceDirectoryError_base<{
+    readonly path: string;
+    readonly step: "inspect" | "create";
+    readonly cause: unknown;
+}> {
+}
+declare const TransitionLockError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "TransitionLockError";
+} & Readonly<A>;
+/**
+ * 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 declare class TransitionLockError extends TransitionLockError_base<{
+    readonly path: string;
+    readonly step: "create-scratch" | "acquire" | "record-holder" | "inspect-timestamp" | "missing-timestamp" | "preserve-timestamp" | "release";
+    readonly cause?: unknown;
+}> {
+}
+declare const TransitionLockUnavailable_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "TransitionLockUnavailable";
+} & Readonly<A>;
+/**
+ * The bounded contention wait elapsed while another invocation held the
+ * workspace transition.
+ */
+export declare class TransitionLockUnavailable extends TransitionLockUnavailable_base<{
+    readonly holder: TransitionLockHolder | undefined;
+    readonly waitedMillis: number;
+}> {
+}
+declare const WorkspaceTransitionCompromised_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "WorkspaceTransitionCompromised";
+} & Readonly<A>;
+/**
+ * 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 declare class WorkspaceTransitionCompromised extends WorkspaceTransitionCompromised_base<{
+    readonly workspaceDir: string;
+    readonly lockPath: string;
+    readonly cause: unknown;
+}> {
+}
+declare const WorkspaceRestorationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "WorkspaceRestorationError";
+} & Readonly<A>;
+/**
+ * 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 declare class WorkspaceRestorationError extends WorkspaceRestorationError_base<{
+    readonly target: string;
+    readonly step: "stage" | "stopped" | "verify";
+    readonly cause: unknown;
+}> {
+}
+/** Failures acquiring the workspace transition lock. */
+export type WorkspaceTransitionAcquireFailure = WorkspaceDirectoryError | TransitionLockError;
+/** Failures the transaction machinery itself produces, beside the transition's own. */
+export type WorkspaceTransactionFailure = WorkspaceSnapshotError | WorkspaceDirectoryError | TransitionLockError | TransitionLockUnavailable | WorkspaceTransitionCompromised;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.js

@@ -0,0 +1,58 @@
+/**
+ * Typed failure vocabulary of the workspace transaction and transition-lock
+ * machinery, plus the holder and contention facts the lock records. The
+ * application error boundary owns rendering, codes, and suggestions for every
+ * failure declared here.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+/**
+ * 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") {
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/footprint-recorder.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Footprint recorder — observed durable changes.
+ *
+ * The layers that touch durable state record what they actually committed,
+ * removed, or restored here; the operation resolution's footprint is these
+ * observations, not planner-claimed artifact paths. Recording is a no-op when
+ * no recorder is provided, so the writers stay usable outside an operation
+ * boundary; reading requires the recorder, because only an operation
+ * boundary has a footprint to report.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Ref from "effect/Ref";
+import * as ServiceMap from "effect/Context";
+export interface FootprintObservation {
+    /** Absolute path of the durable change. */
+    readonly path: string;
+    readonly change: "created" | "modified" | "removed" | "restored";
+}
+declare const FootprintRecorder_base: ServiceMap.ServiceClass<FootprintRecorder, "@agentxm/workspace-transactions/FootprintRecorder", {
+    readonly ref: Ref.Ref<ReadonlyArray<FootprintObservation>>;
+}>;
+export declare class FootprintRecorder extends FootprintRecorder_base {
+}
+/** Record one observed durable change. No-op without a recorder. */
+export declare const recordFootprint: (observation: FootprintObservation) => Effect.Effect<void>;
+/** Every durable change observed so far by the operation's recorder. */
+export declare const readFootprint: Effect.Effect<ReadonlyArray<FootprintObservation>, never, FootprintRecorder>;
+export declare const makeFootprintRecorder: Effect.Effect<ServiceMap.Service.Shape<typeof FootprintRecorder>>;
+export {};
+//# sourceMappingURL=footprint-recorder.d.ts.map