@better-fs-tools/read 0.1.0 → 0.2.0

package/README.md

@@ -107,7 +107,7 @@ read({ path, offset, limit }, ctx)
   │     ├─ on a miss: suggest  one bounded listing, names only
   │     └─ on a directory .... a directory converter lists it, else NOT_A_FILE
   │  authorize ............... host policy on the open file, before the core reads content
-  │  sample + classifiers .... text, image, PDF, notebook, binary, ...
+  │  sample + classifiers .... text, image, PDF, Office, binary, ...
   │  converters .............. other formats to text or media parts
   │  scan .................... lines, clamping, view bytes, token budget, scan limit
   │  verify .................. size check and change detection
@@ -343,7 +343,9 @@ While a prompt waits, the file stays open. If the file changes during the wait,
 
 `classifiers` is an ordered list. Each classifier sees a bounded sample of the file (`limits.sampleBytes`). The first classifier with an opinion wins.
 
-The default chain detects images, PDFs, Office documents, notebooks, binary content, and text encodings. It returns these `unsupported` codes: `IMAGE`, `PDF`, `OFFICE_DOCUMENT`, `NOTEBOOK`, `BINARY`, and `UNKNOWN_ENCODING`. Each refusal has a note with code `unsupported-<code>`, for example `unsupported-pdf`.
+The default chain detects images, PDFs, Office documents, binary content, and text encodings. It returns these `unsupported` codes: `IMAGE`, `PDF`, `OFFICE_DOCUMENT`, `BINARY`, and `UNKNOWN_ENCODING`. Each refusal has a note with code `unsupported-<code>`, for example `unsupported-pdf`.
+
+A Jupyter notebook is JSON, so the default chain reads it as text. `notebookClassifier()` is exported but not in the chain. Put it first, as `classifiers: [notebookClassifier(), ...defaultClassifiers()]`, to refuse notebooks with code `NOTEBOOK`, or to convert them with `notebookConverter()`. The write tools use the same classifiers, so the same list makes them refuse a notebook too.
 
 To detect by extension, or to change a refusal message:
 
@@ -370,13 +372,15 @@ A classifier only decides what a file is. A converter changes the content.
 
 ## File conversion, images, and directories
 
-`converters` is a list. It runs after classification. The first file converter whose `accepts` returns `true` handles the file. The first directory converter handles directories. With no converters, text is read, other formats are `unsupported`, and a directory gives `NOT_A_FILE`.
+`converters` is a list. It runs after classification. The first file converter whose `accepts` returns `true` handles the file. The first directory converter handles directories. With no converters, text is read, other formats are `unsupported`, and a directory gives `NOT_A_FILE`. The core has no converters by default. The Pi and AI SDK hosts add `imageConverter()` when you pass no `converters`.
 
 ```ts
 import { createNodeReadTool } from "@better-fs-tools/node";
 import {
+  defaultClassifiers,
   directoryListing,
   imageConverter,
+  notebookClassifier,
   notebookConverter,
   textConverter,
 } from "@better-fs-tools/read";
@@ -385,6 +389,9 @@ import {
 declare function pdfToText(source: AsyncIterable<Uint8Array>): AsyncIterable<string>;
 
 export const read = createNodeReadTool({
+  // The default chain reads a notebook as JSON text. notebookClassifier()
+  // marks it NOTEBOOK, so notebookConverter() can take it.
+  classifiers: [notebookClassifier(), ...defaultClassifiers()],
   converters: [
     imageConverter(),
     notebookConverter({ outputs: false }),
@@ -400,12 +407,12 @@ export const read = createNodeReadTool({
 });
 ```
 
