@better-fs-tools/read 0.0.0-stage → 0.1.0

package/dist/signature/offset-limit.js

@@ -0,0 +1,59 @@
+import { DEFAULT_NAME, lineSchema, objectSchema, pathSchema, readLine, readObject, readPath, resolveNames, } from "./schema.js";
+const PARAMS = ["path", "offset", "limit"];
+export function defaultReadSignature(options = {}) {
+    if (options === null || typeof options !== "object") {
+        throw new TypeError("defaultReadSignature options must be an object");
+    }
+    const name = resolveNames(PARAMS, options.names);
+    const keys = PARAMS.map((param) => name[param]);
+    const describe = options.describe ?? {};
+    const schema = objectSchema([
+        [
+            name.path,
+            pathSchema(describe.path ??
+                "Path to read, relative to the working directory or absolute within an allowed root."),
+        ],
+        [
+            name.offset,
+            lineSchema(describe.offset ?? "One-based source line to start reading at. Defaults to 1."),
+        ],
+        [
+            name.limit,
+            lineSchema(describe.limit ??
+                "Maximum number of source lines to return, before the configured limits apply."),
+        ],
+    ], name.path);
+    return Object.freeze({
+        name: options.name ?? DEFAULT_NAME,
+        description: options.description ??
+            `Read a UTF-8 text file. \`${name.offset}\` is a one-based source line and ` +
+                `\`${name.limit}\` is a number of source lines. Output is bounded by line, byte, and ` +
+                "line-length limits. When the result reports truncation, follow the continuation it " +
+                `returns instead of guessing the next \`${name.offset}\`. Paths outside the allowed ` +
+                "roots, binary content, and special files are refused.",
+        schema,
+        toInput(input) {
+            const record = readObject(input, keys);
+            const path = readPath(record[name.path], name.path);
+            const offset = readLine(record[name.offset], name.offset);
+            const limit = readLine(record[name.limit], name.limit);
+            return canonical(path, offset, limit);
+        },
+        param: (canonical) => name[canonical],
+        fromInput(retry) {
+            const model = { [name.path]: retry.path };
+            if (retry.offset !== undefined)
+                model[name.offset] = retry.offset;
+            if (retry.limit !== undefined)
+                model[name.limit] = retry.limit;
+            return model;
+        },
+    });
+}
+export function canonical(path, offset, limit) {
+    return {
+        path,
+        ...(offset === undefined ? {} : { offset }),
+        ...(limit === undefined ? {} : { limit }),
+    };
+}

package/dist/signature/schema.d.ts

@@ -0,0 +1,10 @@
+import type { JsonObject } from "../contract/json.ts";
+export declare const PATH_PATTERN = "^[^\\u0000]*[^\\s\\u0000][^\\u0000]*$";
+export declare const DEFAULT_NAME = "read";
+export declare function pathSchema(description: string): JsonObject;
+export declare function lineSchema(description: string): JsonObject;
+export declare function objectSchema(properties: readonly (readonly [string, JsonObject])[], requiredKey: string): JsonObject;
+export declare function readObject(input: unknown, keys: readonly string[]): Record<string, unknown>;
+export declare function readPath(value: unknown, name: string): string;
+export declare function readLine(value: unknown, name: string): number | undefined;
+export declare function resolveNames<TParam extends string>(params: readonly TParam[], names?: Partial<Record<TParam, string>>): Readonly<Record<TParam, string>>;

package/dist/signature/schema.js

