@smthrs/std 0.0.0-stage → 1.0.0-rc.12

package/dist/esm/internal/Exec.js

@@ -0,0 +1,285 @@
+/**
+ * Buffered shell execution over the permission-aware process spawner.
+ *
+ * `@smthrs/kernel` used to expose a `Shell` service whose `exec` returned a
+ * buffered `{ stdout, stderr, exitCode }`. The kernel replaced it with
+ * `ChildProcessSpawner`, Effect's own process boundary, which streams and has
+ * no buffered form. This module is the buffered form the shell flows still
+ * want, expressed in terms of the spawner so the `proc:spawn` capability check
+ * and the command-line resource stay exactly where the kernel put them.
+ *
+ * Commands run through the platform shell (`shell: true`), matching the old
+ * service: the flows take a command *line*, not an argv.
+ *
+ * @since 1.0.0
+ */
+import * as ChildProcessEnvironment from "@smthrs/kernel/ChildProcessEnvironment";
+import * as ChildProcessSpawner from "@smthrs/kernel/ChildProcessSpawner";
+import * as Effect from "effect/Effect";
+import * as ChildProcess from "effect/process/ChildProcess";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import * as StdError from "../StdError.js";
+import { elideMiddle } from "./Text.js";
+/**
+ * Failure codes a buffered execution can report, matching the codes the
+ * removed kernel `Shell` used so handler-level mapping is unchanged.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export const ExecErrorCode = Schema.Literals(["timeout", "spawn_error", "arguments_too_long", "capture_overflow"]);
+/**
+ * A command that never produced an exit code.
+ *
+ * A non-zero exit is a successful {@link ExecResult}, not a failure; this
+ * error is reserved for a command that could not start (`arguments_too_long`
+ * when the operating system refused it for the size of its arguments) or was
+ * cut off by its timeout, or whose captured output exceeded a refusing capture
+ * bound.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export class ExecError extends Schema.TaggedError()("@smthrs/std/ExecError", {
+    code: ExecErrorCode,
+    message: Schema.String,
+    /** The limit a `timeout` ran past, in milliseconds. */
+    limitMillis: Schema.optional(Schema.Number)
+}) {
+}
+const decoder = new TextDecoder("utf-8");
+const emptyTail = () => ({ chunks: [], bytes: 0, dropped: 0 });
+/** A UTF-8 continuation byte is `10xxxxxx`; every other byte starts a character. */
+const isContinuation = (byte) => (byte & 0b1100_0000) === 0b1000_0000;
+const join = (chunks, size) => {
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+};
+/** Appends one chunk and drops from the front whatever no longer fits. */
+const keepTail = (state, chunk, maxBytes) => {
+    if (chunk.byteLength === 0)
+        return;
+    state.chunks.push(chunk);
+    state.bytes += chunk.byteLength;
+    while (state.bytes > maxBytes && state.chunks.length > 0) {
+        const excess = state.bytes - maxBytes;
+        const first = state.chunks[0];
+        if (first.byteLength <= excess) {
+            state.chunks.shift();
+            state.bytes -= first.byteLength;
+            state.dropped += first.byteLength;
+        }
+        else {
+            state.chunks[0] = first.subarray(excess);
+            state.bytes -= excess;
+            state.dropped += excess;
+        }
+    }
+};
+/**
+ * Joins the retained chunks and decodes them, skipping the partial code point a
+ * dropped head can leave behind.
+ *
+ * A code point is at most four bytes, so at most three leading continuation
+ * bytes can precede the first whole character. Skipping them is counted as
+ * dropped rather than decoded to a replacement character the process never
+ * printed.
+ */
+const decodeTail = (state) => {
+    const bytes = join(state.chunks, state.bytes);
+    if (state.dropped === 0)
+        return { text: decoder.decode(bytes), droppedBytes: 0 };
+    let start = 0;
+    while (start < bytes.byteLength && start < 3 && isContinuation(bytes[start]))
+        start++;
+    return { text: decoder.decode(bytes.subarray(start)), droppedBytes: state.dropped + start };
+};
+/**
+ * The length of a cut head without the character the cut left unfinished.
+ *
+ * Its last character starts at the last byte that is not a continuation byte,
+ * and that byte says how many bytes the character needs. One that needs more
+ * than the head holds is dropped, for the same reason {@link decodeTail} skips
+ * a partial code point.
+ */
+const wholeLength = (bytes) => {
+    for (let back = 1; back <= Math.min(3, bytes.byteLength); back++) {
+        const byte = bytes[bytes.byteLength - back];
+        if (isContinuation(byte))
+            continue;
+        const width = byte >= 0b1111_0000 ? 4 : byte >= 0b1110_0000 ? 3 : byte >= 0b1100_0000 ? 2 : 1;
+        return width > back ? bytes.byteLength - back : bytes.byteLength;
+    }
+    return bytes.byteLength;
+};
+/**
+ * Decodes a stream kept by its ends. A stream that fit is decoded whole;
+ * otherwise each end is cut on a character boundary and one line naming every
+ * byte between them stands where the middle was.
+ */
+const decodeEnds = (state) => {
+    if (state.tail.dropped === 0) {
+        const whole = join([...state.head, ...state.tail.chunks], state.headBytes + state.tail.bytes);
+        return { text: decoder.decode(whole), droppedBytes: 0 };
+    }
+    const head = join(state.head, state.headBytes);
+    const kept = wholeLength(head);
+    const tail = decodeTail(state.tail);
+    const droppedBytes = head.byteLength - kept + tail.droppedBytes;
+    return { text: elideMiddle(decoder.decode(head.subarray(0, kept)), droppedBytes, tail.text), droppedBytes };
+};
+const boundedTail = (stream, maxBytes, overflow) => Stream.runFold(stream, emptyTail, (state, chunk) => {
+    keepTail(state, chunk, maxBytes);
+    return state;
+}).pipe(Effect.map((state) => overflow === "refuse" && state.dropped > 0
+    ? { text: "", droppedBytes: state.dropped }
+    : decodeTail(state)));
+/**
+ * Keeps the first half of the bound and the last half. The head fills first,
+ * and every byte after it passes through the tail, which drops from its front:
+ * what falls out of the tail is the middle.
+ */
+const boundedEnds = (stream, maxBytes) => {
+    const headBytes = Math.floor(maxBytes / 2);
+    return Stream.runFold(stream, () => ({ head: [], headBytes: 0, tail: emptyTail() }), (state, chunk) => {
+        const taken = Math.min(headBytes - state.headBytes, chunk.byteLength);
+        if (taken > 0) {
+            state.head.push(chunk.subarray(0, taken));
+            state.headBytes += taken;
+        }
+        keepTail(state.tail, chunk.subarray(taken), maxBytes - headBytes);
+        return state;
+    }).pipe(Effect.map(decodeEnds));
+};
+const capture = (stream, maxBytes, overflow) => maxBytes === undefined
+    ? Effect.map(Stream.mkString(Stream.decodeText(stream)), (text) => ({ text, droppedBytes: 0 }))
+    : overflow === "ends"
+        ? boundedEnds(stream, maxBytes)
+        : boundedTail(stream, maxBytes, overflow);
+/**
+ * A command whose arguments exceed the operating system's limit fails `execve`
+ * with `E2BIG` before it starts: one argument over 128 KiB on Linux, all of
+ * them over 1 MiB on macOS. A heredoc in a command line, or a file's text
+ * passed as an argument, is one such argument. The platform error's own text
+ * repeats the whole command line, so this text is written here instead, and a
+ * caller may show it as it stands.
+ */
+const argumentsTooLong = (error) => error.cause?.code === "E2BIG"
+    ? new ExecError({
+        code: "arguments_too_long",
+        message: "Command not started: its arguments exceed the operating system's size limit (E2BIG). Send long text on standard input or in a file, not in the command line or its arguments."
+    })
+    : undefined;
+const unbounded = (command, options) => Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const settings = {
+        ...(options.args === undefined ? { shell: true } : {}),
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        env: ChildProcessEnvironment.make(process.env, options.env),
+        extendEnv: false,
+        ...(options.stdin === undefined
+            ? {}
+            : { stdin: Stream.make(new TextEncoder().encode(options.stdin)) })
+    };
+    const handle = yield* spawner.spawn(options.args === undefined
+        ? ChildProcess.make(command, settings)
+        : ChildProcess.make(command, [...options.args], settings)).pipe(
+    // Node's `spawn` throws E2BIG instead of emitting `error`, and Effect's
+    // raw Node spawner calls it unguarded, so there it arrives as a defect.
+    Effect.catchDefect((defect) => {
+        const refused = argumentsTooLong({ cause: defect });
+        return refused === undefined ? Effect.die(defect) : Effect.fail(refused);
+    }));
+    // stdout, stderr, and the exit code have to be consumed concurrently: a
+    // command that fills a pipe blocks until the pipe is drained, so waiting
+    // for exit first would deadlock on any output larger than the buffer.
+    const [stdout, stderr, exitCode] = yield* Effect.all([
+        capture(handle.stdout, options.maxCaptureBytes, options.overflow),
+        capture(handle.stderr, options.maxCaptureBytes, options.overflow),
+        handle.exitCode
+    ], { concurrency: "unbounded" });
+    if (options.overflow === "refuse") {
+        const overflowed = [
+            stdout.droppedBytes > 0 ? "stdout" : undefined,
+            stderr.droppedBytes > 0 ? "stderr" : undefined
+        ]
+            .filter((stream) => stream !== undefined);
+        if (overflowed.length > 0) {
+            return yield* Effect.fail(new ExecError({
+                code: "capture_overflow",
+                message: `${command} ${overflowed.join(" and ")} exceeded the ${options.maxCaptureBytes}-byte capture cap; refusing partial output`
+            }));
+        }
+    }
+    return {
+        stdout: stdout.text,
+        stderr: stderr.text,
+        exitCode,
+        stdoutDroppedBytes: stdout.droppedBytes,
+        stderrDroppedBytes: stderr.droppedBytes
+    };
+}).pipe(Effect.scoped, Effect.mapError((error) => error instanceof ExecError ? error : argumentsTooLong(error) ?? new ExecError({
+    code: "spawn_error",
+    message: `exec: ${command}: ${error.message}`
+})));
+/**
+ * Runs a command line through the platform shell and buffers its output.
+ *
+ * Cancellation is scope closure: the spawn is scoped, so an interrupted fiber
+ * — including the one a `timeoutMs` interrupts — terminates the process rather
+ * than leaking it.
+ *
+ * @category execution
+ * @since 1.0.0
+ */
+export const exec = (command, options = {}) => options.timeoutMs === undefined
+    ? unbounded(command, options)
+    : Effect.timeoutOrElse(unbounded(command, options), {
+        duration: options.timeoutMs,
+        orElse: () => Effect.fail(new ExecError({
+            code: "timeout",
+            message: `exec: \`${command}\` exceeded ${options.timeoutMs}ms`,
+            limitMillis: options.timeoutMs
+        }))
+    });
+/**
+ * The model-facing failure code a command that never produced an exit code
+ * carries.
+ *
+ * A timeout keeps its own code, because "the command never finished" and "the
+ * command never started" are different things to a caller deciding whether to
+ * retry. Arguments the operating system refused for their size are the
+ * caller's own input, which a shell flow publishes, so they read as
+ * `invalid_input`. Every other way of producing no exit code is a host failure.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export const toStdErrorCode = (error) => error.code === "timeout" ? "timeout" : error.code === "arguments_too_long" ? "invalid_input" : "command_failed";
+/**
+ * The model-facing failure one execution error becomes.
+ *
+ * A timeout names the command, which is what the caller asked for and all a
+ * timeout has to say. Arguments too long to start carry the reason and the
+ * fix, and nothing of the command. Any other failure carries the message the
+ * execution produced, which already names the command.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export const toStdError = (command, error) => new StdError.StdError({
+    code: toStdErrorCode(error),
+    message: error.code === "timeout"
+        ? `Command timed out: ${command}`
+        : error.code === "arguments_too_long"
+            ? error.message
+            : `Command failed to start: ${error.message}`,
+    ...(error.limitMillis === undefined ? {} : { limitMillis: error.limitMillis })
+});
+//# sourceMappingURL=Exec.js.map

package/dist/esm/internal/Exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Exec.js","sourceRoot":"","sources":["../../../src/internal/Exec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,uBAAuB,MAAM,wCAAwC,CAAA;AACjF,OAAO,KAAK,mBAAmB,MAAM,oCAAoC,CAAA;AACzE,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,YAAY,MAAM,6BAA6B,CAAA;AAC3D,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAEvC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,EAAE,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,CAAC,CAAC,CAAA;AAUlH;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,SAAU,SAAQ,MAAM,CAAC,WAAW,EAAa,CAAC,uBAAuB,EAAE;IACtF,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;CAC5C,CAAC;CAAG;AAkFL,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,OAAO,CAAC,CAAA;AAExC,MAAM,SAAS,GAAG,GAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAA;AAEpE,oFAAoF;AACpF,MAAM,cAAc,GAAG,CAAC,IAAY,EAAW,EAAE,CAAC,CAAC,IAAI,GAAG,WAAW,CAAC,KAAK,WAAW,CAAA;AAEtF,MAAM,IAAI,GAAG,CAAC,MAAiC,EAAE,IAAY,EAAc,EAAE;IAC3E,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAA;IAClC,IAAI,MAAM,GAAG,CAAC,CAAA;IACd,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;QACxB,MAAM,IAAI,KAAK,CAAC,UAAU,CAAA;IAC5B,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAED,0EAA0E;AAC1E,MAAM,QAAQ,GAAG,CAAC,KAAW,EAAE,KAAiB,EAAE,QAAgB,EAAQ,EAAE;IAC1E,IAAI,KAAK,CAAC,UAAU,KAAK,CAAC;QAAE,OAAM;IAClC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACxB,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,UAAU,CAAA;IAC/B,OAAO,KAAK,CAAC,KAAK,GAAG,QAAQ,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,GAAG,QAAQ,CAAA;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAE,CAAA;QAC9B,IAAI,KAAK,CAAC,UAAU,IAAI,MAAM,EAAE,CAAC;YAC/B,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;YACpB,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,UAAU,CAAA;YAC/B,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,UAAU,CAAA;QACnC,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;YACxC,KAAK,CAAC,KAAK,IAAI,MAAM,CAAA;YACrB,KAAK,CAAC,OAAO,IAAI,MAAM,CAAA;QACzB,CAAC;IACH,CAAC;AACH,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,GAAG,CAAC,KAAW,EAAW,EAAE;IAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;IAC7C,IAAI,KAAK,CAAC,OAAO,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAA;IAChF,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,OAAO,KAAK,GAAG,KAAK,CAAC,UAAU,IAAI,KAAK,GAAG,CAAC,IAAI,cAAc,CAAC,KAAK,CAAC,KAAK,CAAE,CAAC;QAAE,KAAK,EAAE,CAAA;IACtF,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,OAAO,GAAG,KAAK,EAAE,CAAA;AAC7F,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,GAAG,CAAC,KAAiB,EAAU,EAAE;IAChD,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC;QACjE,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAE,CAAA;QAC5C,IAAI,cAAc,CAAC,IAAI,CAAC;YAAE,SAAQ;QAClC,MAAM,KAAK,GAAG,IAAI,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC7F,OAAO,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAA;IAClE,CAAC;IACD,OAAO,KAAK,CAAC,UAAU,CAAA;AACzB,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,UAAU,GAAG,CAAC,KAAW,EAAW,EAAE;IAC1C,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC7F,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAA;IACzD,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;IAC9C,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAA;IAC9B,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACnC,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,GAAG,IAAI,GAAG,IAAI,CAAC,YAAY,CAAA;IAC/D,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,CAAA;AAC7G,CAAC,CAAA;AAED,MAAM,WAAW,GAAG,CAClB,MAAoC,EACpC,QAAgB,EAChB,QAA8B,EACH,EAAE,CAC7B,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;IACjD,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAA;IAChC,OAAO,KAAK,CAAA;AACd,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAC3B,QAAQ,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,GAAG,CAAC;IACxC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,YAAY,EAAE,KAAK,CAAC,OAAO,EAAE;IAC3C,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CACtB,CAAC,CAAA;AAEJ;;;;GAIG;AACH,MAAM,WAAW,GAAG,CAAI,MAAoC,EAAE,QAAgB,EAA6B,EAAE;IAC3G,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAA;IAC1C,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,GAAS,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QAC1G,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;QACrE,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAA;YACzC,KAAK,CAAC,SAAS,IAAI,KAAK,CAAA;QAC1B,CAAC;QACD,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAA;QACjE,OAAO,KAAK,CAAA;IACd,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAA;AACjC,CAAC,CAAA;AAED,MAAM,OAAO,GAAG,CACd,MAAoC,EACpC,QAA4B,EAC5B,QAA8B,EACH,EAAE,CAC7B,QAAQ,KAAK,SAAS;IACpB,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC,CAAC;IAC/F,CAAC,CAAC,QAAQ,KAAK,MAAM;QACrB,CAAC,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC;QAC/B,CAAC,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAA;AAE7C;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,CAAC,KAAmC,EAAyB,EAAE,CACrF,KAAK,CAAC,KAAiD,EAAE,IAAI,KAAK,OAAO;IACxE,CAAC,CAAC,IAAI,SAAS,CAAC;QACd,IAAI,EAAE,oBAAoB;QAC1B,OAAO,EACL,+KAA+K;KAClL,CAAC;IACF,CAAC,CAAC,SAAS,CAAA;AAEf,MAAM,SAAS,GAAG,CAChB,OAAe,EACf,OAAoB,EAC2D,EAAE,CACjF,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,mBAAmB,CAAC,mBAAmB,CAAA;IAC9D,MAAM,QAAQ,GAAgC;QAC5C,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QAC1D,GAAG,EAAE,uBAAuB,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC;QAC3D,SAAS,EAAE,KAAK;QAChB,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS;YAC7B,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;KACrE,CAAA;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,CACjC,OAAO,CAAC,IAAI,KAAK,SAAS;QACxB,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC;QACtC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAC5D,CAAC,IAAI;IACJ,wEAAwE;IACxE,wEAAwE;IACxE,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,EAAE,EAAE;QAC5B,MAAM,OAAO,GAAG,gBAAgB,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;QACnD,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAC1E,CAAC,CAAC,CACH,CAAA;IACD,wEAAwE;IACxE,yEAAyE;IACzE,sEAAsE;IACtE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAClD;QACE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,QAAQ,CAAC;QACjE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,QAAQ,CAAC;QACjE,MAAM,CAAC,QAAQ;KAChB,EACD,EAAE,WAAW,EAAE,WAAW,EAAE,CAC7B,CAAA;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG;YACjB,MAAM,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;YAC9C,MAAM,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;SAC/C;aACE,MAAM,CAAC,CAAC,MAAM,EAAoB,EAAE,CAAC,MAAM,KAAK,SAAS,CAAC,CAAA;QAC7D,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CACvB,IAAI,SAAS,CAAC;gBACZ,IAAI,EAAE,kBAAkB;gBACxB,OAAO,EAAE,GAAG,OAAO,IACjB,UAAU,CAAC,IAAI,CAAC,OAAO,CACzB,iBAAiB,OAAO,CAAC,eAAe,4CAA4C;aACrF,CAAC,CACH,CAAA;QACH,CAAC;IACH,CAAC;IACD,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,IAAI;QACnB,MAAM,EAAE,MAAM,CAAC,IAAI;QACnB,QAAQ;QACR,kBAAkB,EAAE,MAAM,CAAC,YAAY;QACvC,kBAAkB,EAAE,MAAM,CAAC,YAAY;KACxC,CAAA;AACH,CAAC,CAAC,CAAC,IAAI,CACL,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,EAAE,CACxB,KAAK,YAAY,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,KAAK,CAAC,IAAI,IAAI,SAAS,CAAC;IAC5E,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,SAAS,OAAO,KAAK,KAAK,CAAC,OAAO,EAAE;CAC9C,CAAC,CACH,CACF,CAAA;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAClB,OAAe,EACf,UAAuB,EAAE,EACsD,EAAE,CACjF,OAAO,CAAC,SAAS,KAAK,SAAS;IAC7B,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC;IAC7B,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE;QAClD,QAAQ,EAAE,OAAO,CAAC,SAAS;QAC3B,MAAM,EAAE,GAAG,EAAE,CACX,MAAM,CAAC,IAAI,CACT,IAAI,SAAS,CAAC;YACZ,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,WAAW,OAAO,eAAe,OAAO,CAAC,SAAS,IAAI;YAC/D,WAAW,EAAE,OAAO,CAAC,SAAS;SAC/B,CAAC,CACH;KACJ,CAAC,CAAA;AAEN;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAgB,EAAiB,EAAE,CAChE,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,oBAAoB,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,gBAAgB,CAAA;AAEjH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAAe,EAAE,KAAgB,EAAqB,EAAE,CACjF,IAAI,QAAQ,CAAC,QAAQ,CAAC;IACpB,IAAI,EAAE,cAAc,CAAC,KAAK,CAAC;IAC3B,OAAO,EAAE,KAAK,CAAC,IAAI,KAAK,SAAS;QAC/B,CAAC,CAAC,sBAAsB,OAAO,EAAE;QACjC,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,oBAAoB;YACrC,CAAC,CAAC,KAAK,CAAC,OAAO;YACf,CAAC,CAAC,4BAA4B,KAAK,CAAC,OAAO,EAAE;IAC/C,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;CAC/E,CAAC,CAAA","sourcesContent":["/**\n * Buffered shell execution over the permission-aware process spawner.\n *\n * `@smthrs/kernel` used to expose a `Shell` service whose `exec` returned a\n * buffered `{ stdout, stderr, exitCode }`. The kernel replaced it with\n * `ChildProcessSpawner`, Effect's own process boundary, which streams and has\n * no buffered form. This module is the buffered form the shell flows still\n * want, expressed in terms of the spawner so the `proc:spawn` capability check\n * and the command-line resource stay exactly where the kernel put them.\n *\n * Commands run through the platform shell (`shell: true`), matching the old\n * service: the flows take a command *line*, not an argv.\n *\n * @since 1.0.0\n */\n\nimport * as ChildProcessEnvironment from \"@smthrs/kernel/ChildProcessEnvironment\"\nimport * as ChildProcessSpawner from \"@smthrs/kernel/ChildProcessSpawner\"\nimport * as Effect from \"effect/Effect\"\nimport * as ChildProcess from \"effect/process/ChildProcess\"\nimport * as Schema from \"effect/Schema\"\nimport * as Stream from \"effect/Stream\"\nimport * as StdError from \"../StdError.ts\"\nimport { elideMiddle } from \"./Text.ts\"\n\n/**\n * Failure codes a buffered execution can report, matching the codes the\n * removed kernel `Shell` used so handler-level mapping is unchanged.\n *\n * @category models\n * @since 1.0.0\n */\nexport const ExecErrorCode = Schema.Literals([\"timeout\", \"spawn_error\", \"arguments_too_long\", \"capture_overflow\"])\n\n/**\n * Failure codes a buffered execution can report.\n *\n * @category models\n * @since 1.0.0\n */\nexport type ExecErrorCode = typeof ExecErrorCode.Type\n\n/**\n * A command that never produced an exit code.\n *\n * A non-zero exit is a successful {@link ExecResult}, not a failure; this\n * error is reserved for a command that could not start (`arguments_too_long`\n * when the operating system refused it for the size of its arguments) or was\n * cut off by its timeout, or whose captured output exceeded a refusing capture\n * bound.\n *\n * @category errors\n * @since 1.0.0\n */\nexport class ExecError extends Schema.TaggedError<ExecError>()(\"@smthrs/std/ExecError\", {\n  code: ExecErrorCode,\n  message: Schema.String,\n  /** The limit a `timeout` ran past, in milliseconds. */\n  limitMillis: Schema.optional(Schema.Number)\n}) {}\n\n/**\n * The buffered result of one command.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface ExecResult {\n  readonly stdout: string\n  readonly stderr: string\n  readonly exitCode: number\n  /** UTF-8 bytes of stdout dropped to stay inside the capture bound; see `overflow`. */\n  readonly stdoutDroppedBytes: number\n  /** UTF-8 bytes of stderr dropped to stay inside the capture bound; see `overflow`. */\n  readonly stderrDroppedBytes: number\n}\n\n/**\n * Options accepted by {@link exec}.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface ExecOptions {\n  readonly cwd?: string | undefined\n  readonly env?: Readonly<Record<string, string>> | undefined\n  readonly timeoutMs?: number | undefined\n  /**\n   * The program's arguments. Present means an argv, absent means a command\n   * line for the platform shell. An argv is how a payload reaches a program\n   * without being quoted into a string: nothing between here and `execve`\n   * re-parses it.\n   */\n  readonly args?: ReadonlyArray<string> | undefined\n  /**\n   * Text written to the program's standard input, as data. A script delivered\n   * this way is never quoted, escaped, or heredoc-terminated, which is the\n   * whole point: quoting corruption cost the measured SWE-bench program twelve\n   * probe failures and one instance's most expensive frame.\n   */\n  readonly stdin?: string | undefined\n  /**\n   * Bytes retained per captured stream. A stream that prints more keeps what\n   * `overflow` names and reports what it dropped, so a command printing\n   * gigabytes costs a bounded amount of memory rather than the whole of what it\n   * printed.\n   *\n   * Absent means unbounded, which is what a caller wants when it needs every\n   * byte a tool produced (`rg --files`, `git worktree list`).\n   */\n  readonly maxCaptureBytes?: number | undefined\n  /**\n   * What a stream past the bound keeps. `tail`, the default, keeps its last\n   * bytes. `ends` keeps its first and last halves and puts one line naming the\n   * dropped bytes where the middle was. `refuse` fails if either stream exceeds\n   * the bound.\n   */\n  readonly overflow?: Overflow | undefined\n}\n\ntype Overflow = \"tail\" | \"ends\" | \"refuse\"\n\n/** One captured stream: the text kept, and the bytes dropped to keep it bounded. */\ninterface Capture {\n  readonly text: string\n  readonly droppedBytes: number\n}\n\ninterface Tail {\n  chunks: Array<Uint8Array>\n  bytes: number\n  dropped: number\n}\n\n/** A stream's first bytes and its last ones: what `overflow: \"ends\"` keeps. */\ninterface Ends {\n  readonly head: Array<Uint8Array>\n  headBytes: number\n  readonly tail: Tail\n}\n\nconst decoder = new TextDecoder(\"utf-8\")\n\nconst emptyTail = (): Tail => ({ chunks: [], bytes: 0, dropped: 0 })\n\n/** A UTF-8 continuation byte is `10xxxxxx`; every other byte starts a character. */\nconst isContinuation = (byte: number): boolean => (byte & 0b1100_0000) === 0b1000_0000\n\nconst join = (chunks: ReadonlyArray<Uint8Array>, size: number): Uint8Array => {\n  const bytes = new Uint8Array(size)\n  let offset = 0\n  for (const chunk of chunks) {\n    bytes.set(chunk, offset)\n    offset += chunk.byteLength\n  }\n  return bytes\n}\n\n/** Appends one chunk and drops from the front whatever no longer fits. */\nconst keepTail = (state: Tail, chunk: Uint8Array, maxBytes: number): void => {\n  if (chunk.byteLength === 0) return\n  state.chunks.push(chunk)\n  state.bytes += chunk.byteLength\n  while (state.bytes > maxBytes && state.chunks.length > 0) {\n    const excess = state.bytes - maxBytes\n    const first = state.chunks[0]!\n    if (first.byteLength <= excess) {\n      state.chunks.shift()\n      state.bytes -= first.byteLength\n      state.dropped += first.byteLength\n    } else {\n      state.chunks[0] = first.subarray(excess)\n      state.bytes -= excess\n      state.dropped += excess\n    }\n  }\n}\n\n/**\n * Joins the retained chunks and decodes them, skipping the partial code point a\n * dropped head can leave behind.\n *\n * A code point is at most four bytes, so at most three leading continuation\n * bytes can precede the first whole character. Skipping them is counted as\n * dropped rather than decoded to a replacement character the process never\n * printed.\n */\nconst decodeTail = (state: Tail): Capture => {\n  const bytes = join(state.chunks, state.bytes)\n  if (state.dropped === 0) return { text: decoder.decode(bytes), droppedBytes: 0 }\n  let start = 0\n  while (start < bytes.byteLength && start < 3 && isContinuation(bytes[start]!)) start++\n  return { text: decoder.decode(bytes.subarray(start)), droppedBytes: state.dropped + start }\n}\n\n/**\n * The length of a cut head without the character the cut left unfinished.\n *\n * Its last character starts at the last byte that is not a continuation byte,\n * and that byte says how many bytes the character needs. One that needs more\n * than the head holds is dropped, for the same reason {@link decodeTail} skips\n * a partial code point.\n */\nconst wholeLength = (bytes: Uint8Array): number => {\n  for (let back = 1; back <= Math.min(3, bytes.byteLength); back++) {\n    const byte = bytes[bytes.byteLength - back]!\n    if (isContinuation(byte)) continue\n    const width = byte >= 0b1111_0000 ? 4 : byte >= 0b1110_0000 ? 3 : byte >= 0b1100_0000 ? 2 : 1\n    return width > back ? bytes.byteLength - back : bytes.byteLength\n  }\n  return bytes.byteLength\n}\n\n/**\n * Decodes a stream kept by its ends. A stream that fit is decoded whole;\n * otherwise each end is cut on a character boundary and one line naming every\n * byte between them stands where the middle was.\n */\nconst decodeEnds = (state: Ends): Capture => {\n  if (state.tail.dropped === 0) {\n    const whole = join([...state.head, ...state.tail.chunks], state.headBytes + state.tail.bytes)\n    return { text: decoder.decode(whole), droppedBytes: 0 }\n  }\n  const head = join(state.head, state.headBytes)\n  const kept = wholeLength(head)\n  const tail = decodeTail(state.tail)\n  const droppedBytes = head.byteLength - kept + tail.droppedBytes\n  return { text: elideMiddle(decoder.decode(head.subarray(0, kept)), droppedBytes, tail.text), droppedBytes }\n}\n\nconst boundedTail = <E>(\n  stream: Stream.Stream<Uint8Array, E>,\n  maxBytes: number,\n  overflow: Overflow | undefined\n): Effect.Effect<Capture, E> =>\n  Stream.runFold(stream, emptyTail, (state, chunk) => {\n    keepTail(state, chunk, maxBytes)\n    return state\n  }).pipe(Effect.map((state) =>\n    overflow === \"refuse\" && state.dropped > 0\n      ? { text: \"\", droppedBytes: state.dropped }\n      : decodeTail(state)\n  ))\n\n/**\n * Keeps the first half of the bound and the last half. The head fills first,\n * and every byte after it passes through the tail, which drops from its front:\n * what falls out of the tail is the middle.\n */\nconst boundedEnds = <E>(stream: Stream.Stream<Uint8Array, E>, maxBytes: number): Effect.Effect<Capture, E> => {\n  const headBytes = Math.floor(maxBytes / 2)\n  return Stream.runFold(stream, (): Ends => ({ head: [], headBytes: 0, tail: emptyTail() }), (state, chunk) => {\n    const taken = Math.min(headBytes - state.headBytes, chunk.byteLength)\n    if (taken > 0) {\n      state.head.push(chunk.subarray(0, taken))\n      state.headBytes += taken\n    }\n    keepTail(state.tail, chunk.subarray(taken), maxBytes - headBytes)\n    return state\n  }).pipe(Effect.map(decodeEnds))\n}\n\nconst capture = <E>(\n  stream: Stream.Stream<Uint8Array, E>,\n  maxBytes: number | undefined,\n  overflow: Overflow | undefined\n): Effect.Effect<Capture, E> =>\n  maxBytes === undefined\n    ? Effect.map(Stream.mkString(Stream.decodeText(stream)), (text) => ({ text, droppedBytes: 0 }))\n    : overflow === \"ends\"\n    ? boundedEnds(stream, maxBytes)\n    : boundedTail(stream, maxBytes, overflow)\n\n/**\n * A command whose arguments exceed the operating system's limit fails `execve`\n * with `E2BIG` before it starts: one argument over 128 KiB on Linux, all of\n * them over 1 MiB on macOS. A heredoc in a command line, or a file's text\n * passed as an argument, is one such argument. The platform error's own text\n * repeats the whole command line, so this text is written here instead, and a\n * caller may show it as it stands.\n */\nconst argumentsTooLong = (error: { readonly cause?: unknown }): ExecError | undefined =>\n  (error.cause as { readonly code?: unknown } | undefined)?.code === \"E2BIG\"\n    ? new ExecError({\n      code: \"arguments_too_long\",\n      message:\n        \"Command not started: its arguments exceed the operating system's size limit (E2BIG). Send long text on standard input or in a file, not in the command line or its arguments.\"\n    })\n    : undefined\n\nconst unbounded = (\n  command: string,\n  options: ExecOptions\n): Effect.Effect<ExecResult, ExecError, ChildProcessSpawner.ChildProcessSpawner> =>\n  Effect.gen(function*() {\n    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner\n    const settings: ChildProcess.CommandOptions = {\n      ...(options.args === undefined ? { shell: true } : {}),\n      ...(options.cwd === undefined ? {} : { cwd: options.cwd }),\n      env: ChildProcessEnvironment.make(process.env, options.env),\n      extendEnv: false,\n      ...(options.stdin === undefined\n        ? {}\n        : { stdin: Stream.make(new TextEncoder().encode(options.stdin)) })\n    }\n    const handle = yield* spawner.spawn(\n      options.args === undefined\n        ? ChildProcess.make(command, settings)\n        : ChildProcess.make(command, [...options.args], settings)\n    ).pipe(\n      // Node's `spawn` throws E2BIG instead of emitting `error`, and Effect's\n      // raw Node spawner calls it unguarded, so there it arrives as a defect.\n      Effect.catchDefect((defect) => {\n        const refused = argumentsTooLong({ cause: defect })\n        return refused === undefined ? Effect.die(defect) : Effect.fail(refused)\n      })\n    )\n    // stdout, stderr, and the exit code have to be consumed concurrently: a\n    // command that fills a pipe blocks until the pipe is drained, so waiting\n    // for exit first would deadlock on any output larger than the buffer.\n    const [stdout, stderr, exitCode] = yield* Effect.all(\n      [\n        capture(handle.stdout, options.maxCaptureBytes, options.overflow),\n        capture(handle.stderr, options.maxCaptureBytes, options.overflow),\n        handle.exitCode\n      ],\n      { concurrency: \"unbounded\" }\n    )\n    if (options.overflow === \"refuse\") {\n      const overflowed = [\n        stdout.droppedBytes > 0 ? \"stdout\" : undefined,\n        stderr.droppedBytes > 0 ? \"stderr\" : undefined\n      ]\n        .filter((stream): stream is string => stream !== undefined)\n      if (overflowed.length > 0) {\n        return yield* Effect.fail(\n          new ExecError({\n            code: \"capture_overflow\",\n            message: `${command} ${\n              overflowed.join(\" and \")\n            } exceeded the ${options.maxCaptureBytes}-byte capture cap; refusing partial output`\n          })\n        )\n      }\n    }\n    return {\n      stdout: stdout.text,\n      stderr: stderr.text,\n      exitCode,\n      stdoutDroppedBytes: stdout.droppedBytes,\n      stderrDroppedBytes: stderr.droppedBytes\n    }\n  }).pipe(\n    Effect.scoped,\n    Effect.mapError((error) =>\n      error instanceof ExecError ? error : argumentsTooLong(error) ?? new ExecError({\n        code: \"spawn_error\",\n        message: `exec: ${command}: ${error.message}`\n      })\n    )\n  )\n\n/**\n * Runs a command line through the platform shell and buffers its output.\n *\n * Cancellation is scope closure: the spawn is scoped, so an interrupted fiber\n * — including the one a `timeoutMs` interrupts — terminates the process rather\n * than leaking it.\n *\n * @category execution\n * @since 1.0.0\n */\nexport const exec = (\n  command: string,\n  options: ExecOptions = {}\n): Effect.Effect<ExecResult, ExecError, ChildProcessSpawner.ChildProcessSpawner> =>\n  options.timeoutMs === undefined\n    ? unbounded(command, options)\n    : Effect.timeoutOrElse(unbounded(command, options), {\n      duration: options.timeoutMs,\n      orElse: () =>\n        Effect.fail(\n          new ExecError({\n            code: \"timeout\",\n            message: `exec: \\`${command}\\` exceeded ${options.timeoutMs}ms`,\n            limitMillis: options.timeoutMs\n          })\n        )\n    })\n\n/**\n * The model-facing failure code a command that never produced an exit code\n * carries.\n *\n * A timeout keeps its own code, because \"the command never finished\" and \"the\n * command never started\" are different things to a caller deciding whether to\n * retry. Arguments the operating system refused for their size are the\n * caller's own input, which a shell flow publishes, so they read as\n * `invalid_input`. Every other way of producing no exit code is a host failure.\n *\n * @category errors\n * @since 1.0.0\n */\nexport const toStdErrorCode = (error: ExecError): StdError.Code =>\n  error.code === \"timeout\" ? \"timeout\" : error.code === \"arguments_too_long\" ? \"invalid_input\" : \"command_failed\"\n\n/**\n * The model-facing failure one execution error becomes.\n *\n * A timeout names the command, which is what the caller asked for and all a\n * timeout has to say. Arguments too long to start carry the reason and the\n * fix, and nothing of the command. Any other failure carries the message the\n * execution produced, which already names the command.\n *\n * @category errors\n * @since 1.0.0\n */\nexport const toStdError = (command: string, error: ExecError): StdError.StdError =>\n  new StdError.StdError({\n    code: toStdErrorCode(error),\n    message: error.code === \"timeout\"\n      ? `Command timed out: ${command}`\n      : error.code === \"arguments_too_long\"\n      ? error.message\n      : `Command failed to start: ${error.message}`,\n    ...(error.limitMillis === undefined ? {} : { limitMillis: error.limitMillis })\n  })\n"]}

