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

package/dist/cjs/internal/EnvelopePrecheck.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/internal/EnvelopePrecheck.ts"],
+  "sourcesContent": ["/**\n * The hermetic pre-check: a lexical scan of shell text for the paths it names,\n * and the refusal when one of them falls outside the declared envelope.\n *\n * The scan is fail-closed over explicit path tokens and nothing more. It\n * cannot prove confinement \u2014 a shell can name a path no lexer sees, through a\n * variable, a substitution, or a program that opens a file of its own \u2014 so a\n * kernel or host sandbox must eventually enforce and report the complete read\n * and write sets.\n *\n * It lives beside the flow rather than inside it because it is its own\n * concept, with its own vocabulary (Access, PathReference) and its own\n * security history: three independent bypasses, each sufficient on its own to\n * defeat it, are closed here.\n *\n * @since 1.0.0\n */\n\nimport type * as Path from \"@smthrs/kernel/Path\"\nimport * as StdError from \"../StdError.ts\"\nimport { withinEnvelope } from \"./Paths.ts\"\n\n/**\n * The filesystem envelope one invocation declared.\n *\n * Structural rather than the hermetic `Bash.Input` itself: the scan needs the\n * three fields and none of the rest, and depending on the flow module would\n * make the flow and its pre-check import each other.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Envelope {\n  readonly cwd?: string | undefined\n  readonly reads: ReadonlyArray<string>\n  readonly writes: ReadonlyArray<string>\n}\n\n/**\n * How a command touches a path it names.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Access = \"read\" | \"write\"\n\n/**\n * One path a command names, and how it touches it.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface PathReference {\n  readonly access: Access\n  readonly value: string\n}\n\nconst commandSeparators = new Set([\"&&\", \"||\", \";\", \"|\", \"&\", \"\\n\"])\nconst redirections = new Set([\">\", \">>\", \"<\", \"<<\"])\nconst writeCommands = new Set([\"chmod\", \"chown\", \"mkdir\", \"rm\", \"rmdir\", \"tee\", \"touch\", \"truncate\", \"unlink\"])\nconst destinationCommands = new Set([\"cp\", \"install\", \"mv\"])\nconst prefixWrappers = new Set([\"env\", \"nice\", \"time\", \"sudo\", \"nohup\", \"xargs\", \"command\", \"exec\"])\n\n// Shell spaces may disappear, but a physical line ends one command. Retaining\n// LF prevents a command on line one from classifying every later line's paths.\n//\n// A word is one or more runs of bare characters and quoted sections, not a\n// bare run alone: `FOO=\"a b\" rm /work/target` used to tokenize as `FOO=\"a`,\n// `b\"`, `rm`, `/work/target`, and since only the first token carried an `=`\n// the command was read as `b\"` rather than `rm` \u2014 so the delete was\n// classified as a read and a hermetic call with `writes: []` spawned. The\n// quoted alternatives come first inside the group so a quoted span is taken\n// whole; the bare class excludes quotes so the branches cannot overlap.\nconst tokenize = (command: string): ReadonlyArray<string> =>\n  command.match(/\\n|>>|<<|&&|\\|\\||[<>;|&]|(?:\"(?:\\\\.|[^\"\\\\])*\"|'[^']*'|[^\\s<>;|&\"']+)+/g) ?? []\n\nconst unquote = (token: string): string => {\n  const first = token[0]\n  const last = token[token.length - 1]\n  return token.length >= 2 && (first === \"'\" || first === \"\\\"\") && last === first\n    ? token.slice(1, -1)\n    : token\n}\n\nconst pathValue = (token: string): string =>\n  unquote(token)\n    .replace(/^\\$\\(+/, \"\")\n    .replace(/[),]+$/, \"\")\n\nconst isPathToken = (path: Path.Path, token: string): boolean =>\n  token === \".\" ||\n  token === \"..\" ||\n  token.startsWith(\"./\") ||\n  token.startsWith(\"../\") ||\n  path.isAbsolute(token) ||\n  /^[A-Za-z]:[\\\\/]/.test(token) ||\n  token.includes(\"/\")\n\nconst segmentReferences = (path: Path.Path, tokens: ReadonlyArray<string>): ReadonlyArray<PathReference> => {\n  const commentIndex = tokens.findIndex((token) => token.startsWith(\"#\"))\n  const active = commentIndex === -1 ? tokens : tokens.slice(0, commentIndex)\n  const hasWrapper = active.some((token) => prefixWrappers.has(path.basename(pathValue(token))))\n  let commandIndex = active.findIndex((token) =>\n    !redirections.has(token) &&\n    !token.includes(\"=\") &&\n    !prefixWrappers.has(path.basename(pathValue(token))) &&\n    !token.startsWith(\"-\") &&\n    token !== \"\"\n  )\n  if (hasWrapper) {\n    // Wrapper options can carry their own values. Prefer a later known\n    // mutating command so an option value cannot lend it a read classification.\n    const mutatingIndex = active.findIndex((token) => {\n      const command = path.basename(pathValue(token))\n      return writeCommands.has(command) || destinationCommands.has(command)\n    })\n    if (mutatingIndex !== -1) commandIndex = mutatingIndex\n  }\n  if (commandIndex === -1) return []\n\n  const command = path.basename(pathValue(active[commandIndex]!))\n  const candidates: Array<{ readonly index: number; readonly value: string }> = []\n  for (let index = 0; index < active.length; index++) {\n    const token = active[index]!\n    if (index === commandIndex || redirections.has(token) || token.startsWith(\"-\")) continue\n    const value = pathValue(token)\n    if (value !== \"\" && isPathToken(path, value)) candidates.push({ index, value })\n  }\n\n  const destinationIndex = destinationCommands.has(command)\n    ? candidates[candidates.length - 1]?.index\n    : undefined\n\n  return candidates.map(({ index, value }) => {\n    const previous = active[index - 1]\n    const access: Access = previous === \">\" || previous === \">>\" ||\n        writeCommands.has(command) || destinationIndex === index\n      ? \"write\"\n      : \"read\"\n    return { access, value }\n  })\n}\n\n/**\n * Every path token the shell text names, one segment at a time.\n *\n * @category pre-check\n * @since 1.0.0\n */\nexport const commandReferences = (path: Path.Path, command: string): ReadonlyArray<PathReference> => {\n  const references: Array<PathReference> = []\n  let segment: Array<string> = []\n  for (const token of tokenize(command)) {\n    if (commandSeparators.has(token)) {\n      references.push(...segmentReferences(path, segment))\n      segment = []\n    } else {\n      segment.push(token)\n    }\n  }\n  references.push(...segmentReferences(path, segment))\n  return references\n}\n\nconst resolvePath = (\n  path: Path.Path,\n  cwd: string,\n  value: string\n): string => path.isAbsolute(value) ? path.normalize(value) : path.resolve(cwd, value)\n\nconst isDeclared = (\n  path: Path.Path,\n  cwd: string,\n  declared: ReadonlyArray<string>,\n  source: string\n): boolean =>\n  withinEnvelope(\n    declared.map((entry) => resolvePath(path, cwd, entry)),\n    resolvePath(path, cwd, source)\n  )\n\n/**\n * The refusal shell text earns by naming a path outside its declared\n * envelope, or `undefined` when every path it names is declared.\n *\n * @category pre-check\n * @since 1.0.0\n */\nexport const outsideEnvelope = (\n  input: Envelope,\n  text: string,\n  path: Path.Path\n): StdError.StdError | undefined => {\n  const base = path.resolve(\".\")\n  const cwd = path.resolve(input.cwd ?? \".\")\n  // Passing the default explicitly is not a declaration the caller owes. A\n  // working directory is where the command runs, not a file it reads, and\n  // `cwd: \".\"` names exactly what omitting `cwd` names \u2014 so refusing it asked\n  // the caller to list the workspace root among its reads to say nothing at\n  // all. Agents hit this constantly: one SWE-bench run spent ten of its\n  // forty-eight tool calls re-issuing the same command after\n  // \"Working directory is outside declared reads: <the workspace root>\". A\n  // cwd that points somewhere else is still declared or refused.\n  if (input.cwd !== undefined && cwd !== base && !isDeclared(path, cwd, input.reads, cwd)) {\n    return new StdError.StdError({\n      code: \"outside_declared_reads\",\n      message: `Working directory is outside declared reads: ${cwd}`,\n      path: cwd\n    })\n  }\n\n  // The Shell contract currently has no sandbox or access-reporting surface.\n  // This lexical scan is intentionally only a fail-closed pre-check for\n  // explicit path tokens. It cannot prove confinement; a kernel/host sandbox\n  // must eventually enforce and report the complete read and write sets.\n  for (const reference of commandReferences(path, text)) {\n    const resolved = resolvePath(path, cwd, reference.value)\n    // /dev/* is the process plumbing every shell one-liner leans on:\n    // `2>/dev/null`, `cat /dev/stdin`. Normalize first so a dot-dot segment\n    // cannot disguise an ordinary filesystem path as process plumbing.\n    if (resolved.startsWith(\"/dev/\")) continue\n    const declared = reference.access === \"write\" ? input.writes : input.reads\n    if (!isDeclared(path, cwd, declared, resolved)) {\n      const code = reference.access === \"write\" ? \"outside_declared_writes\" : \"outside_declared_reads\"\n      return new StdError.StdError({\n        code,\n        message: `Command path is outside declared ${reference.access}s: ${resolved}`,\n        path: resolved\n      })\n    }\n  }\n  return undefined\n}\n"],
+  "mappings": "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",
+  "names": ["command"]
+}

