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

package/dist/esm/Read.js

@@ -0,0 +1,300 @@
+/**
+ * Read flow declaration and portable handler.
+ *
+ * `content` is raw file text. It used to be rendered as `NNN\t<line>`, and that
+ * rendering was the single most expensive tool defect measured on the 45-instance
+ * SWE-bench trace program: an anchor copied out of a read carried the gutter, so
+ * every `edit` built from a read missed, and every cell that wanted a literal
+ * line had to strip the prefix in JavaScript first. Two instances (django-13346,
+ * django-14351) spent whole frames writing string surgery against text the file
+ * does not contain. Line numbers are facts about the page, so they are page
+ * fields — `startLine` and `endLine` — and never bytes inside the text.
+ *
+ * Every line in `content` is a whole line: a page cut short by the byte budget
+ * drops its trailing partial line rather than handing back a fragment that looks
+ * like an anchor and is not one. CRLF lines retain their trailing CR; only
+ * the page's final LF is omitted.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { capability, envelope } from "./internal/Declaration.js";
+import * as FileMutation from "./internal/FileMutation.js";
+import * as FsFailure from "./internal/FsFailure.js";
+import { DEFAULT_READ_LIMIT, MAX_LINE_CHARS, MAX_OUTPUT_BYTES, notice, slice, truncateBytes } from "./internal/Text.js";
+import * as StdError from "./StdError.js";
+export { Preconditions, ReadSession } from "./internal/FileMutation.js";
+/**
+ * Registry name for the read flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const name = "read";
+/**
+ * Model-facing description of the read flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export 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.";
+/**
+ * Input schema for the read flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export 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"
+    })
+});
+/**
+ * Output schema for the read flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export 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" }))
+});
+/**
+ * Static conservative effect envelope for the read flow.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effects = envelope({
+    tier: "sealed",
+    mode: "hermetic",
+    reads: ["/**"],
+    writes: []
+});
+/**
+ * Narrows the read effect envelope to one input path.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (input) => envelope({
+    tier: "sealed",
+    mode: "hermetic",
+    reads: [input.path],
+    writes: []
+});
+/**
+ * Capabilities required by the read flow.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities = [capability("fs:read", "/**")];
+/**
+ * Declaration-only read flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export const flow = { name, description, input: Input, output: Output, capabilities, effects };
+/**
+ * What a call to this flow does, for a reader of a run.
+ *
+ * Display metadata only. `@smthrs/registry` `Descriptor.FlowActivity` is the
+ * governing vocabulary and `StandardFlows` binds this value onto the flow's
+ * descriptor, where the binding site checks it. `declarationDigest` excludes
+ * it, so declaring it cannot invalidate a call identity or a cached prompt.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export const activity = "reads";
+/**
+ * How one recorded call to this flow reads: the verb for each settlement, the
+ * input field that is its subject, and the measured output fields a one-line
+ * summary may count.
+ *
+ * Display metadata only, governed by `@smthrs/registry`
+ * `Descriptor.CallPresentation` and checked where `StandardFlows` binds it.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export 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 === MAX_LINE_CHARS)
+            return line.slice(0, end);
+        scalars++;
+        end += scalar.length;
+    }
+    return line;
+};
+/**
+ * The largest file `read` loads.
+ *
+ * `read` decodes the whole file to count its lines, so the file is held in
+ * memory twice over: its bytes and a UTF-16 string. Past this bound a page
+ * read would cost the host gigabytes for a window of a few thousand lines,
+ * and past 2 GiB Node cannot load the file at all.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export 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;
+};
+/**
+ * Where a guessed relative path stops existing, and what is there instead.
+ *
+ * A worker that guesses `packages/smithers/flow/src/Flow.ts` learns nothing
+ * from "not found" and guesses again. Naming the nearest directory that exists
+ * and its entries, closest name first, turns the next call into a choice.
+ * Absolute paths and paths that climb out with `..` get no listing: the call
+ * declared one file, and the working tree is the only place a listing is
+ * already the caller's to read.
+ */
+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
+})));
+/**
+ * Reads, validates, and renders one page of a UTF-8 text file.
+ *
+ * The kernel filesystem exposes bytes rather than a guaranteed UTF-8 string,
+ * so decoding is deliberately fatal to keep binary input in the typed channel.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export 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 = slice(text, { offset, limit: input.limit ?? DEFAULT_READ_LIMIT });
+    // An empty file has no lines, and reading one is not an out-of-range read:
+    // the caller asked for the first page and there is nothing on it. Only an
+    // offset past the first line of a file that has none is out of range.
+    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 = truncateBytes(lines.join("\n"), MAX_OUTPUT_BYTES, { keep: "head" });
+    // A byte budget cuts mid-line. A partial line reads like an anchor and is not
+    // one, so the page ends at the last whole line it could afford.
+    const whole = rendered.truncated
+        ? rendered.text.slice(0, Math.max(0, rendered.text.lastIndexOf("\n")))
+        : rendered.text;
+    // Each clipped line fits the byte budget, so a truncated page retains at least one whole line.
+    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 ${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: `${notice("lines", shown, page.totalLines)}${clipped}` } : {})
+    };
+});
+//# sourceMappingURL=Read.js.map

package/dist/esm/Read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Read.js","sourceRoot":"","sources":["../../src/Read.ts"],"names":[],"mappings":"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","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 — `startLine` and `endLine` — 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"]}

package/dist/esm/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/esm/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/esm/Relocate.js

@@ -0,0 +1,153 @@
+/**
+ * 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 { withoutTrailingSlash } from "./internal/Paths.js";
+/**
+ * The flows whose input names where they run or what they read, and the field
+ * that says so.
+ *
+ * A closed table rather than a per-flow hook, because the set is small and the
+ * rule for admitting one is exact: the field has to name a location the whole
+ * call is relative to. `bash` runs in a directory; the four readers resolve
+ * their subject against the workspace root. Everything else — an edit, a patch,
+ * a web fetch, a memory write — either names no location or writes, and both
+ * are refused above this module.
+ *
+ * `test` is deliberately absent. It answers this exact question already, with
+ * `against: "base"`, and a second mechanism pointed at the same tree is a way
+ * for two answers to disagree.
+ */
+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" }
+};
+/**
+ * Resolves `.` and `..` inside a relative path, or answers `undefined` when the
+ * path climbs out of whatever it would be joined under.
+ *
+ * This is the whole of the isolation the reader rule can enforce, and it is not
+ * optional. Prefixing blindly turns `../../mod.py` into
+ * `.flows-checkpoints/cp-1-0/../../mod.py`, which is a path back into the live
+ * tree — so the cell would read the work it is trying to take a baseline
+ * against, the journal would record that reading under the checkpoint it named,
+ * and the call key folds the checkpoint in, so the live reading would replay as
+ * a pinned one forever. A proof built on it is a proof of nothing, which is the
+ * exact failure this module exists to abolish.
+ */
+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 undefined;
+        parts.pop();
+    }
+    return parts.join("/");
+};
+/**
+ * The part of `declared` that names a place inside `root`, or `undefined` when
+ * it names somewhere the checkpoint does not hold a copy of.
+ *
+ * A relative path is already workspace-relative. An absolute one is compared
+ * against the root on the side that issued it — a container call names the
+ * mount, a host call names this machine — because that is the only prefix the
+ * store can strip without guessing.
+ */
+const within = (root, declared) => {
+    if (!declared.startsWith("/"))
+        return contained(declared);
+    if (withoutTrailingSlash(declared) === root)
+        return "";
+    return declared.startsWith(`${root}/`) ? contained(declared.slice(root.length + 1)) : undefined;
+};
+/**
+ * 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 const relocate = (flow, input, materialized) => {
+    const rule = located[flow];
+    if (rule === undefined)
+        return { _tag: "UnsupportedFlow" };
+    const record = input !== null && typeof input === "object" && !Array.isArray(input)
+        ? input
+        : {};
+    const declared = record[rule.field];
+    if (rule.kind === "cwd") {
+        // A container call is given the path the container will resolve; a host
+        // call is given the host's. `bash` chooses which by naming a container, so
+        // this reads the same field it does.
+        const containerised = typeof record["container"] === "string" && record["container"] !== "";
+        const base = containerised ? materialized.guest : materialized.host;
+        const kept = typeof declared === "string" && declared !== ""
+            ? within(containerised ? materialized.guestRoot : materialized.root, declared)
+            : "";
+        return {
+            _tag: "Relocated",
+            input: { ...record, cwd: kept === undefined || kept === "" ? base : `${base}/${kept}` }
+        };
+    }
+    const relative = materialized.host.slice(withoutTrailingSlash(materialized.root).length + 1);
+    if (declared === undefined)
+        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 === undefined)
+        return { _tag: "OutsideTree", path: declared };
+    return { _tag: "Relocated", input: { ...record, [rule.field]: kept === "" ? relative : `${relative}/${kept}` } };
+};
+//# sourceMappingURL=Relocate.js.map

package/dist/esm/Relocate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Relocate.js","sourceRoot":"","sources":["../../src/Relocate.ts"],"names":[],"mappings":"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","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` — 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 — 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 — an edit, a patch,\n * a web fetch, a memory write — 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 — 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 — a container call names the\n * mount, a host call names this machine — 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 — from the *guest* side when it names a\n * container, because that is the path the container will be given — 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 —\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"]}