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

package/dist/cjs/Read.js

@@ -0,0 +1,223 @@
+"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 name2 in all)
+    __defProp(target, name2, { get: all[name2], 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 Read_exports = {};
+__export(Read_exports, {
+  Input: () => Input,
+  MAX_READ_FILE_BYTES: () => MAX_READ_FILE_BYTES,
+  Output: () => Output,
+  Preconditions: () => import_FileMutation.Preconditions,
+  ReadSession: () => import_FileMutation.ReadSession,
+  activity: () => activity,
+  capabilities: () => capabilities,
+  description: () => description,
+  effects: () => effects,
+  effectsFor: () => effectsFor,
+  flow: () => flow,
+  name: () => name,
+  presentation: () => presentation,
+  run: () => run
+});
+module.exports = __toCommonJS(Read_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var FileSystem = __toESM(require("effect/FileSystem"), 1);
+var Option = __toESM(require("effect/Option"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var import_Declaration = require("./internal/Declaration.js");
+var FileMutation = __toESM(require("./internal/FileMutation.js"), 1);
+var FsFailure = __toESM(require("./internal/FsFailure.js"), 1);
+var import_Text = require("./internal/Text.js");
+var StdError = __toESM(require("./StdError.js"), 1);
+var import_FileMutation = require("./internal/FileMutation.js");
+const name = "read";
+const description = "Read a text file by 1-based offset and limit. content is RAW file text with no line-number prefixes, so any line of it is an edit anchor as it stands; the numbers are startLine/endLine.";
+const Input = Schema.Struct({
+  path: Schema.String.annotate({ description: "Path of the text file to read" }),
+  offset: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))).annotate({
+    description: "1-based line offset"
+  }),
+  limit: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))).annotate({
+    description: "Maximum number of lines to return"
+  })
+});
+const Output = Schema.Struct({
+  content: Schema.String.annotate({
+    description: "Raw page text, preserving CR bytes and omitting the final LF; never line-number prefixed"
+  }),
+  startLine: Schema.Number.annotate({ description: "First returned 1-based line number" }),
+  endLine: Schema.Number.annotate({
+    description: "Last returned 1-based line number, or startLine - 1 when no lines are returned"
+  }),
+  totalLines: Schema.Number.annotate({ description: "Total number of source lines" }),
+  truncated: Schema.Boolean.annotate({ description: "Whether displayed output was truncated" }),
+  notice: Schema.optional(Schema.String.annotate({ description: "Truncation disclosure" }))
+});
+const effects = (0, import_Declaration.envelope)({
+  tier: "sealed",
+  mode: "hermetic",
+  reads: ["/**"],
+  writes: []
+});
+const effectsFor = (input) => (0, import_Declaration.envelope)({
+  tier: "sealed",
+  mode: "hermetic",
+  reads: [input.path],
+  writes: []
+});
+const capabilities = [(0, import_Declaration.capability)("fs:read", "/**")];
+const flow = { name, description, input: Input, output: Output, capabilities, effects };
+const activity = "reads";
+const presentation = {
+  verb: { pending: "reading", success: "read", failure: "failed to read" },
+  subject: "path",
+  result: "read"
+};
+const clipLine = (line) => {
+  let scalars = 0;
+  let end = 0;
+  for (const scalar of line) {
+    if (scalars === import_Text.MAX_LINE_CHARS) return line.slice(0, end);
+    scalars++;
+    end += scalar.length;
+  }
+  return line;
+};
+const MAX_READ_FILE_BYTES = 64 * 1024 * 1024;
+const fileError = (path) => FsFailure.reading(path, `File not found: ${path}`);
+const sharedPrefix = (left, right) => {
+  let index = 0;
+  while (index < left.length && index < right.length && left[index] === right[index]) index++;
+  return index;
+};
+const nearest = (fileSystem, path) => Effect.gen(function* () {
+  const segments = path.split("/").filter((segment) => segment !== "" && segment !== ".");
+  if (path.startsWith("/") || segments.includes("..")) return "";
+  for (let depth = segments.length - 1; depth >= 0; depth--) {
+    const directory = segments.slice(0, depth).join("/");
+    const entries = yield* fileSystem.readDirectory(directory === "" ? "." : directory).pipe(Effect.option);
+    if (Option.isNone(entries)) continue;
+    const missing = segments[depth].toLowerCase();
+    const ranked = entries.value.filter((entry) => !entry.startsWith(".")).map((entry) => ({ entry, score: sharedPrefix(entry.toLowerCase(), missing) })).sort((left, right) => right.score - left.score).map(({ entry }) => entry);
+    if (ranked.length === 0) return "";
+    const shown = ranked.slice(0, 12).join(", ");
+    const more = ranked.length > 12 ? ` and ${ranked.length - 12} more` : "";
+    return `. ${directory === "" ? "The working directory" : directory} holds: ${shown}${more}.`;
+  }
+  return "";
+});
+const missingFile = (fileSystem, path) => Effect.flatMap(nearest(fileSystem, path), (hint) => Effect.fail(
+  new StdError.StdError({
+    code: "not_found",
+    message: `File not found: ${path}${hint}`,
+    path
+  })
+));
+const run = Effect.fn("Read.run")(function* (input) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const info = yield* fileSystem.stat(input.path).pipe(
+    Effect.catchTag(
+      "PlatformError",
+      (error) => error.reason._tag === "NotFound" ? missingFile(fileSystem, input.path) : Effect.fail(fileError(input.path)(error))
+    )
+  );
+  if (info.type === "Directory") {
+    return yield* Effect.fail(
+      new StdError.StdError({
+        code: "is_directory",
+        message: `Cannot read a directory: ${input.path}`,
+        path: input.path
+      })
+    );
+  }
+  if (info.type !== "File") {
+    return yield* Effect.fail(
+      new StdError.StdError({
+        code: "not_found",
+        message: `File not found: ${input.path}`,
+        path: input.path
+      })
+    );
+  }
+  const size = Number(info.size);
+  if (size > MAX_READ_FILE_BYTES) {
+    return yield* Effect.fail(
+      new StdError.StdError({
+        code: "response_too_large",
+        message: `${input.path} is ${size} bytes, over the ${MAX_READ_FILE_BYTES}-byte read limit; search it with grep or print a line range with bash`,
+        path: input.path
+      })
+    );
+  }
+  const bytes = yield* fileSystem.readFile(input.path).pipe(Effect.mapError(fileError(input.path)));
+  if (bytes.includes(0)) {
+    return yield* Effect.fail(
+      new StdError.StdError({
+        code: "binary_file",
+        message: `Cannot read binary file: ${input.path}`,
+        path: input.path
+      })
+    );
+  }
+  const text = yield* Effect.try({
+    try: () => new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+    catch: () => new StdError.StdError({
+      code: "binary_file",
+      message: `File is not valid UTF-8: ${input.path}`,
+      path: input.path
+    })
+  });
+  const offset = input.offset ?? 1;
+  const page = (0, import_Text.slice)(text, { offset, limit: input.limit ?? import_Text.DEFAULT_READ_LIMIT });
+  if (offset > Math.max(page.totalLines, 1)) {
+    return yield* Effect.fail(
+      new StdError.StdError({
+        code: "offset_out_of_range",
+        message: `Line offset ${offset} is outside ${input.path}`,
+        path: input.path
+      })
+    );
+  }
+  const lines = page.lines.map(clipLine);
+  const longLinesTruncated = lines.some((line, index) => line !== page.lines[index]);
+  const rendered = (0, import_Text.truncateBytes)(lines.join("\n"), import_Text.MAX_OUTPUT_BYTES, { keep: "head" });
+  const whole = rendered.truncated ? rendered.text.slice(0, Math.max(0, rendered.text.lastIndexOf("\n"))) : rendered.text;
+  const shown = rendered.truncated ? whole.split("\n").length : lines.length;
+  const endLine = page.startLine + shown - 1;
+  const truncated = longLinesTruncated || rendered.truncated || page.endLine < page.totalLines;
+  const clipped = longLinesTruncated ? ` Lines longer than ${import_Text.MAX_LINE_CHARS} Unicode scalar values are clipped, so such a line is not an edit anchor.` : "";
+  yield* FileMutation.recordRead(fileSystem, input.path, bytes);
+  return {
+    content: whole,
+    startLine: page.startLine,
+    endLine,
+    totalLines: page.totalLines,
+    truncated,
+    ...truncated ? { notice: `${(0, import_Text.notice)("lines", shown, page.totalLines)}${clipped}` } : {}
+  };
+});
+//# sourceMappingURL=Read.js.map