package/dist/esm/internal/FileMutation.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Mutation preparation for versioned hosts and cooperative locks for ordinary hosts.
+ * Ordinary locks fail closed after process death; they are never stolen on a timer.
+ *
+ * @since 1.0.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import type * as Path from "effect/Path";
+import type * as Scope from "effect/Scope";
+import * as StdError from "../StdError.ts";
+/**
+ * Authenticated standard-flow call session; absent callers cannot borrow another run's base.
+ *
+ * @category context
+ * @since 1.0.0
+ */
+export declare const ReadSession: Context.Reference<string | undefined>;
+/**
+ * The coding host attaches one run-scoped precondition policy to its guarded filesystem.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export declare const Preconditions: unique symbol;
+/**
+ * One prepared file change; moves include a write and a guarded source removal.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Change {
+    readonly path: string;
+    /** Null removes a file. Writes preserve existing metadata; new files use host defaults. */
+    readonly content: Uint8Array | null;
+}
+/**
+ * A per-invocation provider receipt boundary, with immutable captured read bases.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Prepared {
+    /** Return bytes matching the captured base, never an unchecked current read. */
+    readonly read: (path: string) => Effect.Effect<Uint8Array, StdError.StdError>;
+    readonly commit: (changes: ReadonlyArray<Change>) => Effect.Effect<void, StdError.StdError>;
+}
+/**
+ * Read records only successful model-facing reads; mutation-internal reads never refresh a base.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface VersionedFileSystem extends FileSystem.FileSystem {
+    readonly [Preconditions]?: {
+        readonly record: (path: string, bytes: Uint8Array, session: string | undefined) => Effect.Effect<void, StdError.StdError>;
+        readonly validate: (paths: ReadonlyArray<string>, session: string | undefined) => Effect.Effect<void, StdError.StdError>;
+        /** Capture this invocation's bases from the existing ledger before tool-internal
+         * reads. The returned commit must compare them again inside the provider, then
+         * settle the entire batch before advancing the ledger. Concurrent reads or
+         * commits must never replace these captured bases. Preparation does not freeze
+         * callers; only the complete commit may acquire guest-wide exclusion.
+         */
+        readonly prepare?: (paths: ReadonlyArray<string>, session: string | undefined) => Effect.Effect<Prepared, StdError.StdError>;
+    };
+}
+/**
+ * Versioned hosts own parent creation and locking inside their atomic commit.
+ *
+ * @category guards
+ * @since 1.0.0
+ */
+export declare const isVersioned: (fs: FileSystem.FileSystem) => boolean;
+/**
+ * Record the entire original file, before pagination, through the host's existing policy.
+ *
+ * @category filesystem
+ * @since 1.0.0
+ */
+export declare const recordRead: (fs: FileSystem.FileSystem, path: string, bytes: Uint8Array) => Effect.Effect<void, StdError.StdError, never>;
+/**
+ * Refuse an unqualified provider before creating any parent or lock directories.
+ *
+ * @category filesystem
+ * @since 1.0.0
+ */
+export declare const validate: (fs: FileSystem.FileSystem, paths: ReadonlyArray<string>) => Effect.Effect<undefined, StdError.StdError, never>;
+/**
+ * The portable body is used only for an ordinary, unversioned filesystem.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Mutation {
+    readonly read: (path: string, ordinary: Effect.Effect<Uint8Array, StdError.StdError>) => Effect.Effect<Uint8Array, StdError.StdError>;
+    readonly commit: (changes: ReadonlyArray<Change>, ordinary: Effect.Effect<void, StdError.StdError>) => Effect.Effect<void, StdError.StdError>;
+}
+/**
+ * Versioned hosts capture bases under a local semaphore until scope exit.
+ * Ordinary hosts hold all named files using exclusive mkdir, so independently
+ * composed hosts and processes agree.
+ * A hash collision only refuses an unrelated edit; it cannot lose exclusion.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const acquire: (fileSystem: FileSystem.FileSystem, paths: ReadonlyArray<string>, creationPaths?: Path.Path) => Effect.Effect<Mutation, StdError.StdError, Scope.Scope>;
+//# sourceMappingURL=FileMutation.d.ts.map

package/dist/esm/internal/FileMutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileMutation.d.ts","sourceRoot":"","sources":["../../../src/internal/FileMutation.ts"],"names":[],"mappings":"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"}

package/dist/esm/internal/FileMutation.js

@@ -0,0 +1,123 @@
+/**
+ * Mutation preparation for versioned hosts and cooperative locks for ordinary hosts.
+ * Ordinary locks fail closed after process death; they are never stolen on a timer.
+ *
+ * @since 1.0.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Semaphore from "effect/Semaphore";
+import * as StdError from "../StdError.js";
+import * as FsFailure from "./FsFailure.js";
+/**
+ * Authenticated standard-flow call session; absent callers cannot borrow another run's base.
+ *
+ * @category context
+ * @since 1.0.0
+ */
+export const ReadSession = Context.Reference("@smthrs/std/ReadSession", {
+    defaultValue: () => undefined
+});
+/**
+ * The coding host attaches one run-scoped precondition policy to its guarded filesystem.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const Preconditions = Symbol.for("@smthrs/std/file-preconditions");
+const unavailable = () => Effect.fail(new StdError.StdError({
+    code: "provider_unavailable",
+    message: "Authenticated atomic file mutation provider unavailable"
+}));
+/**
+ * Versioned hosts own parent creation and locking inside their atomic commit.
+ *
+ * @category guards
+ * @since 1.0.0
+ */
+export const isVersioned = (fs) => fs[Preconditions] !== undefined;
+/**
+ * Record the entire original file, before pagination, through the host's existing policy.
+ *
+ * @category filesystem
+ * @since 1.0.0
+ */
+export const recordRead = (fs, path, bytes) => Effect.flatMap(ReadSession, (session) => fs[Preconditions]?.record(path, bytes, session) ?? Effect.void);
+/**
+ * Refuse an unqualified provider before creating any parent or lock directories.
+ *
+ * @category filesystem
+ * @since 1.0.0
+ */
+export const validate = (fs, paths) => Effect.gen(function* () {
+    const policy = fs[Preconditions];
+    if (policy === undefined)
+        return;
+    const session = yield* ReadSession;
+    yield* policy.validate(paths, session);
+    if (policy.prepare === undefined)
+        return yield* unavailable();
+});
+// This serializes one host's preparation, ledger and diagnostic ordering only.
+// It is NOT the guest's outside-writer exclusion or its atomic commit boundary.
+const hostLocks = new WeakMap();
+// The on-disk lock protocol owns this hash; dependency upgrades must not
+// change the name and let two versions acquire different locks for one file.
+// Case/normalization aliases deliberately share a lock, including on hosts
+// whose realPath preserves caller casing. Case-sensitive hosts may refuse a
+// simultaneous change to a distinct case variant; that is safe contention.
+const lockHash = (value) => {
+    value = value.normalize("NFC").toUpperCase();
+    let hash = 5381;
+    for (let index = 0; index < value.length; index++)
+        hash = (hash * 33) ^ value.charCodeAt(index);
+    return (hash >>> 0).toString(16);
+};
+const parent = (path) => path.slice(0, path.lastIndexOf(path.startsWith("/") ? "/" : "\\") + 1);
+/**
+ * Versioned hosts capture bases under a local semaphore until scope exit.
+ * Ordinary hosts hold all named files using exclusive mkdir, so independently
+ * composed hosts and processes agree.
+ * A hash collision only refuses an unrelated edit; it cannot lose exclusion.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const acquire = (fileSystem, paths, creationPaths) => Effect.gen(function* () {
+    // Unavailable coding providers refuse before acquiring even protocol state.
+    // The versioned provider owns exclusion and revalidation at its commit;
+    // cooperative caller-side locks cannot exclude terminal or SSH writers.
+    yield* validate(fileSystem, paths);
+    const policy = fileSystem[Preconditions];
+    if (policy !== undefined) {
+        let lock = hostLocks.get(policy);
+        if (lock === undefined) {
+            lock = Semaphore.makeUnsafe(1);
+            hostLocks.set(policy, lock);
+        }
+        const held = lock;
+        yield* Effect.acquireRelease(held.take(1), () => held.release(1), { interruptible: true });
+        const session = yield* ReadSession;
+        const prepared = yield* policy.prepare(paths, session);
+        return { read: (path) => prepared.read(path), commit: (changes) => prepared.commit(changes) };
+    }
+    const locks = new Map();
+    for (const path of paths) {
+        const destination = yield* fileSystem.realPath(path).pipe(Effect.catch((error) => error.reason._tag === "NotFound" && creationPaths !== undefined
+            ? fileSystem.realPath(creationPaths.dirname(path)).pipe(Effect.map((directory) => creationPaths.join(directory, creationPaths.basename(path))))
+            : Effect.fail(error)), Effect.mapError(FsFailure.reading(path, `File not found: ${path}`)));
+        const lock = `${parent(destination)}.smithers-${lockHash(destination)}.lock`;
+        locks.set(lock, path);
+    }
+    for (const [lock, path] of [...locks].sort(([left], [right]) => left.localeCompare(right))) {
+        yield* Effect.acquireRelease(fileSystem.makeDirectory(lock, { mode: 0o700 }).pipe(Effect.mapError(FsFailure.denied(path, (error) => new StdError.StdError({
+            code: error.reason._tag === "AlreadyExists" ? "no_match" : "command_failed",
+            message: error.reason._tag === "AlreadyExists"
+                ? `Concurrent mutation of ${path}: lock ${lock} is held. Re-read and retry after the other writer finishes; a stopped writer's lock requires explicit recovery.`
+                : `Could not lock ${path} for mutation`,
+            path
+        })))), () => fileSystem.remove(lock, { recursive: true }).pipe(Effect.orDie));
+    }
+    return { read: (_path, ordinary) => ordinary, commit: (_changes, ordinary) => ordinary };
+});
+//# sourceMappingURL=FileMutation.js.map

package/dist/esm/internal/FileMutation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileMutation.js","sourceRoot":"","sources":["../../../src/internal/FileMutation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAIvC,OAAO,KAAK,SAAS,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAC1C,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAE3C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,SAAS,CAAqB,yBAAyB,EAAE;IAC1F,YAAY,EAAE,GAAG,EAAE,CAAC,SAAS;CAC9B,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAA;AAwDzE,MAAM,WAAW,GAAG,GAAG,EAAE,CACvB,MAAM,CAAC,IAAI,CACT,IAAI,QAAQ,CAAC,QAAQ,CAAC;IACpB,IAAI,EAAE,sBAAsB;IAC5B,OAAO,EAAE,yDAAyD;CACnE,CAAC,CACH,CAAA;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,EAAyB,EAAW,EAAE,CAC/D,EAA0B,CAAC,aAAa,CAAC,KAAK,SAAS,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,EAAyB,EAAE,IAAY,EAAE,KAAiB,EAAE,EAAE,CACvF,MAAM,CAAC,OAAO,CACZ,WAAW,EACX,CAAC,OAAO,EAAE,EAAE,CAAE,EAA0B,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CACrG,CAAA;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,EAAyB,EAAE,KAA4B,EAAE,EAAE,CAClF,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,MAAM,GAAI,EAA0B,CAAC,aAAa,CAAC,CAAA;IACzD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAM;IAChC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,WAAW,CAAA;IAClC,KAAK,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;IACtC,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,CAAC,WAAW,EAAE,CAAA;AAC/D,CAAC,CAAC,CAAA;AAmBJ,+EAA+E;AAC/E,gFAAgF;AAChF,MAAM,SAAS,GAAG,IAAI,OAAO,EAA+B,CAAA;AAE5D,yEAAyE;AACzE,6EAA6E;AAC7E,2EAA2E;AAC3E,4EAA4E;AAC5E,2EAA2E;AAC3E,MAAM,QAAQ,GAAG,CAAC,KAAa,EAAU,EAAE;IACzC,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAA;IAC5C,IAAI,IAAI,GAAG,IAAI,CAAA;IACf,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE;QAAE,IAAI,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAA;IAC/F,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;AAClC,CAAC,CAAA;AAED,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;AAEvG;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CACrB,UAAiC,EACjC,KAA4B,EAC5B,aAAyB,EACgC,EAAE,CAC3D,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,4EAA4E;IAC5E,wEAAwE;IACxE,wEAAwE;IACxE,KAAK,CAAC,CAAC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,CAAA;IAClC,MAAM,MAAM,GAAI,UAAkC,CAAC,aAAa,CAAC,CAAA;IACjE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,IAAI,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QAChC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,IAAI,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;YAC9B,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QAC7B,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAA;QACjB,KAAK,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;QAC1F,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,WAAW,CAAA;QAClC,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,OAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;QACvD,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAA;IAC/F,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAA;IACvC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CACvD,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CACrB,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,UAAU,IAAI,aAAa,KAAK,SAAS;YAC7D,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CACrD,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CACvF;YACD,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CACvB,EACD,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,mBAAmB,IAAI,EAAE,CAAC,CAAC,CACpE,CAAA;QACD,MAAM,IAAI,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,aAAa,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAA;QAC5E,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IACvB,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QAC3F,KAAK,CAAC,CAAC,MAAM,CAAC,cAAc,CAC1B,UAAU,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,CAClD,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAC/C,IAAI,QAAQ,CAAC,QAAQ,CAAC;YACpB,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,gBAAgB;YAC3E,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,eAAe;gBAC5C,CAAC,CAAC,0BAA0B,IAAI,UAAU,IAAI,kHAAkH;gBAChK,CAAC,CAAC,kBAAkB,IAAI,eAAe;YACzC,IAAI;SACL,CAAC,CAAC,CAAC,CACP,EACD,GAAG,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CACtE,CAAA;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAA;AAC1F,CAAC,CAAC,CAAA","sourcesContent":["/**\n * Mutation preparation for versioned hosts and cooperative locks for ordinary hosts.\n * Ordinary locks fail closed after process death; they are never stolen on a timer.\n *\n * @since 1.0.0\n */\n\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport type * as FileSystem from \"effect/FileSystem\"\nimport type * as Path from \"effect/Path\"\nimport type * as Scope from \"effect/Scope\"\nimport * as Semaphore from \"effect/Semaphore\"\nimport * as StdError from \"../StdError.ts\"\nimport * as FsFailure from \"./FsFailure.ts\"\n\n/**\n * Authenticated standard-flow call session; absent callers cannot borrow another run's base.\n *\n * @category context\n * @since 1.0.0\n */\nexport const ReadSession = Context.Reference<string | undefined>(\"@smthrs/std/ReadSession\", {\n  defaultValue: () => undefined\n})\n\n/**\n * The coding host attaches one run-scoped precondition policy to its guarded filesystem.\n *\n * @category identifiers\n * @since 1.0.0\n */\nexport const Preconditions = Symbol.for(\"@smthrs/std/file-preconditions\")\n\n/**\n * One prepared file change; moves include a write and a guarded source removal.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Change {\n  readonly path: string\n  /** Null removes a file. Writes preserve existing metadata; new files use host defaults. */\n  readonly content: Uint8Array | null\n}\n\n/**\n * A per-invocation provider receipt boundary, with immutable captured read bases.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Prepared {\n  /** Return bytes matching the captured base, never an unchecked current read. */\n  readonly read: (path: string) => Effect.Effect<Uint8Array, StdError.StdError>\n  readonly commit: (changes: ReadonlyArray<Change>) => Effect.Effect<void, StdError.StdError>\n}\n\n/**\n * Read records only successful model-facing reads; mutation-internal reads never refresh a base.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface VersionedFileSystem extends FileSystem.FileSystem {\n  readonly [Preconditions]?: {\n    readonly record: (\n      path: string,\n      bytes: Uint8Array,\n      session: string | undefined\n    ) => Effect.Effect<void, StdError.StdError>\n    readonly validate: (\n      paths: ReadonlyArray<string>,\n      session: string | undefined\n    ) => Effect.Effect<void, StdError.StdError>\n    /** Capture this invocation's bases from the existing ledger before tool-internal\n     * reads. The returned commit must compare them again inside the provider, then\n     * settle the entire batch before advancing the ledger. Concurrent reads or\n     * commits must never replace these captured bases. Preparation does not freeze\n     * callers; only the complete commit may acquire guest-wide exclusion.\n     */\n    readonly prepare?: (\n      paths: ReadonlyArray<string>,\n      session: string | undefined\n    ) => Effect.Effect<Prepared, StdError.StdError>\n  }\n}\n\nconst unavailable = () =>\n  Effect.fail(\n    new StdError.StdError({\n      code: \"provider_unavailable\",\n      message: \"Authenticated atomic file mutation provider unavailable\"\n    })\n  )\n\n/**\n * Versioned hosts own parent creation and locking inside their atomic commit.\n *\n * @category guards\n * @since 1.0.0\n */\nexport const isVersioned = (fs: FileSystem.FileSystem): boolean =>\n  (fs as VersionedFileSystem)[Preconditions] !== undefined\n\n/**\n * Record the entire original file, before pagination, through the host's existing policy.\n *\n * @category filesystem\n * @since 1.0.0\n */\nexport const recordRead = (fs: FileSystem.FileSystem, path: string, bytes: Uint8Array) =>\n  Effect.flatMap(\n    ReadSession,\n    (session) => (fs as VersionedFileSystem)[Preconditions]?.record(path, bytes, session) ?? Effect.void\n  )\n\n/**\n * Refuse an unqualified provider before creating any parent or lock directories.\n *\n * @category filesystem\n * @since 1.0.0\n */\nexport const validate = (fs: FileSystem.FileSystem, paths: ReadonlyArray<string>) =>\n  Effect.gen(function*() {\n    const policy = (fs as VersionedFileSystem)[Preconditions]\n    if (policy === undefined) return\n    const session = yield* ReadSession\n    yield* policy.validate(paths, session)\n    if (policy.prepare === undefined) return yield* unavailable()\n  })\n\n/**\n * The portable body is used only for an ordinary, unversioned filesystem.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Mutation {\n  readonly read: (\n    path: string,\n    ordinary: Effect.Effect<Uint8Array, StdError.StdError>\n  ) => Effect.Effect<Uint8Array, StdError.StdError>\n  readonly commit: (\n    changes: ReadonlyArray<Change>,\n    ordinary: Effect.Effect<void, StdError.StdError>\n  ) => Effect.Effect<void, StdError.StdError>\n}\n\n// This serializes one host's preparation, ledger and diagnostic ordering only.\n// It is NOT the guest's outside-writer exclusion or its atomic commit boundary.\nconst hostLocks = new WeakMap<object, Semaphore.Semaphore>()\n\n// The on-disk lock protocol owns this hash; dependency upgrades must not\n// change the name and let two versions acquire different locks for one file.\n// Case/normalization aliases deliberately share a lock, including on hosts\n// whose realPath preserves caller casing. Case-sensitive hosts may refuse a\n// simultaneous change to a distinct case variant; that is safe contention.\nconst lockHash = (value: string): string => {\n  value = value.normalize(\"NFC\").toUpperCase()\n  let hash = 5381\n  for (let index = 0; index < value.length; index++) hash = (hash * 33) ^ value.charCodeAt(index)\n  return (hash >>> 0).toString(16)\n}\n\nconst parent = (path: string) => path.slice(0, path.lastIndexOf(path.startsWith(\"/\") ? \"/\" : \"\\\\\") + 1)\n\n/**\n * Versioned hosts capture bases under a local semaphore until scope exit.\n * Ordinary hosts hold all named files using exclusive mkdir, so independently\n * composed hosts and processes agree.\n * A hash collision only refuses an unrelated edit; it cannot lose exclusion.\n *\n * @private\n * @since 1.0.0\n */\nexport const acquire = (\n  fileSystem: FileSystem.FileSystem,\n  paths: ReadonlyArray<string>,\n  creationPaths?: Path.Path\n): Effect.Effect<Mutation, StdError.StdError, Scope.Scope> =>\n  Effect.gen(function*() {\n    // Unavailable coding providers refuse before acquiring even protocol state.\n    // The versioned provider owns exclusion and revalidation at its commit;\n    // cooperative caller-side locks cannot exclude terminal or SSH writers.\n    yield* validate(fileSystem, paths)\n    const policy = (fileSystem as VersionedFileSystem)[Preconditions]\n    if (policy !== undefined) {\n      let lock = hostLocks.get(policy)\n      if (lock === undefined) {\n        lock = Semaphore.makeUnsafe(1)\n        hostLocks.set(policy, lock)\n      }\n      const held = lock\n      yield* Effect.acquireRelease(held.take(1), () => held.release(1), { interruptible: true })\n      const session = yield* ReadSession\n      const prepared = yield* policy.prepare!(paths, session)\n      return { read: (path) => prepared.read(path), commit: (changes) => prepared.commit(changes) }\n    }\n    const locks = new Map<string, string>()\n    for (const path of paths) {\n      const destination = yield* fileSystem.realPath(path).pipe(\n        Effect.catch((error) =>\n          error.reason._tag === \"NotFound\" && creationPaths !== undefined\n            ? fileSystem.realPath(creationPaths.dirname(path)).pipe(\n              Effect.map((directory) => creationPaths.join(directory, creationPaths.basename(path)))\n            )\n            : Effect.fail(error)\n        ),\n        Effect.mapError(FsFailure.reading(path, `File not found: ${path}`))\n      )\n      const lock = `${parent(destination)}.smithers-${lockHash(destination)}.lock`\n      locks.set(lock, path)\n    }\n    for (const [lock, path] of [...locks].sort(([left], [right]) => left.localeCompare(right))) {\n      yield* Effect.acquireRelease(\n        fileSystem.makeDirectory(lock, { mode: 0o700 }).pipe(\n          Effect.mapError(FsFailure.denied(path, (error) =>\n            new StdError.StdError({\n              code: error.reason._tag === \"AlreadyExists\" ? \"no_match\" : \"command_failed\",\n              message: error.reason._tag === \"AlreadyExists\"\n                ? `Concurrent mutation of ${path}: lock ${lock} is held. Re-read and retry after the other writer finishes; a stopped writer's lock requires explicit recovery.`\n                : `Could not lock ${path} for mutation`,\n              path\n            })))\n        ),\n        () => fileSystem.remove(lock, { recursive: true }).pipe(Effect.orDie)\n      )\n    }\n    return { read: (_path, ordinary) => ordinary, commit: (_changes, ordinary) => ordinary }\n  })\n"]}

