@better-fs-tools/read 0.0.0-tegami-trusted-publish-setup → 0.2.0

package/dist/core/cursor.js

@@ -0,0 +1,93 @@
+const INTERNAL_CHUNK_BYTES = 64 * 1_024;
+export class AbortReadError extends Error {
+}
+export class ByteCursor {
+    iterator;
+    chunk = null;
+    pushed = null;
+    offset = 0;
+    constructor(source) {
+        this.iterator = source[Symbol.asyncIterator]();
+    }
+    unshift(piece) {
+        if (this.pushed !== null)
+            throw new Error("Only one byte piece can be pushed back");
+        this.pushed = piece;
+    }
+    async next(signal) {
+        if (this.pushed !== null) {
+            const piece = this.pushed;
+            this.pushed = null;
+            return { done: false, value: piece };
+        }
+        while (this.chunk === null || this.offset >= this.chunk.byteLength) {
+            this.chunk = null;
+            this.offset = 0;
+            const item = await this.pull(signal);
+            assertIteratorResult(item);
+            if (item.done)
+                return { done: true, value: undefined };
+            assertChunk(item.value);
+            if (item.value.byteLength === 0)
+                continue;
+            this.chunk = item.value;
+        }
+        const end = Math.min(this.offset + INTERNAL_CHUNK_BYTES, this.chunk.byteLength);
+        const piece = this.chunk.subarray(this.offset, end);
+        this.offset = end;
+        if (this.offset >= this.chunk.byteLength) {
+            this.chunk = null;
+            this.offset = 0;
+        }
+        return { done: false, value: piece };
+    }
+    async close() {
+        const iterator = this.iterator;
+        this.iterator = null;
+        this.chunk = null;
+        this.pushed = null;
+        try {
+            await iterator?.return?.(undefined);
+        }
+        catch {
+            // An adapter that fails to unwind is not allowed to fail the read.
+        }
+    }
+    async pull(signal) {
+        const iterator = this.iterator;
+        if (iterator === null)
+            return { done: true, value: undefined };
+        return raceAbort(() => iterator.next(), signal);
+    }
+}
+export async function raceAbort(start, signal) {
+    if (!signal)
+        return start();
+    if (signal.aborted)
+        throw new AbortReadError("aborted");
+    let removeListener;
+    const aborted = new Promise((_resolve, reject) => {
+        const onAbort = () => reject(new AbortReadError("aborted"));
+        signal.addEventListener("abort", onAbort, { once: true });
+        removeListener = () => signal.removeEventListener("abort", onAbort);
+    });
+    try {
+        return await Promise.race([(async () => start())(), aborted]);
+    }
+    finally {
+        removeListener?.();
+    }
+}
+function assertChunk(chunk) {
+    if (!(chunk instanceof Uint8Array)) {
+        throw new TypeError("Byte source yielded a non-Uint8Array chunk");
+    }
+}
+function assertIteratorResult(item) {
+    if (item === null ||
+        typeof item !== "object" ||
+        !("done" in item) ||
+        typeof item.done !== "boolean") {
+        throw new TypeError("Byte source returned an invalid iterator result");
+    }
+}

package/dist/core/deps.d.ts

@@ -0,0 +1,6 @@
+import type { FileSystem } from "@better-fs-tools/fs";
+import type { ReadDependencies, ReadToolDeps } from "../contract/deps.ts";
+import type { ReadStateStore } from "../contract/state.ts";
+export declare function resolveDependencies<THost>(deps: ReadToolDeps<THost>): ReadDependencies<THost>;
+export declare function isFileSystem(value: unknown): value is FileSystem;
+export declare function isStateStore(value: unknown): value is ReadStateStore;

package/dist/core/deps.js