package/dist/cjs/Read.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Read.ts"],
+  "sourcesContent": ["/**\n * Read flow declaration and portable handler.\n *\n * `content` is raw file text. It used to be rendered as `NNN\\t<line>`, and that\n * rendering was the single most expensive tool defect measured on the 45-instance\n * SWE-bench trace program: an anchor copied out of a read carried the gutter, so\n * every `edit` built from a read missed, and every cell that wanted a literal\n * line had to strip the prefix in JavaScript first. Two instances (django-13346,\n * django-14351) spent whole frames writing string surgery against text the file\n * does not contain. Line numbers are facts about the page, so they are page\n * fields \u2014 `startLine` and `endLine` \u2014 and never bytes inside the text.\n *\n * Every line in `content` is a whole line: a page cut short by the byte budget\n * drops its trailing partial line rather than handing back a fragment that looks\n * like an anchor and is not one. CRLF lines retain their trailing CR; only\n * the page's final LF is omitted.\n *\n * @since 1.0.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as FileSystem from \"effect/FileSystem\"\nimport * as Option from \"effect/Option\"\nimport * as Schema from \"effect/Schema\"\nimport { capability, envelope } from \"./internal/Declaration.ts\"\nimport * as FileMutation from \"./internal/FileMutation.ts\"\nimport * as FsFailure from \"./internal/FsFailure.ts\"\nimport { DEFAULT_READ_LIMIT, MAX_LINE_CHARS, MAX_OUTPUT_BYTES, notice, slice, truncateBytes } from \"./internal/Text.ts\"\nimport * as StdError from \"./StdError.ts\"\n\nexport { Preconditions, ReadSession, type VersionedFileSystem } from \"./internal/FileMutation.ts\"\n\n/**\n * Registry name for the read flow.\n *\n * @category identifiers\n * @since 1.0.0\n */\nexport const name = \"read\"\n\n/**\n * Model-facing description of the read flow.\n *\n * @category descriptions\n * @since 1.0.0\n */\nexport const description =\n  \"Read a text file by 1-based offset and limit. content is RAW file text with no line-number prefixes, so any line of it is an edit anchor as it stands; the numbers are startLine/endLine.\"\n\n/**\n * Input schema for the read flow.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Input = Schema.Struct({\n  path: Schema.String.annotate({ description: \"Path of the text file to read\" }),\n  offset: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))).annotate({\n    description: \"1-based line offset\"\n  }),\n  limit: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))).annotate({\n    description: \"Maximum number of lines to return\"\n  })\n})\n\n/**\n * Decoded input accepted by the `read` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Input = typeof Input.Type\n\n/**\n * Output schema for the read flow.\n *\n * @category schemas\n * @since 1.0.0\n */\nexport const Output = Schema.Struct({\n  content: Schema.String.annotate({\n    description: \"Raw page text, preserving CR bytes and omitting the final LF; never line-number prefixed\"\n  }),\n  startLine: Schema.Number.annotate({ description: \"First returned 1-based line number\" }),\n  endLine: Schema.Number.annotate({\n    description: \"Last returned 1-based line number, or startLine - 1 when no lines are returned\"\n  }),\n  totalLines: Schema.Number.annotate({ description: \"Total number of source lines\" }),\n  truncated: Schema.Boolean.annotate({ description: \"Whether displayed output was truncated\" }),\n  notice: Schema.optional(Schema.String.annotate({ description: \"Truncation disclosure\" }))\n})\n\n/**\n * Decoded output returned by the `read` flow.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Output = typeof Output.Type\n\n/**\n * Static conservative effect envelope for the read flow.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effects = envelope({\n  tier: \"sealed\",\n  mode: \"hermetic\",\n  reads: [\"/**\"],\n  writes: []\n})\n\n/**\n * Narrows the read effect envelope to one input path.\n *\n * @category effects\n * @since 1.0.0\n */\nexport const effectsFor = (input: typeof Input.Type) =>\n  envelope({\n    tier: \"sealed\",\n    mode: \"hermetic\",\n    reads: [input.path],\n    writes: []\n  })\n\n/**\n * Capabilities required by the read flow.\n *\n * @category capabilities\n * @since 1.0.0\n */\nexport const capabilities = [capability(\"fs:read\", \"/**\")]\n\n/**\n * Declaration-only read flow.\n *\n * @category flows\n * @since 1.0.0\n */\nexport const flow = { name, description, input: Input, output: Output, capabilities, effects } as const\n\n/**\n * What a call to this flow does, for a reader of a run.\n *\n * Display metadata only. `@smthrs/registry` `Descriptor.FlowActivity` is the\n * governing vocabulary and `StandardFlows` binds this value onto the flow's\n * descriptor, where the binding site checks it. `declarationDigest` excludes\n * it, so declaring it cannot invalidate a call identity or a cached prompt.\n *\n * @category presentation\n * @since 1.0.0-rc.0\n */\nexport const activity = \"reads\" as const\n\n/**\n * How one recorded call to this flow reads: the verb for each settlement, the\n * input field that is its subject, and the measured output fields a one-line\n * summary may count.\n *\n * Display metadata only, governed by `@smthrs/registry`\n * `Descriptor.CallPresentation` and checked where `StandardFlows` binds it.\n *\n * @category presentation\n * @since 1.0.0-rc.0\n */\nexport const presentation = {\n  verb: { pending: \"reading\", success: \"read\", failure: \"failed to read\" },\n  subject: \"path\",\n  result: \"read\"\n} as const\n\nconst clipLine = (line: string): string => {\n  let scalars = 0\n  let end = 0\n  for (const scalar of line) {\n    if (scalars === MAX_LINE_CHARS) return line.slice(0, end)\n    scalars++\n    end += scalar.length\n  }\n  return line\n}\n\n/**\n * The largest file `read` loads.\n *\n * `read` decodes the whole file to count its lines, so the file is held in\n * memory twice over: its bytes and a UTF-16 string. Past this bound a page\n * read would cost the host gigabytes for a window of a few thousand lines,\n * and past 2 GiB Node cannot load the file at all.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const MAX_READ_FILE_BYTES = 64 * 1024 * 1024\n\nconst fileError = (path: string) => FsFailure.reading(path, `File not found: ${path}`)\n\nconst sharedPrefix = (left: string, right: string): number => {\n  let index = 0\n  while (index < left.length && index < right.length && left[index] === right[index]) index++\n  return index\n}\n\n/**\n * Where a guessed relative path stops existing, and what is there instead.\n *\n * A worker that guesses `packages/smithers/flow/src/Flow.ts` learns nothing\n * from \"not found\" and guesses again. Naming the nearest directory that exists\n * and its entries, closest name first, turns the next call into a choice.\n * Absolute paths and paths that climb out with `..` get no listing: the call\n * declared one file, and the working tree is the only place a listing is\n * already the caller's to read.\n */\nconst nearest = (\n  fileSystem: FileSystem.FileSystem,\n  path: string\n): Effect.Effect<string> =>\n  Effect.gen(function*() {\n    const segments = path.split(\"/\").filter((segment) => segment !== \"\" && segment !== \".\")\n    if (path.startsWith(\"/\") || segments.includes(\"..\")) return \"\"\n    for (let depth = segments.length - 1; depth >= 0; depth--) {\n      const directory = segments.slice(0, depth).join(\"/\")\n      const entries = yield* fileSystem.readDirectory(directory === \"\" ? \".\" : directory).pipe(Effect.option)\n      if (Option.isNone(entries)) continue\n      const missing = segments[depth]!.toLowerCase()\n      const ranked = entries.value\n        .filter((entry) => !entry.startsWith(\".\"))\n        .map((entry) => ({ entry, score: sharedPrefix(entry.toLowerCase(), missing) }))\n        .sort((left, right) => right.score - left.score)\n        .map(({ entry }) => entry)\n      if (ranked.length === 0) return \"\"\n      const shown = ranked.slice(0, 12).join(\", \")\n      const more = ranked.length > 12 ? ` and ${ranked.length - 12} more` : \"\"\n      return `. ${directory === \"\" ? \"The working directory\" : directory} holds: ${shown}${more}.`\n    }\n    return \"\"\n  })\n\nconst missingFile = (fileSystem: FileSystem.FileSystem, path: string) =>\n  Effect.flatMap(nearest(fileSystem, path), (hint) =>\n    Effect.fail(\n      new StdError.StdError({\n        code: \"not_found\",\n        message: `File not found: ${path}${hint}`,\n        path\n      })\n    ))\n\n/**\n * Reads, validates, and renders one page of a UTF-8 text file.\n *\n * The kernel filesystem exposes bytes rather than a guaranteed UTF-8 string,\n * so decoding is deliberately fatal to keep binary input in the typed channel.\n *\n * @category handlers\n * @since 1.0.0\n */\nexport const run = Effect.fn(\"Read.run\")(function*(\n  input: typeof Input.Type\n): Effect.fn.Return<typeof Output.Type, StdError.StdError, FileSystem.FileSystem> {\n  const fileSystem = yield* FileSystem.FileSystem\n  const info = yield* fileSystem.stat(input.path).pipe(\n    Effect.catchTag(\n      \"PlatformError\",\n      (error) =>\n        error.reason._tag === \"NotFound\"\n          ? missingFile(fileSystem, input.path)\n          : Effect.fail(fileError(input.path)(error))\n    )\n  )\n  if (info.type === \"Directory\") {\n    return yield* Effect.fail(\n      new StdError.StdError({\n        code: \"is_directory\",\n        message: `Cannot read a directory: ${input.path}`,\n        path: input.path\n      })\n    )\n  }\n  if (info.type !== \"File\") {\n    return yield* Effect.fail(\n      new StdError.StdError({\n        code: \"not_found\",\n        message: `File not found: ${input.path}`,\n        path: input.path\n      })\n    )\n  }\n  const size = Number(info.size)\n  if (size > MAX_READ_FILE_BYTES) {\n    return yield* Effect.fail(\n      new StdError.StdError({\n        code: \"response_too_large\",\n        message:\n          `${input.path} is ${size} bytes, over the ${MAX_READ_FILE_BYTES}-byte read limit; search it with grep or print a line range with bash`,\n        path: input.path\n      })\n    )\n  }\n  const bytes = yield* fileSystem.readFile(input.path).pipe(Effect.mapError(fileError(input.path)))\n  if (bytes.includes(0)) {\n    return yield* Effect.fail(\n      new StdError.StdError({\n        code: \"binary_file\",\n        message: `Cannot read binary file: ${input.path}`,\n        path: input.path\n      })\n    )\n  }\n  const text = yield* Effect.try({\n    try: () => new TextDecoder(\"utf-8\", { fatal: true }).decode(bytes),\n    catch: () =>\n      new StdError.StdError({\n        code: \"binary_file\",\n        message: `File is not valid UTF-8: ${input.path}`,\n        path: input.path\n      })\n  })\n  const offset = input.offset ?? 1\n  const page = slice(text, { offset, limit: input.limit ?? DEFAULT_READ_LIMIT })\n  // An empty file has no lines, and reading one is not an out-of-range read:\n  // the caller asked for the first page and there is nothing on it. Only an\n  // offset past the first line of a file that has none is out of range.\n  if (offset > Math.max(page.totalLines, 1)) {\n    return yield* Effect.fail(\n      new StdError.StdError({\n        code: \"offset_out_of_range\",\n        message: `Line offset ${offset} is outside ${input.path}`,\n        path: input.path\n      })\n    )\n  }\n  const lines = page.lines.map(clipLine)\n  const longLinesTruncated = lines.some((line, index) => line !== page.lines[index])\n  const rendered = truncateBytes(lines.join(\"\\n\"), MAX_OUTPUT_BYTES, { keep: \"head\" })\n  // A byte budget cuts mid-line. A partial line reads like an anchor and is not\n  // one, so the page ends at the last whole line it could afford.\n  const whole = rendered.truncated\n    ? rendered.text.slice(0, Math.max(0, rendered.text.lastIndexOf(\"\\n\")))\n    : rendered.text\n  // Each clipped line fits the byte budget, so a truncated page retains at least one whole line.\n  const shown = rendered.truncated ? whole.split(\"\\n\").length : lines.length\n  const endLine = page.startLine + shown - 1\n  const truncated = longLinesTruncated || rendered.truncated || page.endLine < page.totalLines\n  const clipped = longLinesTruncated\n    ? ` Lines longer than ${MAX_LINE_CHARS} Unicode scalar values are clipped, so such a line is not an edit anchor.`\n    : \"\"\n  yield* FileMutation.recordRead(fileSystem, input.path, bytes)\n  return {\n    content: whole,\n    startLine: page.startLine,\n    endLine,\n    totalLines: page.totalLines,\n    truncated,\n    ...(truncated ? { notice: `${notice(\"lines\", shown, page.totalLines)}${clipped}` } : {})\n  }\n})\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/Relocate.d.ts

@@ -0,0 +1,73 @@
+/**
+ * What can be pointed at a checkpoint, and what cannot.
+ *
+ * {@link relocate} is the closed answer, and it is the half of the checkpoint
+ * feature that tracks the flows rather than git: it knows that `bash` carries
+ * its working directory in `cwd` and that `read`, `ls`, `grep` and `glob` carry
+ * their subject in `path`, `path`, `root` and `root`. `Checkpoints` changes when
+ * git does; this changes when one of those five input shapes does, which is why
+ * it is a module of its own. `Relocate.test.ts` decodes every rewritten input
+ * with the flow's own `Input` schema, so a renamed field fails there rather than
+ * silently relocating nothing.
+ *
+ * `bash` names *where it runs*, so it is relocated by its `cwd` — into the
+ * checkpoint, and into the same subdirectory of it the call asked for, because a
+ * check declared in `tests/` that silently ran at the top would come back
+ * failing for a reason nobody chose. `read`, `ls`, `grep` and `glob` name *what
+ * they touch* relative to the workspace root, so they are relocated by prefixing
+ * that root — and only when the path they name stays inside the tree, because an
+ * absolute path in these runs is a container path the host cannot rebase and a
+ * `..` path is the live tree under another name. Every other flow answers
+ * `checkpoint_unsupported` through the harness, including `test`, which already
+ * has `against: "base"` for exactly this question and would otherwise have two
+ * mechanisms that can disagree.
+ *
+ * @since 1.0.0
+ */
+import type { Schema } from "effect";
+import type { Materialized } from "./Checkpoints.ts";
+/**
+ * Why one input could not be pointed at a checkpoint.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Relocation = {
+    readonly _tag: "Relocated";
+    readonly input: Schema.Json;
+} | {
+    readonly _tag: "UnsupportedFlow";
+} | {
+    readonly _tag: "AbsolutePath";
+    readonly path: string;
+} | {
+    readonly _tag: "OutsideTree";
+    readonly path: string;
+};
+/**
+ * Rewrites one call's input so the call runs against a materialized checkpoint.
+ *
+ * Returns the rewritten input, or the reason there is none. A `bash` call runs
+ * in the checkpoint's directory — from the *guest* side when it names a
+ * container, because that is the path the container will be given — and keeps
+ * whatever subdirectory it asked for: a check declared in `tests/` runs in the
+ * checkpoint's `tests/`. A working directory the checkpoint holds no copy of,
+ * such as somewhere else on the machine, becomes the checkpoint's own top,
+ * because a tree is all this can offer and there is no subpath in it to keep.
+ *
+ * A reader takes the checkpoint's workspace-relative directory as the prefix of
+ * what it names, because these flows resolve their subject against the
+ * workspace root and the checkpoint is a directory under it.
+ *
+ * Two paths are refused rather than rewritten, and both for the same reason —
+ * the host would otherwise hand back a reading of a tree the cell did not name.
+ * An absolute path in these runs is a container path, and the host cannot know
+ * which prefix of it names the tree. A relative path that climbs past the
+ * checkpoint with `..` names the live tree, exactly the tree the reading was
+ * taken to avoid.
+ *
+ * @category conversions
+ * @since 1.0.0
+ */
+export declare const relocate: (flow: string, input: Schema.Json, materialized: Materialized) => Relocation;
+//# sourceMappingURL=Relocate.d.ts.map

package/dist/cjs/Relocate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Relocate.d.ts","sourceRoot":"","sources":["../../src/Relocate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AA0BpD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GACpC;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AA4C3D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,QAAQ,GACnB,MAAM,MAAM,EACZ,OAAO,MAAM,CAAC,IAAI,EAClB,cAAc,YAAY,KACzB,UA4BF,CAAA"}

package/dist/cjs/Relocate.js

@@ -0,0 +1,72 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Relocate_exports = {};
+__export(Relocate_exports, {
+  relocate: () => relocate
+});
+module.exports = __toCommonJS(Relocate_exports);
+var import_Paths = require("./internal/Paths.js");
+const located = {
+  bash: { field: "cwd", kind: "cwd" },
+  read: { field: "path", kind: "path" },
+  ls: { field: "path", kind: "path" },
+  grep: { field: "root", kind: "path" },
+  glob: { field: "root", kind: "path" }
+};
+const contained = (path) => {
+  const parts = [];
+  for (const segment of path.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment !== "..") {
+      parts.push(segment);
+      continue;
+    }
+    if (parts.length === 0) return void 0;
+    parts.pop();
+  }
+  return parts.join("/");
+};
+const within = (root, declared) => {
+  if (!declared.startsWith("/")) return contained(declared);
+  if ((0, import_Paths.withoutTrailingSlash)(declared) === root) return "";
+  return declared.startsWith(`${root}/`) ? contained(declared.slice(root.length + 1)) : void 0;
+};
+const relocate = (flow, input, materialized) => {
+  const rule = located[flow];
+  if (rule === void 0) return { _tag: "UnsupportedFlow" };
+  const record = input !== null && typeof input === "object" && !Array.isArray(input) ? input : {};
+  const declared = record[rule.field];
+  if (rule.kind === "cwd") {
+    const containerised = typeof record["container"] === "string" && record["container"] !== "";
+    const base = containerised ? materialized.guest : materialized.host;
+    const kept2 = typeof declared === "string" && declared !== "" ? within(containerised ? materialized.guestRoot : materialized.root, declared) : "";
+    return {
+      _tag: "Relocated",
+      input: { ...record, cwd: kept2 === void 0 || kept2 === "" ? base : `${base}/${kept2}` }
+    };
+  }
+  const relative = materialized.host.slice((0, import_Paths.withoutTrailingSlash)(materialized.root).length + 1);
+  if (declared === void 0) return { _tag: "Relocated", input: { ...record, [rule.field]: relative } };
+  if (typeof declared !== "string") return { _tag: "UnsupportedFlow" };
+  if (declared.startsWith("/")) return { _tag: "AbsolutePath", path: declared };
+  const kept = contained(declared);
+  if (kept === void 0) return { _tag: "OutsideTree", path: declared };
+  return { _tag: "Relocated", input: { ...record, [rule.field]: kept === "" ? relative : `${relative}/${kept}` } };
+};
+//# sourceMappingURL=Relocate.js.map