-| Converter                                       | Result                                                                                                                                 |
-| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `imageConverter({ transform })`                 | Accepts code `IMAGE`. Gives a `media` result with the image as one content part. `transform` can resize it.                            |
-| `notebookConverter({ outputs })`                | Accepts code `NOTEBOOK`. Gives the cells as text. `outputs` defaults to `true`. Broken notebook JSON is refused as `INVALID_NOTEBOOK`. |
-| `textConverter({ id, accepts, mimeType, run })` | Builds a text converter from a stream function, for example `pdftotext`, `pandoc`, or `markitdown` in your host.                       |
-| `directoryListing({ trailingSlash, sort })`     | A directory becomes text, one entry for each line. `sort` is `"name"` (the default) or `"type-then-name"`.                             |
+| Converter                                       | Result                                                                                                                                                                     |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `imageConverter({ transform })`                 | Accepts code `IMAGE`. Gives a `media` result with the image as one content part. `transform` can resize it.                                                                |
+| `notebookConverter({ outputs })`                | Accepts code `NOTEBOOK`, so it needs `notebookClassifier()`. Gives the cells as text. `outputs` defaults to `true`. Broken notebook JSON is refused as `INVALID_NOTEBOOK`. |
+| `textConverter({ id, accepts, mimeType, run })` | Builds a text converter from a stream function, for example `pdftotext`, `pandoc`, or `markitdown` in your host.                                                           |
+| `directoryListing({ trailingSlash, sort })`     | A directory becomes text, one entry for each line. `sort` is `"name"` (the default) or `"type-then-name"`.                                                                 |
 
 A converter returns one of these outcomes:
 
@@ -428,7 +435,7 @@ Conversion runs again on each continuation read. Cache inside your converter if
 | Limit                 | Default | Meaning                                               |
 | --------------------- | ------- | ----------------------------------------------------- |
 | `maxLines`            | 2,000   | Lines in the view. Also the ceiling for `limit`.      |
-| `maxViewBytes`        | 128 KiB | UTF-8 bytes of source text in the view                |
+| `maxViewBytes`        | 50 KiB  | UTF-8 bytes of source text in the view                |
 | `maxCharsPerLine`     | 2,000   | Characters in one line before it is clamped           |
 | `maxScanBytes`        | 64 MiB  | Bytes scanned before totals and content identity stop |
 | `sampleBytes`         | 8 KiB   | Bytes given to classifiers. At most `maxScanBytes`.   |
@@ -548,7 +555,7 @@ export const read = createNodeReadTool({
     gutter: hashlineGutter({ width: 2 }), // "12:a3|text"
     header: fileHashHeader(), // "file-hash: sha256:..."
     footer: eofFooter((n) => `(End of file - total ${n} lines)`),
-    notes: (note) => (note.code === "weak-identity" ? null : note),
+    notes: (note) => (note.severity === "info" ? null : note),
   }),
 });
 ```
@@ -568,7 +575,7 @@ import { opencodeFormat } from "@better-fs-tools/read/formats";
 export const read = createNodeReadTool({ formatter: opencodeFormat() });
 ```
 
-A custom formatter implements `format(outcome, ctx)`. It is synchronous and pure over the outcome. `ctx` has the `digest`, the `limits`, the `call`, and a `mode`. The mode is `"model"` for model output and `"view"` for the body only, with no notes, header, or footer. The Pi adapter uses `"view"` for its truncation details. If your formatter returns parts in `"view"` mode, Pi leaves those details out. A formatter sees only the finished outcome. It cannot read the file. If the formatter throws or returns neither a string nor an array, the call still succeeds: the core adds an `extension-failed` warning and formats the result with `lineNumberFormatter()`.
+A custom formatter implements `format(outcome, ctx)`. It is synchronous and pure over the outcome. `ctx` has the `digest`, the `limits`, the `call`, and a `mode`. The mode is `"model"` for model output and `"view"` for the body only, with no notes, header, or footer. The Pi adapter uses `"view"` for its truncation details. If your formatter returns parts in `"view"` mode, Pi leaves those details out. A formatter sees only the finished outcome. It cannot read the file. If the formatter throws or returns neither a string nor an array, the call still succeeds: the core formats the result with `lineNumberFormatter()` and adds no note.
 
 ## Messages and notes
 