@@ -0,0 +1,121 @@
+import { defaultClassifiers } from "../classifiers/index.js";
+import { lineNumberFormatter } from "../formatters/index.js";
+import { defaultSuggest } from "../suggest/index.js";
+import { isRecord } from "./input.js";
+import { resolveReadLimits } from "./limits.js";
+import { resolveReadMessages } from "./messages.js";
+const KNOWN_DEPENDENCY_KEYS = new Set([
+    "fs",
+    "limits",
+    "messages",
+    "classifiers",
+    "resolve",
+    "suggest",
+    "authorize",
+    "converters",
+    "budget",
+    "hooks",
+    "state",
+    "digest",
+    "clock",
+    "formatter",
+]);
+export function resolveDependencies(deps) {
+    if (!isRecord(deps))
+        throw new TypeError("read tool dependencies must be an object");
+    for (const key of Object.keys(deps)) {
+        if (!KNOWN_DEPENDENCY_KEYS.has(key))
+            throw new TypeError(`Unknown read tool dependency: ${key}`);
+    }
+    const { fs } = deps;
+    if (typeof fs !== "function" && !isFileSystem(fs)) {
+        throw new TypeError("fs must be a FileSystem or a function that returns one");
+    }
+    const classifiers = deps.classifiers ?? defaultClassifiers();
+    if (!Array.isArray(classifiers) || classifiers.length === 0) {
+        throw new TypeError("classifiers must be a non-empty array");
+    }
+    const formatter = deps.formatter ?? lineNumberFormatter();
+    if (!isRecord(formatter) || typeof formatter.format !== "function") {
+        throw new TypeError("formatter must have a format function");
+    }
+    const resolve = deps.resolve ?? null;
+    if (resolve !== null && (!isRecord(resolve) || typeof resolve.resolve !== "function")) {
+        throw new TypeError("resolve must be a path resolver or null");
+    }
+    const suggest = deps.suggest === undefined ? defaultSuggest() : deps.suggest;
+    if (suggest !== null && typeof suggest !== "function") {
+        throw new TypeError("suggest must be a function or null");
+    }
+    const authorize = deps.authorize ?? null;
+    if (authorize !== null && (!isRecord(authorize) || typeof authorize.authorize !== "function")) {
+        throw new TypeError("authorize must be an authorizer or null");
+    }
+    const converters = deps.converters === undefined ? [] : deps.converters;
+    if (!Array.isArray(converters) || !converters.every(isConverter)) {
+        throw new TypeError("converters must be an array of file and directory converters");
+    }
+    const budget = deps.budget ?? null;
+    if (budget !== null && !isViewBudget(budget)) {
+        throw new TypeError("budget must be a view budget with an id, measure, and a positive max, or null");
+    }
+    const hooks = deps.hooks === undefined ? [] : deps.hooks;
+    if (!Array.isArray(hooks) || !hooks.every(isHook)) {
+        throw new TypeError("hooks must be an array of hooks with an id and afterRead");
+    }
+    const clock = deps.clock ?? (() => new Date());
+    if (typeof clock !== "function")
+        throw new TypeError("clock must be a function");
+    const state = deps.state ?? null;
+    if (state !== null && typeof state !== "function" && !isStateStore(state)) {
+        throw new TypeError("state must be a store, a function that returns one, or null");
+    }
+    const digest = deps.digest ?? null;
+    if (state !== null && digest === null) {
+        throw new TypeError("state needs a digest: records name the digest that made them");
+    }
+    return Object.freeze({
+        fs,
+        limits: resolveReadLimits(deps.limits),
+        messages: resolveReadMessages(deps.messages),
+        classifiers: Object.freeze([...classifiers]),
+        resolve,
+        suggest,
+        authorize,
+        converters: Object.freeze([...converters]),
+        budget,
+        hooks: Object.freeze([...hooks]),
+        state,
+        digest,
+        clock,
+        formatter,
+    });
+}
+export function isFileSystem(value) {
+    return isRecord(value) && typeof value.open === "function";
+}
+function isConverter(value) {
+    if (!isRecord(value) || typeof value.id !== "string" || typeof value.convert !== "function") {
+        return false;
+    }
+    if (value.target === "directory")
+        return true;
+    return value.target === "file" && typeof value.accepts === "function";
+}
+function isViewBudget(value) {
+    return (isRecord(value) &&
+        typeof value.id === "string" &&
+        typeof value.measure === "function" &&
+        typeof value.max === "number" &&
+        Number.isFinite(value.max) &&
+        value.max > 0);
+}
+function isHook(value) {
+    return isRecord(value) && typeof value.id === "string" && typeof value.afterRead === "function";
+}
+export function isStateStore(value) {
+    return (isRecord(value) &&
+        typeof value.get === "function" &&
+        typeof value.put === "function" &&
+        typeof value.delete === "function");
+}

package/dist/core/directory.d.ts