package/dist/cjs/internal/Exec.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 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 ChildProcessSpawner from "@smthrs/kernel/ChildProcessSpawner";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as StdError from "../StdError.ts";
+/**
+ * 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 declare const ExecErrorCode: Schema.Literals<readonly ["timeout", "spawn_error", "capture_overflow"]>;
+/**
+ * Failure codes a buffered execution can report.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type ExecErrorCode = typeof ExecErrorCode.Type;
+declare const ExecError_base: Schema.Class<ExecError, Schema.TaggedStruct<"@smthrs/std/ExecError", {
+    readonly code: Schema.Literals<readonly ["timeout", "spawn_error", "capture_overflow"]>;
+    readonly message: Schema.String;
+    /** The limit a `timeout` ran past, in milliseconds. */
+    readonly limitMillis: Schema.optional<Schema.Number>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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 or was cut off by its
+ * timeout, or whose captured output exceeded a refusing capture bound.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class ExecError extends ExecError_base {
+}
+/**
+ * The buffered result of one command.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface ExecResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+    /** UTF-8 bytes dropped from the head of stdout to stay inside the capture bound. */
+    readonly stdoutDroppedBytes: number;
+    /** UTF-8 bytes dropped from the head of stderr to stay inside the capture bound. */
+    readonly stderrDroppedBytes: number;
+}
+/**
+ * Options accepted by {@link exec}.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface ExecOptions {
+    readonly cwd?: string | undefined;
+    readonly env?: Readonly<Record<string, string>> | undefined;
+    readonly timeoutMs?: number | undefined;
+    /**
+     * The program's arguments. Present means an argv, absent means a command
+     * line for the platform shell. An argv is how a payload reaches a program
+     * without being quoted into a string: nothing between here and `execve`
+     * re-parses it.
+     */
+    readonly args?: ReadonlyArray<string> | undefined;
+    /**
+     * Text written to the program's standard input, as data. A script delivered
+     * this way is never quoted, escaped, or heredoc-terminated, which is the
+     * whole point: quoting corruption cost the measured SWE-bench program twelve
+     * probe failures and one instance's most expensive frame.
+     */
+    readonly stdin?: string | undefined;
+    /**
+     * Bytes retained per captured stream. A stream that prints more keeps its
+     * tail and reports what it dropped, so a command printing gigabytes costs a
+     * bounded amount of memory rather than the whole of what it printed.
+     *
+     * Absent means unbounded, which is what a caller wants when it needs every
+     * byte a tool produced (`rg --files`, `git worktree list`).
+     */
+    readonly maxCaptureBytes?: number | undefined;
+    /** Defaults to `tail`; `refuse` fails if either stream exceeds the bound. */
+    readonly overflow?: "tail" | "refuse" | undefined;
+}
+/**
+ * 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 declare const exec: (command: string, options?: ExecOptions) => Effect.Effect<ExecResult, ExecError, ChildProcessSpawner.ChildProcessSpawner>;
+/**
+ * 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. Every other way of producing no exit code is a host failure.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare const toStdErrorCode: (error: ExecError) => StdError.Code;
+/**
+ * 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. Any other failure carries the message the execution
+ * produced, which already names the command.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare const toStdError: (command: string, error: ExecError) => StdError.StdError;
+export {};
+//# sourceMappingURL=Exec.d.ts.map

package/dist/cjs/internal/Exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Exec.d.ts","sourceRoot":"","sources":["../../../src/internal/Exec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,mBAAmB,MAAM,oCAAoC,CAAA;AACzE,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,0EAAkE,CAAA;AAE5F;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;;;;IAenD,uDAAuD;;;AAbzD;;;;;;;;;GASG;AACH,qBAAa,SAAU,SAAQ,cAK7B;CAAG;AAEL;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,oFAAoF;IACpF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;IACnC,oFAAoF;IACpF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;CACpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAA;IAC3D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAA;CAClD;AAiJD;;;;;;;;;GASG;AACH,eAAO,MAAM,IAAI,GACf,SAAS,MAAM,EACf,UAAS,WAAgB,KACxB,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,EAAE,mBAAmB,CAAC,mBAAmB,CAazE,CAAA;AAEN;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,SAAS,KAAG,QAAQ,CAAC,IACF,CAAA;AAEzD;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,OAAO,SAAS,KAAG,QAAQ,CAAC,QAOpE,CAAA"}

package/dist/cjs/internal/Exec.js

@@ -0,0 +1,158 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Exec_exports = {};
+__export(Exec_exports, {
+  ExecError: () => ExecError,
+  ExecErrorCode: () => ExecErrorCode,
+  exec: () => exec,
+  toStdError: () => toStdError,
+  toStdErrorCode: () => toStdErrorCode
+});
+module.exports = __toCommonJS(Exec_exports);
+var ChildProcessEnvironment = __toESM(require("@smthrs/kernel/ChildProcessEnvironment"), 1);
+var ChildProcessSpawner = __toESM(require("@smthrs/kernel/ChildProcessSpawner"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var Stream = __toESM(require("effect/Stream"), 1);
+var ChildProcess = __toESM(require("effect/unstable/process/ChildProcess"), 1);
+var StdError = __toESM(require("../StdError.js"), 1);
+const ExecErrorCode = Schema.Literals(["timeout", "spawn_error", "capture_overflow"]);
+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 decodeTail = (state) => {
+  const bytes = new Uint8Array(state.bytes);
+  let offset = 0;
+  for (const chunk of state.chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  if (state.dropped === 0) return { text: decoder.decode(bytes), droppedBytes: 0 };
+  let start = 0;
+  while (start < bytes.byteLength && start < 3 && (bytes[start] & 192) === 128) start++;
+  return { text: decoder.decode(bytes.subarray(start)), droppedBytes: state.dropped + start };
+};
+const boundedTail = (stream, maxBytes, overflow) => Stream.runFold(
+  stream,
+  () => ({ chunks: [], bytes: 0, dropped: 0 }),
+  (state, chunk) => {
+    if (chunk.byteLength === 0) return state;
+    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;
+      }
+    }
+    return state;
+  }
+).pipe(Effect.map(
+  (state) => overflow === "refuse" && state.dropped > 0 ? { text: "", droppedBytes: state.dropped } : decodeTail(state)
+));
+const capture = (stream, maxBytes, overflow) => maxBytes === void 0 ? Effect.map(Stream.mkString(Stream.decodeText(stream)), (text) => ({ text, droppedBytes: 0 })) : boundedTail(stream, maxBytes, overflow);
+const unbounded = (command, options) => Effect.gen(function* () {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const settings = {
+    ...options.args === void 0 ? { shell: true } : {},
+    ...options.cwd === void 0 ? {} : { cwd: options.cwd },
+    env: ChildProcessEnvironment.make(process.env, options.env),
+    extendEnv: false,
+    ...options.stdin === void 0 ? {} : { stdin: Stream.make(new TextEncoder().encode(options.stdin)) }
+  };
+  const handle = yield* spawner.spawn(
+    options.args === void 0 ? ChildProcess.make(command, settings) : ChildProcess.make(command, [...options.args], settings)
+  );
+  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" : void 0,
+      stderr.droppedBytes > 0 ? "stderr" : void 0
+    ].filter((stream) => stream !== void 0);
+    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 : new ExecError({
+      code: "spawn_error",
+      message: `exec: ${command}: ${error.message}`
+    })
+  )
+);
+const exec = (command, options = {}) => options.timeoutMs === void 0 ? 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
+    })
+  )
+});
+const toStdErrorCode = (error) => error.code === "timeout" ? "timeout" : "command_failed";
+const toStdError = (command, error) => new StdError.StdError({
+  code: toStdErrorCode(error),
+  message: error.code === "timeout" ? `Command timed out: ${command}` : `Command failed to start: ${error.message}`,
+  ...error.limitMillis === void 0 ? {} : { limitMillis: error.limitMillis }
+});
+//# sourceMappingURL=Exec.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/internal/Exec.ts"],
+  "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 Schema from \"effect/Schema\"\nimport * as Stream from \"effect/Stream\"\nimport * as ChildProcess from \"effect/unstable/process/ChildProcess\"\nimport * as StdError from \"../StdError.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\", \"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 or was cut off by its\n * timeout, or whose captured output exceeded a refusing capture 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 dropped from the head of stdout to stay inside the capture bound. */\n  readonly stdoutDroppedBytes: number\n  /** UTF-8 bytes dropped from the head of stderr to stay inside the capture bound. */\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 its\n   * tail and reports what it dropped, so a command printing gigabytes costs a\n   * bounded amount of memory rather than the whole of what it 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  /** Defaults to `tail`; `refuse` fails if either stream exceeds the bound. */\n  readonly overflow?: \"tail\" | \"refuse\" | undefined\n}\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\nconst decoder = new TextDecoder(\"utf-8\")\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 UTF-8 continuation byte is `10xxxxxx`, and a code point is at most four\n * bytes, so at most three leading continuation bytes can precede the first\n * whole character. Skipping them is counted as dropped rather than decoded to a\n * replacement character the process never printed.\n */\nconst decodeTail = (state: Tail): Capture => {\n  const bytes = new Uint8Array(state.bytes)\n  let offset = 0\n  for (const chunk of state.chunks) {\n    bytes.set(chunk, offset)\n    offset += chunk.byteLength\n  }\n  if (state.dropped === 0) return { text: decoder.decode(bytes), droppedBytes: 0 }\n  let start = 0\n  while (start < bytes.byteLength && start < 3 && (bytes[start]! & 0b1100_0000) === 0b1000_0000) start++\n  return { text: decoder.decode(bytes.subarray(start)), droppedBytes: state.dropped + start }\n}\n\nconst boundedTail = <E>(\n  stream: Stream.Stream<Uint8Array, E>,\n  maxBytes: number,\n  overflow: \"tail\" | \"refuse\" | undefined\n): Effect.Effect<Capture, E> =>\n  Stream.runFold(\n    stream,\n    (): Tail => ({ chunks: [], bytes: 0, dropped: 0 }),\n    (state, chunk) => {\n      if (chunk.byteLength === 0) return state\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      return state\n    }\n  ).pipe(Effect.map((state) =>\n    overflow === \"refuse\" && state.dropped > 0\n      ? { text: \"\", droppedBytes: state.dropped }\n      : decodeTail(state)\n  ))\n\nconst capture = <E>(\n  stream: Stream.Stream<Uint8Array, E>,\n  maxBytes: number | undefined,\n  overflow: \"tail\" | \"refuse\" | undefined\n): Effect.Effect<Capture, E> =>\n  maxBytes === undefined\n    ? Effect.map(Stream.mkString(Stream.decodeText(stream)), (text) => ({ text, droppedBytes: 0 }))\n    : boundedTail(stream, maxBytes, overflow)\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    )\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 : 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 * \u2014 including the one a `timeoutMs` interrupts \u2014 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. 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\" : \"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. Any other failure carries the message the execution\n * 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      : `Command failed to start: ${error.message}`,\n    ...(error.limitMillis === undefined ? {} : { limitMillis: error.limitMillis })\n  })\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/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/cjs/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/cjs/internal/FileMutation.js