@@ -683,7 +690,7 @@ Your dependencies can narrow access. They cannot widen it.
 - The filesystem is the only place that grants access. It checks roots, deny roots, the realpath, and the type in one `open()` call. `resolve` runs before it and `authorize` runs after it.
 - Each read opens at most one file. A resolver only changes the path that goes into that open.
 - `nodeFileSystem` opens files with `O_NOFOLLOW | O_NONBLOCK` and checks the type first. It refuses directories, FIFOs, sockets, and devices before any content read. It refuses `/dev`, `/proc`, and `/sys` before it touches the filesystem.
-- The core reads no content byte before `authorize` allows it, so no content reaches a classifier, a converter, or the model. `@better-fs-tools/cloudflare-shell` and `@better-fs-tools/just-bash` (a result with a `buffered-backend` note) have already fetched the whole file in `open()`. `@better-fs-tools/cloudflare-computer` has started a `readFile` stream but read no chunk. If a denied read must not reach the backend, use a deny root, or leave the path out of the filesystem's allowed roots.
+- The core reads no content byte before `authorize` allows it, so no content reaches a classifier, a converter, or the model. `@better-fs-tools/cloudflare-shell` and `@better-fs-tools/just-bash` have already fetched the whole file in `open()`. `@better-fs-tools/cloudflare-computer` has started a `readFile` stream but read no chunk. If a denied read must not reach the backend, use a deny root, or leave the path out of the filesystem's allowed roots.
 - The scan is bounded. Converters get a capped stream from the open file, never a path.
 - Change detection runs after the scan and after conversion. A file that changed returns `CHANGED_DURING_READ`.
 - A suggested name is never opened.
@@ -694,11 +701,11 @@ Your dependencies can narrow access. They cannot widen it.
 
 Each adapter owns the signature, abort forwarding, and the mapping from `result.content` to the framework's content types. The adapters accept every core dependency and pass it through.
 