@@ -0,0 +1,16 @@
+import type { FileSystem, NotAFileError } from "@better-fs-tools/fs";
+import type { DirectoryConverter } from "../contract/extensions.ts";
+import type { ReadRequest } from "../contract/input.ts";
+import type { ReadReport } from "../contract/result.ts";
+import type { CallScope } from "./call-scope.ts";
+export declare function directoryConverter<THost>(scope: CallScope<THost>, fs: FileSystem): DirectoryConverter<THost> | null;
+export interface ConvertDirectoryInput<THost> {
+    readonly fs: FileSystem;
+    readonly request: ReadRequest;
+    readonly openedPath: string;
+    readonly error: NotAFileError;
+    readonly resolvedFrom: string | null;
+    readonly converter: DirectoryConverter<THost>;
+    readonly scope: CallScope<THost>;
+}
+export declare function convertDirectory<THost>(input: ConvertDirectoryInput<THost>): Promise<ReadReport>;

package/dist/core/directory.js

@@ -0,0 +1,113 @@
+import { checkConvertOutcome, firstMediaType, mediaBytes, refusedOutcome, scanConvertedText, tooLarge, } from "./converted.js";
+import { AbortReadError, raceAbort } from "./cursor.js";
+import { extensionId } from "./extension-error.js";
+import { ReadStop, fromFileSystemError } from "./outcomes.js";
+import { textOutcome } from "./text-outcome.js";
+const DIRECTORY = Object.freeze({
+    kind: "directory",
+    classifier: "fs",
+    code: null,
+    mimeType: null,
+    confidence: "high",
+    reasons: Object.freeze(["directory"]),
+});
+export function directoryConverter(scope, fs) {
+    if (typeof fs.list !== "function")
+        return null;
+    for (const converter of scope.deps.converters) {
+        if (converter.target === "directory")
+            return converter;
+    }
+    return null;
+}
+export async function convertDirectory(input) {
+    const { fs, request, openedPath: path, error, converter, scope } = input;
+    const { limits, messages } = scope.deps;
+    // A virtual backend's EISDIR has no target, so the opened path stands in.
+    const dir = error.target?.resolvedPath ?? path;
+    const file = {
+        requestedPath: request.path,
+        resolvedPath: dir,
+        displayPath: error.target?.displayPath ?? path,
+        backend: fs.id,
+        size: null,
+        mtimeMs: null,
+        identity: null,
+        mimeType: null,
+        resolvedFrom: input.resolvedFrom,
+        version: null,
+    };
+    let listing = null;
+    const convertInput = Object.freeze({
+        path,
+        target: error.target,
+        async list() {
+            const listed = await scope.list("open", dir, file.displayPath);
+            listing ??= listed;
+            return listed;
+        },
+    });
+    const throwIfListingFailed = () => {
+        scope.checkAbort();
+        scope.throwHeld();
+        const listed = listing;
+        if (listed !== null && !listed.ok) {
+            throw new ReadStop(fromFileSystemError(messages, request, listed.error, scope.phase));
+        }
+    };
+    const failed = (thrown) => {
+        throwIfListingFailed();
+        return scope.extensionFailure("converters", extensionId(converter, thrown));
+    };
+    scope.enter("conversion");
+    let produced;
+    try {
+        produced = await raceAbort(() => converter.convert(convertInput, scope.hookContext()), scope.signal);
+    }
+    catch (thrown) {
+        throw failed(thrown);
+    }
+    throwIfListingFailed();
+    const outcome = checkConvertOutcome(produced);
+    if (outcome === null)
+        throw failed();
+    if (outcome.kind === "refuse") {
+        return refusedOutcome(request, file, DIRECTORY, outcome.code, outcome.note);
+    }
+    if (outcome.kind === "media") {
+        if (mediaBytes(outcome.parts) > limits.maxMediaBytes) {
+            return tooLarge(messages, request, file, DIRECTORY, "media", limits.maxMediaBytes);
+        }
+        return {
+            tool: "read",
+            status: "media",
+            request,
+            file,
+            classification: DIRECTORY,
+            conversion: { converter: converter.id, mimeType: firstMediaType(outcome.parts) },
+            parts: outcome.parts,
+            observation: null,
+            notes: outcome.notes ?? [],
+        };
+    }
+    let scan;
+    try {
+        scan = await scanConvertedText(outcome.text, request, file, scope);
+    }
+    catch (thrown) {
+        if (thrown instanceof ReadStop || thrown instanceof AbortReadError)
+            throw thrown;
+        throw failed(thrown);
+    }
+    return textOutcome({
+        deps: scope.deps,
+        fs: null,
+        request,
+        file,
+        classification: DIRECTORY,
+        conversion: { converter: converter.id, mimeType: outcome.mimeType },
+        scan,
+        contentId: null,
+        notes: outcome.notes ?? [],
+    });
+}