@@ -0,0 +1,116 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var FileMutation_exports = {};
+__export(FileMutation_exports, {
+  Preconditions: () => Preconditions,
+  ReadSession: () => ReadSession,
+  acquire: () => acquire,
+  isVersioned: () => isVersioned,
+  recordRead: () => recordRead,
+  validate: () => validate
+});
+module.exports = __toCommonJS(FileMutation_exports);
+var Context = __toESM(require("effect/Context"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Semaphore = __toESM(require("effect/Semaphore"), 1);
+var StdError = __toESM(require("../StdError.js"), 1);
+var FsFailure = __toESM(require("./FsFailure.js"), 1);
+const ReadSession = Context.Reference("@smthrs/std/ReadSession", {
+  defaultValue: () => void 0
+});
+const Preconditions = /* @__PURE__ */ Symbol.for("@smthrs/std/file-preconditions");
+const unavailable = () => Effect.fail(
+  new StdError.StdError({
+    code: "provider_unavailable",
+    message: "Authenticated atomic file mutation provider unavailable"
+  })
+);
+const isVersioned = (fs) => fs[Preconditions] !== void 0;
+const recordRead = (fs, path, bytes) => Effect.flatMap(
+  ReadSession,
+  (session) => fs[Preconditions]?.record(path, bytes, session) ?? Effect.void
+);
+const validate = (fs, paths) => Effect.gen(function* () {
+  const policy = fs[Preconditions];
+  if (policy === void 0) return;
+  const session = yield* ReadSession;
+  yield* policy.validate(paths, session);
+  if (policy.prepare === void 0) return yield* unavailable();
+});
+const hostLocks = /* @__PURE__ */ new WeakMap();
+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);
+const acquire = (fileSystem, paths, creationPaths) => Effect.gen(function* () {
+  yield* validate(fileSystem, paths);
+  const policy = fileSystem[Preconditions];
+  if (policy !== void 0) {
+    let lock = hostLocks.get(policy);
+    if (lock === void 0) {
+      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 = /* @__PURE__ */ new Map();
+  for (const path of paths) {
+    const destination = yield* fileSystem.realPath(path).pipe(
+      Effect.catch(
+        (error) => error.reason._tag === "NotFound" && creationPaths !== void 0 ? 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: 448 }).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/cjs/internal/FileMutation.js.map

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