expandai 0.0.2 → 0.0.3

package/src/Init/MutationTransaction.ts

@@ -0,0 +1,747 @@
+import { FileSystem, Path, Error as PlatformError } from '@effect/platform'
+import { NodeFileSystem, NodePath } from '@effect/platform-node'
+import { Array, Cause, Chunk, Effect, Either, Exit, Inspectable, Option, Schema, Scope } from 'effect'
+
+type MutationType = 'write' | 'remove' | 'mkdir'
+
+interface MutationBase {
+	readonly type: MutationType
+	readonly path: string
+	readonly expected?: MutationExpectedState
+	readonly validate?: Effect.Effect<unknown, unknown>
+}
+
+export type MutationExpectedState =
+	| { readonly exists: false }
+	| {
+			readonly exists: true
+			readonly type: 'File'
+			readonly bytes: Uint8Array
+			readonly mode: number
+	  }
+	| {
+			readonly exists: true
+			readonly type: 'Directory'
+			readonly mode: number
+	  }
+
+export interface WriteMutation extends MutationBase {
+	readonly type: 'write'
+	readonly bytes: Uint8Array
+	readonly mode?: number
+}
+
+export interface RemoveMutation extends MutationBase {
+	readonly type: 'remove'
+}
+
+export interface MakeDirectoryMutation extends MutationBase {
+	readonly type: 'mkdir'
+	readonly mode?: number
+}
+
+export type MutationOperation = WriteMutation | RemoveMutation | MakeDirectoryMutation
+
+const MutationFailure = Schema.Struct({
+	path: Schema.String,
+	operation: Schema.Literal('write', 'remove', 'mkdir'),
+	error: Schema.Defect,
+})
+
+export type MutationFailure = typeof MutationFailure.Type
+
+export class MutationSymlinkError extends Schema.TaggedError<MutationSymlinkError>()('MutationSymlinkError', {
+	path: Schema.String,
+}) {
+	get message() {
+		return `Refusing to mutate through symbolic link ${this.path}`
+	}
+}
+
+class MutationPathChangedError extends Schema.TaggedError<MutationPathChangedError>()('MutationPathChangedError', {
+	path: Schema.String,
+}) {
+	get message() {
+		return `Path lineage changed while the mutation transaction was using ${this.path}`
+	}
+}
+
+class MutationRollbackConflictError extends Schema.TaggedError<MutationRollbackConflictError>()(
+	'MutationRollbackConflictError',
+	{
+		path: Schema.String,
+	},
+) {
+	get message() {
+		return `Rollback preserved concurrent state at ${this.path}`
+	}
+}
+
+export class MutationValidationError extends Schema.TaggedError<MutationValidationError>()(
+	'MutationValidationError',
+	MutationFailure.fields,
+) {
+	get message() {
+		return `Mutation validation failed for ${this.path}: ${Inspectable.format(this.error)}`
+	}
+}
+
+export class MutationApplicationError extends Schema.TaggedError<MutationApplicationError>()(
+	'MutationApplicationError',
+	{
+		...MutationFailure.fields,
+		rollbackFailures: Schema.Array(MutationFailure),
+	},
+) {
+	get message() {
+		const rollbackSummary =
+			this.rollbackFailures.length === 0 ? '' : `; ${this.rollbackFailures.length} rollback operation(s) also failed`
+		return `Mutation failed for ${this.path}: ${Inspectable.format(this.error)}${rollbackSummary}`
+	}
+}
+
+export class MutationRollbackError extends Schema.TaggedError<MutationRollbackError>()('MutationRollbackError', {
+	rollbackFailures: Schema.Array(MutationFailure),
+}) {
+	get message() {
+		return `${this.rollbackFailures.length} rollback operation(s) failed after a defect or interruption`
+	}
+}
+
+export type MutationTransactionError =
+	| MutationSymlinkError
+	| MutationValidationError
+	| MutationApplicationError
+	| MutationRollbackError
+
+interface Snapshot {
+	readonly exists: boolean
+	readonly bytes?: Uint8Array
+	readonly dev?: number
+	readonly entries?: string[]
+	readonly ino?: number
+	readonly mode?: number
+	readonly realPath?: string
+	readonly type?: 'File' | 'Directory'
+}
+
+interface PathIdentity {
+	readonly path: string
+	readonly exists: boolean
+	readonly dev?: number
+	readonly ino?: number
+	readonly realPath?: string
+	readonly type?: FileSystem.File.Type
+}
+
+interface PlannedMutation {
+	readonly operation: MutationOperation
+	readonly path: string
+	readonly snapshot: Snapshot
+}
+
+const MODE_MAX = 0o7777
+
+function pathLineage(pathService: Path.Path, target: string): string[] {
+	const absolute = pathService.resolve(target)
+	const root = pathService.parse(absolute).root
+
+	function collect(current: string): string[] {
+		if (current === root) return [root]
+		return [...collect(pathService.dirname(current)), current]
+	}
+
+	return collect(absolute)
+}
+
+function bytesEqual(left: Uint8Array | undefined, right: Uint8Array | undefined): boolean {
+	if (left === undefined || right === undefined) return left === right
+	if (left.byteLength !== right.byteLength) return false
+	return left.every((value, index) => value === right[index])
+}
+
+function entriesEqual(left: string[] | undefined, right: string[] | undefined): boolean {
+	if (left === undefined || right === undefined) return left === right
+	return left.length === right.length && left.every((value, index) => value === right[index])
+}
+
+function statesEqual(left: Snapshot, right: Snapshot): boolean {
+	return (
+		left.exists === right.exists &&
+		left.type === right.type &&
+		left.mode === right.mode &&
+		bytesEqual(left.bytes, right.bytes) &&
+		entriesEqual(left.entries, right.entries)
+	)
+}
+
+function ownershipEqual(left: Snapshot, right: Snapshot): boolean {
+	return (
+		statesEqual(left, right) &&
+		(!left.exists || (left.dev === right.dev && left.ino === right.ino && left.realPath === right.realPath))
+	)
+}
+
+function matchesExpectedState(actual: Snapshot, expected: MutationExpectedState): boolean {
+	if (actual.exists !== expected.exists) return false
+	if (!expected.exists) return true
+	if (actual.type !== expected.type || actual.mode !== expected.mode) return false
+	return expected.type === 'Directory' || bytesEqual(actual.bytes, expected.bytes)
+}
+
+function isErrnoCode(input: unknown, code: string): boolean {
+	return typeof input === 'object' && input !== null && 'code' in input && input.code === code
+}
+
+function identitiesEqual(left: ReadonlyArray<PathIdentity>, right: ReadonlyArray<PathIdentity>): boolean {
+	return (
+		left.length === right.length &&
+		left.every((entry, index) => {
+			const other = right[index]
+			return (
+				other !== undefined &&
+				entry.path === other.path &&
+				entry.exists === other.exists &&
+				entry.dev === other.dev &&
+				entry.ino === other.ino &&
+				entry.realPath === other.realPath &&
+				entry.type === other.type
+			)
+		})
+	)
+}
+
+function validationError(operation: MutationOperation, error: unknown): MutationValidationError {
+	return new MutationValidationError({ path: operation.path, operation: operation.type, error })
+}
+
+function invalidMutation(operation: MutationOperation, message: string): MutationValidationError {
+	return validationError(operation, new Error(message))
+}
+
+function applicationError(operation: MutationOperation, error: unknown): MutationApplicationError {
+	return new MutationApplicationError({
+		path: operation.path,
+		operation: operation.type,
+		error,
+		rollbackFailures: [],
+	})
+}
+
+const makeMutationTransaction = Effect.gen(function* () {
+	const fileSystem = yield* FileSystem.FileSystem
+	const pathService = yield* Path.Path
+
+	const assertNotSymbolicLink = Effect.fnUntraced(function* (candidate: string) {
+		const result = yield* Effect.either(fileSystem.readLink(candidate))
+		if (Either.isRight(result)) return yield* new MutationSymlinkError({ path: candidate })
+		const error = result.left
+		if (
+			error instanceof PlatformError.SystemError &&
+			(error.reason === 'InvalidData' ||
+				error.reason === 'NotFound' ||
+				(error.method === 'readLink' && isErrnoCode(error.cause, 'EINVAL')))
+		) {
+			return
+		}
+		return yield* error
+	})
+
+	const inspectLineage = Effect.fnUntraced(function* (target: string) {
+		return yield* Effect.forEach(pathLineage(pathService, target), (candidate) =>
+			Effect.gen(function* () {
+				yield* assertNotSymbolicLink(candidate)
+				const exists = yield* fileSystem.exists(candidate)
+				if (!exists) {
+					const missing: PathIdentity = { path: candidate, exists: false }
+					return missing
+				}
+				const info = yield* fileSystem.stat(candidate)
+				const identity: PathIdentity = {
+					path: candidate,
+					exists: true,
+					dev: info.dev,
+					ino: Option.getOrUndefined(info.ino),
+					realPath: yield* fileSystem.realPath(candidate),
+					type: info.type,
+				}
+				return identity
+			}),
+		)
+	})
+
+	// @effect/platform and Node expose only path-based mutation APIs here: this
+	// closes detected lineage races but cannot eliminate the final syscall TOCTOU
+	// window without non-portable openat/renameat/unlinkat-style primitives.
+	const withStableLineage = Effect.fnUntraced(function* <A, E, R>(target: string, action: Effect.Effect<A, E, R>) {
+		const before = yield* inspectLineage(target)
+		const actionExit = yield* Effect.exit(action)
+		const afterExit = yield* Effect.exit(inspectLineage(target))
+		if (Exit.isFailure(afterExit)) {
+			return yield* Exit.isFailure(actionExit)
+				? Effect.failCause(Cause.sequential(actionExit.cause, afterExit.cause))
+				: Effect.failCause(afterExit.cause)
+		}
+		if (!identitiesEqual(before, afterExit.value)) {
+			const changed = new MutationPathChangedError({ path: target })
+			return yield* Exit.isFailure(actionExit)
+				? Effect.failCause(Cause.sequential(actionExit.cause, Cause.fail(changed)))
+				: changed
+		}
+		return yield* Exit.isFailure(actionExit) ? Effect.failCause(actionExit.cause) : Effect.succeed(actionExit.value)
+	})
+
+	const rawSnapshot = Effect.fnUntraced(function* (target: string, includeDirectoryEntries: boolean) {
+		const exists = yield* fileSystem.exists(target)
+		if (!exists) {
+			const absent: Snapshot = { exists: false }
+			return absent
+		}
+		const info = yield* fileSystem.stat(target)
+		if (info.type === 'File') {
+			const file: Snapshot = {
+				exists: true,
+				bytes: yield* fileSystem.readFile(target),
+				dev: info.dev,
+				ino: Option.getOrUndefined(info.ino),
+				mode: info.mode & MODE_MAX,
+				realPath: yield* fileSystem.realPath(target),
+				type: 'File',
+			}
+			return file
+		}
+		if (info.type === 'Directory') {
+			const entries = includeDirectoryEntries ? [...(yield* fileSystem.readDirectory(target))].sort() : undefined
+			const directory: Snapshot = {
+				exists: true,
+				dev: info.dev,
+				...(entries === undefined ? {} : { entries }),
+				ino: Option.getOrUndefined(info.ino),
+				mode: info.mode & MODE_MAX,
+				realPath: yield* fileSystem.realPath(target),
+				type: 'Directory',
+			}
+			return directory
+		}
+		return yield* new MutationPathChangedError({ path: target })
+	})
+
+	const snapshot = Effect.fnUntraced(function* (target: string, includeDirectoryEntries: boolean = true) {
+		return yield* withStableLineage(
+			target,
+			rawSnapshot(target, includeDirectoryEntries).pipe(
+				Effect.flatMap((first) =>
+					rawSnapshot(target, includeDirectoryEntries).pipe(
+						Effect.flatMap((second) =>
+							statesEqual(first, second) ? Effect.succeed(second) : new MutationPathChangedError({ path: target }),
+						),
+					),
+				),
+			),
+		)
+	})
+
+	const validateMode = Effect.fnUntraced(function* (operation: MutationOperation) {
+		if ('mode' in operation && operation.mode !== undefined) {
+			const valid = Number.isInteger(operation.mode) && operation.mode >= 0 && operation.mode <= MODE_MAX
+			if (!valid) return yield* invalidMutation(operation, `Invalid file mode ${operation.mode}`)
+		}
+	})
+
+	const validateOperations = Effect.fnUntraced(function* (operations: ReadonlyArray<MutationOperation>) {
+		const targets = new Set<string>()
+		const plannedDirectories = new Set<string>()
+		return yield* Effect.forEach(operations, (operation) => {
+			const absolutePath = pathService.resolve(operation.path)
+			return Effect.gen(function* () {
+				if (targets.has(absolutePath)) {
+					return yield* invalidMutation(operation, `Multiple mutations target ${absolutePath}`)
+				}
+				targets.add(absolutePath)
+				yield* validateMode(operation)
+
+				const lineage = yield* inspectLineage(absolutePath)
+				yield* Effect.forEach(
+					lineage,
+					(identity, index) => {
+						const isTarget = index === lineage.length - 1
+						if (!identity.exists) {
+							const permitted = operation.type === 'mkdir' || isTarget || plannedDirectories.has(identity.path)
+							return permitted
+								? Effect.void
+								: invalidMutation(operation, `Parent directory does not exist: ${identity.path}`)
+						}
+						if (!isTarget && identity.type !== 'Directory') {
+							return invalidMutation(operation, `Parent path is not a directory: ${identity.path}`)
+						}
+						if (isTarget && operation.type === 'mkdir' && identity.type !== 'Directory') {
+							return invalidMutation(operation, `Directory mutation targets ${identity.type}: ${identity.path}`)
+						}
+						if (isTarget && operation.type !== 'mkdir' && identity.type !== 'File') {
+							return invalidMutation(operation, `File mutation targets ${identity.type}: ${identity.path}`)
+						}
+						return Effect.void
+					},
+					{ discard: true },
+				)
+
+				if (operation.validate !== undefined) yield* operation.validate
+				if (operation.type === 'mkdir') {
+					Array.forEach(pathLineage(pathService, absolutePath), (candidate) => plannedDirectories.add(candidate))
+				}
+				return { operation, absolutePath } as const
+			}).pipe(
+				Effect.mapError((error) =>
+					error instanceof MutationValidationError || error instanceof MutationSymlinkError
+						? error
+						: validationError(operation, error),
+				),
+			)
+		})
+	})
+
+	/**
+	 * Scoped per call, not per transaction. The staging container lives inside the
+	 * target's own parent directory, so while it exists it is an entry in that
+	 * directory — and `statesEqual` compares directory entries. Holding the
+	 * finalizer until the end of `run` therefore made rollback fail on exactly the
+	 * case it exists for: a write into a directory this transaction created, whose
+	 * restore compares the parent against a snapshot taken before the container
+	 * appeared, sees one extra entry, and aborts with a rollback conflict.
+	 */
+	const writeAtomically = Effect.fnUntraced(function* (
+		target: string,
+		contents: Uint8Array,
+		expectedCurrent: Snapshot,
+		mode?: number,
+		onInstalled?: (installed: Snapshot) => Effect.Effect<void>,
+	) {
+		const parent = pathService.dirname(target)
+		const temporary = yield* Effect.acquireRelease(
+			withStableLineage(parent, fileSystem.makeTempFile({ directory: parent, prefix: '.expandai-init-' })),
+			// `makeTempFile` nests the file inside its own `.expandai-init-*`
+			// directory, so removing just the file left that directory behind on
+			// every atomic write — they accumulated in the user's home and survived
+			// `uninstall`. Remove the container, never the target's own parent.
+			(temporary) => {
+				const container = pathService.dirname(temporary)
+				const stray = pathService.resolve(container) !== pathService.resolve(parent)
+				return withStableLineage(
+					parent,
+					stray
+						? fileSystem.remove(container, { force: true, recursive: true })
+						: fileSystem.remove(temporary, { force: true }),
+				).pipe(Effect.ignore)
+			},
+		)
+		yield* withStableLineage(temporary, fileSystem.writeFile(temporary, contents))
+		if (mode !== undefined) yield* withStableLineage(temporary, fileSystem.chmod(temporary, mode))
+		const temporarySnapshot = yield* snapshot(temporary)
+		const expectedInstalled: Snapshot = { ...temporarySnapshot, realPath: pathService.resolve(target) }
+		yield* withStableLineage(
+			parent,
+			Effect.gen(function* () {
+				const current = yield* snapshot(target)
+				if (!ownershipEqual(current, expectedCurrent)) {
+					return yield* new MutationPathChangedError({ path: target })
+				}
+				// Install and register-the-undo, atomically. Everything after this point
+				// — including the post-install verification below — can fail freely:
+				// the undo is already on the scope, so rollback knows about the change.
+				// This is the only mask left, and it is two statements wide.
+				yield* Effect.uninterruptible(
+					fileSystem
+						.rename(temporary, target)
+						.pipe(Effect.zipRight(onInstalled === undefined ? Effect.void : onInstalled(expectedInstalled))),
+				)
+			}),
+		)
+		const installed = yield* snapshot(target)
+		if (!ownershipEqual(installed, expectedInstalled)) return yield* new MutationPathChangedError({ path: target })
+		return installed
+	}, Effect.scoped)
+
+	const removeSafely = Effect.fnUntraced(function* (
+		target: string,
+		expectedCurrent: Snapshot,
+		onInstalled?: (installed: Snapshot) => Effect.Effect<void>,
+	) {
+		const installed: Snapshot = { exists: false }
+		const remove =
+			expectedCurrent.type === 'Directory' ? fileSystem.remove(target, { recursive: true }) : fileSystem.remove(target)
+		yield* withStableLineage(
+			pathService.dirname(target),
+			Effect.gen(function* () {
+				const current = yield* snapshot(target)
+				if (!ownershipEqual(current, expectedCurrent)) {
+					return yield* new MutationPathChangedError({ path: target })
+				}
+				yield* Effect.uninterruptible(
+					remove.pipe(Effect.zipRight(onInstalled === undefined ? Effect.void : onInstalled(installed))),
+				)
+			}),
+		)
+		const verified = yield* snapshot(target)
+		if (!statesEqual(verified, installed)) return yield* new MutationPathChangedError({ path: target })
+		return installed
+	})
+
+	const makeDirectoryAtomically = Effect.fnUntraced(function* (
+		target: string,
+		expectedCurrent: Snapshot,
+		mode?: number,
+		onInstalled?: (installed: Snapshot) => Effect.Effect<void>,
+	) {
+		const parent = pathService.dirname(target)
+		const temporary = yield* Effect.acquireRelease(
+			withStableLineage(
+				parent,
+				fileSystem.makeTempDirectory({ directory: parent, prefix: '.expandai-init-directory-' }),
+			),
+			(temporary) =>
+				withStableLineage(parent, fileSystem.remove(temporary, { force: true, recursive: true })).pipe(Effect.ignore),
+		)
+		if (mode !== undefined) yield* withStableLineage(temporary, fileSystem.chmod(temporary, mode))
+		const temporarySnapshot = yield* snapshot(temporary)
+		const expectedInstalled: Snapshot = { ...temporarySnapshot, realPath: pathService.resolve(target) }
+		yield* withStableLineage(
+			parent,
+			Effect.gen(function* () {
+				const current = yield* snapshot(target)
+				if (!ownershipEqual(current, expectedCurrent)) {
+					return yield* new MutationPathChangedError({ path: target })
+				}
+				// Install and register-the-undo, atomically. Everything after this point
+				// — including the post-install verification below — can fail freely:
+				// the undo is already on the scope, so rollback knows about the change.
+				// This is the only mask left, and it is two statements wide.
+				yield* Effect.uninterruptible(
+					fileSystem
+						.rename(temporary, target)
+						.pipe(Effect.zipRight(onInstalled === undefined ? Effect.void : onInstalled(expectedInstalled))),
+				)
+			}),
+		)
+		const installed = yield* snapshot(target)
+		if (!ownershipEqual(installed, expectedInstalled)) return yield* new MutationPathChangedError({ path: target })
+		return installed
+	}, Effect.scoped)
+
+	/**
+	 * Each undo banks its own cause: `addFinalizer` requires `Effect<X, never, R>`,
+	 * so a release cannot fail in the typed channel. `run` folds these into the
+	 * transaction's failure once the scope has closed, preserving the reporting the
+	 * old `attachRollbackFailures` path gave us.
+	 */
+	const bankFailure = (
+		failures: MutationFailure[],
+		path: string,
+		operation: MutationType,
+		undo: Effect.Effect<unknown, unknown>,
+	) =>
+		Effect.exit(undo).pipe(
+			Effect.flatMap((exit) =>
+				Exit.isSuccess(exit)
+					? Effect.void
+					: Effect.sync(() => {
+							failures.push({ path, operation, error: exit.cause })
+						}).pipe(
+							// Also logged, not only banked. When the transaction is
+							// interrupted rather than failed, the fiber may never reach the
+							// bookkeeping that folds these into the returned cause — and
+							// "rollback was incomplete" is the one thing an operator must not
+							// lose. The typed cause still carries them on every other path.
+							Effect.zipRight(Effect.logError(`Rollback failed for ${path} (${operation})`, Cause.pretty(exit.cause))),
+						),
+			),
+		)
+
+	/**
+	 * Confirms the change is still ours, applies `restore`, and confirms the result
+	 * matches the state we started from.
+	 *
+	 * The *shape* of the restoration comes from the caller — the code that knows
+	 * what it just did — not from inspecting `before` here. The previous version
+	 * branched on `before.type` with no branch for a directory, so an unhandled
+	 * prior state surfaced as a rollback *conflict*, blaming a concurrent writer
+	 * for a case nobody had implemented.
+	 */
+	const undoWith = Effect.fnUntraced(function* (
+		path: string,
+		installed: Snapshot,
+		before: Snapshot,
+		restore: (current: Snapshot) => Effect.Effect<unknown, unknown>,
+	) {
+		const current = yield* snapshot(path)
+		if (!ownershipEqual(current, installed)) return yield* new MutationRollbackConflictError({ path })
+		yield* restore(current)
+		const restored = yield* snapshot(path)
+		if (!statesEqual(restored, before)) return yield* new MutationRollbackConflictError({ path })
+	})
+
+	/** Undo for something created where nothing was: remove it again. */
+	const undoToAbsent = (path: string, installed: Snapshot, before: Snapshot) =>
+		undoWith(path, installed, before, (current) => removeSafely(path, current))
+
+	/** Undo for something replaced or deleted: put the original bytes back. */
+	const undoToFile = (path: string, installed: Snapshot, before: Snapshot, bytes: Uint8Array) =>
+		undoWith(path, installed, before, (current) => writeAtomically(path, bytes, current, before.mode))
+
+	/**
+	 * Applies one mutation, registering the effect that reverses it on `scope` at
+	 * the instant it lands.
+	 *
+	 * The scope is passed explicitly rather than taken from the environment: an
+	 * ambient scope of transaction lifetime would silently adopt any future
+	 * unscoped `acquireRelease` in this file and hold its resource open for the
+	 * whole transaction — the defect that once made rollback fail. Staging
+	 * resources still scope to the single operation that creates them.
+	 */
+	const applyOne = Effect.fnUntraced(function* (
+		planned: PlannedMutation,
+		scope: Scope.Scope,
+		failures: MutationFailure[],
+	) {
+		const { operation, path, snapshot: before } = planned
+		const current = yield* snapshot(path)
+		if (!ownershipEqual(current, before)) return yield* new MutationPathChangedError({ path })
+
+		const register =
+			(undoPath: string, undo: (installed: Snapshot) => Effect.Effect<unknown, unknown>) => (installed: Snapshot) =>
+				Scope.addFinalizerExit(scope, (exit) =>
+					Exit.isSuccess(exit) ? Effect.void : bankFailure(failures, undoPath, operation.type, undo(installed)),
+				)
+
+		if (operation.type === 'write') {
+			const desiredMode = operation.mode ?? before.mode
+			if (before.type === 'File' && bytesEqual(before.bytes, operation.bytes) && before.mode === desiredMode) return
+			const original = before.exists ? before.bytes : undefined
+			yield* writeAtomically(
+				path,
+				operation.bytes,
+				before,
+				desiredMode,
+				register(path, (installed) =>
+					original === undefined
+						? undoToAbsent(path, installed, before)
+						: undoToFile(path, installed, before, original),
+				),
+			)
+			return
+		}
+		if (operation.type === 'remove') {
+			if (!before.exists) return
+			// Validation refuses a non-`File` target, so the bytes are present.
+			const original = before.bytes
+			if (original === undefined) return yield* new MutationPathChangedError({ path })
+			yield* removeSafely(
+				path,
+				before,
+				register(path, (installed) => undoToFile(path, installed, before, original)),
+			)
+			return
+		}
+
+		if (before.exists) return
+		yield* Effect.forEach(
+			pathLineage(pathService, path),
+			(candidate) =>
+				Effect.gen(function* () {
+					// Existing ancestors are owned by other processes. Their identity
+					// must stay stable, but unrelated sibling entries may legitimately churn.
+					const candidateBefore = yield* snapshot(candidate, false)
+					if (candidateBefore.exists) return
+					yield* makeDirectoryAtomically(
+						candidate,
+						candidateBefore,
+						operation.mode,
+						register(candidate, (installed) => undoToAbsent(candidate, installed, candidateBefore)),
+					)
+				}),
+			{ discard: true },
+		)
+	})
+
+	const attachRollbackFailures = Effect.fnUntraced(function* (
+		cause: Cause.Cause<MutationTransactionError>,
+		rollbackFailures: ReadonlyArray<MutationFailure>,
+	) {
+		if (rollbackFailures.length === 0) return cause
+		const mapped = Cause.map(cause, (error) =>
+			error instanceof MutationApplicationError
+				? new MutationApplicationError({
+						path: error.path,
+						operation: error.operation,
+						error: error.error,
+						rollbackFailures: [...rollbackFailures],
+					})
+				: error,
+		)
+		const hasApplicationError = Chunk.some(Cause.failures(cause), (error) => error instanceof MutationApplicationError)
+		return hasApplicationError
+			? mapped
+			: Cause.sequential(mapped, Cause.fail(new MutationRollbackError({ rollbackFailures: [...rollbackFailures] })))
+	})
+
+	const run = Effect.fn('MutationTransaction.run')(function* (operations: ReadonlyArray<MutationOperation>) {
+		const validated = yield* validateOperations(operations)
+		const planned = yield* Effect.forEach(validated, ({ operation, absolutePath }) =>
+			Effect.gen(function* () {
+				const actual = yield* snapshot(absolutePath)
+				if (operation.expected !== undefined && !matchesExpectedState(actual, operation.expected)) {
+					return yield* invalidMutation(operation, 'Expected mutation state no longer matches')
+				}
+				return { operation, path: absolutePath, snapshot: actual } satisfies PlannedMutation
+			}).pipe(
+				Effect.mapError((error) =>
+					error instanceof MutationValidationError ? error : validationError(operation, error),
+				),
+			),
+		)
+
+		// Rollback is a scope, not a transaction-wide mask.
+		//
+		// Each installer registers its undo on `scope` in the same uninterruptible
+		// step that performs the change, so no change can exist on disk that rollback
+		// does not know about — including one whose post-install verification then
+		// fails. `Effect.onExit` is `uninterruptibleMask((restore) =>
+		// matchCauseEffect(restore(self), ...))` (`core.ts:1113`), so closing the
+		// scope runs every undo, in reverse order of registration
+		// (`fiberRuntime.ts:3256`), and cannot itself be interrupted. Both guarantees
+		// come from combinators rather than from this function remembering to restore
+		// correctly.
+		const scope = yield* Scope.make()
+		// Per run, not per service: two transactions on one `MutationTransaction`
+		// instance would otherwise share one array and cross-attribute — or clear —
+		// each other's rollback diagnostics.
+		const rollbackFailures: MutationFailure[] = []
+		const application = Effect.forEach(
+			planned,
+			(item) =>
+				applyOne(item, scope, rollbackFailures).pipe(
+					Effect.mapError((error) =>
+						error instanceof MutationApplicationError ? error : applicationError(item.operation, error),
+					),
+				),
+			{ discard: true },
+		)
+
+		const exit = yield* Effect.exit(
+			application.pipe(Effect.onExit((applicationExit) => Scope.close(scope, applicationExit))),
+		)
+		if (Exit.isSuccess(exit)) return
+
+		const cause = yield* attachRollbackFailures(exit.cause, rollbackFailures)
+		return yield* Effect.failCause(cause)
+	})
+
+	return { run } as const
+})
+
+export class MutationTransaction extends Effect.Service<MutationTransaction>()(
+	'@expandai/cli/Init/MutationTransaction',
+	{
+		dependencies: [NodeFileSystem.layer, NodePath.layer],
+		effect: makeMutationTransaction,
+	},
+) {}