-| Package                                                                            | Factory                        | Notes                                                                                                                                                                 |
-| ---------------------------------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`@better-fs-tools/ai-sdk`](https://www.npmjs.com/package/@better-fs-tools/ai-sdk) | `createAiSdkReadTool(options)` | `execute` returns the whole `ReadResult`. `toModelOutput` maps media parts to AI SDK `file` parts. You pass `fs`.                                                     |
-| [`@better-fs-tools/pi`](https://www.npmjs.com/package/@better-fs-tools/pi)         | `createPiReadTool(options)`    | Each call is confined to Pi's `ctx.cwd`. `fs`, `cwd`, and `allowedRoots` are refused. The `pi.extensions` entry registers `read`, `edit`, `write`, and `apply_patch`. |
-| [`@better-fs-tools/node`](https://www.npmjs.com/package/@better-fs-tools/node)     | `createNodeReadTool(options?)` | The core with Node defaults, for your own tool.                                                                                                                       |
+| Package                                                                            | Factory                        | Notes                                                                                                                                                  |
+| ---------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [`@better-fs-tools/ai-sdk`](https://www.npmjs.com/package/@better-fs-tools/ai-sdk) | `createAiSdkReadTool(options)` | `execute` returns the whole `ReadResult`. `toModelOutput` maps media parts to AI SDK `file` parts. You pass `fs`.                                      |
+| [`@better-fs-tools/pi`](https://www.npmjs.com/package/@better-fs-tools/pi)         | `createPiReadTool(options)`    | Each call is confined to Pi's `ctx.cwd`. `fs`, `cwd`, and `allowedRoots` are refused. The `pi.extensions` entry registers `read`, `edit`, and `write`. |
+| [`@better-fs-tools/node`](https://www.npmjs.com/package/@better-fs-tools/node)     | `createNodeReadTool(options?)` | The core with Node defaults, for your own tool.                                                                                                        |
 
 Cloudflare Agents hosts use `@better-fs-tools/ai-sdk` with `cloudflareShellFileSystem` from [`@better-fs-tools/cloudflare-shell`](https://www.npmjs.com/package/@better-fs-tools/cloudflare-shell). [`@better-fs-tools/cloudflare-computer`](https://www.npmjs.com/package/@better-fs-tools/cloudflare-computer) and [`@better-fs-tools/just-bash`](https://www.npmjs.com/package/@better-fs-tools/just-bash) are filesystems. Use them with `createReadTool()` or with an adapter.
 

package/dist/classifiers/index.d.ts

@@ -8,8 +8,9 @@ export { officeClassifier } from "./office.ts";
 export { pdfClassifier } from "./pdf.ts";
 export { utf8Classifier } from "./utf8.ts";
 /**
- * The built-in chain in evaluation order: image, pdf, office, notebook,
- * binary, utf8. The first classifier with an opinion wins. utf8Classifier
- * runs last and is the one that returns text.
+ * The built-in chain in evaluation order: image, pdf, office, binary, utf8.
+ * The first classifier with an opinion wins. utf8Classifier runs last and is
+ * the one that returns text. A notebook is JSON text here. Put
+ * notebookClassifier() before the chain to refuse or convert notebooks.
  */
 export declare function defaultClassifiers(options?: DefaultClassifierOptions): Classifier[];

package/dist/classifiers/index.js

@@ -1,6 +1,5 @@
 import { binaryClassifier } from "./binary.js";
 import { imageClassifier } from "./image.js";
-import { notebookClassifier } from "./notebook.js";
 import { officeClassifier } from "./office.js";
 import { pdfClassifier } from "./pdf.js";
 import { utf8Classifier } from "./utf8.js";
@@ -12,9 +11,10 @@ export { officeClassifier } from "./office.js";
 export { pdfClassifier } from "./pdf.js";
 export { utf8Classifier } from "./utf8.js";
 /**
- * The built-in chain in evaluation order: image, pdf, office, notebook,
- * binary, utf8. The first classifier with an opinion wins. utf8Classifier
- * runs last and is the one that returns text.
+ * The built-in chain in evaluation order: image, pdf, office, binary, utf8.
+ * The first classifier with an opinion wins. utf8Classifier runs last and is
+ * the one that returns text. A notebook is JSON text here. Put
+ * notebookClassifier() before the chain to refuse or convert notebooks.
  */
 export function defaultClassifiers(options = {}) {
     const notes = options.notes ?? {};
@@ -22,7 +22,6 @@ export function defaultClassifiers(options = {}) {
         imageClassifier(withNote(notes.IMAGE)),
         pdfClassifier(withNote(notes.PDF)),
         officeClassifier(withNote(notes.OFFICE_DOCUMENT)),
-        notebookClassifier(withNote(notes.NOTEBOOK)),
         binaryClassifier(withNote(notes.BINARY)),
         utf8Classifier(withNote(notes.UNKNOWN_ENCODING)),
     ];

package/dist/contract/limits.d.ts

@@ -1,7 +1,7 @@
 export interface ReadLimits {
     /** Lines in the view. Default 2_000. */
     readonly maxLines: number;
-    /** UTF-8 bytes of source text in the view. Default 128 KiB. */
+    /** UTF-8 bytes of source text in the view. Default 50 KiB (51 200). */
     readonly maxViewBytes: number;
     /** Characters per line before clamping. Default 2_000. */
     readonly maxCharsPerLine: number;

package/dist/contract/messages.d.ts

@@ -107,14 +107,4 @@ export interface ReadMessageCatalog extends ToolMessages {
     viewModified(c: {
         hook: string;
     }): string;
-    weakIdentity(c: {
-        backend: string;
-    }): string;
-    bufferedBackend(c: {
-        backend: string;
-    }): string;
-    /** The formatter threw or returned neither a string nor an array. */
-    formatterFailed(c: {
-        formatter: string;
-    }): string;
 }

package/dist/core/convert.js

@@ -3,7 +3,6 @@ import { ConvertSource } from "./convert-source.js";
 import { checkConvertOutcome, firstMediaType, mediaBytes, refusedOutcome, scanConvertedText, tooLarge, } from "./converted.js";
 import { AbortReadError, raceAbort } from "./cursor.js";
 import { extensionId } from "./extension-error.js";
-import { capabilityNotes } from "./notes.js";
 import { buildObservation } from "./observation.js";
 import { ReadStop } from "./outcomes.js";
 import { textOutcome } from "./text-outcome.js";
@@ -111,7 +110,7 @@ async function drainAndVerify(source, handle, input, throwIfSourceFailed) {
     await verifyHandle(handle, deps.messages, request, file, scope);
 }
 function mediaOutcome(input, classification, parts, notes, source) {
-    const { deps, fs, request, file, converter } = input;
+    const { deps, request, file, converter } = input;
     return {
         tool: "read",
         status: "media",
@@ -128,6 +127,6 @@ function mediaOutcome(input, classification, parts, notes, source) {
             // Media is not source text, so it cannot back a text edit.
             wholeFileVisible: false,
         }),
-        notes: [...notes, ...capabilityNotes(fs, deps.messages)],
+        notes,
     };
 }

package/dist/core/format.js

@@ -1,5 +1,4 @@
 import { lineNumberFormatter } from "../formatters/index.js";
-import { extensionId } from "./extension-error.js";
 export function formatResult(deps, call, outcome) {
     const ctx = {
         digest: deps.digest,
@@ -14,20 +13,7 @@ export function formatResult(deps, call, outcome) {
     catch { }
     if (content !== null)
         return { ...outcome, content };
-    const id = extensionId(deps.formatter);
-    const failed = {
-        ...outcome,
-        notes: [
-            ...outcome.notes,
-            {
-                code: "extension-failed",
-                severity: "warning",
-                message: deps.messages.formatterFailed({ formatter: id ?? "formatter" }),
-                data: id === null ? { extension: "formatter" } : { extension: "formatter", id },
-            },
-        ],
-    };
-    return { ...failed, content: toContent(lineNumberFormatter().format(failed, ctx)) ?? [] };
+    return { ...outcome, content: toContent(lineNumberFormatter().format(outcome, ctx)) ?? [] };
 }
 function toContent(output) {
     if (typeof output === "string")

package/dist/core/limits.js

@@ -1,7 +1,7 @@
 /** The default read limits. They are not ceilings: a host may raise any of them. */
 export const defaultReadLimits = Object.freeze({
     maxLines: 2_000,
-    maxViewBytes: 128 * 1_024,
+    maxViewBytes: 50 * 1_024,
     maxCharsPerLine: 2_000,
     maxScanBytes: 64 * 1_024 * 1_024,
     sampleBytes: 8_192,

package/dist/core/messages.js

@@ -6,14 +6,14 @@ const catalog = {
     offsetUnreached: ({ request, reachedLine, retry }) => `Scanning stopped before line ${request.offset} was reached. Retry from line ${reachedLine} with ${retry}.`,
     lineClamped: ({ lines, total, maxChars }) => `Source line${total === 1 ? "" : "s"} ${lines.join(", ")}${total > lines.length ? ", …" : ""} exceeded ${maxChars} characters and ${total === 1 ? "was" : "were"} clamped.`,
     limitClamped: ({ requested, max }) => `The requested line count of ${requested} is over the maximum, so at most ${max} lines are shown.`,
-    scanLimit: ({ maxScanBytes }) => `Scanning stopped at ${maxScanBytes} bytes; total lines and raw content identity are unknown.`,
+    scanLimit: ({ maxScanBytes }) => `Scanning stopped at ${maxScanBytes} bytes, so the total line count is unknown.`,
     empty: ({ path }) => `${path} is empty (0 bytes); no retry is needed.`,
     notFound: ({ request, suggestions }) => suggestions.length === 0
         ? `${request.path} was not found.`
         : `${request.path} was not found. Nearby names: ${quoted(suggestions)}.`,
     pathRepaired: ({ from, to }) => `The requested filename ${JSON.stringify(from)} was repaired to the unique Unicode-equivalent path ${JSON.stringify(to)}.`,
-    notAFile: ({ request, kind }) => `${request.path} is a ${kindLabel(kind)}; directories, FIFOs, sockets, and devices are refused before any content read.`,
-    dangerousPath: ({ request, detail }) => `${request.path} belongs to a refused policy class${detail === null ? "" : ` (${detail})`}.`,
+    notAFile: ({ request, kind }) => `${request.path} is a ${kindLabel(kind)}.`,
+    dangerousPath: ({ request, detail }) => `${request.path} is refused by policy${detail === null ? "" : ` (${detail})`}. Choose another path.`,
     outsideAllowedRoots: ({ request }) => `${request.path} is outside every configured allowed root.`,
     permissionDenied: ({ request }) => `Permission was denied for ${request.path}.`,
     denied: ({ path, detail }) => `${path} was refused by policy${detail === null ? "" : ` (${detail})`}.`,
@@ -26,15 +26,12 @@ const catalog = {
             : `The media converted from ${request.path} is larger than the ${limit}-byte media limit, so it was not returned.`;
     },
     changedDuringRead: ({ request, retry }) => `${request.path} changed while it was being read. Read it again with ${retry} before relying on this result.`,
-    aborted: ({ phase }) => `The read was aborted during the ${phase} phase; no observation was recorded.`,
+    aborted: ({ phase }) => `The read was aborted during the ${phase} phase, so nothing was read.`,
     invalidInput: ({ detail }) => `The read input was rejected: ${detail}`,
     extensionFailed: ({ request, extension, phase }) => `The ${extension} extension failed during the ${phase} phase while reading ${request.path}; this is a host problem rather than a property of the file.`,
     ioError: ({ request }) => `The backend failed while reading ${request === null ? "the requested path" : request.path}.`,
-    unsupportedBackend: ({ request, detail }) => `No classifier had an opinion about ${request.path}${detail === null ? "" : ` (${detail})`}; this is a configuration problem rather than a property of the file.`,
+    unsupportedBackend: ({ request, detail }) => `This host cannot read ${request.path}${detail === null ? "" : ` (${detail})`}. Do not retry.`,
     viewModified: ({ hook }) => `The ${hook} hook changed this view, so it is not the exact file text.`,
-    weakIdentity: ({ backend }) => `The ${backend} backend has no stable identity, so this observation cannot back a write precondition.`,
-    bufferedBackend: ({ backend }) => `The ${backend} backend buffers whole objects instead of streaming them.`,
-    formatterFailed: ({ formatter }) => `The ${formatter} formatter failed, so the default formatter formatted this result.`,
 };
 /** The default wording of every read message. */
 export const defaultReadMessages = Object.freeze(catalog);

package/dist/core/notes.d.ts

@@ -1,4 +1,3 @@
-import type { FileSystem } from "@better-fs-tools/fs";
 import type { ReadRequest } from "../contract/input.ts";
 import type { ReadLimits } from "../contract/limits.ts";
 import type { ReadMessageCatalog } from "../contract/messages.ts";
@@ -13,4 +12,3 @@ export interface ViewNoteContext {
 }
 export declare function buildViewNotes(context: ViewNoteContext): ReadNote[];
 export declare function emptyNote(messages: Readonly<ReadMessageCatalog>, path: string): ReadNote;
-export declare function capabilityNotes(fs: FileSystem, messages: Readonly<ReadMessageCatalog>): ReadNote[];

package/dist/core/notes.js

@@ -89,26 +89,6 @@ export function buildViewNotes(context) {
 export function emptyNote(messages, path) {
     return { code: "empty", severity: "info", message: messages.empty({ path }) };
 }
-export function capabilityNotes(fs, messages) {
-    const notes = [];
-    if (!fs.capabilities.identity) {
-        notes.push({
-            code: "weak-identity",
-            severity: "info",
-            message: messages.weakIdentity({ backend: fs.id }),
-            data: { backend: fs.id },
-        });
-    }
-    if (!fs.capabilities.streaming) {
-        notes.push({
-            code: "buffered-backend",
-            severity: "info",
-            message: messages.bufferedBackend({ backend: fs.id }),
-            data: { backend: fs.id },
-        });
-    }
-    return notes;
-}
 function retryFrom(request, offset) {
     return { path: request.path, offset, limit: request.limit };
 }

package/dist/core/text-outcome.js

@@ -1,4 +1,4 @@
-import { buildViewNotes, capabilityNotes, emptyNote } from "./notes.js";
+import { buildViewNotes, emptyNote } from "./notes.js";
 import { buildObservation } from "./observation.js";
 export function textOutcome(input) {
     const { deps, fs, request, file, classification, conversion, scan } = input;
@@ -67,7 +67,6 @@ export function textOutcome(input) {
             ...(conversion === null && reachedEof && scannedBytes === 0
                 ? [emptyNote(deps.messages, file.displayPath)]
                 : []),
-            ...(fs === null ? [] : capabilityNotes(fs, deps.messages)),
         ],
     };
 }

package/docs/architecture.md

@@ -113,10 +113,11 @@ handle.verify()  did the opened object change?
 handle.close()   always, from a finally block
 ```
 
-Two capabilities remain, and each one decides one thing:
+One capability remains. It adds no note to the result, because the model cannot act on it:
 
-- `streaming: false` adds a `buffered-backend` note.
-- `identity: false` adds a `weak-identity` note, because the observation cannot back a write precondition.
+- `identity: false` sets `file.identity` to `null`. The write tools then judge freshness by the content hash only.
+
+The read core reads `bytes()` the same way whether it yields one chunk or many, so a backend does not report which.
 
 An optional `list()` is the list capability. Without it, there are no suggestions and no directory listings.
 
@@ -214,7 +215,7 @@ The core makes the other failures itself:
 - `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.
+A formatter that throws, or returns neither a string nor an array, does not reject the call. The core formats the result with `lineNumberFormatter()` and adds no note. The status stays as it was.
 
 ## Adapters
 

package/docs/result-schema.md

@@ -97,12 +97,13 @@ Field notes:
 
 `code` comes from the classifier, a converter refusal, or the core:
 
-| Code                                                                        | Source                                                                                                                                              |
-| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `IMAGE`, `PDF`, `OFFICE_DOCUMENT`, `NOTEBOOK`, `BINARY`, `UNKNOWN_ENCODING` | The default classifiers                                                                                                                             |
-| `INVALID_NOTEBOOK`                                                          | `notebookConverter()` on broken notebook JSON                                                                                                       |
-| `TOO_LARGE`                                                                 | The core: converter input over `maxConvertBytes`, or media over `maxMediaBytes`. A backend ceiling gives `status: "error"` with `TOO_LARGE` instead |
-| any other string                                                            | Your own classifier or converter                                                                                                                    |
+| Code                                                            | Source                                                                                                                                              |
+| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `IMAGE`, `PDF`, `OFFICE_DOCUMENT`, `BINARY`, `UNKNOWN_ENCODING` | The default classifiers                                                                                                                             |
+| `NOTEBOOK`                                                      | `notebookClassifier()`, which is not in the default chain                                                                                           |
+| `INVALID_NOTEBOOK`                                              | `notebookConverter()` on broken notebook JSON                                                                                                       |
+| `TOO_LARGE`                                                     | The core: converter input over `maxConvertBytes`, or media over `maxMediaBytes`. A backend ceiling gives `status: "error"` with `TOO_LARGE` instead |
+| any other string                                                | Your own classifier or converter                                                                                                                    |
 
 ## `error`
 
@@ -162,8 +163,6 @@ Notes from the core:
 | `scan-limit`                                                                                                | warning  | none                                         | `{ maxScanBytes }`                                                                                          |
 | `offset-past-eof`                                                                                           | info     | the last line                                | `{ totalLines }`                                                                                            |
 | `empty`                                                                                                     | info     | none                                         | none                                                                                                        |
-| `weak-identity`                                                                                             | info     | none                                         | `{ backend }`                                                                                               |
-| `buffered-backend`                                                                                          | info     | none                                         | `{ backend }`                                                                                               |
 | `not-found`                                                                                                 | warning  | none                                         | `{ suggestions?, entriesTruncated?, detail?, cause? }`                                                      |
 | `not-a-file`                                                                                                | warning  | none                                         | `{ kind, detail?, cause? }`                                                                                 |
 | `dangerous-path`, `outside-allowed-roots`, `permission-denied`, `denied`, `unsupported-backend`, `io-error` | warning  | none                                         | `{ detail?, cause? }` from the filesystem. A thrown error gives `io-error` with `{ detail }`.               |
@@ -172,20 +171,21 @@ Notes from the core:
 | `changed-during-read`                                                                                       | warning  | the same range                               | none                                                                                                        |
 | `aborted`                                                                                                   | warning  | none                                         | `{ phase }`                                                                                                 |
 | `invalid-input`                                                                                             | warning  | none                                         | `{ path }` when the input had a string path                                                                 |
-| `extension-failed`                                                                                          | warning  | none                                         | `{ extension, phase, id? }`. A formatter failure gives `{ extension: "formatter", id? }`.                   |
+| `extension-failed`                                                                                          | warning  | none                                         | `{ extension, phase, id? }`                                                                                 |
 | `view-modified`                                                                                             | info     | none                                         | `{ hook }`                                                                                                  |
 
 Notes from the built-in helpers:
 
-| `code`                                                                                                                                              | Severity | From                    | `data`                          |
-| --------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------- | ------------------------------- |
-| `utf8-bom`                                                                                                                                          | info     | `utf8Classifier`        | none                            |
-| `unsupported-image`, `unsupported-pdf`, `unsupported-office-document`, `unsupported-notebook`, `unsupported-binary`, `unsupported-unknown-encoding` | warning  | the default classifiers | as set by a `NoteOverride`      |
-| `path-repaired`                                                                                                                                     | warning  | `unicodeRepair()`       | `{ from, to }`                  |
-| `invalid-notebook`                                                                                                                                  | warning  | `notebookConverter()`   | none                            |
-| `directory-truncated`                                                                                                                               | warning  | `directoryListing()`    | `{ maxDirectoryEntries }`       |
-| `empty-directory`                                                                                                                                   | info     | `directoryListing()`    | none                            |
-| `repeat-read`                                                                                                                                       | info     | `repeatReadGuard()`     | `{ observationId, observedAt }` |
+| `code`                                                                                                                      | Severity | From                    | `data`                          |
+| --------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------- | ------------------------------- |
+| `utf8-bom`                                                                                                                  | info     | `utf8Classifier`        | none                            |
+| `unsupported-image`, `unsupported-pdf`, `unsupported-office-document`, `unsupported-binary`, `unsupported-unknown-encoding` | warning  | the default classifiers | as set by a `NoteOverride`      |
+| `unsupported-notebook`                                                                                                      | warning  | `notebookClassifier()`  | as set by a `NoteOverride`      |
+| `path-repaired`                                                                                                             | warning  | `unicodeRepair()`       | `{ from, to }`                  |
+| `invalid-notebook`                                                                                                          | warning  | `notebookConverter()`   | none                            |
+| `directory-truncated`                                                                                                       | warning  | `directoryListing()`    | `{ maxDirectoryEntries }`       |
+| `empty-directory`                                                                                                           | info     | `directoryListing()`    | none                            |
+| `repeat-read`                                                                                                               | info     | `repeatReadGuard()`     | `{ observationId, observedAt }` |
 
 `directoryListing()` also has a `list-failed` refusal for a listing that failed. The core reports the listing's own error first, so a read with the built-in converter gives that error, for example `DENIED` or `IO_ERROR`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-fs-tools/read",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A bounded file reader for TypeScript agent tools.",
   "license": "MIT",
   "repository": {
@@ -46,7 +46,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@better-fs-tools/fs": "^0.1.0"
+    "@better-fs-tools/fs": "^0.2.0"
   },
   "devDependencies": {
     "typebox": "^1.3.16"