@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/workspace/test-stubs.js

@@ -0,0 +1,412 @@
+/**
+ * Default no-op stubs for workspace getter methods on WorkspaceMutationsService.
+ * Spread into test mocks to satisfy the interface without implementing every method.
+ *
+ * @internal Test-only. Not exported from the barrel.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import YAML from "yaml";
+import { makeRegistryPackLockEntry as buildRegistryPackLockEntry, } from "../lockfile/index.js";
+import { decodeExtensionNameSync, extensionTypes, parseSourceQualifiedRegistrySourcePatternParts, decodeHandleSync, } from "@agentxm/extension-model/unstable/extensions";
+import { SourceHashSchema } from "@agentxm/extension-model/unstable/sources/source-hash";
+import { TreeIntegritySchema } from "./materialized-tree.js";
+import {} from "@agentxm/extension-model/unstable/extensions/installable-types";
+import {} from "@agentxm/extension-model/unstable/extensions/handle";
+import { decodeAbsolutePathSync, decodeRelativePathSync, } from "@agentxm/extension-model/unstable/path-types";
+import { decodeVersionSync, } from "@agentxm/extension-model/unstable/version-constraints";
+const emptyRows = () => Effect.succeed([]);
+const emptyInventory = () => Effect.succeed({
+    items: [],
+    count: 0,
+    configuredCount: 0,
+    implicitCount: 0,
+    installedCount: 0,
+    unmanagedCount: 0,
+});
+const fs = (() => {
+    const module = process.getBuiltinModule("node:fs");
+    if (!module) {
+        throw new Error("node:fs builtin is unavailable");
+    }
+    return module;
+})();
+const path = (() => {
+    const module = process.getBuiltinModule("node:path");
+    if (!module) {
+        throw new Error("node:path builtin is unavailable");
+    }
+    return module;
+})();
+/**
+ * Build a `configured` read-model row. Tests that previously stubbed
+ * `getConfiguredSkills` with a `{ name: { source, enabled } }` map supply the
+ * same facts here and feed the result to {@link rowsFor}.
+ */
+export const configuredRow = (args) => ({
+    type: args.type,
+    name: args.name,
+    source: args.source,
+    enabled: args.enabled ?? true,
+    packagingKind: args.packagingKind ?? "native",
+    lifecycle: "configured",
+});
+/** Build an `implicit` read-model row (pack member or lockfile-only entry). */
+export const implicitRow = (args) => ({
+    type: args.type,
+    name: args.name,
+    source: Option.fromUndefinedOr(args.source),
+    enabled: true,
+    packagingKind: args.packagingKind ?? "native",
+    lifecycle: "implicit",
+});
+/** Build an `unmanaged` read-model row (observed on disk, unclaimed). */
+export const unmanagedRow = (args) => ({
+    type: args.type,
+    name: args.name,
+    source: Option.none(),
+    enabled: true,
+    packagingKind: args.packagingKind ?? "non-native",
+    locations: args.locations ?? [],
+    agents: [],
+    ownershipEvidence: [],
+    lifecycle: "unmanaged",
+});
+/**
+ * Build a `records.rows` stub from per-type row lists. Types absent from the
+ * map yield an empty array, matching the real reader's totality.
+ */
+export const rowsFor = (byType) => (type) => Effect.succeed(byType[type] ?? []);
+/**
+ * No-op stubs for all read-model record getters. Spread into mock objects:
+ * ```ts
+ * const ws: WorkspaceMutationsService = {
+ *   records: readModelRecordStubs,
+ *   // your overrides
+ * };
+ * ```
+ */
+export const readModelRecordStubs = {
+    getInventory: () => Effect.succeed({
+        items: [],
+        count: 0,
+        configuredCount: 0,
+        implicitCount: 0,
+        installedCount: 0,
+        unmanagedCount: 0,
+    }),
+    getExtensionInventory: emptyInventory,
+    rows: emptyRows,
+};
+/**
+ * Base workspace mock with no-op defaults for all methods.
+ * Tests should only override the methods they exercise.
+ *
+ * @example
+ * ```ts
+ * const ws = makeBaseWorkspaceMock("/tmp/axm", {
+ *   setSkill: vi.fn(() => Effect.void),
+ * });
+ * ```
+ */
+export const makeBaseWorkspaceMock = (axmDir = "/tmp/axm", overrides) => {
+    const baseDir = axmDir.replace(/\/\.axm$/, "") || "/tmp";
+    const { rows, records: recordOverrides, ...serviceOverrides } = overrides ?? {};
+    const records = {
+        ...readModelRecordStubs,
+        ...(rows === undefined ? {} : { rows }),
+        ...(recordOverrides ?? {}),
+    };
+    const emptyLocked = () => Effect.succeed({});
+    const configuredForType = (type) => {
+        const normalize = (effect) => effect.pipe(Effect.map((entries) => entries));
+        switch (type) {
+            case "skill":
+                return normalize((serviceOverrides.getConfiguredSkillEntries ?? emptyLocked)());
+            case "mcp-server":
+                return normalize((serviceOverrides.getConfiguredMcpServerEntries ?? emptyLocked)());
+            case "subagent":
+                return normalize((serviceOverrides.getConfiguredSubagentEntries ?? emptyLocked)());
+            case "pack":
+                return normalize((serviceOverrides.getConfiguredPackEntries ?? emptyLocked)());
+            case "rule":
+                return normalize((serviceOverrides.getConfiguredRuleEntries ?? emptyLocked)());
+            case "hook":
+                return normalize((serviceOverrides.getConfiguredHookEntries ?? emptyLocked)());
+            case "knowledge":
+                return normalize((serviceOverrides.getConfiguredKnowledgeEntries ?? emptyLocked)());
+        }
+    };
+    const sourceOf = (row) => row.lifecycle === "configured" ? row.source : Option.getOrUndefined(row.source);
+    const desiredEntriesForType = (type) => Effect.all({
+        rows: records.rows(type),
+        configured: configuredForType(type),
+    }).pipe(Effect.map(({ rows, configured }) => {
+        const entries = new Map();
+        for (const row of rows) {
+            const source = sourceOf(row);
+            if (source === undefined || row.lifecycle === "unmanaged")
+                continue;
+            entries.set(row.name, { name: row.name, source, enabled: row.enabled });
+        }
+        for (const [name, value] of Object.entries(configured)) {
+            if (entries.has(name) ||
+                typeof value !== "object" ||
+                value === null ||
+                !("source" in value) ||
+                typeof value.source !== "string") {
+                continue;
+            }
+            entries.set(name, {
+                name,
+                source: value.source,
+                enabled: !("enabled" in value) || typeof value.enabled !== "boolean" || value.enabled,
+            });
+        }
+        return [...entries.values()];
+    }));
+    const getSynthesizedDesiredStateGraph = () => Effect.gen(function* () {
+        const rowsByType = yield* Effect.forEach(extensionTypes, (type) => desiredEntriesForType(type).pipe(Effect.map((entries) => ({ type, entries }))));
+        const nodes = rowsByType.flatMap(({ type, entries }) => entries.map((entry) => {
+            const source = entry.source;
+            const parsed = parseSourceQualifiedRegistrySourcePatternParts(source);
+            const identity = parsed === undefined ? source : `${parsed.owner}/${parsed.type}/${parsed.name}`;
+            return {
+                type,
+                name: entry.name,
+                identity,
+                source,
+                enabled: entry.enabled,
+                constraints: parsed?.versionRange === undefined ? [] : [parsed.versionRange],
+                origins: [
+                    {
+                        type: "settings",
+                        source,
+                        enabled: entry.enabled,
+                    },
+                ],
+            };
+        }));
+        return { complete: true, nodes, problems: [] };
+    });
+    const runTransaction = (args) => Effect.gen(function* () {
+        const value = yield* args.transition;
+        yield* args.validate(value);
+        return value;
+    });
+    // The mock acquires nothing: unit tests share literal workspace paths, and
+    // a real lock would contend across parallel test files. Tests exercising
+    // real transition semantics override this with the real acquirer.
+    const acquireTransition = () => Effect.succeed(Option.none());
+    const entryFrom = (read) => (name) => read().pipe(Effect.map((entries) => Option.fromUndefinedOr(entries[name])));
+    const lockedSkills = serviceOverrides.getLockedSkills ?? (() => Effect.succeed({}));
+    const lockedMcpServers = serviceOverrides.getLockedMcpServers ?? (() => Effect.succeed({}));
+    const lockedSubagents = serviceOverrides.getLockedSubagents ?? (() => Effect.succeed({}));
+    const lockedRules = serviceOverrides.getLockedRules ?? (() => Effect.succeed({}));
+    const lockedHooks = serviceOverrides.getLockedHooks ?? (() => Effect.succeed({}));
+    const lockedKnowledge = serviceOverrides.getLockedKnowledge ?? (() => Effect.succeed({}));
+    const lockedPacks = serviceOverrides.getLockedPacks ?? (() => Effect.succeed({}));
+    const base = {
+        scope: "project",
+        path: axmDir,
+        baseDir,
+        layout: {
+            scope: "project",
+            workspaceRoot: decodeAbsolutePathSync(path.resolve(baseDir)),
+            projectRoot: decodeAbsolutePathSync(path.resolve(baseDir)),
+            settingsPath: decodeAbsolutePathSync(path.resolve(baseDir, "axm.json")),
+            lockPath: decodeAbsolutePathSync(path.resolve(baseDir, "axm-lock.yaml")),
+            runtimeDir: decodeAbsolutePathSync(path.resolve(baseDir, ".axm")),
+            acquiredRoot: decodeAbsolutePathSync(path.resolve(baseDir, "agent_extensions")),
+            authoredRoot: (type) => decodeAbsolutePathSync(path.resolve(baseDir, type === "mcp-server" ? "mcps" : `${type}s`)),
+        },
+        records,
+        runTransaction,
+        acquireTransition,
+        getLockfileState: () => Effect.succeed("ok"),
+        getDesiredStateGraph: getSynthesizedDesiredStateGraph,
+        getConfiguredSources: () => Effect.succeed([]),
+        getConfiguredSourceByName: () => Effect.succeed(Option.none()),
+        getRegistrySourceHosts: () => Effect.succeed([]),
+        getConfiguredOwner: () => Effect.succeed(Option.none()),
+        getPublishDefaultVisibility: () => Effect.succeed(Option.none()),
+        getMinimumReleaseAge: () => Effect.succeed("24h"),
+        getMinimumReleaseAgeExclude: () => Effect.succeed([]),
+        addConfiguredSource: () => Effect.void,
+        getConfiguredSkillEntries: () => Effect.succeed({}),
+        getConfiguredRuleEntries: () => Effect.succeed({}),
+        getConfiguredHookEntries: () => Effect.succeed({}),
+        getLockedRules: lockedRules,
+        getLockedRuleEntry: entryFrom(lockedRules),
+        setRule: () => Effect.void,
+        setRuleLock: () => Effect.void,
+        removeRule: () => Effect.void,
+        removeRuleSettings: () => Effect.void,
+        removeRuleLock: () => Effect.void,
+        updateRuleEntry: () => Effect.void,
+        setRuleEntry: () => Effect.void,
+        getLockedHooks: lockedHooks,
+        getLockedHookEntry: entryFrom(lockedHooks),
+        setHook: () => Effect.void,
+        setHookLock: () => Effect.void,
+        removeHook: () => Effect.void,
+        removeHookSettings: () => Effect.void,
+        removeHookLock: () => Effect.void,
+        updateHookEntry: () => Effect.void,
+        setHookEntry: () => Effect.void,
+        getConfiguredKnowledgeEntries: () => Effect.succeed({}),
+        getKnowledgeDiscoveryConfig: () => Effect.succeed({ instructions: true }),
+        getLockedKnowledge: lockedKnowledge,
+        getLockedKnowledgeEntry: entryFrom(lockedKnowledge),
+        setKnowledge: () => Effect.void,
+        setKnowledgeLock: () => Effect.void,
+        removeKnowledge: () => Effect.void,
+        removeKnowledgeSettings: () => Effect.void,
+        removeKnowledgeLock: () => Effect.void,
+        updateKnowledgeEntry: () => Effect.void,
+        setKnowledgeEntry: () => Effect.void,
+        getConfiguredPackEntries: () => Effect.succeed({}),
+        getConfiguredAgents: () => Effect.succeed(["claude-code"]),
+        getInstructionsConfig: () => Effect.succeed(Option.none()),
+        setInstructionsConfig: () => Effect.void,
+        getConfiguredMcpServerEntries: () => Effect.succeed({}),
+        getLockedSkills: lockedSkills,
+        getLockedSkill: entryFrom(lockedSkills),
+        getSkillDir: () => Effect.succeed({
+            canonicalPath: `${axmDir}/extensions/agentxm/@test/skills/test`,
+            skillSrcPath: `${axmDir}/extensions/agentxm/@test/skills/test/src`,
+        }),
+        setSkill: () => Effect.void,
+        setSkillLock: () => Effect.void,
+        removeSkill: () => Effect.void,
+        removeSkillFromSettings: () => Effect.void,
+        updateSkillEntry: () => Effect.void,
+        setSkillEntry: () => Effect.void,
+        addConfiguredAgent: () => Effect.void,
+        removeConfiguredAgent: () => Effect.void,
+        getLockedPacks: lockedPacks,
+        getLockedPack: entryFrom(lockedPacks),
+        setPack: () => Effect.void,
+        setPackLock: () => Effect.void,
+        setPackEntry: () => Effect.void,
+        removePack: () => Effect.void,
+        getPackDir: () => Effect.succeed({ canonicalPath: `${axmDir}/extensions/agentxm/@test/packs/test` }),
+        getLockedSubagents: lockedSubagents,
+        getLockedSubagent: entryFrom(lockedSubagents),
+        getConfiguredSubagentEntries: () => Effect.succeed({}),
+        setSubagent: () => Effect.void,
+        setSubagentLock: () => Effect.void,
+        removeSubagent: () => Effect.void,
+        updateSubagentEntry: () => Effect.void,
+        setSubagentEntry: () => Effect.void,
+        removeSubagentSettings: () => Effect.void,
+        removeSubagentLock: () => Effect.void,
+        getLockedMcpServers: lockedMcpServers,
+        getLockedMcpServer: entryFrom(lockedMcpServers),
+        setMcpServer: () => Effect.void,
+        setMcpServerLock: () => Effect.void,
+        updateMcpServerEntry: () => Effect.void,
+        setMcpServerEntry: () => Effect.void,
+        removeMcpServer: () => Effect.void,
+        removeSkillLock: () => Effect.void,
+        removeMcpServerSettings: () => Effect.void,
+        removeMcpServerLock: () => Effect.void,
+        removePackSettings: () => Effect.void,
+        removePackLock: () => Effect.void,
+        isExtensionRequiredByInstalledPack: () => Effect.succeed(false),
+    };
+    return {
+        ...base,
+        ...serviceOverrides,
+        layout: serviceOverrides.layout ?? base.layout,
+    };
+};
+export const TEST_CONTENT_IDENTITY = Schema.decodeUnknownSync(SourceHashSchema)("test-content");
+export const TEST_TREE_INTEGRITY = Schema.decodeUnknownSync(TreeIntegritySchema)(`sha256-tree-v1:${"0".repeat(64)}`);
+const hasEntries = (value) => value !== undefined && Object.keys(value).length > 0;
+export const writeWorkspaceFiles = (runtimeDir, opts = {}) => {
+    const settings = {
+        agents: [...(opts.agents ?? ["claude-code"])],
+        ...(opts.owner && { owner: opts.owner }),
+        ...(hasEntries(opts.skills) && { skills: opts.skills }),
+        ...(hasEntries(opts["mcps"]) && { mcps: opts["mcps"] }),
+        ...(hasEntries(opts.subagents) && { subagents: opts.subagents }),
+        ...(hasEntries(opts.rules) && { rules: opts.rules }),
+        ...(hasEntries(opts.packs) && { packs: opts.packs }),
+        ...(opts.sources && { sources: opts.sources }),
+    };
+    const lockfile = {
+        lockfileVersion: 6,
+        skills: opts.lockfileSkills ?? {},
+        ...(hasEntries(opts.lockfileMcpServers) && { mcps: opts.lockfileMcpServers }),
+        ...(hasEntries(opts.lockfileSubagents) && { subagents: opts.lockfileSubagents }),
+        ...(hasEntries(opts.lockfileRules) && { rules: opts.lockfileRules }),
+        ...(hasEntries(opts.lockfilePacks) && { packs: opts.lockfilePacks }),
+    };
+    const workspaceRoot = path.dirname(runtimeDir);
+    fs.mkdirSync(runtimeDir, { recursive: true });
+    fs.writeFileSync(path.join(workspaceRoot, "axm.json"), JSON.stringify(settings));
+    fs.writeFileSync(path.join(workspaceRoot, "axm-lock.yaml"), YAML.stringify(lockfile));
+};
+export const makeLocalSkillLockEntry = (opts) => ({
+    type: "local",
+    sourceType: "local",
+    sourceName: "local",
+    packageFormat: "agentxm",
+    extensionType: "skill",
+    workspaceName: decodeExtensionNameSync("installed"),
+    packageOwner: decodeHandleSync("@test"),
+    packageName: decodeExtensionNameSync("installed"),
+    path: decodeRelativePathSync(opts?.path ?? "installed"),
+    contentIdentity: TEST_CONTENT_IDENTITY,
+    treeIntegrity: TEST_TREE_INTEGRITY,
+});
+export const makeRegistrySkillLockEntry = (opts) => ({
+    type: "registry",
+    sourceType: "registry",
+    packageFormat: "agentxm",
+    endpoint: opts.endpoint ?? new URL("https://registry.agentxm.ai"),
+    extensionType: "skill",
+    workspaceName: decodeExtensionNameSync(opts.name),
+    owner: opts.owner,
+    name: decodeExtensionNameSync(opts.name),
+    resolvedVersion: opts.resolvedVersion ?? decodeVersionSync("1.0.0"),
+    integrity: opts.integrity ?? "sha512-AAAA==",
+    sourceName: opts.sourceName ?? "agentxm",
+    publisherBindingId: opts.publisherBindingId ?? "hbnd_test",
+    treeIntegrity: TEST_TREE_INTEGRITY,
+});
+export const makeRegistryMcpServerLockEntry = (opts) => ({
+    type: "registry",
+    sourceType: "registry",
+    packageFormat: "agentxm",
+    endpoint: opts.endpoint ?? new URL("https://registry.agentxm.ai"),
+    extensionType: "mcp-server",
+    workspaceName: decodeExtensionNameSync(opts.name),
+    owner: opts.owner,
+    name: decodeExtensionNameSync(opts.name),
+    resolvedVersion: opts.resolvedVersion ?? decodeVersionSync("1.0.0"),
+    integrity: opts.integrity ?? "sha512-AAAA==",
+    sourceName: opts.sourceName ?? "agentxm",
+    publisherBindingId: opts.publisherBindingId ?? "hbnd_test",
+    treeIntegrity: TEST_TREE_INTEGRITY,
+});
+export const makeRegistryPackLockEntry = (opts) => buildRegistryPackLockEntry({
+    sourceType: "registry",
+    packageFormat: "agentxm",
+    endpoint: opts.endpoint ?? new URL("https://registry.agentxm.ai"),
+    extensionType: "pack",
+    workspaceName: decodeExtensionNameSync(opts.name),
+    owner: opts.owner,
+    name: decodeExtensionNameSync(opts.name),
+    resolvedVersion: opts.resolvedVersion ?? decodeVersionSync("1.0.0"),
+    integrity: opts.integrity ?? "sha512-AAAA==",
+    sourceName: opts.sourceName ?? "agentxm",
+    publisherBindingId: opts.publisherBindingId ?? "hbnd_test",
+    manifestContentIdentity: opts.sourceHash === undefined
+        ? TEST_CONTENT_IDENTITY
+        : Schema.decodeUnknownSync(SourceHashSchema)(opts.sourceHash),
+    treeIntegrity: TEST_TREE_INTEGRITY,
+});
+//# sourceMappingURL=test-stubs.js.map

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