package/dist/core/extension-error.d.ts

@@ -0,0 +1,9 @@
+/** Lets EXTENSION_FAILED name the failing step of a composite extension. */
+export declare class ExtensionStepError extends Error {
+    readonly id: string;
+    constructor(id: string, cause: unknown);
+}
+export declare function stepFailure(step: {
+    readonly id: string;
+}, error: unknown): ExtensionStepError;
+export declare function extensionId(extension: unknown, error?: unknown): string | null;

package/dist/core/extension-error.js

@@ -0,0 +1,18 @@
+/** Lets EXTENSION_FAILED name the failing step of a composite extension. */
+export class ExtensionStepError extends Error {
+    id;
+    constructor(id, cause) {
+        super(`extension step ${id} failed`, { cause });
+        this.id = id;
+    }
+}
+export function stepFailure(step, error) {
+    return error instanceof ExtensionStepError ? error : new ExtensionStepError(step.id, error);
+}
+export function extensionId(extension, error) {
+    if (error instanceof ExtensionStepError)
+        return error.id;
+    if (extension === null || typeof extension !== "object" || !("id" in extension))
+        return null;
+    return typeof extension.id === "string" ? extension.id : null;
+}

package/dist/core/format.d.ts

@@ -0,0 +1,8 @@
+import type { ReadContext } from "../contract/context.ts";
+import type { ReadDependencies } from "../contract/deps.ts";
+import type { ContentPart, ReadReport, ReadResult } from "../contract/result.ts";
+export declare function formatResult<THost>(deps: ReadDependencies<THost>, call: ReadContext<THost>, outcome: ReadReport): ReadResult;
+/** The text parts of any tool result's `content`, joined with newlines. */
+export declare function textOf(result: {
+    readonly content: readonly ContentPart[];
+}): string;

package/dist/core/format.js

@@ -0,0 +1,29 @@
+import { lineNumberFormatter } from "../formatters/index.js";
+export function formatResult(deps, call, outcome) {
+    const ctx = {
+        digest: deps.digest,
+        limits: deps.limits,
+        mode: "model",
+        call,
+    };
+    let content = null;
+    try {
+        content = toContent(deps.formatter.format(outcome, ctx));
+    }
+    catch { }
+    if (content !== null)
+        return { ...outcome, content };
+    return { ...outcome, content: toContent(lineNumberFormatter().format(outcome, ctx)) ?? [] };
+}
+function toContent(output) {
+    if (typeof output === "string")
+        return [{ type: "text", text: output }];
+    return Array.isArray(output) ? [...output] : null;
+}
+/** The text parts of any tool result's `content`, joined with newlines. */
+export function textOf(result) {
+    return result.content
+        .filter((part) => part.type === "text")
+        .map((part) => part.text)
+        .join("\n");
+}

package/dist/core/hooks.d.ts

@@ -0,0 +1,3 @@
+import type { ReadReport } from "../contract/result.ts";
+import type { CallScope } from "./call-scope.ts";
+export declare function runHooks<THost>(scope: CallScope<THost>, outcome: ReadReport): Promise<ReadReport>;

package/dist/core/hooks.js