@@ -0,0 +1,80 @@
+// No lookaround: strict grammar engines may refuse one.
+export const PATH_PATTERN = "^[^\\u0000]*[^\\s\\u0000][^\\u0000]*$";
+const PATH_REGEX = new RegExp(PATH_PATTERN, "u");
+export const DEFAULT_NAME = "read";
+export function pathSchema(description) {
+    return { type: "string", minLength: 1, pattern: PATH_PATTERN, description };
+}
+export function lineSchema(description) {
+    return { type: "integer", minimum: 1, maximum: Number.MAX_SAFE_INTEGER, description };
+}
+export function objectSchema(properties, requiredKey) {
+    return deepFreeze({
+        type: "object",
+        additionalProperties: false,
+        properties: Object.fromEntries(properties),
+        required: [requiredKey],
+    });
+}
+export function readObject(input, keys) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new TypeError(`Read input must be an object with ${list(keys)}`);
+    }
+    const record = input;
+    for (const key of Object.keys(record)) {
+        if (!keys.includes(key)) {
+            throw new TypeError(`Unknown read input key: ${key}. Expected ${list(keys)}`);
+        }
+    }
+    return record;
+}
+export function readPath(value, name) {
+    if (value === undefined)
+        throw new TypeError(`${name} is required`);
+    if (typeof value !== "string" || !PATH_REGEX.test(value)) {
+        throw new TypeError(`${name} must be a non-blank string without NUL`);
+    }
+    return value;
+}
+export function readLine(value, name) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError(`${name} must be a positive integer`);
+    }
+    return value;
+}
+export function resolveNames(params, names = {}) {
+    if (names === null || typeof names !== "object" || Array.isArray(names)) {
+        throw new TypeError("names must be an object");
+    }
+    const resolved = {};
+    const seen = new Set();
+    for (const key of Object.keys(names)) {
+        if (!params.includes(key)) {
+            throw new TypeError(`Unknown parameter in names: ${key}. Expected ${list(params)}`);
+        }
+    }
+    for (const param of params) {
+        const name = names[param] ?? param;
+        if (typeof name !== "string" || name.trim().length === 0) {
+            throw new TypeError(`names.${param} must be a non-blank string`);
+        }
+        if (seen.has(name))
+            throw new TypeError(`Parameter name ${name} is used twice`);
+        seen.add(name);
+        resolved[param] = name;
+    }
+    return Object.freeze(resolved);
+}
+function list(keys) {
+    return keys.join(", ");
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/state/index.d.ts

@@ -0,0 +1,15 @@
+import type { Clock } from "../contract/digest.ts";
+import type { ReadStateStore } from "../contract/state.ts";
+export interface MemoryStoreOptions {
+    /** Default 1_000. */
+    readonly maxEntries?: number;
+    /** Default 30 minutes. */
+    readonly ttlMs?: number;
+    /** The same clock type as the tools' `clock` dependency. Default the time now. */
+    readonly clock?: Clock;
+}
+/**
+ * A process-local store with an entry cap and a TTL. Use one store per
+ * session, or namespace the keys of a shared store.
+ */
+export declare function memoryStore(options?: MemoryStoreOptions): ReadStateStore;

package/dist/state/index.js

@@ -0,0 +1,77 @@
+const DEFAULT_MAX_ENTRIES = 1_000;
+const DEFAULT_TTL_MS = 30 * 60 * 1_000;
+/**
+ * A process-local store with an entry cap and a TTL. Use one store per
+ * session, or namespace the keys of a shared store.
+ */
+export function memoryStore(options = {}) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("memory store options must be an object");
+    }
+    const maxEntries = positiveInteger(options.maxEntries ?? DEFAULT_MAX_ENTRIES, "maxEntries");
+    const ttlMs = positiveInteger(options.ttlMs ?? DEFAULT_TTL_MS, "ttlMs");
+    const clock = options.clock ?? (() => new Date());
+    if (typeof clock !== "function")
+        throw new TypeError("clock must be a function");
+    const entries = new Map();
+    const now = () => {
+        const value = clock();
+        const time = value instanceof Date ? value.getTime() : Number.NaN;
+        if (!Number.isFinite(time))
+            throw new TypeError("clock must return a valid Date");
+        return time;
+    };
+    const prune = (time) => {
+        for (const [key, entry] of entries) {
+            if (entry.expiresAt <= time)
+                entries.delete(key);
+        }
+    };
+    const markRecentlyUsed = (key, entry) => {
+        entries.delete(key);
+        entries.set(key, entry);
+    };
+    return Object.freeze({
+        async get(key) {
+            assertKey(key);
+            const time = now();
+            prune(time);
+            const entry = entries.get(key);
+            if (entry === undefined)
+                return null;
+            markRecentlyUsed(key, entry);
+            return entry.record;
+        },
+        async put(key, record) {
+            assertKey(key);
+            if (record === null || typeof record !== "object") {
+                throw new TypeError("record must be an object");
+            }
+            const time = now();
+            prune(time);
+            entries.delete(key);
+            entries.set(key, { record, expiresAt: time + ttlMs });
+            while (entries.size > maxEntries) {
+                const oldest = entries.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                entries.delete(oldest);
+            }
+        },
+        async delete(key) {
+            assertKey(key);
+            entries.delete(key);
+        },
+    });
+}
+function assertKey(key) {
+    if (typeof key !== "string" || key === "") {
+        throw new TypeError("store key must be a non-empty string");
+    }
+}
+function positiveInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive safe integer`);
+    }
+    return value;
+}

package/dist/suggest/canonicalize.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Folds the differences that make a copied filename miss on a POSIX
+ * filesystem: NFC and NFD, narrow and non-breaking spaces, and typographic
+ * quotes.
+ */
+export declare function canonicalizeFileName(value: string): string;

package/dist/suggest/canonicalize.js

@@ -0,0 +1,12 @@
+/**
+ * Folds the differences that make a copied filename miss on a POSIX
+ * filesystem: NFC and NFD, narrow and non-breaking spaces, and typographic
+ * quotes.
+ */
+export function canonicalizeFileName(value) {
+    return value
+        .normalize("NFC")
+        .replace(/[  ]/gu, " ")
+        .replace(/[‘’]/gu, "'")
+        .replace(/[“”]/gu, '"');
+}

package/dist/suggest/default-suggest.d.ts

@@ -0,0 +1,3 @@
+import type { Suggest } from "../contract/extensions.ts";
+/** suggestFileNames, with Unicode-equivalent names ranked first. */
+export declare function defaultSuggest(): Suggest<unknown>;

package/dist/suggest/default-suggest.js

@@ -0,0 +1,12 @@
+import { canonicalizeFileName } from "./canonicalize.js";
+import { suggestFileNames } from "./suggest-file-names.js";
+/** suggestFileNames, with Unicode-equivalent names ranked first. */
+export function defaultSuggest() {
+    return (ctx) => {
+        const names = ctx.entries.map((entry) => entry.name);
+        const canonical = canonicalizeFileName(ctx.name);
+        const equivalent = names.filter((name) => name !== ctx.name && canonicalizeFileName(name) === canonical);
+        const near = suggestFileNames(ctx.name, names, ctx.max);
+        return [...new Set([...equivalent, ...near])].slice(0, ctx.max);
+    };
+}

package/dist/suggest/index.d.ts

@@ -0,0 +1,3 @@
+export { canonicalizeFileName } from "./canonicalize.ts";
+export { defaultSuggest } from "./default-suggest.ts";
+export { suggestFileNames } from "./suggest-file-names.ts";

package/dist/suggest/index.js

@@ -0,0 +1,3 @@
+export { canonicalizeFileName } from "./canonicalize.js";
+export { defaultSuggest } from "./default-suggest.js";
+export { suggestFileNames } from "./suggest-file-names.js";

package/dist/suggest/suggest-file-names.d.ts

@@ -0,0 +1,2 @@
+/** Up to `maximum` names close to `requested`: same stem, a shared prefix, or a small edit distance. */
+export declare function suggestFileNames(requested: string, names: readonly string[], maximum: number): readonly string[];

package/dist/suggest/suggest-file-names.js

@@ -0,0 +1,46 @@
+/** Up to `maximum` names close to `requested`: same stem, a shared prefix, or a small edit distance. */
+export function suggestFileNames(requested, names, maximum) {
+    const requestedLower = requested.toLowerCase();
+    const requestedStem = stem(requestedLower);
+    return names
+        .map((name) => ({ name, score: suggestionScore(requestedLower, requestedStem, name) }))
+        .filter(({ score }) => score < Number.POSITIVE_INFINITY)
+        .sort((left, right) => left.score - right.score || left.name.localeCompare(right.name))
+        .slice(0, maximum)
+        .map(({ name }) => name);
+}
+function suggestionScore(requested, requestedStem, candidate) {
+    const lower = candidate.toLowerCase();
+    if (lower === requested)
+        return 0;
+    if (stem(lower) === requestedStem)
+        return 10;
+    if (lower.startsWith(requested) || requested.startsWith(lower)) {
+        return 20 + Math.abs(lower.length - requested.length);
+    }
+    const distance = boundedDistance(requested, lower, 3);
+    return distance === null ? Number.POSITIVE_INFINITY : 30 + distance;
+}
+function stem(value) {
+    const index = value.lastIndexOf(".");
+    return index <= 0 ? value : value.slice(0, index);
+}
+function boundedDistance(left, right, maximum) {
+    if (Math.abs(left.length - right.length) > maximum)
+        return null;
+    let prior = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+        const next = [leftIndex];
+        let rowMinimum = leftIndex;
+        for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+            const value = Math.min(prior[rightIndex] + 1, next[rightIndex - 1] + 1, prior[rightIndex - 1] + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1));
+            next.push(value);
+            rowMinimum = Math.min(rowMinimum, value);
+        }
+        if (rowMinimum > maximum)
+            return null;
+        prior = next;
+    }
+    const distance = prior[right.length];
+    return distance <= maximum ? distance : null;
+}

package/docs/architecture.md

@@ -0,0 +1,249 @@
+# Architecture
+
+This page explains how `@better-fs-tools/read` runs one read, and why it is built this way. [result-schema.md](result-schema.md) describes the result. The [README](../README.md) shows how to configure each step.
+
+## The pipeline
+
+```text
+read(input, ctx?)
+  │  parseReadInput ........... strict canonical validation, limit clamp
+  │  fs(call) ................. once; a FileSystem or a factory result
+  ▼
+ReadRequest { path, offset, limit, ranged }
+  │  resolve .................. one path, or not found; at most one ctx.list
+  ▼
+fs.open(path) ................. roots, deny roots, realpath, type check
+  │   not found ──▶ suggest ... authorize(list) + one fs.list; NOT_FOUND with names
+  │   directory ──▶ directory converter: authorize(list) + one fs.list ─▶ text lines ─▶ scan
+  ▼
+OpenFile (no content byte read yet)
+  │  authorize(read) .......... host policy on the open target
+  ▼
+sample (limits.sampleBytes) ─▶ classifiers (sync)
+  │
+  ├─ a FileConverter accepts ─▶ convert(capped bytes)
+  │                               ├─ text  ─▶ scan
+  │                               ├─ media ─▶ ReadMedia (size cap)
+  │                               └─ refuse ─▶ ReadUnsupported
+  ├─ text ──────────────────────────────────▶ scan (lines, view bytes, budget, clamp, scan cap)
+  └─ unsupported ───────────────────────────▶ ReadUnsupported
+  ▼
+size check + handle.verify() .. change detection, also after conversion
+  ▼
+hooks.afterRead (in order) .... rule checks after each hook
+  ▼
+record ........................ state(call), only when there is an observation
+  ▼
+formatter.format(outcome, { mode: "model", call, ... }) ─▶ content
+  ▼
+ReadResult
+```
+
+| Stage               | Phase          | Dependency                   | What happens                                                                                                                                                                                                                                         |
+| ------------------- | -------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Input               | `input`        | `limits`                     | `parseReadInput` accepts only `path`, `offset`, and `limit`. The path must be a non-blank string with no NUL. `offset` and `limit` must be positive safe integers. `limit` is clamped to `limits.maxLines`, and the tool adds a `clamped` info note. |
+| Filesystem          | `open`         | `fs`                         | A `FileSystem`, or a factory of the call context. The factory runs once for each read.                                                                                                                                                               |
+| Resolve             | `resolve`      | `resolve`                    | Changes the path string that goes into the one open, or reports not found.                                                                                                                                                                           |
+| Open                | `open`         | `fs`, `suggest`              | One `fs.open()`. A miss lists the parent once for `suggest`. A directory goes to the first directory converter, if there is one.                                                                                                                     |
+| Authorize           | `authorize`    | `authorize`                  | Host policy on the open file, before the core reads any content byte. See [What open() fetches before authorize](#what-open-fetches-before-authorize).                                                                                               |
+| Sample and classify | `sampling`     | `classifiers`                | Reads `limits.sampleBytes`, then asks each classifier in order. The first opinion wins.                                                                                                                                                              |
+| Convert             | `conversion`   | `converters`                 | The first file converter that accepts the classification reads a capped stream from byte 0.                                                                                                                                                          |
+| Scan                | `scan`         | `limits`, `budget`, `digest` | Decodes UTF-8, splits lines, selects the view, clamps, counts, and hashes.                                                                                                                                                                           |
+| Verify              | `verification` | `fs`                         | Checks the size and asks the open handle whether the file changed.                                                                                                                                                                                   |
+| Hooks               | `hooks`        | `hooks`, `state`             | Each hook gets the outcome and the previous record, and returns an outcome.                                                                                                                                                                          |
+| Record              | none           | `state`, `digest`            | Stores the observation. A store failure does not fail the read.                                                                                                                                                                                      |
+| Format              | none           | `formatter`, `messages`      | Turns the outcome into content parts.                                                                                                                                                                                                                |
+
+The core owns line scanning, view selection, clamping, the byte limit, continuation arithmetic, change detection, and note assembly. That list is the reason the package exists. Everything else is a dependency.
+
+### What open() fetches before authorize
+
+`@better-fs-tools/cloudflare-shell` and `@better-fs-tools/just-bash` buffer the whole file inside `open()`, so the bytes have left the backend before `authorize` runs. `@better-fs-tools/cloudflare-computer` does not buffer: its `open()` starts a `readFile` stream, so the request reaches the backend, but it reads no chunk before `authorize`. `nodeFileSystem` streams, and `memoryFileSystem` already holds the bytes. The core passes no byte on until `authorize` allows it. If a denied read must not reach the backend, refuse the path in the filesystem with a deny root, or leave it out of the allowed roots.
+
+## Source layout
+
+| Path                                                                                                        | Role                                                                                                        |
+| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `src/contract/`                                                                                             | The public types, one file for each area. No runtime code. `base.ts` holds the tool-neutral types           |
+| `src/core/create-read-tool.ts`, `core/deps.ts`                                                              | Checks and resolves the dependencies once, synchronously                                                    |
+| `src/core/pipeline.ts`                                                                                      | The stage order, and nothing else                                                                           |
+| `src/core/call-scope.ts`                                                                                    | Per-read state: the call object, the phase, `fs(call)`, `state(call)`, the listing budget, and abort checks |
+| `src/core/resolve.ts`, `open.ts`, `suggest.ts`, `authorize.ts`                                              | Resolve, open, suggestions on a miss, and the authorize checks                                              |
+| `src/core/sample.ts`, `classify.ts`                                                                         | The bounded sample and the classifier chain                                                                 |
+| `src/core/convert.ts`, `convert-source.ts`, `converted.ts`, `directory.ts`                                  | Converter selection, the capped source stream, converted outcomes, and directory reads                      |
+| `src/core/scan.ts`, `scanner.ts`, `cursor.ts`, `budget.ts`                                                  | The scan loop, the line scanner, chunk handling with abort racing, and the checked budget                   |
+| `src/core/verify.ts`, `observation.ts`, `text-outcome.ts`, `notes.ts`                                       | Change detection, observations, the `ok` outcome, and truncation notes                                      |
+| `src/core/hooks.ts`, `same.ts`, `record.ts`                                                                 | The hook runner and its rule checks, and the record                                                         |
+| `src/core/outcomes.ts`, `extension-error.ts`, `format.ts`                                                   | Failures, `EXTENSION_FAILED`, the formatter call, and `textOf`                                              |
+| `src/classifiers/`, `resolve/`, `suggest/`, `authorize/`, `converters/`, `hooks/`, `budget/`, `formatters/` | The built-in helpers, one file for each                                                                     |
+| `src/signature/`, `src/formats/`                                                                            | The `./signature` and `./formats` subpaths                                                                  |
+| `src/state/`, `src/digest/`                                                                                 | `memoryStore` and `sha256Digest`, exported from the root                                                    |
+
+## One call, one context
+
+The adapter builds a `ReadContext` for each tool call: `{ signal?, callId?, host }`. It extends the tool-neutral `ToolCallContext`. The core passes this object by reference to every stage and every host function, as `ctx.call`. It never reads, copies, freezes, or stores `host`. `host` never appears in the result, the record, notes, or content.
+
+`CallScope` holds the per-read state:
+
+- `fs(call)` runs at most once, after input validation and before `resolve`. An abort before that point means the filesystem is never built.
+- `state(call)` runs at most once, and only when the core needs the store: to read `previous` for the hooks, or to record an observation.
+- A read has at most two listings. One is for a resolver (`ctx.list()`). The other is for suggestions or a directory converter. A second request for the same slot gets a `denied` list outcome with detail `listing budget spent`. `authorize` with `action: "list"` runs before each listing.
+- A listing never throws. A missing `list()`, a denial, an abort, or a throwing backend becomes an error outcome. A throwing list authorizer is held and raised after the stage that listed, so a resolver cannot swallow it.
+- The signal is checked before each stage and raced against each backend call. An abort gives `ABORTED` with the current phase, and no host code runs after it.
+
+### Tool-neutral base types
+
+`src/contract/base.ts` holds the types that the read, write, and bash tools share: `ToolCallContext`, `ToolName`, `Note`, `ToolError`, `ToolMessages`, `ToolHookContext`, `ToolResolveContext`, `PathResolver`, `ResolveOutcome`, `AccessTarget`, `AccessDecision`, `ToolAuthorizer`, `ToolSignature`, and `SignatureDocs`. `@better-fs-tools/write` and `@better-fs-tools/shell` import them from this package, so they have no copy of their own.
+
+- `ReadHookContext` extends `ToolHookContext` with `tool: "read"`, the request, and the limits. `ReadResolveContext` adds `paths` and `list()`, so it fits `ToolResolveContext`.
+- Resolvers take a `ToolResolveContext`. The built-in resolvers never need the read request, so they work for every tool.
+- `denyPaths` is a `ToolAuthorizer`. It sees only the fields every target has, and uses `ctx.messages.denied({ path, detail })`, which every tool's catalog has. A `ToolAuthorizer` fits the read `ReadAuthorizer`.
+- The read `ReadAuthorizeDecision` keeps `ReadNote`, so a denial can carry a `retry`. An `AccessDecision` fits it.
+
+The public types keep `THost` out of conditional types. `ReadContext<THost>` is an interface with a required `host`. Only the `ReadTool<THost>` parameter type makes the context and `host` optional when `THost` includes `undefined`. With this shape, a helper typed with `unknown` for the host fits a tool with any host type. A conditional context type made `ReadFormatter` and the other contexts invariant in `THost` under TypeScript 7, and then host-free helpers did not fit.
+
+## Why the filesystem returns a handle
+
+A contract with separate `stat(path)` and `readBytes(path)` calls cannot close the gap between the check and the read. So `open()` does the whole decision: resolve, check roots and deny roots, check the type, and open. It returns an `OpenFile`. The core calls the same members in the same order for every backend:
+
+```text
+handle.info      metadata, from the object that was opened
+handle.bytes()   single-use AsyncIterable<Uint8Array>
+handle.verify()  did the opened object change?
+handle.close()   always, from a finally block
+```
+
+Two capabilities remain, and each one decides one thing:
+
+- `streaming: false` adds a `buffered-backend` note.
+- `identity: false` adds a `weak-identity` note, because the observation cannot back a write precondition.
+
+An optional `list()` is the list capability. Without it, there are no suggestions and no directory listings.
+
+When `open()` refuses a directory, FIFO, socket, or device, it returns a `not-a-file` error with a `kind`. For a directory it also gives a `target` with the resolved and display paths. A directory converter lists `target.resolvedPath`, and `authorize` sees that path. When the target is `null`, the core uses the lexical path.
+
+## Scanning
+
+`LineScanner` keeps the current line prefix, the selected view, the decoder state, and a few counters, and nothing else. Memory stays flat for a large file. Lines end at `\n`, `\r\n`, and a bare `\r`. A trailing newline does not add a line, so a file that ends with a newline has exact totals.
+
+The view stops at the first of these limits, always at a line boundary:
+
+- `lines`: `request.limit` lines were shown.
+- `bytes`: the next line would pass `limits.maxViewBytes` of source text.
+- `budget`: the next line would pass `budget.max`. The budget never stops the first line of a view.
+
+Two more reasons can apply to the whole read:
+
+- `line-length`: a line was longer than `limits.maxCharsPerLine` and was clamped. `line.sourceChars` keeps the original length.
+- `scan-limit`: `limits.maxScanBytes` was reached. `totals.lines` and `observation.contentId` are then `null`.
+
+The scan continues past the view to count lines and hash the content. When the view stops early, the first line that was not shown becomes `continuation.next`, a whole canonical input.
+
+View bytes count source text plus one separator byte for each line after the first. They do not count the gutter. So a formatter can change or remove the gutter without changing what fits in a read.
+
+If the sample looked like text but a later chunk is not valid UTF-8, the scan stops and the core asks the classifier chain for its `encodingFailure` refusal. Classifiers never run twice.
+
+## Classification and conversion
+
+Classifiers are synchronous and see only a bounded sample that is already in memory. The classifier that recognizes a format also owns the refusal note that the model sees, and the code in `ReadUnsupported.code`.
+
+Converters come after classification. `accepts(match)` is synchronous, and it is the only place where a converter can decline. `convert` must return an outcome: text, media, or a refusal.
+
+A file converter gets a stream that the core owns. The stream starts at byte 0 (the sample, then the rest of the file), counts and hashes the bytes, and stops at `limits.maxConvertBytes` with an internal error. The core turns that error into `unsupported` with code `TOO_LARGE`, also when the converter catches it. When a converter stops before the end, the core reads the rest of the source within the same cap. So `contentId` is always the hash of the whole source, and the size check can run. Converted text then goes through the same `LineScanner` as file text.
+
+Media parts over `limits.maxMediaBytes` in total give `TOO_LARGE`. A media outcome has `wholeFileVisible: false`. Its `viewId` hashes the parts.
+
+A directory has no handle. The directory converter gets one bounded listing through `CallScope`, and returns text. The text goes through the scanner, so `offset` and `limit` page over entries. A failed listing ends the read with the matching error. A directory result has `observation: null`, because there is nothing to verify.
+
+## Change detection
+
+After the scan or the conversion, the core checks the size when it reached the end, and calls `handle.verify()`. A changed file gives `CHANGED_DURING_READ` with a retry of the same range. This runs after an `askUser` prompt too, so an edit during the prompt is caught.
+
+## Hooks
+
+Hooks run in order after verification and before the record, for every outcome that has a request. They do not run for `INVALID_INPUT`, which has no request, or for `ABORTED`, because the caller has given up.
+
+After each hook the core checks the rules:
+
+- The status cannot move from `error` or `unsupported` to `ok` or `media`.
+- `request`, `file`, `classification`, `conversion`, `truncation`, `continuation`, `totals`, and `observation` must be the same values. When the status changes, only the fields that both outcomes have are compared.
+
+A hook that throws, returns something that is not an outcome, or breaks a rule gives `EXTENSION_FAILED`.
+
+If a hook changed the view lines or the media parts, the core adds a `view-modified` note that names the hook, recomputes `observation.viewId` and `observation.id`, and sets `wholeFileVisible` to `false`. The stored record then matches what the model saw.
+
+Hooks are host code. The model cannot choose which files a hook reads, so a hook that reads files uses the host's own permissions. The core does not check those reads.
+
+## Observations and records
+
+An observation exists when there is a `digest`:
+
+| Field              | Value                                                                                            |
+| ------------------ | ------------------------------------------------------------------------------------------------ |
+| `statId`           | Hash of the resolved path, identity, size, and modification time                                 |
+| `contentId`        | Hash of the source bytes. `null` when the scan stopped before the end.                           |
+| `viewId`           | Hash of what the model saw: the view text, or the media parts                                    |
+| `id`               | Hash of `statId`, `contentId`, and `viewId`                                                      |
+| `wholeFileVisible` | `true` only when the offset is 1, nothing was truncated or clamped, and no hook changed the view |
+
+The record stores these fields with the request range, under the key `file.resolvedPath`. It is schema 2: it also has `origin: "read"`, the backend `version`, and the `digest` id. The write tools store records with `origin: "write"` and `request: null` in the same store, so a later edit knows what the model has seen. The hook runner treats a record of another schema as absent, and `repeatReadGuard` ignores a write record. `record` builds it field by field from the outcome, so nothing from `call` reaches the store. A store whose `get` or `put` fails does not fail the read. A `state` factory that throws does.
+
+## Errors
+
+Filesystem adapters return typed reasons, and the core maps them one to one. The core never parses a detail string.
+
+| Adapter reason          | Result code             |
+| ----------------------- | ----------------------- |
+| `not-found`             | `NOT_FOUND`             |
+| `not-a-file`            | `NOT_A_FILE`            |
+| `dangerous-path`        | `DANGEROUS_PATH`        |
+| `outside-allowed-roots` | `OUTSIDE_ALLOWED_ROOTS` |
+| `permission-denied`     | `PERMISSION_DENIED`     |
+| `denied`                | `DENIED`                |
+| `too-large`             | `TOO_LARGE`             |
+| `unsupported`           | `UNSUPPORTED_BACKEND`   |
+| `aborted`               | `ABORTED`               |
+| `io`                    | `IO_ERROR`              |
+
+The core makes the other failures itself:
+
+- `INVALID_INPUT` from `parseReadInput`.
+- `DENIED` from an authorizer. It has `file: null`, so a denial does not show the real path.
+- `CHANGED_DURING_READ` from the size check or `verify()`.
+- `UNSUPPORTED_BACKEND` when no classifier had an opinion.
+- `IO_ERROR` when a filesystem method or the byte stream throws.
+- `EXTENSION_FAILED` when host code throws or breaks a rule. `data.extension` names the dependency (`fs`, `state`, `resolve`, `suggest`, `authorize`, `converters`, `budget`, or `hooks`), `data.phase` names the stage, and `data.id` names the extension object when it has one.
+
+A formatter that throws, or returns neither a string nor an array, does not reject the call. The core adds an `extension-failed` warning with `data: { extension: "formatter", id? }` and formats the result with `lineNumberFormatter()`. The status stays as it was.
+
+## Adapters
+
+Adapters sit above the core. A `ReadSignature` owns the tool name, the JSON Schema, and the mapping between model input and canonical input. `readSignatureMessages(signature)` makes retry text use the model's names. The structured result always stays canonical.
+
+The AI SDK adapter passes `ToolExecutionOptions` as `host`. The Pi adapter passes Pi's `ExtensionContext`, and builds the filesystem for each call from `ctx.cwd` with an `fs` factory. No adapter adds policy of its own, except Pi's rule that the root is always the call's working directory.
+
+## Packages
+
+| Package                                   | Depends on                                         |
+| ----------------------------------------- | -------------------------------------------------- |
+| `fs`                                      | nothing                                            |
+| `read`                                    | `fs`                                               |
+| `shell`                                   | `fs`, `read`                                       |
+| `write`                                   | `fs`, `read`, `shell`                              |
+| `node`                                    | `fs`, `read`, `write`, `shell`                     |
+| `ai-sdk`                                  | `read`, `write`, `shell`, and the `ai` peer        |
+| `pi`                                      | `node`, `read`, `write`, `shell`, and the Pi peers |
+| `cloudflare-shell`, `cloudflare-computer` | `fs`                                               |
+| `just-bash`                               | `fs`, `shell`, and the `just-bash` peer            |
+
+`fs` holds the filesystem contract, so a filesystem adapter does not depend on the read tool. No package but `node` and `pi` imports a `node:` module.
+
+## Deliberate omissions
+
+- **No alias repair.** The core accepts `path`, `offset`, and `limit` only. Other names belong to a signature.
+- **No Node defaults in the core.** `fs` is required and `digest` defaults to `null`. `createNodeReadTool()` in `@better-fs-tools/node` gives the local defaults. A Workers build cannot pull in `node:fs` by mistake.
+- **No converter path access.** A converter gets the capped stream, never the path.
+- **No nested reads from hooks.** A hook that needs another file reads it with host code.
+- **No write guard.** The precondition check belongs with the write tool that uses the record.
+- **No telemetry.** A host that wants timing can wrap the returned function.
+- **POSIX only.** Windows paths are not supported in this release.