package/dist/esm/internal/FsFailure.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Maps a filesystem failure to the standard-flow code that names its reason.
+ *
+ * A permission denial is not a missing file. Telling the model a denied path
+ * does not exist sends it searching for a file that is right there, and hides
+ * the denial from whoever reads the run. Every standard flow that touches the
+ * filesystem routes its failures through here so `PermissionDenied` always
+ * reaches the model as `permission_denied`.
+ *
+ * @since 1.0.0
+ */
+import type * as PlatformError from "effect/PlatformError";
+import * as StdError from "../StdError.ts";
+/**
+ * The failure for a path the host or the kernel guard refused.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const permissionDenied: (path: string) => StdError.StdError;
+/**
+ * Maps `PermissionDenied` to `permission_denied` and any other reason through
+ * `otherwise`.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const denied: (path: string, otherwise: (error: PlatformError.PlatformError) => StdError.StdError) => (error: PlatformError.PlatformError) => StdError.StdError;
+/**
+ * Maps a read-side failure: `NotFound` to `not_found` with `notFoundMessage`,
+ * `PermissionDenied` to `permission_denied`, and anything else to
+ * `command_failed` carrying the host's reason.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const reading: (path: string, notFoundMessage: string) => (error: PlatformError.PlatformError) => StdError.StdError;
+//# sourceMappingURL=FsFailure.d.ts.map