@@ -0,0 +1,140 @@
+import { isContentPart } from "./converted.js";
+import { raceAbort } from "./cursor.js";
+import { extensionId } from "./extension-error.js";
+import { isRecord } from "./input.js";
+import { withEditedView } from "./observation.js";
+import { isNote } from "./outcomes.js";
+import { same } from "./same.js";
+const HOOK_FROZEN_FIELDS = [
+    "tool",
+    "request",
+    "file",
+    "classification",
+    "conversion",
+    "truncation",
+    "continuation",
+    "totals",
+    "observation",
+];
+const STATUSES = new Set(["ok", "media", "unsupported", "error"]);
+export async function runHooks(scope, outcome) {
+    const { hooks } = scope.deps;
+    if (hooks.length === 0)
+        return outcome;
+    scope.enter("hooks");
+    const ctx = Object.freeze({
+        ...scope.hookContext(),
+        previous: await previousRecord(scope, outcome),
+    });
+    let current = outcome;
+    for (const hook of hooks) {
+        current = await runHook(scope, hook, current, ctx);
+    }
+    return current;
+}
+async function runHook(scope, hook, before, ctx) {
+    scope.checkAbort();
+    let produced;
+    try {
+        produced = await raceAbort(() => hook.afterRead(before, ctx), scope.signal);
+    }
+    catch (error) {
+        scope.checkAbort();
+        throw scope.extensionFailure("hooks", extensionId(hook, error));
+    }
+    scope.checkAbort();
+    if (!keepsRules(before, produced))
+        throw scope.extensionFailure("hooks", extensionId(hook));
+    if (!viewChanged(before, produced))
+        return produced;
+    return markEdited(scope, hook.id, produced);
+}
+function markEdited(scope, hookId, outcome) {
+    const { messages, digest } = scope.deps;
+    const note = {
+        code: "view-modified",
+        severity: "info",
+        message: messages.viewModified({ hook: hookId }),
+        data: { hook: hookId },
+    };
+    const notes = [...outcome.notes, note];
+    if (outcome.status !== "ok" && outcome.status !== "media")
+        return { ...outcome, notes };
+    if (outcome.observation === null || digest === null)
+        return { ...outcome, notes };
+    const view = outcome.status === "ok" ? viewText(outcome) : outcome.parts;
+    return { ...outcome, notes, observation: withEditedView(digest, outcome.observation, view) };
+}
+async function previousRecord(scope, outcome) {
+    if (outcome.file === null)
+        return null;
+    const store = scope.stateStore();
+    if (store === null)
+        return null;
+    let record;
+    try {
+        record = await store.get(outcome.file.resolvedPath);
+    }
+    catch {
+        // Session state is a cache: a failing store never fails the read.
+        return null;
+    }
+    return isRecord(record) && record.schema === 2 ? record : null;
+}
+function keepsRules(before, after) {
+    if (!isRecord(after) || !STATUSES.has(after.status))
+        return false;
+    if (!Array.isArray(after.notes) || !after.notes.every(isNote))
+        return false;
+    const refused = before.status === "error" || before.status === "unsupported";
+    if (refused && (after.status === "ok" || after.status === "media"))
+        return false;
+    if (!editableFieldsWellTyped(after))
+        return false;
+    for (const key of HOOK_FROZEN_FIELDS) {
+        const had = Object.hasOwn(before, key);
+        const has = Object.hasOwn(after, key);
+        if (had && has && !same(before[key], after[key]))
+            return false;
+        if (had !== has && before.status === after.status)
+            return false;
+    }
+    return true;
+}
+function editableFieldsWellTyped(after) {
+    switch (after.status) {
+        case "ok": {
+            const { view } = after;
+            return (isRecord(view) &&
+                Array.isArray(view.lines) &&
+                view.lines.every((line) => isRecord(line) &&
+                    typeof line.number === "number" &&
+                    typeof line.text === "string" &&
+                    typeof line.clamped === "boolean"));
+        }
+        case "media":
+            return Array.isArray(after.parts) && after.parts.every(isContentPart);
+        case "unsupported":
+            return typeof after.code === "string" && after.code !== "";
+        default: {
+            const { error } = after;
+            return (isRecord(error) &&
+                typeof error.code === "string" &&
+                error.code !== "" &&
+                typeof error.phase === "string" &&
+                typeof error.message === "string");
+        }
+    }
+}
+function viewChanged(before, after) {
+    if (before.status === "ok" && after.status === "ok") {
+        const lines = (outcome) => outcome.view.lines.map((line) => [line.number, line.text]);
+        return !same(lines(before), lines(after));
+    }
+    if (before.status === "media" && after.status === "media")
+        return !same(before.parts, after.parts);
+    return false;
+}
+function viewText(outcome) {
+    return outcome.view.lines.map((line) => line.text).join("\n");
+}

package/dist/core/input.d.ts

@@ -0,0 +1,10 @@
+import type { ReadRequest } from "../contract/input.ts";
+import type { ReadLimits } from "../contract/limits.ts";
+/**
+ * Validates raw read input. `offset` defaults to 1 and `limit` to `limits.maxLines`,
+ * and a larger `limit` is lowered to it. Throws TypeError on an unknown key, a
+ * blank path or one with NUL, or an offset or limit that is not a positive integer.
+ */
+export declare function parseReadInput(input: unknown, limits: Readonly<ReadLimits>): ReadRequest;
+export declare function clampedLimit(input: unknown, request: ReadRequest): number | null;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/core/input.js

