@smthrs/engine-store 0.0.0-stage → 1.0.0-rc.4

package/dist/esm/WorkspaceSandbox.js

@@ -0,0 +1,985 @@
+/**
+ * Functional workspace transactions for action execution.
+ *
+ * An action body normally mutates the host tree in place, which leaves the
+ * engine two bad options: trust the declaration, or diff the whole repository
+ * after the fact. This module takes the third one. The body runs against an
+ * **isolated workspace** seeded with exactly its declared read set; its writes
+ * are a value — a whole-tree diff — that reaches the host only through an
+ * explicit {@link Service.materialize} step with preconditions and rollback.
+ *
+ * Two consequences follow, and they are the reason this exists:
+ *
+ * - **Whole-tree write observation is structural.** The transaction *is* the
+ *   tree, so "did this body write outside its declared write set" is a map
+ *   comparison, not an inference. `StepBoundary`'s filesystem layer can only
+ *   re-measure paths it was told about, which is why it never claims
+ *   `wholeTreeWritesVerified` and why nothing it settled could enter the
+ *   cross-run cache.
+ * - **The host is untouched until copy-back.** An execution whose observations
+ *   contradict its declaration is {@link Invalidated}, and an invalidated
+ *   result exposes provenance and violations *only* — never the candidate
+ *   output, files, or queued effects.
+ *
+ * This is a **deterministic transaction model, not a security boundary** — the
+ * same caveat the proof of concept carried. A body that reaches the host
+ * through a service this module does not seed (a spawned native process, an
+ * undecorated socket) is outside the transaction. Actually denying that
+ * ambient access requires a machine boundary such as the providers in
+ * `packages/smithers/flows/sandbox/docs/api.md`. The one host
+ * write this module *does* perform is confined, however: copy-back resolves
+ * symlinks before it lands a byte and refuses any target whose canonical
+ * location escapes the workspace root.
+ *
+ * Settled bundles reach the host without a human review gate. Governing
+ * design: `docs/concepts/workspace-transactions.md`.
+ *
+ * @since 0.1.0
+ */
+import * as ArtifactStore from "@smthrs/artifacts/ArtifactStore";
+import * as FileLease from "@smthrs/artifacts/FileLease";
+import { Sha256 } from "@smthrs/crypto";
+import * as KernelFileSystem from "@smthrs/kernel/FileSystem";
+import { Workspace as KernelWorkspace } from "@smthrs/kernel/Workspace";
+import { DerivedKey } from "@smthrs/keys";
+import * as FileSet from "@smthrs/plan/FileSet";
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Metric from "effect/Metric";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import * as RcMap from "effect/RcMap";
+import * as Ref from "effect/Ref";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Semaphore from "effect/Semaphore";
+import * as EngineStoreMetrics from "./EngineStoreMetrics.js";
+import * as FileBoundarySnapshot from "./internal/FileBoundarySnapshot.js";
+import * as FileEnumeration from "./internal/FileEnumeration.js";
+import { compareText } from "./internal/Ordering.js";
+/**
+ * Context service made available only inside a workspace transaction.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export const Workspace = Context.Service("@smthrs/engine-store/WorkspaceSandbox/Workspace");
+/**
+ * Stable workspace sandbox failure codes.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const WorkspaceErrorCode = Schema.Literals([
+    "invalid_path",
+    "not_found",
+    "host_unavailable",
+    "path_escapes_workspace",
+    "commit_lock_timeout"
+]);
+/**
+ * A body could not execute inside — or its result could not be moved through —
+ * an isolated workspace.
+ *
+ * `cause` carries the refusing host or artifact-store failure whole, so a
+ * debugger sees the original error instead of a flattened message
+ * (`PlatformError`'s own convention).
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class WorkspaceError extends Schema.TaggedError()("@smthrs/engine-store/WorkspaceError", {
+    code: WorkspaceErrorCode,
+    message: Schema.String,
+    cause: Schema.optional(Schema.Defect())
+}) {
+}
+/**
+ * Copy-back would overwrite host state that changed since the transaction's
+ * base snapshot was taken.
+ *
+ * The engine answers this by retrying the attempt from a fresh base a bounded
+ * number of times. This local retry is rebase-shaped. The worktree-lane
+ * surface was removed; this error does not recreate it.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class MaterializationConflict extends Schema.TaggedError()("@smthrs/engine-store/MaterializationConflict", {
+    paths: Schema.Array(Schema.NonEmptyString.check(Schema.isMaxLength(4_096))).check(Schema.isMaxLength(1_024)),
+    message: Schema.NonEmptyString.check(Schema.isMaxLength(16_384))
+}) {
+}
+/**
+ * Whether a failure is a materialization conflict in live or durable form.
+ * Persisted failures retain the schema tag but not the class prototype, so
+ * replay classification must recognize both representations.
+ *
+ * @category guards
+ * @since 0.1.0
+ */
+export const isMaterializationConflict = (error) => {
+    if (typeof error !== "object" || error === null)
+        return false;
+    try {
+        if (error instanceof MaterializationConflict)
+            return true;
+        const own = (name) => {
+            const descriptor = Object.getOwnPropertyDescriptor(error, name);
+            return descriptor !== undefined && descriptor.enumerable && "value" in descriptor
+                ? descriptor.value
+                : undefined;
+        };
+        const paths = own("paths");
+        const message = own("message");
+        if (own("_tag") !== MaterializationConflict.identifier ||
+            typeof message !== "string" ||
+            message.length === 0 ||
+            message.length > 16_384 ||
+            !Array.isArray(paths) ||
+            Object.getPrototypeOf(paths) !== Array.prototype ||
+            paths.length > 1_024)
+            return false;
+        for (let index = 0; index < paths.length; index++) {
+            const descriptor = Object.getOwnPropertyDescriptor(paths, String(index));
+            if (descriptor === undefined ||
+                !("value" in descriptor) ||
+                !descriptor.enumerable ||
+                typeof descriptor.value !== "string" ||
+                descriptor.value.length === 0 ||
+                descriptor.value.length > 4_096)
+                return false;
+        }
+        if (Reflect.ownKeys(paths).some((key) => key !== "length" &&
+            (typeof key !== "string" || !/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= paths.length)))
+            return false;
+        return Reflect.ownKeys(error).every((key) => key === "_tag" || key === "paths" || key === "message");
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Context service for the selected workspace sandbox implementation.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export const WorkspaceSandbox = Context.Service("@smthrs/engine-store/WorkspaceSandbox");
+/**
+ * Constructs a workspace sandbox from an implementation.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (service) => WorkspaceSandbox.of(service);
+/**
+ * Provides a workspace sandbox implementation.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = (service) => Layer.succeed(WorkspaceSandbox, make(service));
+/**
+ * Context service for the queued-effect dispatch stage. Optional: with no
+ * dispatcher provided the engine journals what a transaction queued and sends
+ * nothing.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export const EffectDispatcher = Context.Service("@smthrs/engine-store/WorkspaceSandbox/EffectDispatcher");
+/**
+ * Provides a queued-effect dispatch stage.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerDispatcher = (dispatcher) => Layer.succeed(EffectDispatcher, EffectDispatcher.of(dispatcher));
+// -----------------------------------------------------------------------------
+// path vocabulary
+// -----------------------------------------------------------------------------
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+const invalidPath = (path) => new WorkspaceError({
+    code: "invalid_path",
+    message: `Workspace paths must be relative paths inside the workspace without '..': ${path}`
+});
+/**
+ * Normalizes a caller path to a workspace-relative key.
+ *
+ * Absolute paths are accepted only under `root`, which is how a body that
+ * resolved `workspace.root` itself still lands inside the transaction; every
+ * other absolute path, and anything traversing upward, is refused rather than
+ * silently confined.
+ */
+const normalizePath = (root, path, allowRoot = false) => {
+    const slashed = path.replaceAll("\\", "/");
+    const slashedRoot = root.replaceAll("\\", "/");
+    const rooted = slashed === slashedRoot
+        ? ""
+        : slashedRoot !== "" && slashed.startsWith(`${slashedRoot}/`)
+            ? slashed.slice(slashedRoot.length + 1)
+            : slashed;
+    const parts = rooted.split("/");
+    if (rooted.startsWith("/") || parts.some((part) => part === ".."))
+        return Result.fail(invalidPath(path));
+    const compact = parts.filter((part) => part !== "" && part !== ".").join("/");
+    return compact === "" && !allowRoot ? Result.fail(invalidPath(path)) : Result.succeed(compact);
+};
+/**
+ * Whether a declared write-set entry covers an observed path. A plain string
+ * is a literal path, even when it contains `*` or `**`, exactly as
+ * `StepBoundary` captures and `FileSet.overlaps` compares it; wildcard
+ * declarations are written as a Glob.
+ */
+const covers = (entry, path) => typeof entry === "string"
+    ? entry === path
+    : entry._tag === "TreeArtifact"
+        ? path === entry.path || path.startsWith(`${entry.path}/`)
+        : FileSet.matchesGlob(entry, path);
+const resource = (path) => ({ kind: "file", id: path });
+/**
+ * Restates a declaration in the transaction's own path vocabulary.
+ *
+ * A caller may declare `out/result.txt` or the absolute path the same file has
+ * on the host — the kernel-decorated `FileSystem` accepts both, so the
+ * declaration does too. Observed paths are always workspace-relative, so the
+ * declaration has to be brought to the same footing before anything is
+ * compared against it, or an absolute declaration would cover nothing and
+ * every write would read as undeclared. An entry that cannot be named inside
+ * the workspace is kept verbatim: it covers nothing, which is the honest
+ * answer for a declaration pointing outside the tree.
+ */
+const workspaceRelative = (root, descriptor) => {
+    const relative = (path) => {
+        const normalized = normalizePath(root, path);
+        return Result.isFailure(normalized) ? path : normalized.success;
+    };
+    return {
+        readSet: descriptor.readSet.map((entry) => FileSet.isGlob(entry)
+            ? {
+                ...entry,
+                include: [relative(entry.include[0]), ...entry.include.slice(1).map(relative)],
+                ...(entry.exclude === undefined ? {} : { exclude: entry.exclude.map(relative) })
+            }
+            : { ...entry, path: relative(entry.path) }),
+        writeSet: descriptor.writeSet.map((entry) => typeof entry === "string"
+            ? relative(entry)
+            : entry._tag === "TreeArtifact"
+                ? { ...entry, path: relative(entry.path) }
+                : {
+                    ...entry,
+                    include: [relative(entry.include[0]), ...entry.include.slice(1).map(relative)],
+                    ...(entry.exclude === undefined ? {} : { exclude: entry.exclude.map(relative) })
+                }),
+        ...(descriptor.removes === undefined ? {} : { removes: descriptor.removes.map(relative) }),
+        boundaryMode: descriptor.boundaryMode
+    };
+};
+const digestOf = (bytes) => Schema.decodeUnknownEffect(Sha256)(bytes).pipe(Effect.orDie);
+const parentDirectory = (path) => {
+    const index = path.lastIndexOf("/");
+    return index <= 0 ? undefined : path.slice(0, index);
+};
+const notFound = (path) => new WorkspaceError({ code: "not_found", message: `Workspace file does not exist: ${path}` });
+/**
+ * The transaction surfaces: the {@link Workspace} tag and a re-rooted Effect
+ * `FileSystem`, both over one path-keyed map.
+ *
+ * The `FileSystem` is built from `makeNoop` on purpose. Only the operations
+ * listed here are meaningful over a functional map, and a body reaching for
+ * one that is not — a temp file, a watch, a stream — gets the platform's own
+ * refusal rather than a plausible lie. Widening the surface is a deliberate
+ * change to this list, never a silent default.
+ */
+const transaction = (base, trace, root) => {
+    const files = new Map(base);
+    const produced = new Set();
+    const resolvePath = (path, allowRoot = false) => {
+        const normalized = normalizePath(root, path, allowRoot);
+        return Result.isFailure(normalized) ? Effect.fail(normalized.failure) : Effect.succeed(normalized.success);
+    };
+    const readBytes = Effect.fn("WorkspaceSandbox.read")(function* (path) {
+        const key = yield* resolvePath(path);
+        trace.attemptedReads.push({ path: key, produced: produced.has(key) });
+        const content = files.get(key);
+        if (content === undefined)
+            return yield* Effect.fail(notFound(key));
+        trace.inputs.push({ path: key, content });
+        return content.slice();
+    });
+    const writeBytes = Effect.fn("WorkspaceSandbox.write")(function* (path, content) {
+        const key = yield* resolvePath(path);
+        produced.add(key);
+        files.set(key, content.slice());
+    });
+    const removePath = Effect.fn("WorkspaceSandbox.remove")(function* (path) {
+        const key = yield* resolvePath(path);
+        produced.add(key);
+        files.delete(key);
+    });
+    const workspace = Workspace.of({
+        readFile: (path) => readBytes(path),
+        writeFile: (path, content) => writeBytes(path, content),
+        removeFile: (path) => removePath(path),
+        queueEffect: (effect) => Effect.sync(() => trace.effects.push(effect))
+    });
+    const refuse = (method, path) => (error) => error.code === "not_found"
+        ? PlatformError.systemError({
+            _tag: "NotFound",
+            module: "FileSystem",
+            method,
+            description: error.message,
+            pathOrDescriptor: path
+        })
+        : PlatformError.badArgument({ module: "FileSystem", method, description: error.message });
+    const fileSystem = FileSystem.makeNoop({
+        // `exists` and `readDirectory` trace every PRESENCE they reveal: under a
+        // whole-tree-seeding host the map holds undeclared world state, and a
+        // probe that observes it is a read the key never folded. Absence stays
+        // untraced — under the declared-set host an undeclared path is absent by
+        // construction, the Bazel forest's own deterministic answer.
+        exists: (path) => resolvePath(path, true).pipe(Effect.map((key) => {
+            if (key === "")
+                return true;
+            if (files.has(key)) {
+                trace.attemptedReads.push({ path: key, produced: produced.has(key) });
+                return true;
+            }
+            const prefix = `${key}/`;
+            let present = false;
+            for (const candidate of files.keys()) {
+                if (!candidate.startsWith(prefix))
+                    continue;
+                trace.attemptedReads.push({ path: candidate, produced: produced.has(candidate) });
+                present = true;
+            }
+            return present;
+        }), 
+        // A path the transaction cannot even name does not exist in it; that
+        // is an answer, not a host failure.
+        Effect.catch(() => Effect.succeed(false))),
+        readFile: (path) => readBytes(path).pipe(Effect.mapError(refuse("readFile", path))),
+        readFileString: (path) => readBytes(path).pipe(Effect.map((bytes) => decoder.decode(bytes)), Effect.mapError(refuse("readFileString", path))),
+        writeFile: (path, data) => writeBytes(path, data).pipe(Effect.mapError(refuse("writeFile", path))),
+        writeFileString: (path, data) => writeBytes(path, encoder.encode(data)).pipe(Effect.mapError(refuse("writeFileString", path))),
+        remove: (path) => removePath(path).pipe(Effect.mapError(refuse("remove", path))),
+        // Directories are implicit in a path-keyed map: creating one is a
+        // successful no-op so a body that mirrors ordinary filesystem discipline
+        // works unchanged, and listing one is a prefix scan.
+        makeDirectory: () => Effect.void,
+        readDirectory: (path) => resolvePath(path, true).pipe(Effect.map((key) => {
+            const prefix = key === "" ? "" : `${key}/`;
+            const entries = new Set();
+            for (const candidate of files.keys()) {
+                if (!candidate.startsWith(prefix))
+                    continue;
+                // A listing reveals each file it names, so each is a traced read.
+                trace.attemptedReads.push({ path: candidate, produced: produced.has(candidate) });
+                entries.add(candidate.slice(prefix.length).split("/")[0]);
+            }
+            return [...entries].sort(compareText);
+        }), Effect.mapError(refuse("readDirectory", path)))
+    });
+    return { files, workspace, fileSystem };
+};
+const changes = Effect.fn("WorkspaceSandbox.changes")(function* (base, current, host) {
+    const paths = [...new Set([...base.keys(), ...current.keys()])].sort(compareText);
+    const result = [];
+    for (const path of paths) {
+        const before = base.get(path);
+        const after = current.get(path);
+        // A path the transaction never observed is not a path the host lacks: ask
+        // the host what is there before claiming the change creates it.
+        const beforeDigest = before === undefined ? yield* host.baseline(path) : yield* digestOf(before);
+        const afterDigest = after === undefined ? undefined : yield* digestOf(after);
+        if (beforeDigest === afterDigest)
+            continue;
+        result.push({
+            path,
+            beforeDigest,
+            afterDigest,
+            ...(after === undefined ? {} : { after: yield* host.retain(after) })
+        });
+    }
+    return result;
+});
+/**
+ * The compare-and-set every copy-back runs before it writes a single byte,
+ * capturing each target's pre-image while it looks.
+ *
+ * Both hosts share it, so "all-or-nothing" cannot drift between the in-memory
+ * conformance implementation and the filesystem one: a bundle whose base moved
+ * is refused whole, and the tree is left exactly as it was found. The captured
+ * pre-images are the rollback journal the filesystem host restores from when a
+ * mid-apply refusal would otherwise strand a half-written tree.
+ */
+const preflight = Effect.fn("WorkspaceSandbox.preflight")(function* (changes, current) {
+    const conflicting = [];
+    const before = new Map();
+    for (const change of changes) {
+        const content = yield* current(change.path);
+        before.set(change.path, content);
+        const digest = content === undefined ? undefined : yield* digestOf(content);
+        conflicting.push(...(digest === change.beforeDigest ? [] : [change.path]));
+    }
+    const conflict = conflicting.length === 0 ? undefined : new MaterializationConflict({
+        paths: conflicting,
+        message: "Workspace state changed after the transaction's base snapshot was taken"
+    });
+    return { conflict, before };
+});
+const revisionOf = Effect.fn("WorkspaceSandbox.revision")(function* (base) {
+    const entries = [];
+    for (const [path, content] of [...base].sort((left, right) => compareText(left[0], right[0]))) {
+        entries.push({ path, digest: yield* digestOf(content) });
+    }
+    return yield* Schema.decodeUnknownEffect(DerivedKey)({ kind: "workspace-revision", entries }).pipe(Effect.orDie);
+});
+/**
+ * Everything the declaration failed to predict, deduplicated.
+ *
+ * Reads and writes are checked against the declaration's exact paths and patterns; writes
+ * against the declared write set's patterns. A read of a file the body itself
+ * produced is not undeclared — the transaction, not the host, supplied it.
+ *
+ * @category accessors
+ * @since 0.1.0
+ */
+export const violations = (descriptor, base, provenance) => {
+    const declaredReads = descriptor.readSet;
+    const observed = [
+        ...provenance.inputs
+            .filter((input) => base.has(input.resource.id) &&
+            !declaredReads.some((entry) => FileSet.isGlob(entry) ? FileSet.matchesGlob(entry, input.resource.id) : entry.path === input.resource.id))
+            .map((input) => ({ kind: "undeclared-read", resource: input.resource })),
+        ...provenance.outputs
+            .filter((output) => ![...descriptor.writeSet, ...descriptor.removes ?? []].some((entry) => covers(entry, output.resource.id)))
+            .map((output) => ({ kind: "undeclared-write", resource: output.resource }))
+    ];
+    return [
+        ...new Map(observed.map((violation) => [`${violation.kind}:${violation.resource.id}`, violation])).values()
+    ];
+};
+/**
+ * Builds a workspace sandbox over a {@link Host}.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeHosted = (host) => {
+    const memo = new Map();
+    /**
+     * The speculative half, untraced: the `execute` span below wraps it, so
+     * the transaction body reports under one span with its metrics.
+     */
+    const executeBody = Effect.fnUntraced(function* (execution) {
+        const boundary = FileBoundarySnapshot.make(execution.descriptor);
+        const key = execution.cacheKey;
+        if (key !== undefined) {
+            const hit = memo.get(key);
+            if (hit !== undefined) {
+                return {
+                    _tag: "Accepted",
+                    result: hit.result,
+                    violations: hit.violations,
+                    cache: { status: "hit", key }
+                };
+            }
+        }
+        const captured = yield* host.snapshot(boundary);
+        // The host owns its returned buffers. Preserve the instant represented by
+        // snapshot() even if that host or another fiber mutates them while the
+        // workflow is suspended.
+        const base = new Map([...captured].map(([path, content]) => [path, content.slice()]));
+        const trace = { inputs: [], attemptedReads: [], effects: [] };
+        const isolated = transaction(base, trace, host.root);
+        const outcome = yield* execution.workflow.pipe(Effect.provideService(Workspace, isolated.workspace), Effect.provideService(FileSystem.FileSystem, isolated.fileSystem), Effect.exit);
+        const inputs = [];
+        for (const input of trace.inputs) {
+            inputs.push({ resource: resource(input.path), digest: yield* digestOf(input.content) });
+        }
+        const descriptor = workspaceRelative(host.root, boundary);
+        const undeclaredReads = trace.attemptedReads.filter((attempt) => !attempt.produced &&
+            !descriptor.readSet.some((entry) => FileSet.isGlob(entry) ? FileSet.matchesGlob(entry, attempt.path) : entry.path === attempt.path));
+        if (Exit.isFailure(outcome)) {
+            // Hard mode only, mirroring the success path below: in expected mode
+            // an undeclared read is a deviation the engine journals, and a body's
+            // own typed failure must surface as itself — converting it into an
+            // isolation verdict would both harden a soft boundary and mask the
+            // error the retry policy classifies on.
+            if (undeclaredReads.length > 0 && boundary.boundaryMode === "hard") {
+                return {
+                    _tag: "Invalidated",
+                    provenance: {
+                        baseRevision: yield* revisionOf(base),
+                        inputs,
+                        outputs: []
+                    },
+                    violations: [
+                        ...new Map(undeclaredReads.map((attempt) => [attempt.path, {
+                                kind: "undeclared-read",
+                                resource: resource(attempt.path)
+                            }])).values()
+                    ]
+                };
+            }
+            return yield* Effect.failCause(outcome.cause);
+        }
+        const output = outcome.value;
+        const files = yield* changes(base, isolated.files, host);
+        const provenance = {
+            baseRevision: yield* revisionOf(base),
+            inputs,
+            outputs: files.map((change) => ({
+                resource: resource(change.path),
+                operation: change.afterDigest === undefined ? "remove" : "write",
+                digest: change.afterDigest
+            }))
+        };
+        const invalid = [
+            ...new Map([
+                ...violations(descriptor, base, provenance),
+                ...undeclaredReads.map((attempt) => ({
+                    kind: "undeclared-read",
+                    resource: resource(attempt.path)
+                }))
+            ].map((violation) => [`${violation.kind}:${violation.resource.id}`, violation])).values()
+        ];
+        // Hard mode discards; expected mode admits the result and leaves the
+        // deviation for the engine to journal and reconcile
+        // (`Effect Taxonomy.md`, "Expected sets — the soft mode"). Either way
+        // the host has not been touched.
+        if (invalid.length > 0 && boundary.boundaryMode === "hard") {
+            return { _tag: "Invalidated", provenance, violations: invalid };
+        }
+        const result = { output, files, provenance, effects: trace.effects };
+        if (key !== undefined) {
+            memo.set(key, { result: result, violations: invalid });
+        }
+        return {
+            _tag: "Accepted",
+            result,
+            violations: invalid,
+            cache: key === undefined ? { status: "disabled" } : { status: "miss", key }
+        };
+    });
+    return make({
+        execute: Effect.fn("WorkspaceSandbox.execute")(function* (execution) {
+            yield* Effect.annotateCurrentSpan({ boundaryMode: execution.descriptor.boundaryMode });
+            return yield* executeBody(execution);
+        }, (effect) => EngineStoreMetrics.observe({
+            timer: EngineStoreMetrics.sandboxExecutionDuration,
+            counter: EngineStoreMetrics.sandboxExecution
+        })(effect)),
+        materialize: Effect.fn("WorkspaceSandbox.materialize")(function* (accepted) {
+            yield* Effect.annotateCurrentSpan({ changes: accepted.result.files.length });
+            // Nothing to copy back needs no commit: a body that changed nothing
+            // (a sealed read) must not need write authority over the root.
+            if (accepted.result.files.length === 0)
+                return;
+            yield* host.commit(accepted.result.files);
+        }, (effect) => EngineStoreMetrics.observe({
+            timer: EngineStoreMetrics.materializationDuration,
+            counter: EngineStoreMetrics.materialization
+        })(effect))
+    });
+};
+/**
+ * Creates a deterministic in-memory workspace sandbox.
+ *
+ * The returned `files` effect observes *host* state, not a running
+ * transaction: it changes only through `service.materialize`. This host hands
+ * the transaction its whole tree rather than seeding the declared read set, so
+ * an undeclared read is observable — which is exactly what makes it the
+ * conformance implementation for the bare tier of `Effect Taxonomy.md`.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeMemory = (initialFiles = {}) => Effect.gen(function* () {
+    const entries = [];
+    for (const [path, content] of Object.entries(initialFiles)) {
+        const normalized = normalizePath("", path);
+        if (Result.isFailure(normalized))
+            return yield* Effect.fail(normalized.failure);
+        entries.push([normalized.success, typeof content === "string" ? encoder.encode(content) : content.slice()]);
+    }
+    const host = yield* Ref.make(new Map(entries));
+    const service = makeHosted({
+        root: "",
+        snapshot: () => Ref.get(host),
+        // This host seeds the transaction with the WHOLE tree, so a path the
+        // transaction did not observe is one the host genuinely did not hold:
+        // `undefined` is the honest snapshot-time answer, and a file that
+        // appeared underneath the transaction is caught by copy-back's
+        // compare-and-set rather than clobbered.
+        baseline: () => Effect.succeed(undefined),
+        retain: (bytes) => Effect.succeed(bytes.slice()),
+        commit: Effect.fn("WorkspaceSandbox.commit")(function* (changes) {
+            yield* Effect.annotateCurrentSpan({ changes: changes.length });
+            const current = yield* Ref.get(host);
+            const { conflict } = yield* preflight(changes, (path) => Effect.succeed(current.get(path)));
+            if (conflict !== undefined) {
+                yield* Metric.update(EngineStoreMetrics.materializationConflicts, 1);
+                return yield* Effect.fail(conflict);
+            }
+            const next = new Map(current);
+            for (const change of changes) {
+                if (change.afterDigest === undefined)
+                    next.delete(change.path);
+                else
+                    next.set(change.path, change.after.slice());
+            }
+            yield* Ref.set(host, next);
+        })
+    });
+    return {
+        service,
+        files: Ref.get(host).pipe(Effect.map((current) => [...current]
+            .map(([path, content]) => ({ path, content }))
+            .sort((left, right) => compareText(left.path, right.path))))
+    };
+});
+// Shared across separately constructed sandboxes. Entries live only while a
+// commit is running or waiting, so short-lived workspace roots do not leak.
+const CommitLocks = Context.Service("@smthrs/engine-store/WorkspaceSandbox/CommitLocks");
+const locksLayer = Layer.effect(CommitLocks, RcMap.make({ lookup: (_root) => Semaphore.make(1) }));
+// The memo map shares the layer across active operations, including operations
+// from different store instances. Their scopes release the final owner.
+const lockOwners = Layer.makeMemoMapUnsafe();
+const coordinateCommit = (root, write) => Effect.scoped(Effect.gen(function* () {
+    const services = yield* Layer.buildWithMemoMap(locksLayer, lockOwners, yield* Scope.Scope);
+    const lock = yield* RcMap.get(Context.get(services, CommitLocks), root);
+    return yield* lock.withPermit(write);
+}));
+const commitLockName = ".smithers-workspace-lock";
+// The conventional engine state directory: the SQLite store, its WAL/SHM
+// siblings, and the artifact objects. A step body must never replace them.
+const engineStateName = ".flows";
+const defaultMaxInlineBytes = 1024 * 1024;
+const hostFailure = (cause) => new WorkspaceError({
+    code: "host_unavailable",
+    message: "the host filesystem could not serve the workspace transaction",
+    cause
+});
+const artifactFailure = (cause) => new WorkspaceError({
+    code: "host_unavailable",
+    message: `the artifact store could not serve the workspace transaction: ${cause.message}`,
+    cause
+});
+/**
+ * The errno names the descriptor-relative host reports when it refuses to
+ * resolve a path inside its pinned root: a symlink at the final component
+ * (`ELOOP`); a symlink at an intermediate component (`ELOOP` on Linux,
+ * `ENOTDIR` on Darwin, which also covers a file standing where a directory
+ * must be); or `..` traversal, a path outside the root, a hard-linked file, or
+ * a root whose identity changed (`EPERM`). Each means the change does not
+ * name a workspace entry reachable without following a link.
+ */
+const confinementCodes = new Set(["ELOOP", "ENOTDIR", "EPERM"]);
+const refusedByConfinement = (error) => error.reason._tag !== "BadArgument" &&
+    typeof error.reason.cause === "object" && error.reason.cause !== null &&
+    confinementCodes.has(error.reason.cause.code);
+/** Maps one copy-back host failure onto the sandbox's typed error codes. */
+const copyBackFailure = (path) => (error) => refusedByConfinement(error)
+    ? new WorkspaceError({
+        code: "path_escapes_workspace",
+        message: `materializing ${path} was refused: it does not name a workspace entry reachable without following a link (${error.message})`,
+        cause: error
+    })
+    : hostFailure(error);
+/**
+ * Maps a commit-lock failure: a missed acquisition deadline is
+ * `commit_lock_timeout`, so a caller can tell "another writer holds the root"
+ * from "the host refused".
+ */
+const lockFailure = (cause) => Cause.isTimeoutError(cause)
+    ? new WorkspaceError({
+        code: "commit_lock_timeout",
+        message: `another writer held ${commitLockName} for the whole acquisition deadline; a lock whose owner stopped is reclaimed once its heartbeat is ${FileLease.defaultStaleAfterMs} ms old`,
+        cause
+    })
+    // `FileLease` hands every other refusal over as the host's `PlatformError`.
+    : copyBackFailure(commitLockName)(cause);
+// Over-approximates the spellings a case-insensitive, normalization-insensitive
+// volume equates: `.FLOWS`, `.flow\u017f`, and `.\ufb02ows` all open `.flows` on
+// default APFS. Folding more than a volume does only refuses more names.
+const foldPath = (path) => path.normalize("NFKC").toUpperCase().toLowerCase().normalize("NFKC");
+// NTFS with 8.3 name creation on (the system volume default) also opens a
+// long name through its generated short name: `.flows` through `FLOWS~1`, or
+// `FL3A2B~1` once the numbered tails collide. Linux reaches such a volume
+// through WSL's `/mnt/c` and macOS through SMB, so the shape is refused on
+// every host. The pattern is broader than the generator: any `~` and digit
+// tail on a base of at most eight characters, with an extension of at most
+// three.
+const shortNameAlias = /^[^.~]{0,7}~\d{1,7}(\.[^.]{0,3})?$/u;
+const isShortNameAlias = (segment) => {
+    // `split` always yields a first element, possibly empty.
+    const base = segment.split(".")[0];
+    return base.length <= 8 && shortNameAlias.test(segment);
+};
+/**
+ * Builds the filesystem-backed workspace sandbox.
+ *
+ * **Copy-in, not overlay.** The transaction is seeded with exactly the
+ * declared read set and nothing else
+ * (`docs/concepts/workspace-transactions.md`). Bazel uses the same strategy, which
+ * is why whole-tree write observation is structural here. Re-rooting a
+ * body onto a bare host tree instead would leave every undeclared file
+ * readable and reduce enforcement to the taxonomy's weakest, post-hoc
+ * detection-by-diff tier; and the OS-level overlay that would fix that is not
+ * reachable through Effect's `FileSystem` tag, so it could not run in a
+ * browser. Seeding costs a copy of the declared reads and buys both.
+ *
+ * **Copy-back is confined and journaled.** Every copy-back host call (the
+ * lock, preflight, apply, and rollback) goes through
+ * `@smthrs/kernel/FileSystem`'s `confined` view: one descriptor-relative,
+ * no-follow request against the workspace root pinned when the commit starts.
+ * A symlink anywhere on a change's path, a hard-linked file, or a root
+ * replaced mid-commit is refused with `path_escapes_workspace`, never
+ * followed, and no check-then-write window exists for a concurrent process to
+ * swap a link into. A copy-back through a symlink that stays inside the root
+ * is refused too: the body writes the referent path itself. `fs` must
+ * therefore carry the kernel's descriptor-relative executor (Node and Bun
+ * hosts use `@smthrs/platform-node`'s `AtomicFileSystem`) or a
+ * whole-filesystem isolation attestation (`withIsolatedFileSystem`, for an
+ * in-memory volume); a plain path-based host is refused at copy-back with
+ * `host_unavailable`. Snapshot reads use `fs` as given. A root-keyed semaphore and
+ * the `.smithers-workspace-lock` lease file (`@smthrs/artifacts/FileLease`)
+ * serialize cooperating callers, including separate processes. Preconditions run before file
+ * changes, and the apply loop keeps each target's pre-image for in-process
+ * rollback. A crash or rollback failure can leave partial changes; see
+ * {@link Service.materialize} for the caller's reconciliation obligations.
+ * Hosts must implement exclusive `wx` file creation, `stat` with an mtime,
+ * `utimes`, `rename`, and `remove` for the reserved lock. Copy-back
+ * also refuses the `.flows` engine state directory and any
+ * {@link FileSystemOptions.reservedPaths}, so no write set or boundary mode
+ * lets a step body replace the engine database or its artifact blobs.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeFileSystem = (fs, platformPath, artifacts, workspaceRoot, options = {}) => {
+    const maxInlineBytes = options.maxInlineBytes ?? defaultMaxInlineBytes;
+    const root = workspaceRoot.replaceAll(/\/+$/g, "");
+    const reserved = [
+        commitLockName,
+        engineStateName,
+        ...(options.reservedPaths ?? []).map((path) => path.replace(/^(\.\/)+/, "").replaceAll(/\/+$/g, ""))
+    ].filter((path) => path !== "" && path !== ".").map((name) => ({ name, segments: foldPath(name).split("/") }));
+    // Why the root-relative `path` is refused, if it targets or lies beneath a
+    // reserved entry. The confined host refuses every symlink on a path, so the
+    // remaining aliases are spellings the volume itself equates: case,
+    // compatibility, and normalization variants on APFS and NTFS, and NTFS 8.3
+    // short names. Comparing folded segments, and refusing a short-name shape
+    // wherever a reserved segment stands, refuses them on every volume,
+    // case-sensitive ones included.
+    const reservedAt = (path) => {
+        const segments = foldPath(path).split("/");
+        const within = reserved.filter((entry) => entry.segments.length <= segments.length);
+        const exact = within.find((entry) => entry.segments.every((segment, index) => segments[index] === segment));
+        if (exact !== undefined)
+            return `the workspace path ${exact.name} is reserved`;
+        const alias = within.find((entry) => 
+        // `within` holds only entries no longer than the path, so every index is present.
+        entry.segments.every((segment, index) => segments[index] === segment || isShortNameAlias(segments[index])));
+        if (alias === undefined)
+            return undefined;
+        const spelling = path.split("/").slice(0, alias.segments.length).join("/");
+        return `the workspace path ${spelling} may be a short-name alias of a reserved path`;
+    };
+    const hostPath = (path) => root === "" ? path : `${root}/${path}`;
+    // One host call, not two: the read reports an absent path itself. On the
+    // confined host
+    // the `exists` probe that used to precede every read was a second CPython
+    // fork (`@smthrs/platform-node/AtomicFileSystem`) for an answer the read
+    // was about to give.
+    const readFrom = (host, path, onError) => host.readFile(path).pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.succeed(undefined)), Effect.mapError(onError));
+    const readIfPresent = Effect.fn("WorkspaceSandbox.readIfPresent")(function* (path) {
+        return yield* readFrom(fs, path, hostFailure);
+    });
+    const canonicalRoot = fs.realPath(root === "" ? "." : root).pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.succeed(undefined)), Effect.mapError(hostFailure));
+    const withCommitLock = (changes, effect) => Effect.gen(function* () {
+        for (const change of changes) {
+            const hit = reservedAt(change.path);
+            if (hit !== undefined)
+                return yield* Effect.fail(hostFailure(hit));
+        }
+        yield* fs.makeDirectory(root === "" ? "." : root, { recursive: true }).pipe(Effect.mapError(hostFailure));
+        // Pinned once per commit, after the root exists: every lock, preflight,
+        // apply, and rollback call below resolves against this root identity.
+        const host = yield* KernelFileSystem.confined(fs, root).pipe(Effect.provideService(Path.Path, platformPath), Effect.mapError(hostFailure));
+        const canonical = yield* canonicalRoot;
+        // The confined view refuses `utimes`, which the lease heartbeat needs.
+        // The heartbeat touches the lock only after a confined, no-follow read
+        // found this call's own token there, so the one path-based call it
+        // makes can at worst refresh an mtime.
+        const leaseHost = { ...host, utimes: fs.utimes };
+        return yield* coordinateCommit(canonical ?? root, FileLease.withLease(leaseHost, hostPath(commitLockName), effect(host), lockFailure, {
+            label: "Workspace commit lock",
+            annotations: { root: canonical ?? root }
+        }));
+    });
+    const commitWith = Effect.fn("WorkspaceSandbox.commit")(function* (host, changes) {
+        yield* Effect.annotateCurrentSpan({ changes: changes.length });
+        // The advisory lock and process semaphore cover preflight, apply, and
+        // rollback. Preconditions run only after both are acquired.
+        const { before, conflict } = yield* preflight(changes, (path) => readFrom(host, hostPath(path), copyBackFailure(path)));
+        if (conflict !== undefined) {
+            yield* Metric.update(EngineStoreMetrics.materializationConflicts, 1);
+            return yield* Effect.fail(conflict);
+        }
+        const resolved = new Map();
+        for (const change of changes) {
+            if (change.afterDigest === undefined)
+                continue;
+            const bytes = change.after ?? (yield* artifacts.get(`${change.afterDigest}`).pipe(Effect.mapError((error) => error._tag === "@smthrs/artifacts/ArtifactStoreError"
+                ? artifactFailure(error)
+                : new WorkspaceError({
+                    code: "not_found",
+                    message: `the retained bytes for ${change.path} are unavailable: ${error.message}`,
+                    cause: error
+                }))));
+            resolved.set(change.path, bytes);
+        }
+        const applied = [];
+        const apply = Effect.gen(function* () {
+            for (const change of changes) {
+                // Journal the change before touching its target: a write that
+                // fails halfway may still have mutated the file it was writing.
+                applied.push(change);
+                const target = hostPath(change.path);
+                if (change.afterDigest === undefined) {
+                    yield* host.remove(target).pipe(Effect.mapError(copyBackFailure(change.path)));
+                    continue;
+                }
+                const parent = parentDirectory(target);
+                if (parent !== undefined) {
+                    yield* host.makeDirectory(parent, { recursive: true }).pipe(Effect.mapError(copyBackFailure(change.path)));
+                }
+                yield* host.writeFile(target, resolved.get(change.path)).pipe(Effect.mapError(copyBackFailure(change.path)));
+            }
+        });
+        const rollback = Effect.gen(function* () {
+            for (const change of [...applied].reverse()) {
+                const target = hostPath(change.path);
+                const previous = before.get(change.path);
+                if (previous === undefined) {
+                    yield* host.remove(target, { force: true }).pipe(Effect.mapError(copyBackFailure(change.path)));
+                }
+                else {
+                    yield* host.writeFile(target, previous).pipe(Effect.mapError(copyBackFailure(change.path)));
+                }
+            }
+            // Keep empty parent directories. Effect's portable FileSystem has no
+            // atomic, non-recursive rmdir; recursively deleting a directory after
+            // a separate emptiness check could erase a concurrent writer's file.
+        });
+        yield* apply.pipe(Effect.catchCause((cause) => Effect.gen(function* () {
+            const restored = yield* Effect.exit(rollback);
+            if (Exit.isSuccess(restored))
+                return yield* Effect.failCause(cause);
+            const reasons = restored.cause.reasons
+                .filter(Cause.isFailReason)
+                .map((reason) => reason.error.message);
+            // Both failures travel: the apply cause that opened the window and
+            // the rollback cause that could not close it, composed the way
+            // `acquireUseRelease` composes a failed use with a failed release.
+            return yield* Effect.failCause(Cause.combine(cause, Cause.fail(new WorkspaceError({
+                code: "host_unavailable",
+                message: `copy-back failed mid-apply and rollback could not restore the workspace: ${reasons.join("; ")}`,
+                cause: restored.cause
+            }))));
+        })), 
+        // Interruption inside the apply window is a mid-sequence abort the
+        // journal exists to prevent; the window is bounded local work, so it
+        // closes before the fiber answers the interrupt.
+        Effect.uninterruptible);
+    });
+    return makeHosted({
+        root,
+        snapshot: Effect.fn("WorkspaceSandbox.snapshot")(function* (descriptor) {
+            yield* Effect.annotateCurrentSpan({
+                reads: descriptor.readSet.length,
+                boundaryMode: descriptor.boundaryMode
+            });
+            const base = new Map();
+            for (const entry of descriptor.readSet) {
+                // Through `FileEnumeration`, never the host `glob`: host results skip
+                // dotfiles, so a declared read glob covering one would seed a sandbox
+                // that silently hides it from the body.
+                const paths = FileSet.isGlob(entry)
+                    ? yield* FileEnumeration.expandGlob(fs, entry, {
+                        resolve: (path) => path === "" ? (root === "" ? "." : root) : hostPath(path)
+                    }).pipe(Effect.mapError(hostFailure))
+                    : [entry.path];
+                for (const path of paths) {
+                    const normalized = normalizePath(root, path);
+                    if (Result.isFailure(normalized))
+                        return yield* Effect.fail(normalized.failure);
+                    const content = yield* readIfPresent(hostPath(normalized.success));
+                    // A declared read that does not exist is seeded as absent, not as an
+                    // error: `StepBoundary.prepare` already records the mismatch as the
+                    // evidence that refuses the cache hit.
+                    if (content !== undefined)
+                        base.set(normalized.success, content);
+                }
+            }
+            for (const path of descriptor.removes ?? []) {
+                const normalized = normalizePath(root, path);
+                /* v8 ignore next -- `FileBoundary.removes` is `FileSet.Pattern`-checked, so a decoded boundary cannot carry an upward or absolute removal; the branch guards hand-built descriptors */
+                if (Result.isFailure(normalized))
+                    return yield* Effect.fail(normalized.failure);
+                const content = yield* readIfPresent(hostPath(normalized.success));
+                if (content !== undefined)
+                    base.set(normalized.success, content);
+            }
+            return base;
+        }),
+        baseline: Effect.fn("WorkspaceSandbox.baseline")(function* (path) {
+            const content = yield* readIfPresent(hostPath(path));
+            return content === undefined ? undefined : yield* digestOf(content);
+        }),
+        // The bytes now live at the change's `afterDigest`; the change itself
+        // carries only the reference, exactly as oversized `StepBoundary`
+        // evidence does.
+        retain: (bytes) => bytes.length <= maxInlineBytes
+            ? Effect.succeed(bytes)
+            : artifacts.put(bytes).pipe(Effect.mapError(artifactFailure), Effect.as(undefined)),
+        commit: (changes) => withCommitLock(changes, (host) => commitWith(host, changes))
+    });
+};
+/**
+ * Provides the filesystem-backed workspace sandbox.
+ *
+ * Host access arrives through Effect's `FileSystem` tag — the same tag the
+ * capability kernel decorates in place — and blob retention through
+ * `@smthrs/artifacts`, so the same sandbox runs over a purely local store or a
+ * local-plus-shared composition without knowing which it got. The workspace
+ * root arrives through the kernel's `Workspace` service, so absolute paths a
+ * body resolved for itself still land inside the transaction.
+ *
+ * The layer refuses to build over a host that {@link makeFileSystem} could
+ * not confine (a plain path-based `FileSystem`), failing with
+ * `host_unavailable`, so a composition that could never copy back safely is
+ * rejected at startup rather than at its first commit.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerFileSystem = (options = {}) => Layer.effect(WorkspaceSandbox, Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const platformPath = yield* Path.Path;
+    const artifacts = yield* ArtifactStore.ArtifactStore;
+    const workspace = yield* KernelWorkspace;
+    yield* KernelFileSystem.requireConfinable(fs, workspace.root).pipe(Effect.mapError(hostFailure));
+    return makeFileSystem(fs, platformPath, artifacts, workspace.root, options);
+}));
+//# sourceMappingURL=WorkspaceSandbox.js.map