package/dist/cjs/Relocate.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Relocate.ts"],
+  "sourcesContent": ["/**\n * What can be pointed at a checkpoint, and what cannot.\n *\n * {@link relocate} is the closed answer, and it is the half of the checkpoint\n * feature that tracks the flows rather than git: it knows that `bash` carries\n * its working directory in `cwd` and that `read`, `ls`, `grep` and `glob` carry\n * their subject in `path`, `path`, `root` and `root`. `Checkpoints` changes when\n * git does; this changes when one of those five input shapes does, which is why\n * it is a module of its own. `Relocate.test.ts` decodes every rewritten input\n * with the flow's own `Input` schema, so a renamed field fails there rather than\n * silently relocating nothing.\n *\n * `bash` names *where it runs*, so it is relocated by its `cwd` \u2014 into the\n * checkpoint, and into the same subdirectory of it the call asked for, because a\n * check declared in `tests/` that silently ran at the top would come back\n * failing for a reason nobody chose. `read`, `ls`, `grep` and `glob` name *what\n * they touch* relative to the workspace root, so they are relocated by prefixing\n * that root \u2014 and only when the path they name stays inside the tree, because an\n * absolute path in these runs is a container path the host cannot rebase and a\n * `..` path is the live tree under another name. Every other flow answers\n * `checkpoint_unsupported` through the harness, including `test`, which already\n * has `against: \"base\"` for exactly this question and would otherwise have two\n * mechanisms that can disagree.\n *\n * @since 1.0.0\n */\n\nimport type { Schema } from \"effect\"\nimport type { Materialized } from \"./Checkpoints.ts\"\nimport { withoutTrailingSlash } from \"./internal/Paths.ts\"\n\n/**\n * The flows whose input names where they run or what they read, and the field\n * that says so.\n *\n * A closed table rather than a per-flow hook, because the set is small and the\n * rule for admitting one is exact: the field has to name a location the whole\n * call is relative to. `bash` runs in a directory; the four readers resolve\n * their subject against the workspace root. Everything else \u2014 an edit, a patch,\n * a web fetch, a memory write \u2014 either names no location or writes, and both\n * are refused above this module.\n *\n * `test` is deliberately absent. It answers this exact question already, with\n * `against: \"base\"`, and a second mechanism pointed at the same tree is a way\n * for two answers to disagree.\n */\nconst located: Readonly<Record<string, { readonly field: string; readonly kind: \"cwd\" | \"path\" }>> = {\n  bash: { field: \"cwd\", kind: \"cwd\" },\n  read: { field: \"path\", kind: \"path\" },\n  ls: { field: \"path\", kind: \"path\" },\n  grep: { field: \"root\", kind: \"path\" },\n  glob: { field: \"root\", kind: \"path\" }\n}\n\n/**\n * Why one input could not be pointed at a checkpoint.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Relocation =\n  | { readonly _tag: \"Relocated\"; readonly input: Schema.Json }\n  | { readonly _tag: \"UnsupportedFlow\" }\n  | { readonly _tag: \"AbsolutePath\"; readonly path: string }\n  | { readonly _tag: \"OutsideTree\"; readonly path: string }\n\n/**\n * Resolves `.` and `..` inside a relative path, or answers `undefined` when the\n * path climbs out of whatever it would be joined under.\n *\n * This is the whole of the isolation the reader rule can enforce, and it is not\n * optional. Prefixing blindly turns `../../mod.py` into\n * `.flows-checkpoints/cp-1-0/../../mod.py`, which is a path back into the live\n * tree \u2014 so the cell would read the work it is trying to take a baseline\n * against, the journal would record that reading under the checkpoint it named,\n * and the call key folds the checkpoint in, so the live reading would replay as\n * a pinned one forever. A proof built on it is a proof of nothing, which is the\n * exact failure this module exists to abolish.\n */\nconst contained = (path: string): string | undefined => {\n  const parts: Array<string> = []\n  for (const segment of path.split(\"/\")) {\n    if (segment === \"\" || segment === \".\") continue\n    if (segment !== \"..\") {\n      parts.push(segment)\n      continue\n    }\n    if (parts.length === 0) return undefined\n    parts.pop()\n  }\n  return parts.join(\"/\")\n}\n\n/**\n * The part of `declared` that names a place inside `root`, or `undefined` when\n * it names somewhere the checkpoint does not hold a copy of.\n *\n * A relative path is already workspace-relative. An absolute one is compared\n * against the root on the side that issued it \u2014 a container call names the\n * mount, a host call names this machine \u2014 because that is the only prefix the\n * store can strip without guessing.\n */\nconst within = (root: string, declared: string): string | undefined => {\n  if (!declared.startsWith(\"/\")) return contained(declared)\n  if (withoutTrailingSlash(declared) === root) return \"\"\n  return declared.startsWith(`${root}/`) ? contained(declared.slice(root.length + 1)) : undefined\n}\n\n/**\n * Rewrites one call's input so the call runs against a materialized checkpoint.\n *\n * Returns the rewritten input, or the reason there is none. A `bash` call runs\n * in the checkpoint's directory \u2014 from the *guest* side when it names a\n * container, because that is the path the container will be given \u2014 and keeps\n * whatever subdirectory it asked for: a check declared in `tests/` runs in the\n * checkpoint's `tests/`. A working directory the checkpoint holds no copy of,\n * such as somewhere else on the machine, becomes the checkpoint's own top,\n * because a tree is all this can offer and there is no subpath in it to keep.\n *\n * A reader takes the checkpoint's workspace-relative directory as the prefix of\n * what it names, because these flows resolve their subject against the\n * workspace root and the checkpoint is a directory under it.\n *\n * Two paths are refused rather than rewritten, and both for the same reason \u2014\n * the host would otherwise hand back a reading of a tree the cell did not name.\n * An absolute path in these runs is a container path, and the host cannot know\n * which prefix of it names the tree. A relative path that climbs past the\n * checkpoint with `..` names the live tree, exactly the tree the reading was\n * taken to avoid.\n *\n * @category conversions\n * @since 1.0.0\n */\nexport const relocate = (\n  flow: string,\n  input: Schema.Json,\n  materialized: Materialized\n): Relocation => {\n  const rule = located[flow]\n  if (rule === undefined) return { _tag: \"UnsupportedFlow\" }\n  const record = input !== null && typeof input === \"object\" && !Array.isArray(input)\n    ? input as Record<string, Schema.Json>\n    : {}\n  const declared = record[rule.field]\n  if (rule.kind === \"cwd\") {\n    // A container call is given the path the container will resolve; a host\n    // call is given the host's. `bash` chooses which by naming a container, so\n    // this reads the same field it does.\n    const containerised = typeof record[\"container\"] === \"string\" && record[\"container\"] !== \"\"\n    const base = containerised ? materialized.guest : materialized.host\n    const kept = typeof declared === \"string\" && declared !== \"\"\n      ? within(containerised ? materialized.guestRoot : materialized.root, declared)\n      : \"\"\n    return {\n      _tag: \"Relocated\",\n      input: { ...record, cwd: kept === undefined || kept === \"\" ? base : `${base}/${kept}` }\n    }\n  }\n  const relative = materialized.host.slice(withoutTrailingSlash(materialized.root).length + 1)\n  if (declared === undefined) return { _tag: \"Relocated\", input: { ...record, [rule.field]: relative } }\n  if (typeof declared !== \"string\") return { _tag: \"UnsupportedFlow\" }\n  if (declared.startsWith(\"/\")) return { _tag: \"AbsolutePath\", path: declared }\n  const kept = contained(declared)\n  if (kept === undefined) return { _tag: \"OutsideTree\", path: declared }\n  return { _tag: \"Relocated\", input: { ...record, [rule.field]: kept === \"\" ? relative : `${relative}/${kept}` } }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA6BA,mBAAqC;AAiBrC,MAAM,UAA+F;AAAA,EACnG,MAAM,EAAE,OAAO,OAAO,MAAM,MAAM;AAAA,EAClC,MAAM,EAAE,OAAO,QAAQ,MAAM,OAAO;AAAA,EACpC,IAAI,EAAE,OAAO,QAAQ,MAAM,OAAO;AAAA,EAClC,MAAM,EAAE,OAAO,QAAQ,MAAM,OAAO;AAAA,EACpC,MAAM,EAAE,OAAO,QAAQ,MAAM,OAAO;AACtC;AA2BA,MAAM,YAAY,CAAC,SAAqC;AACtD,QAAM,QAAuB,CAAC;AAC9B,aAAW,WAAW,KAAK,MAAM,GAAG,GAAG;AACrC,QAAI,YAAY,MAAM,YAAY,IAAK;AACvC,QAAI,YAAY,MAAM;AACpB,YAAM,KAAK,OAAO;AAClB;AAAA,IACF;AACA,QAAI,MAAM,WAAW,EAAG,QAAO;AAC/B,UAAM,IAAI;AAAA,EACZ;AACA,SAAO,MAAM,KAAK,GAAG;AACvB;AAWA,MAAM,SAAS,CAAC,MAAc,aAAyC;AACrE,MAAI,CAAC,SAAS,WAAW,GAAG,EAAG,QAAO,UAAU,QAAQ;AACxD,UAAI,mCAAqB,QAAQ,MAAM,KAAM,QAAO;AACpD,SAAO,SAAS,WAAW,GAAG,IAAI,GAAG,IAAI,UAAU,SAAS,MAAM,KAAK,SAAS,CAAC,CAAC,IAAI;AACxF;AA2BO,MAAM,WAAW,CACtB,MACA,OACA,iBACe;AACf,QAAM,OAAO,QAAQ,IAAI;AACzB,MAAI,SAAS,OAAW,QAAO,EAAE,MAAM,kBAAkB;AACzD,QAAM,SAAS,UAAU,QAAQ,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK,IAC9E,QACA,CAAC;AACL,QAAM,WAAW,OAAO,KAAK,KAAK;AAClC,MAAI,KAAK,SAAS,OAAO;AAIvB,UAAM,gBAAgB,OAAO,OAAO,WAAW,MAAM,YAAY,OAAO,WAAW,MAAM;AACzF,UAAM,OAAO,gBAAgB,aAAa,QAAQ,aAAa;AAC/D,UAAMA,QAAO,OAAO,aAAa,YAAY,aAAa,KACtD,OAAO,gBAAgB,aAAa,YAAY,aAAa,MAAM,QAAQ,IAC3E;AACJ,WAAO;AAAA,MACL,MAAM;AAAA,MACN,OAAO,EAAE,GAAG,QAAQ,KAAKA,UAAS,UAAaA,UAAS,KAAK,OAAO,GAAG,IAAI,IAAIA,KAAI,GAAG;AAAA,IACxF;AAAA,EACF;AACA,QAAM,WAAW,aAAa,KAAK,UAAM,mCAAqB,aAAa,IAAI,EAAE,SAAS,CAAC;AAC3F,MAAI,aAAa,OAAW,QAAO,EAAE,MAAM,aAAa,OAAO,EAAE,GAAG,QAAQ,CAAC,KAAK,KAAK,GAAG,SAAS,EAAE;AACrG,MAAI,OAAO,aAAa,SAAU,QAAO,EAAE,MAAM,kBAAkB;AACnE,MAAI,SAAS,WAAW,GAAG,EAAG,QAAO,EAAE,MAAM,gBAAgB,MAAM,SAAS;AAC5E,QAAM,OAAO,UAAU,QAAQ;AAC/B,MAAI,SAAS,OAAW,QAAO,EAAE,MAAM,eAAe,MAAM,SAAS;AACrE,SAAO,EAAE,MAAM,aAAa,OAAO,EAAE,GAAG,QAAQ,CAAC,KAAK,KAAK,GAAG,SAAS,KAAK,WAAW,GAAG,QAAQ,IAAI,IAAI,GAAG,EAAE;AACjH;",
+  "names": ["kept"]
+}