@@ -0,0 +1,218 @@
+/**
+ * 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 type * as Cause from "effect/Cause";
+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 Semaphore from "effect/Semaphore";
+/** One pre-mutation preimage of a protected path, keyed to its owning closure. */
+export type Snapshot = {
+    readonly closure: string | undefined;
+} & ({
+    readonly target: string;
+    readonly state: "absent";
+} | {
+    readonly target: string;
+    readonly state: "copied";
+    readonly backup: string;
+} | {
+    readonly target: string;
+    readonly state: "symlink";
+    readonly linkTarget: string;
+});
+/** A closure rollback that could not complete, recorded for the transaction end. */
+export interface PendingClosureRestorationFailure {
+    readonly closureId: string;
+    readonly restorationCause: unknown;
+    readonly retained: ReadonlyArray<string>;
+}
+export interface WorkspaceTransactionContext {
+    readonly fs: FileSystem.FileSystem;
+    readonly path: Path.Path;
+    readonly workspaceDir: string;
+    /** Uniquely prefixed OS-temporary directory holding rollback snapshots. */
+    readonly snapshotStore: {
+        dir: string | undefined;
+    };
+    /** Per-closure first-touch dedupe; the key "" is the operation closure. */
+    readonly protectedTargets: Map<string, Set<string>>;
+    readonly snapshots: Array<Snapshot>;
+    readonly snapshotSemaphore: Semaphore.Semaphore;
+    /** Closure rollbacks that failed; the transaction fails typed at its end. */
+    readonly pendingRestorationFailures: Array<PendingClosureRestorationFailure>;
+    /** Monotonic backup-name counter: settlement drops entries, names never recur. */
+    readonly snapshotSequence: {
+        value: number;
+    };
+}
+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>;
+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>;
+}> {
+}
+/** 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 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;
+/**
+ * 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 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>;
+/**
+ * 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 declare const readPendingClosureRestorationFailures: Effect.Effect<Option.Option<{
+    readonly failures: ReadonlyArray<{
+        readonly closureId: string;
+        readonly restorationCause: unknown;
+        readonly retained: ReadonlyArray<string>;
+    }>;
+    readonly snapshotDir: string | undefined;
+}>>;
+/**
+ * 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>;
+export {};
+//# sourceMappingURL=transaction.d.ts.map