@@ -0,0 +1,45 @@
+const KEYS = new Set(["path", "offset", "limit"]);
+/**
+ * Validates raw read input. `offset` defaults to 1 and `limit` to `limits.maxLines`,
+ * and a larger `limit` is lowered to it. Throws TypeError on an unknown key, a
+ * blank path or one with NUL, or an offset or limit that is not a positive integer.
+ */
+export function parseReadInput(input, limits) {
+    if (!isRecord(input))
+        throw new TypeError("Read input must be an object");
+    for (const key of Object.keys(input)) {
+        if (!KEYS.has(key))
+            throw new TypeError(`Unknown read input key: ${key}`);
+    }
+    const path = validatePath(input.path);
+    const offset = input.offset === undefined ? 1 : validateInteger(input.offset, "offset");
+    const limit = input.limit === undefined
+        ? limits.maxLines
+        : Math.min(validateInteger(input.limit, "limit"), limits.maxLines);
+    return {
+        path,
+        offset,
+        limit,
+        ranged: input.offset !== undefined || input.limit !== undefined,
+    };
+}
+function validatePath(value) {
+    if (typeof value !== "string" || value.trim() === "" || value.includes("\0")) {
+        throw new TypeError("path must be a non-empty string without NUL");
+    }
+    return value;
+}
+function validateInteger(value, name) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive safe integer`);
+    }
+    return value;
+}
+export function clampedLimit(input, request) {
+    if (!isRecord(input) || typeof input.limit !== "number")
+        return null;
+    return input.limit > request.limit ? input.limit : null;
+}
+export function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/dist/core/limits.d.ts

@@ -0,0 +1,9 @@
+import type { ReadLimits } from "../contract/limits.ts";
+/** The default read limits. They are not ceilings: a host may raise any of them. */
+export declare const defaultReadLimits: Readonly<ReadLimits>;
+/**
+ * Merges overrides over `defaultReadLimits`. Throws TypeError on an unknown key,
+ * a value that is not a positive safe integer, or a `sampleBytes` you set above
+ * `maxScanBytes`. A default `sampleBytes` above your `maxScanBytes` is lowered to it.
+ */
+export declare function resolveReadLimits(overrides?: Partial<ReadLimits>): Readonly<ReadLimits>;

package/dist/core/limits.js

@@ -0,0 +1,43 @@
+/** The default read limits. They are not ceilings: a host may raise any of them. */
+export const defaultReadLimits = Object.freeze({
+    maxLines: 2_000,
+    maxViewBytes: 50 * 1_024,
+    maxCharsPerLine: 2_000,
+    maxScanBytes: 64 * 1_024 * 1_024,
+    sampleBytes: 8_192,
+    maxDirectoryEntries: 200,
+    maxSuggestions: 5,
+    maxConvertBytes: 64 * 1_024 * 1_024,
+    maxMediaBytes: 5 * 1_024 * 1_024,
+});
+const LIMIT_KEYS = Object.keys(defaultReadLimits);
+/**
+ * Merges overrides over `defaultReadLimits`. Throws TypeError on an unknown key,
+ * a value that is not a positive safe integer, or a `sampleBytes` you set above
+ * `maxScanBytes`. A default `sampleBytes` above your `maxScanBytes` is lowered to it.
+ */
+export function resolveReadLimits(overrides = {}) {
+    if (overrides === null || typeof overrides !== "object" || Array.isArray(overrides)) {
+        throw new TypeError("limits must be an object");
+    }
+    const unknown = Object.keys(overrides).find((key) => !Object.hasOwn(defaultReadLimits, key));
+    if (unknown !== undefined)
+        throw new TypeError(`Unknown read limit: ${unknown}`);
+    const resolved = { ...defaultReadLimits };
+    for (const key of LIMIT_KEYS) {
+        const value = overrides[key];
+        if (value === undefined)
+            continue;
+        if (!Number.isSafeInteger(value) || value <= 0) {
+            throw new TypeError(`${key} must be a positive safe integer`);
+        }
+        resolved[key] = value;
+    }
+    if (resolved.sampleBytes > resolved.maxScanBytes) {
+        if (overrides.sampleBytes !== undefined) {
+            throw new TypeError("sampleBytes must not be more than maxScanBytes");
+        }
+        resolved.sampleBytes = resolved.maxScanBytes;
+    }
+    return Object.freeze(resolved);
+}