package/dist/cjs/RemoteSearch.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The search contract for a tree on another machine, in two round trips.
+ *
+ * `PortableSearch` asks `FileSystem` one question per directory, per entry
+ * and per file. On a machine reached through a transport, such as a
+ * benchmark's task container behind `docker exec`, every question is a
+ * process start, so one `grep` over a 6,000-file repository is some 20,000 of
+ * them. This peer asks the machine's own shell twice instead. `find` lists
+ * the tree under the root, leaving out the directories every walk skips, and
+ * `tar` returns its `.gitignore` files with the listing. The in-process peer
+ * then decides which files the search reads, a second `tar` returns exactly
+ * those, and `PortableSearch` answers over that copy. Every result, notice,
+ * and refusal is therefore the in-process peer's own: this module decides
+ * only where the bytes come from.
+ *
+ * It runs through the machine's own `ChildProcessSpawner`, the one
+ * `Sandbox.hostContext` serves beside the machine's `FileSystem`. The machine
+ * needs `sh`, `find`, `xargs`, `tar`, `head`, and `base64`; GNU, BusyBox, and
+ * BSD userlands all have them. Output crosses as base64, so a transport whose
+ * channel carries only text returns it intact. A search reads at most
+ * {@link maxBytes} of file content and refuses beyond that, naming the root
+ * to narrow.
+ *
+ * @since 1.0.0-rc.8
+ */
+import type * as ChildProcessSpawner from "@smthrs/kernel/ChildProcessSpawner";
+import * as Path from "@smthrs/kernel/Path";
+import { Context } from "effect";
+import * as Search from "./Search.ts";
+/**
+ * The most file content one search brings back from the machine.
+ *
+ * The copy is held in memory while the in-process peer reads it, so the
+ * bound is on this process's memory rather than on the search: a root that
+ * holds more is refused with `response_too_large` and a narrower root or
+ * globs answer it.
+ *
+ * @category constants
+ * @since 1.0.0-rc.8
+ */
+export declare const maxBytes: number;
+/**
+ * Builds the peer over a machine's spawner and its `Path`, which resolves a
+ * relative root where the machine's file operations do. `maxBytes` lowers
+ * the bound on the file content one search brings back; the default is
+ * {@link maxBytes}.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.8
+ */
+export declare const make: (services: Context.Context<ChildProcessSpawner.ChildProcessSpawner | Path.Path>, options?: {
+    readonly maxBytes?: number | undefined;
+}) => Search.Search;
+//# sourceMappingURL=RemoteSearch.d.ts.map

package/dist/cjs/RemoteSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RemoteSearch.d.ts","sourceRoot":"","sources":["../../src/RemoteSearch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,KAAK,mBAAmB,MAAM,oCAAoC,CAAA;AAC9E,OAAO,KAAK,IAAI,MAAM,qBAAqB,CAAA;AAC3C,OAAO,EAAE,OAAO,EAAU,MAAM,QAAQ,CAAA;AASxC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAGrC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,QAAoB,CAAA;AA+FzC;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,GACf,UAAU,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,mBAAmB,GAAG,IAAI,CAAC,IAAI,CAAC,EAC9E,UAAU;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,KACnD,MAAM,CAAC,MAwCT,CAAA"}

package/dist/cjs/RemoteSearch.js

@@ -0,0 +1,134 @@
+"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 RemoteSearch_exports = {};
+__export(RemoteSearch_exports, {
+  make: () => make,
+  maxBytes: () => maxBytes
+});
+module.exports = __toCommonJS(RemoteSearch_exports);
+var Path = __toESM(require("@smthrs/kernel/Path"), 1);
+var import_effect = require("effect");
+var Base64 = __toESM(require("effect/encoding/Base64"), 1);
+var FileSystem = __toESM(require("effect/FileSystem"), 1);
+var Result = __toESM(require("effect/Result"), 1);
+var Exec = __toESM(require("./internal/Exec.js"), 1);
+var Prune = __toESM(require("./internal/Prune.js"), 1);
+var RemoteTree = __toESM(require("./internal/RemoteTree.js"), 1);
+var Tar = __toESM(require("./internal/Tar.js"), 1);
+var PortableSearch = __toESM(require("./PortableSearch.js"), 1);
+var Search = __toESM(require("./Search.js"), 1);
+var StdError = __toESM(require("./StdError.js"), 1);
+const maxBytes = 256 * 1024 * 1024;
+const maxListingBytes = 64 * 1024 * 1024;
+const quoted = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
+const pruned = `\\( ${Prune.repositoryDirectories.map((name) => `-name ${quoted(name)}`).join(" -o ")} \\) -prune`;
+const missing = (tool) => `searching this machine needs ${tool}, which it does not have`;
+const requireTools = `for t in find xargs tar head; do command -v "$t" >/dev/null || { echo "${missing("$t")}" >&2; exit 3; }; done`;
+const listing = [
+  "set -f",
+  requireTools,
+  "r=$1",
+  "{",
+  `  if [ -d "$r" ]; then if [ -r "$r" ] && [ -x "$r" ]; then printf 'd%s\\0' "$r"; else printf 'u%s\\0' "$r"; fi`,
+  `  elif [ -f "$r" ]; then printf 'f%s\\0' "$r"`,
+  `  elif [ -e "$r" ]; then printf 'o%s\\0' "$r"`,
+  "  fi",
+  // No `-exec … {} +` inside parentheses: BusyBox `find` never runs one there.
+  `  find -H "$r" -mindepth 1 ${pruned} -o -type d -exec printf 'd%s\\0' {} + -o -type f -exec printf 'f%s\\0' {} + -o -type l -exec sh -c 'for p do if [ -d "$p" ]; then k=D; elif [ -f "$p" ]; then k=F; else k=L; fi; printf "%s%s\\0" "$k" "$p"; done' sh {} + -o -exec printf 'o%s\\0' {} + 2>/dev/null`,
+  "  printf 'E\\0'",
+  `  if [ "$3" = 1 ]; then find -H "$r" -mindepth 1 ${pruned} -o -type f -name .gitignore -print0 2>/dev/null | (cd / && COPYFILE_DISABLE=1 xargs -0 -r tar -cf - -- 2>/dev/null); fi`,
+  '} | head -c "$2" | base64'
+].join("\n");
+const fetching = [
+  requireTools,
+  'cd / && COPYFILE_DISABLE=1 xargs -0 -r tar -chf - -- 2>/dev/null | head -c "$1" | base64'
+].join("\n");
+const failed = (root, reason) => new StdError.StdError({
+  code: "command_failed",
+  message: `Could not search ${root} on this machine: ${reason}`,
+  path: root
+});
+const tooLarge = (root, bound) => new StdError.StdError({
+  code: "response_too_large",
+  message: `The files under ${root} come to more than ${bound} bytes; narrow the root or the globs`,
+  path: root
+});
+const bootstrap = `command -v base64 >/dev/null || { echo "${missing("base64")}" >&2; exit 3; }; IFS= read -r p && p=$(printf %s "$p" | base64 -d) && exec sh -c "$p" sh "$@"`;
+const run = (root, script, args, bound, stdin = "") => import_effect.Effect.gen(function* () {
+  const result = yield* Exec.exec("sh", {
+    args: ["-c", bootstrap, "sh", ...args],
+    stdin: `${Base64.encode(new TextEncoder().encode(script))}
+${stdin}`
+  }).pipe(import_effect.Effect.mapError((error) => failed(root, error.message)));
+  if (result.exitCode !== 0) {
+    return yield* import_effect.Effect.fail(failed(root, result.stderr.trim() || `exit ${result.exitCode}`));
+  }
+  const decoded = Base64.decode(result.stdout.replaceAll(/\s/g, ""));
+  if (Result.isFailure(decoded)) return yield* import_effect.Effect.fail(failed(root, "the machine answered with invalid base64"));
+  if (decoded.success.length >= bound) return yield* import_effect.Effect.fail(tooLarge(root, bound - 1));
+  return decoded.success;
+});
+const make = (services, options) => {
+  const path = import_effect.Context.get(services, Path.Path);
+  const contentBound = (options?.maxBytes ?? maxBytes) + 1;
+  const copy = (tree) => import_effect.Context.make(FileSystem.FileSystem, RemoteTree.fileSystem(tree, path)).pipe(import_effect.Context.add(Path.Path, path));
+  const listed = (root, noIgnore) => {
+    const resolved = path.resolve(root);
+    const bound = maxListingBytes + 1;
+    return import_effect.Effect.flatMap(
+      run(root, listing, [resolved, String(bound), noIgnore === true ? "0" : "1"], bound),
+      (bytes) => {
+        const tree = RemoteTree.parse(bytes, resolved, path);
+        return tree === void 0 ? import_effect.Effect.fail(failed(root, "the listing came back malformed")) : import_effect.Effect.succeed(tree);
+      }
+    );
+  };
+  return Search.make({
+    grep: (input) => import_effect.Effect.gen(function* () {
+      const tree = yield* listed(input.root, input.noIgnore);
+      const read = yield* PortableSearch.searched(input).pipe(import_effect.Effect.provide(copy(tree)));
+      const files = [...new Set(read.map((file) => path.resolve(file)))];
+      const bytes = files.length === 0 ? new Uint8Array() : yield* run(
+        input.root,
+        fetching,
+        [String(contentBound)],
+        contentBound,
+        files.map((file) => `${file}\0`).join("")
+      );
+      const members = files.length === 0 || bytes.length > 0 ? Tar.files(bytes) : void 0;
+      if (members === void 0) return yield* import_effect.Effect.fail(failed(input.root, "the files came back malformed"));
+      const contents = new Map([...tree.contents, ...RemoteTree.absolute(members)]);
+      return yield* PortableSearch.make(copy({ ...tree, contents })).grep(input);
+    }).pipe(import_effect.Effect.provide(services)),
+    glob: (input) => import_effect.Effect.flatMap(listed(input.root, input.noIgnore), (tree) => PortableSearch.make(copy(tree)).glob(input)).pipe(
+      import_effect.Effect.provide(services)
+    )
+  });
+};
+//# sourceMappingURL=RemoteSearch.js.map