@poe-platform/safe-bash 0.1.630 → 0.1.632

package/dist/safe-bash/shell/input.js

@@ -1,8 +1,290 @@
-import { PublicDiagnostic } from "../diagnostics.js";
 import { FsError, toByteSource } from "../contracts/index.js";
-import { yieldTurn } from "../contracts/yield.js";
+import { monotonicNow, yieldTurn } from "../contracts/yield.js";
 import { Budget, interruptible } from "./runtime.js";
-import { concatShellValues, shellValueFromBytes } from "../contracts/value.js";
+import { concatShellValues, shellValueBytes, shellValueFromBytes, shellValueText } from "../contracts/value.js";
+import { openCommandFile } from "../contracts/filesystem-descriptor.js";
+const inputBuffers = new WeakMap();
+const inputByteLength = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), "byteLength").get;
+export function inputBufferUsage(budget) {
+    let bytes = 0;
+    const leases = inputBuffers.get(budget);
+    if (leases)
+        for (const lease of leases)
+            bytes += lease.capacity;
+    return Object.freeze({ bytes, buffers: leases?.size ?? 0 });
+}
+class InputBufferLease {
+    budget;
+    capacity;
+    bytes;
+    constructor(budget, capacity, allocate) {
+        this.budget = budget;
+        this.capacity = capacity;
+        budget.signal.throwIfAborted();
+        if (!Number.isSafeInteger(capacity) || capacity <= 0 || capacity > Math.max(1, budget.limits.maxInputBytes)) {
+            throw new FsError("EFBIG", { syscall: "read" });
+        }
+        let leases = inputBuffers.get(budget);
+        if (!leases) {
+            leases = new Set();
+            inputBuffers.set(budget, leases);
+        }
+        leases.add(this);
+        try {
+            this.bytes = allocate();
+            budget.signal.throwIfAborted();
+        }
+        catch (error) {
+            this.release();
+            budget.signal.throwIfAborted();
+            throw error;
+        }
+    }
+    release() {
+        this.bytes = undefined;
+        const leases = inputBuffers.get(this.budget);
+        leases?.delete(this);
+        if (!leases?.size)
+            inputBuffers.delete(this.budget);
+    }
+}
+export function prepareBytesInput(value, budget) {
+    budget.signal.throwIfAborted();
+    if (typeof value !== "string" && !(value instanceof Uint8Array))
+        throw new TypeError("Shell input must be a string or Uint8Array");
+    const length = typeof value === "string" ? Buffer.byteLength(value) : inputByteLength.call(value);
+    if (length > budget.limits.maxInputBytes)
+        throw new FsError("EFBIG", { syscall: "read" });
+    let buffer;
+    let sent = false;
+    let closed = false;
+    let closing;
+    const close = () => {
+        closed = true;
+        buffer?.release();
+        buffer = undefined;
+        budget.signal.removeEventListener("abort", aborted);
+        return closing ??= Promise.resolve();
+    };
+    const aborted = () => { void close(); };
+    try {
+        if (length) {
+            buffer = new InputBufferLease(budget, length, () => typeof value === "string" ? new TextEncoder().encode(value) : new Uint8Array(value));
+        }
+        budget.signal.addEventListener("abort", aborted, { once: true });
+        const source = {
+            [Symbol.asyncIterator]() { return this; },
+            async next() {
+                budget.signal.throwIfAborted();
+                const bytes = buffer?.bytes;
+                if (closed || sent || !bytes?.byteLength)
+                    return { done: true, value: undefined };
+                sent = true;
+                return { done: false, value: bytes };
+            },
+            async return() { await close(); return { done: true, value: undefined }; },
+        };
+        return Object.freeze({ source, close, options: Object.freeze({ provenance: "stream", poll: () => {
+                    budget.signal.throwIfAborted();
+                    if (closed)
+                        throw new Error("Prepared input is closed");
+                    return !sent && length ? "ready" : "eof";
+                } }) });
+    }
+    catch (error) {
+        void close();
+        throw error;
+    }
+}
+export async function prepareFileInput(context, path, budget, inputProfile = context.fs, admittedStat) {
+    const { fs, signal: parent, registerCleanup: register, cleanupFailurePrioritySignal } = context;
+    const registerCleanup = register.bind(context);
+    const signal = AbortSignal.any([parent, budget.signal]);
+    const readerController = new AbortController();
+    const readSignal = AbortSignal.any([signal, readerController.signal]);
+    let descriptor;
+    let legacy;
+    let legacySource;
+    let stat;
+    let accepting = true;
+    let ended = false;
+    let buffer;
+    let size = 0;
+    let pendingReads = 0;
+    let work = Promise.resolve();
+    let admitted;
+    const acquisition = new Promise(resolve => { admitted = resolve; });
+    let closing;
+    let teardownFailed = false;
+    const close = () => {
+        accepting = false;
+        if (pendingReads && !readerController.signal.aborted)
+            readerController.abort(new FsError("EBADF", { syscall: "read", path }));
+        closing ??= (async () => {
+            await acquisition;
+            await work;
+            try {
+                if (descriptor)
+                    await descriptor.close();
+                else
+                    await legacy?.return?.();
+            }
+            catch (error) {
+                teardownFailed = true;
+                (cleanupFailurePrioritySignal ?? signal).throwIfAborted();
+                throw error;
+            }
+            finally {
+                descriptor = undefined;
+                legacy = undefined;
+                legacySource = undefined;
+                buffer?.release();
+                buffer = undefined;
+                signal.removeEventListener("abort", aborted);
+            }
+            signal.throwIfAborted();
+        })();
+        void closing.catch(() => { });
+        return closing;
+    };
+    const aborted = () => { void close().catch(() => { }); };
+    const check = () => {
+        signal.throwIfAborted();
+        if (!accepting)
+            throw new FsError("EBADF", { syscall: "read", path });
+    };
+    try {
+        registerCleanup(cleanupFailurePrioritySignal === undefined ? close : async () => {
+            try {
+                await close();
+            }
+            catch (error) {
+                if (teardownFailed)
+                    cleanupFailurePrioritySignal.throwIfAborted();
+                throw error;
+            }
+        });
+        signal.addEventListener("abort", aborted, { once: true });
+        check();
+        const capabilities = await fs.capabilitiesFor?.(path, { signal }) ?? fs.capabilities;
+        check();
+        let provenance = "unknown";
+        if (capabilities.open === true || capabilities.open !== false && typeof fs.open === "function") {
+            descriptor = await openCommandFile({ fs, signal, registerCleanup, cleanupFailurePrioritySignal }, path, { access: "read", signal });
+        }
+        else {
+            stat = admittedStat ?? await fs.stat(path, { signal });
+            check();
+            legacySource = await fileInput(fs, path, budget.limits.maxInputBytes, readSignal, inputProfile, { stat, registerCleanup });
+            legacy = legacySource[Symbol.asyncIterator]();
+            stat = legacySource.stat ?? stat;
+        }
+        check();
+        if (descriptor) {
+            stat = await descriptor.stat({ signal });
+            check();
+        }
+        if (stat) {
+            if (stat.type === "directory")
+                throw new FsError("EISDIR", { syscall: "read", path });
+            if (descriptor || legacySource?.stat)
+                provenance = stat.type === "file" ? "regular" : stat.type === "character" ? "stream" : "unknown";
+        }
+        const source = {
+            [Symbol.asyncIterator]() { return this; },
+            next(maximum = 64 * 1024) {
+                try {
+                    signal.throwIfAborted();
+                    if (!Number.isSafeInteger(maximum) || maximum <= 0)
+                        throw new RangeError("Input chunk size must be a positive safe integer");
+                    if (ended)
+                        return Promise.resolve({ done: true, value: undefined });
+                    check();
+                }
+                catch (error) {
+                    return Promise.reject(error);
+                }
+                pendingReads++;
+                const operation = work.then(async () => {
+                    signal.throwIfAborted();
+                    if (ended)
+                        return { done: true, value: undefined };
+                    check();
+                    if (legacy) {
+                        const result = await (legacySource?.readChunk ? legacySource.readChunk(maximum) : legacy.next());
+                        check();
+                        ended = result.done === true && provenance !== "regular";
+                        return result;
+                    }
+                    if (!buffer) {
+                        const capacity = Math.min(64 * 1024, budget.limits.maxInputBytes) || 1;
+                        buffer = new InputBufferLease(budget, capacity, () => new Uint8Array(capacity));
+                    }
+                    const bytes = buffer.bytes;
+                    const remaining = budget.limits.maxInputBytes - size;
+                    const chunk = bytes.subarray(0, Math.min(maximum, remaining >= bytes.length ? bytes.length : remaining + 1));
+                    const length = await descriptor.read(chunk, null, { signal: readSignal });
+                    check();
+                    if (!Number.isSafeInteger(length) || length < 0 || length > chunk.length)
+                        throw new FsError("EIO", { syscall: "read", path });
+                    if (length > budget.limits.maxInputBytes - size)
+                        throw new FsError("EFBIG", { syscall: "read", path });
+                    size += length;
+                    const done = length === 0;
+                    ended = done && provenance !== "regular";
+                    return done ? { done: true, value: undefined } : { done: false, value: chunk.subarray(0, length) };
+                });
+                work = operation.then(() => { pendingReads--; }, () => { pendingReads--; });
+                return operation.then(async (result) => {
+                    if (result.done && provenance !== "regular") {
+                        if (legacy)
+                            await close();
+                        else {
+                            buffer?.release();
+                            buffer = undefined;
+                        }
+                    }
+                    signal.throwIfAborted();
+                    return result;
+                }, async (error) => {
+                    try {
+                        await close();
+                    }
+                    catch { }
+                    signal.throwIfAborted();
+                    throw error;
+                });
+            },
+            async return() { await close(); return { done: true, value: undefined }; },
+        };
+        admitted();
+        const seek = legacySource?.seek;
+        return Object.freeze({ source, close, options: Object.freeze({
+                provenance, eof: provenance === "regular" ? "retryable" : "terminal",
+                ...(descriptor ? { descriptor } : {}), ...(stat ? { stat } : {}),
+                readChunk: source.next.bind(source),
+                ...(seek ? { async seek(position, callerSignal) {
+                        callerSignal.throwIfAborted();
+                        check();
+                        await work;
+                        check();
+                        callerSignal.throwIfAborted();
+                        await seek.call(legacySource, position, callerSignal);
+                        check();
+                        ended = false;
+                    } } : {}),
+            }) });
+    }
+    catch (error) {
+        admitted();
+        try {
+            await close();
+        }
+        catch { }
+        signal.throwIfAborted();
+        throw error;
+    }
+}
 export async function fileInput(fs, path, maxBytes, signal, inputProfile = fs, ownership) {
     let admittedCapabilities;
     if (ownership?.stat.type === "file") {
@@ -18,7 +300,6 @@ export async function fileInput(fs, path, maxBytes, signal, inputProfile = fs, o
             })();
             return closing;
         };
-        ownership.registerCleanup(close);
         const work = async (operation) => {
             signal.throwIfAborted();
             if (closed)
@@ -31,6 +312,7 @@ export async function fileInput(fs, path, maxBytes, signal, inputProfile = fs, o
         try {
             const capabilities = admittedCapabilities = await work(() => Promise.resolve(fs.capabilitiesFor?.(path, { signal }) ?? fs.capabilities));
             if (capabilities.retainedRead === true && fs.openReadFile) {
+                ownership.registerCleanup(close);
                 try {
                     await work(async () => { handle = await fs.openReadFile(path, { signal }); });
                 }
@@ -161,8 +443,80 @@ export async function fileInput(fs, path, maxBytes, signal, inputProfile = fs, o
         }),
     };
 }
+const inputClock = {
+    now: monotonicNow,
+    schedule(delayMs, expire) {
+        const timer = setTimeout(expire, Math.min(delayMs, 2_147_483_647));
+        return () => clearTimeout(timer);
+    },
+};
+class InputDeadline {
+    clock;
+    parent;
+    #controller = new AbortController();
+    #expiresAt;
+    #cancel;
+    #closed = false;
+    signal;
+    constructor(clock, timeoutMs, parent) {
+        this.clock = clock;
+        this.parent = parent;
+        const now = clock.now();
+        this.#expiresAt = now + timeoutMs;
+        if (!Number.isFinite(now) || !Number.isFinite(this.#expiresAt))
+            throw new RangeError("Invalid input clock deadline");
+        this.signal = AbortSignal.any([parent, this.#controller.signal]);
+        parent.throwIfAborted();
+        parent.addEventListener("abort", this.close, { once: true });
+        try {
+            this.#schedule();
+        }
+        catch (error) {
+            this.close();
+            throw error;
+        }
+    }
+    expired() {
+        this.parent.throwIfAborted();
+        if (!this.#closed && this.clock.now() >= this.#expiresAt) {
+            this.#controller.abort();
+            this.close();
+        }
+        return this.#controller.signal.aborted;
+    }
+    #schedule() {
+        const cancel = this.clock.schedule(Math.max(0, this.#expiresAt - this.clock.now()), () => {
+            this.#cancel = undefined;
+            if (this.#closed || this.parent.aborted)
+                return;
+            if (!this.expired())
+                this.#schedule();
+        });
+        if (this.#closed)
+            cancel();
+        else
+            this.#cancel = cancel;
+    }
+    close = () => {
+        this.#closed = true;
+        const cancel = this.#cancel;
+        this.#cancel = undefined;
+        this.parent.removeEventListener("abort", this.close);
+        try {
+            cancel?.();
+        }
+        catch (error) {
+            if (!this.parent.aborted)
+                throw error;
+        }
+    };
+}
 class InputCursor {
     #iterator;
+    #provenance;
+    #eof;
+    #poll;
+    #clock;
     #readChunk;
     #budget;
     stat;
@@ -171,28 +525,49 @@ class InputCursor {
     remainder;
     #unread = [];
     #read;
+    #readResult;
+    #readError;
+    #readSettled = false;
     #readFailed = false;
     #turn = Promise.resolve();
     #returned;
     #ended = false;
     #closed = false;
+    #active = false;
     #produced = 0;
     #boundedReads = false;
-    constructor(source, provenance, budget) {
+    constructor(source, options, budget) {
+        const { provenance = options.stat?.type === "file" ? "regular" : options.stat?.type === "character" ? "stream" : "unknown", eof = "terminal", poll, clock = inputClock } = options;
+        if (provenance !== "unknown" && provenance !== "regular" && provenance !== "stream")
+            throw new TypeError("Invalid input provenance");
+        if (eof !== "terminal" && eof !== "retryable" || eof === "retryable" && provenance !== "regular")
+            throw new TypeError("Retryable input EOF requires regular provenance");
+        if (poll !== undefined && typeof poll !== "function")
+            throw new TypeError("Invalid input polling capability");
+        const { now, schedule } = clock;
+        if (typeof now !== "function" || typeof schedule !== "function")
+            throw new TypeError("Invalid input clock");
+        this.#provenance = provenance;
+        this.#eof = eof;
+        this.#poll = poll?.bind(options);
+        this.#clock = Object.freeze({ now: now.bind(clock), schedule: schedule.bind(clock) });
         this.#iterator = source[Symbol.asyncIterator]();
-        this.#readChunk = provenance.readChunk;
+        this.#readChunk = options.readChunk?.bind(options);
         this.#budget = budget;
-        if (provenance.stat)
-            this.stat = provenance.stat;
-        if (provenance.seek)
+        if (options.stat)
+            this.stat = options.stat;
+        if (options.seek)
             this.seek = async (position, signal) => {
                 if (this.#read)
                     await interruptible(this.#read, signal);
                 signal.throwIfAborted();
-                await provenance.seek(position, signal);
+                await options.seek(position, signal);
                 this.remainder = undefined;
                 this.#unread.length = 0;
                 this.#read = undefined;
+                this.#readResult = undefined;
+                this.#readError = undefined;
+                this.#readSettled = false;
                 this.#ended = false;
                 this.position = position;
             };
@@ -209,16 +584,78 @@ class InputCursor {
         if (this.#produced > this.#budget.limits.maxInputBytes)
             this.#budget.fail("maxInputBytes");
     }
-    async consume(signal, operation) {
+    get bufferedBytes() {
+        if (this.#active)
+            return 0;
+        return (this.remainder?.length ?? 0) + this.#unread.reduce((length, chunk) => length + chunk.length, 0)
+            + (this.#readResult && !this.#readResult.done ? this.#readResult.value.length : 0);
+    }
+    readiness() {
+        if (this.#active)
+            return "blocked";
+        if (this.remainder?.length || this.#unread.some(chunk => chunk.length))
+            return "ready";
+        if (this.#readError)
+            throw this.#readError.reason;
+        if (this.#ended || this.#readResult?.done)
+            return "eof";
+        if (this.#readResult && this.#readResult.value.length)
+            return "ready";
+        if (this.#closed)
+            throw new Error("Shell input cursor is closed");
+        if (this.#provenance === "regular")
+            return "ready";
+        const readiness = this.#poll?.() ?? "unknown";
+        if (!["ready", "eof", "blocked", "unknown"].includes(readiness))
+            throw new TypeError("Invalid input readiness");
+        if (readiness === "eof" && this.#read && !this.#readSettled)
+            return "unknown";
+        return readiness;
+    }
+    probeRead() {
+        const readiness = this.readiness();
+        return { readiness: readiness === "eof" ? "ready" : readiness,
+            timeout: this.#provenance === "regular" ? "ignore" : this.#provenance === "stream" ? "honor" : "unknown" };
+    }
+    deadline(timeoutMs, signal, scope) {
+        if (timeoutMs === undefined)
+            return undefined;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            throw new RangeError("Read timeout must be positive and finite; use readiness for zero timeout");
+        if (this.#provenance === "unknown")
+            throw new TypeError("Read timeout requires explicit input provenance");
+        if (this.#provenance === "regular")
+            return undefined;
+        scope.reserve(192, 3);
+        return new InputDeadline(this.#clock, timeoutMs, signal);
+    }
+    async consume(signal, operation, interrupted) {
+        if (signal.aborted && interrupted)
+            return interrupted(signal.reason);
         signal.throwIfAborted();
         const previous = this.#turn;
         let release;
         const completed = new Promise((resolve) => { release = resolve; });
         this.#turn = previous.then(() => completed);
         try {
-            await interruptible(previous, signal);
-            signal.throwIfAborted();
-            return await operation();
+            try {
+                await interruptible(previous, signal);
+                signal.throwIfAborted();
+            }
+            catch (error) {
+                if (signal.aborted && interrupted)
+                    return await interrupted(error);
+                throw error;
+            }
+            if (this.#eof === "retryable")
+                this.#ended = false;
+            this.#active = true;
+            try {
+                return await operation();
+            }
+            finally {
+                this.#active = false;
+            }
         }
         finally {
             release();
@@ -237,6 +674,8 @@ class InputCursor {
         if (this.#ended || this.#closed)
             return { value: undefined, done: true };
         if (!this.#read) {
+            this.#readSettled = false;
+            this.#readResult = undefined;
             this.#read = Promise.resolve().then(() => this.#closed ? { value: undefined, done: true } : this.#readChunk ? this.#readChunk(maxBytes) : this.#iterator.next()).then((result) => {
                 if (result.done)
                     return { value: undefined, done: true };
@@ -245,13 +684,15 @@ class InputCursor {
                 if (this.#boundedReads && result.value.byteLength > this.#budget.limits.maxInputBytes - this.#produced)
                     this.#budget.fail("maxInputBytes");
                 this.#produced += result.value.byteLength;
-                return { value: new Uint8Array(result.value), done: false };
+                return { value: this.#boundedReads ? new Uint8Array(result.value) : result.value, done: false };
             });
+            void this.#read.then(result => { this.#readSettled = true; this.#readResult = result; }, reason => { this.#readSettled = true; this.#readError = { reason }; });
         }
         try {
             const result = await interruptible(this.#read, signal);
             signal.throwIfAborted();
             this.#read = undefined;
+            this.#readResult = undefined;
             if (result.done)
                 this.#ended = true;
             return result;
@@ -266,7 +707,7 @@ class InputCursor {
         }
     }
     async close(signal) {
-        if (this.#ended && !this.seek) {
+        if (this.#ended && this.#eof === "terminal" && !this.seek) {
             signal.throwIfAborted();
             return;
         }
@@ -285,36 +726,75 @@ class InputCursor {
         signal.throwIfAborted();
     }
 }
-class ReadText {
-    #chunks = [];
-    #pending = [];
-    append(value) {
-        if (!value)
-            return;
-        this.#pending.push(value);
-        if (this.#pending.length === 1024) {
-            this.#chunks.push(this.#pending.join(""));
-            this.#pending.length = 0;
+class ReadBuffer {
+    scope;
+    maximum;
+    #buffer = new Uint8Array();
+    #reservation;
+    length = 0;
+    constructor(scope, maximum) {
+        this.scope = scope;
+        this.maximum = maximum;
+    }
+    append(byte) {
+        if (this.length === this.#buffer.length) {
+            const capacity = Math.min(this.maximum, Math.max(64, this.#buffer.length * 2));
+            const reservation = this.scope.reserve(capacity + 64, 1);
+            try {
+                const buffer = new Uint8Array(capacity);
+                buffer.set(this.#buffer);
+                reservation.commit(buffer);
+                this.#reservation?.release();
+                this.#reservation = reservation;
+                this.#buffer = buffer;
+            }
+            catch (error) {
+                reservation.release();
+                throw error;
+            }
         }
+        this.#buffer[this.length++] = byte;
     }
-    finish() { return this.#chunks.join("") + this.#pending.join(""); }
+    bytes() { return this.#buffer.subarray(0, this.length); }
+}
+function utf8Length(first) {
+    return first >= 0xc2 && first <= 0xdf ? 2 : first >= 0xe0 && first <= 0xef ? 3 : first >= 0xf0 && first <= 0xf4 ? 4 : 1;
+}
+function utf8Continuation(first, position, byte) {
+    if (byte < 0x80 || byte > 0xbf)
+        return false;
+    return position !== 1 || (first !== 0xe0 || byte >= 0xa0) && (first !== 0xed || byte < 0xa0)
+        && (first !== 0xf0 || byte >= 0x90) && (first !== 0xf4 || byte < 0x90);
+}
+function displayWidth(bytes, offset) {
+    const first = bytes[offset];
+    const width = utf8Length(first);
+    let consumed = 1;
+    while (consumed < width && offset + consumed < bytes.length && utf8Continuation(first, consumed, bytes[offset + consumed]))
+        consumed++;
+    return consumed;
 }
 export class ShellInput {
     budget;
+    descriptor;
     #cursor;
     #owned;
     #lifetime = new AbortController();
     #cleanupSignal;
     signal;
+    #reads = new Set();
     stat;
     seek;
     #closing;
-    constructor(source, budget, signal = budget.signal, provenance = {}) {
+    constructor(source, budget, signal = budget.signal, options) {
         this.budget = budget;
         this.#owned = !(source instanceof ShellInput);
-        this.#cursor = source instanceof ShellInput ? source.#cursor : new InputCursor(source, provenance, budget);
+        if (!this.#owned && options !== undefined)
+            throw new TypeError("Borrowed input cannot replace cursor capabilities");
+        this.#cursor = source instanceof ShellInput ? source.#cursor : new InputCursor(source, options ?? {}, budget);
+        this.descriptor = source instanceof ShellInput ? source.descriptor : options?.descriptor;
         this.#cleanupSignal = signal;
-        this.signal = AbortSignal.any([signal, this.#lifetime.signal]);
+        this.signal = AbortSignal.any([budget.signal, signal, this.#lifetime.signal]);
         if (this.#cursor.stat)
             this.stat = this.#cursor.stat;
         if (this.#cursor.seek)
@@ -327,6 +807,22 @@ export class ShellInput {
                 });
             };
     }
+    get bufferedBytes() {
+        this.signal.throwIfAborted();
+        return this.#cursor.bufferedBytes;
+    }
+    readiness() {
+        this.signal.throwIfAborted();
+        const readiness = this.#cursor.readiness();
+        this.signal.throwIfAborted();
+        return readiness;
+    }
+    probeRead() {
+        this.signal.throwIfAborted();
+        const result = this.#cursor.probeRead();
+        this.signal.throwIfAborted();
+        return result;
+    }
     get position() { return this.#cursor.position; }
     read(maxBytes, callerSignal) {
         const signal = AbortSignal.any([this.signal, callerSignal]);
@@ -388,9 +884,10 @@ export class ShellInput {
     next() {
         return this.#cursor.consume(this.signal, async () => {
             const result = await this.#cursor.take(this.signal);
-            if (!result.done)
-                this.#cursor.position += result.value.byteLength;
-            return result;
+            if (result.done)
+                return result;
+            this.#cursor.position += result.value.byteLength;
+            return { done: false, value: new Uint8Array(result.value) };
         });
     }
     [Symbol.asyncIterator]() {
@@ -417,7 +914,7 @@ export class ShellInput {
                 this.#cursor.position += end;
                 this.budget.source(end);
                 if (end)
-                    chunks.push(result.value.subarray(0, end));
+                    chunks.push(new Uint8Array(result.value.subarray(0, end)));
                 length += end;
                 if (newline >= 0)
                     break;
@@ -431,8 +928,86 @@ export class ShellInput {
             return bytes;
         });
     }
-    line(raw, options) {
-        return this.#cursor.consume(this.signal, () => options ? this.readBounded(raw, options) : this.readLine(raw));
+    async record(options = {}) {
+        this.signal.throwIfAborted();
+        const { delimiter = 10 } = options;
+        this.signal.throwIfAborted();
+        if (!Number.isInteger(delimiter) || delimiter < 0 || delimiter > 255)
+            throw new RangeError("Invalid raw record delimiter");
+        const scope = this.budget.values.scope();
+        let active = true;
+        let completion;
+        let resolve;
+        const finish = () => {
+            if (!completion || active)
+                return;
+            this.#reads.delete(release);
+            scope.close();
+            resolve();
+        };
+        const release = () => {
+            if (!completion) {
+                completion = new Promise(done => { resolve = done; });
+                finish();
+            }
+            return completion;
+        };
+        try {
+            scope.reserve(128, 2);
+            this.#reads.add(release);
+            const result = await this.#cursor.consume(this.signal, async () => {
+                const buffer = new ReadBuffer(scope, this.budget.limits.maxOutputBytes);
+                let chunk = new Uint8Array();
+                let offset = 0;
+                let pulls = 0;
+                let reason = "eof";
+                try {
+                    while (true) {
+                        this.signal.throwIfAborted();
+                        if (offset === chunk.length) {
+                            if (++pulls % 128 === 0)
+                                await yieldTurn(this.signal);
+                            const next = await this.#cursor.take(this.signal);
+                            if (next.done)
+                                break;
+                            chunk = next.value;
+                            offset = 0;
+                            if (!chunk.length)
+                                continue;
+                        }
+                        if (buffer.length >= this.budget.limits.maxOutputBytes)
+                            this.budget.fail("maxOutputBytes");
+                        const byte = chunk[offset++];
+                        this.#cursor.position++;
+                        buffer.append(byte);
+                        if (byte === delimiter) {
+                            reason = "delimiter";
+                            break;
+                        }
+                        if (buffer.length % 1024 === 0)
+                            await yieldTurn(this.signal);
+                    }
+                    const shellValue = shellValueFromBytes(buffer.bytes(), scope);
+                    this.signal.throwIfAborted();
+                    return Object.freeze({ shellValue, reason, release });
+                }
+                finally {
+                    if (offset < chunk.length)
+                        this.#cursor.remainder = chunk.subarray(offset);
+                }
+            });
+            this.signal.throwIfAborted();
+            return result;
+        }
+        catch (error) {
+            void release();
+            this.signal.throwIfAborted();
+            throw error;
+        }
+        finally {
+            active = false;
+            finish();
+        }
     }
     /** Select uses read's escape rules without projecting raw REPLY bytes to text. */
     selectLine(allocation) {
@@ -543,160 +1118,359 @@ export class ShellInput {
             }
         });
     }
-    async readBounded(raw, options) {
-        const text = new ReadText();
-        let characters = 0;
-        const escaped = new Set();
-        const decoder = new TextDecoder("utf-8", { fatal: true });
-        const delimiter = options.delimiter ?? 10;
+    async line(raw, options = {}) {
+        const { count, delimiter = 10, byteCount = false, exact = false, timeoutMs } = options;
+        this.signal.throwIfAborted();
+        if (count !== undefined && (!Number.isSafeInteger(count) || count < 0))
+            throw new RangeError("Invalid read count");
+        if (!Number.isInteger(delimiter) || delimiter < 0 || delimiter > 255)
+            throw new RangeError("Invalid read delimiter");
+        const scope = this.budget.values.scope();
+        let active = 1;
+        let closed = false;
+        let completion;
+        let resolve;
+        const finish = () => {
+            if (!closed || active)
+                return;
+            this.#reads.delete(release);
+            scope.close();
+            resolve();
+        };
+        const release = () => {
+            if (!completion) {
+                completion = new Promise(done => { resolve = done; });
+                closed = true;
+                finish();
+            }
+            return completion;
+        };
+        const assertOpen = () => {
+            this.signal.throwIfAborted();
+            if (closed)
+                throw new Error("Read result is closed");
+            scope.assertOpen();
+        };
         let chunk = new Uint8Array();
         let offset = 0;
-        let length = 0;
-        let escaping = false;
-        let escapedCharacter = false;
-        let units = 0;
-        let pulls = 0;
-        let terminated = options.count === 0;
+        let deadline;
         try {
-            while (!terminated) {
-                if (offset === chunk.length) {
-                    if (++pulls % 128 === 0)
-                        await yieldTurn(this.signal);
-                    const result = await this.#cursor.take(this.signal);
-                    if (result.done) {
-                        break;
+            scope.reserve(256, 3);
+            this.#reads.add(release);
+            deadline = this.#cursor.deadline(timeoutMs, this.signal, scope);
+            const read = async () => {
+                try {
+                    const buffer = new ReadBuffer(scope, this.budget.limits.maxOutputBytes);
+                    const escapedByteOffsets = [];
+                    let escaping = false;
+                    let visible = true;
+                    let units = 0;
+                    let consumed = 0;
+                    let checkpoint = 0;
+                    let pulls = 0;
+                    let terminated = count === 0;
+                    const outcome = { reason: terminated ? "count" : "eof" };
+                    const nextByte = async () => {
+                        this.signal.throwIfAborted();
+                        if (deadline?.expired()) {
+                            outcome.reason = "timeout";
+                            return undefined;
+                        }
+                        while (offset === chunk.length) {
+                            if (++pulls % 128 === 0)
+                                await yieldTurn(this.signal);
+                            let result;
+                            try {
+                                result = await this.#cursor.take(deadline?.signal ?? this.signal);
+                            }
+                            catch (error) {
+                                this.signal.throwIfAborted();
+                                if (deadline?.expired()) {
+                                    outcome.reason = "timeout";
+                                    return undefined;
+                                }
+                                throw error;
+                            }
+                            if (result.done) {
+                                if (deadline?.expired())
+                                    outcome.reason = "timeout";
+                                return undefined;
+                            }
+                            chunk = result.value;
+                            offset = 0;
+                            if (deadline?.expired()) {
+                                outcome.reason = "timeout";
+                                return undefined;
+                            }
+                        }
+                        this.signal.throwIfAborted();
+                        this.#cursor.position++;
+                        return chunk[offset++];
+                    };
+                    const account = () => {
+                        if (++consumed > this.budget.limits.maxOutputBytes)
+                            this.budget.fail("maxOutputBytes");
+                    };
+                    while (!terminated) {
+                        if (consumed - checkpoint >= 1024) {
+                            checkpoint = consumed;
+                            await yieldTurn(this.signal);
+                        }
+                        const first = await nextByte();
+                        if (first === undefined) {
+                            if (escaping && visible && !buffer.length && outcome.reason === "eof")
+                                buffer.append(1);
+                            break;
+                        }
+                        const quoted = escaping;
+                        escaping = false;
+                        if (quoted && first === 10) {
+                            account();
+                            continue;
+                        }
+                        if (!quoted && !raw && first === 92) {
+                            account();
+                            escaping = true;
+                            continue;
+                        }
+                        if (!quoted && !exact && first === delimiter) {
+                            terminated = true;
+                            outcome.reason = "delimiter";
+                            break;
+                        }
+                        account();
+                        if (!quoted && first === 0)
+                            continue;
+                        if (quoted && visible && first !== 0) {
+                            scope.reserve(64, 2);
+                            escapedByteOffsets.push(buffer.length);
+                        }
+                        if (visible && first === 0) {
+                            if (quoted && !buffer.length)
+                                buffer.append(1);
+                            visible = false;
+                        }
+                        else if (visible)
+                            buffer.append(first);
+                        const width = byteCount ? 1 : utf8Length(first);
+                        const committedLength = buffer.length;
+                        for (let position = 1; position < width; position++) {
+                            const next = await nextByte();
+                            if (next === undefined)
+                                break;
+                            account();
+                            if (next === 0)
+                                visible = false;
+                            else if (visible)
+                                buffer.append(next);
+                            if (!utf8Continuation(first, position, next))
+                                break;
+                        }
+                        if (outcome.reason === "timeout") {
+                            buffer.length = committedLength;
+                            break;
+                        }
+                        units++;
+                        if (units === count) {
+                            terminated = true;
+                            outcome.reason = "count";
+                        }
+                        if (units % 1024 === 0)
+                            await yieldTurn(this.signal);
                     }
-                    chunk = result.value;
-                    offset = 0;
-                    if (!chunk.length)
-                        continue;
-                }
-                const byte = chunk[offset++];
-                this.#cursor.position++;
-                if (!options.exact && !escaping && byte === delimiter) {
-                    terminated = true;
-                    break;
-                }
-                if (++length > this.budget.limits.maxOutputBytes)
-                    this.budget.fail("maxOutputBytes");
-                if (length % 1024 === 0) {
-                    await yieldTurn(this.signal);
                     this.signal.throwIfAborted();
-                }
-                if (byte === 0)
-                    continue;
-                if (!raw && !escaping && byte === 92) {
-                    escaping = true;
-                    continue;
-                }
-                if (escaping) {
-                    escaping = false;
-                    if (byte === 10)
-                        continue;
-                    escapedCharacter = true;
-                }
-                const decoded = decoder.decode(Uint8Array.of(byte), { stream: true });
-                let decodedCharacters = 0;
-                for (const character of decoded) {
-                    if (escapedCharacter) {
-                        escapedCharacter = false;
-                        escaped.add(characters);
+                    deadline?.close();
+                    const reason = outcome.reason;
+                    let bytes = buffer.bytes();
+                    if (reason === "timeout" && (escapedByteOffsets.length || escaping && visible)) {
+                        const projected = new ReadBuffer(scope, this.budget.limits.maxOutputBytes);
+                        let escape = 0;
+                        for (let position = 0; position < bytes.length; position++) {
+                            if (escapedByteOffsets[escape] === position) {
+                                projected.append(1);
+                                escapedByteOffsets[escape++] = projected.length;
+                            }
+                            projected.append(bytes[position]);
+                            if (position % 1024 === 0)
+                                await yieldTurn(this.signal);
+                        }
+                        if (escaping && visible) {
+                            scope.reserve(64, 2);
+                            escapedByteOffsets.push(projected.length);
+                            projected.append(1);
+                        }
+                        bytes = projected.bytes();
                     }
-                    text.append(character);
-                    characters++;
-                    decodedCharacters++;
+                    const shellValue = shellValueFromBytes(bytes, scope);
+                    const escaped = new Set();
+                    let escapeIndex = 0;
+                    let characters = 0;
+                    for (let start = 0; start < bytes.length; start += displayWidth(bytes, start)) {
+                        if (escapedByteOffsets[escapeIndex] === start) {
+                            escaped.add(characters);
+                            escapeIndex++;
+                        }
+                        if (++characters % 1024 === 0)
+                            await yieldTurn(this.signal);
+                    }
+                    Object.freeze(escapedByteOffsets);
+                    const result = {
+                        value: shellValueText(shellValue), shellValue, escaped, escapedByteOffsets, terminated, reason, release,
+                        fields: async (ifs, maximum) => {
+                            assertOpen();
+                            active++;
+                            try {
+                                if (maximum !== undefined && (!Number.isSafeInteger(maximum) || maximum < 0))
+                                    throw new RangeError("Invalid read field count");
+                                const separators = shellValueBytes(ifs, scope);
+                                scope.reserve(128, 2);
+                                const keys = new Set();
+                                const escapedStart = (start) => {
+                                    let lower = 0;
+                                    let upper = escapedByteOffsets.length;
+                                    while (lower < upper) {
+                                        const middle = lower + Math.floor((upper - lower) / 2);
+                                        const offset = escapedByteOffsets[middle];
+                                        if (offset === start)
+                                            return true;
+                                        if (offset < start)
+                                            lower = middle + 1;
+                                        else
+                                            upper = middle;
+                                    }
+                                    return false;
+                                };
+                                const width = (input, start) => {
+                                    if (input === bytes && reason === "timeout" && bytes[start] === 1 && escapedStart(start + 1))
+                                        return 2;
+                                    if (byteCount || input === bytes && escapedStart(start))
+                                        return 1;
+                                    const length = displayWidth(input, start);
+                                    return length === utf8Length(input[start]) ? length : 1;
+                                };
+                                const key = (input, start) => {
+                                    let value = 1;
+                                    for (let position = start, end = start + width(input, start); position < end; position++)
+                                        value = value * 257 + input[position];
+                                    return value;
+                                };
+                                let steps = 0;
+                                for (let start = 0; start < separators.length; start += width(separators, start)) {
+                                    const value = key(separators, start);
+                                    if (!keys.has(value)) {
+                                        scope.reserve(32, 1);
+                                        keys.add(value);
+                                    }
+                                    for (let position = start, end = start + width(separators, start); position < end; position++) {
+                                        const byteKey = 257 + separators[position];
+                                        if (!keys.has(byteKey)) {
+                                            scope.reserve(32, 1);
+                                            keys.add(byteKey);
+                                        }
+                                    }
+                                    if (++steps % 1024 === 0) {
+                                        await yieldTurn(this.signal);
+                                        assertOpen();
+                                    }
+                                }
+                                const separator = (start) => !escapedStart(start)
+                                    && !(reason === "timeout" && bytes[start] === 1 && escapedStart(start + 1)) && keys.has(key(bytes, start));
+                                const whitespace = (start) => (bytes[start] === 32 || bytes[start] === 9 || bytes[start] === 10) && separator(start);
+                                let end = 0;
+                                for (let start = 0; start < bytes.length; start += width(bytes, start)) {
+                                    if (!whitespace(start))
+                                        end = start + width(bytes, start);
+                                    if (++steps % 1024 === 0) {
+                                        await yieldTurn(this.signal);
+                                        assertOpen();
+                                    }
+                                }
+                                let position = 0;
+                                const advance = () => {
+                                    assertOpen();
+                                    position += width(bytes, position);
+                                    if (++steps % 1024 === 0)
+                                        return yieldTurn(this.signal);
+                                    return undefined;
+                                };
+                                const fields = [];
+                                while (position < end && whitespace(position)) {
+                                    const pending = advance();
+                                    if (pending)
+                                        await pending;
+                                }
+                                while (position < end && fields.length < (maximum ?? Number.MAX_SAFE_INTEGER)) {
+                                    const start = position;
+                                    while (position < end && !separator(position)) {
+                                        const pending = advance();
+                                        if (pending)
+                                            await pending;
+                                    }
+                                    let fieldEnd = position;
+                                    while (position < end && whitespace(position)) {
+                                        const pending = advance();
+                                        if (pending)
+                                            await pending;
+                                    }
+                                    if (position < end && separator(position)) {
+                                        const pending = advance();
+                                        if (pending)
+                                            await pending;
+                                    }
+                                    while (position < end && whitespace(position)) {
+                                        const pending = advance();
+                                        if (pending)
+                                            await pending;
+                                    }
+                                    if (maximum !== undefined && fields.length === maximum - 1 && position < end)
+                                        fieldEnd = end;
+                                    scope.reserve(64, 1);
+                                    fields.push(Object.freeze({ start, end: fieldEnd, value: shellValueFromBytes(bytes.subarray(start, fieldEnd), scope) }));
+                                }
+                                assertOpen();
+                                return Object.freeze(fields);
+                            }
+                            finally {
+                                active--;
+                                finish();
+                            }
+                        },
+                    };
+                    assertOpen();
+                    return Object.freeze(result);
                 }
-                units += options.byteCount ? 1 : decodedCharacters;
-                if (units === options.count)
-                    terminated = true;
-            }
-            decoder.decode();
-            return { value: text.finish(), escaped, terminated };
+                finally {
+                    if (offset < chunk.length)
+                        this.#cursor.remainder = chunk.subarray(offset);
+                }
+            };
+            const result = await this.#cursor.consume(deadline?.signal ?? this.signal, read, async (error) => {
+                this.signal.throwIfAborted();
+                if (deadline?.expired())
+                    return read();
+                throw error;
+            });
+            this.signal.throwIfAborted();
+            return result;
         }
         catch (error) {
-            if (error instanceof TypeError && error.message.includes("encoded data"))
-                throw new PublicDiagnostic("read: unsupported non-UTF-8 text boundary");
+            void release();
+            this.signal.throwIfAborted();
             throw error;
         }
         finally {
-            if (offset < chunk.length)
-                this.#cursor.remainder = chunk.subarray(offset);
+            deadline?.close();
+            active--;
+            finish();
         }
     }
-    async readLine(raw) {
-        const chunks = [];
-        let length = 0;
-        let terminated = false;
-        while (true) {
-            const result = await this.#cursor.take(this.signal);
-            if (result.done)
-                break;
-            const newline = result.value.indexOf(10);
-            this.#cursor.position += newline < 0 ? result.value.byteLength : newline + 1;
-            const chunk = newline < 0 ? result.value : result.value.subarray(0, newline);
-            if (chunk.byteLength > this.budget.limits.maxOutputBytes - length)
-                this.budget.fail("maxOutputBytes");
-            chunks.push(new Uint8Array(chunk));
-            length += chunk.byteLength;
-            if (newline >= 0) {
-                if (newline + 1 < result.value.length)
-                    this.#cursor.remainder = result.value.subarray(newline + 1);
-                let slashes = 0;
-                if (!raw) {
-                    for (let chunkIndex = chunks.length - 1; chunkIndex >= 0; chunkIndex--) {
-                        const bytes = chunks[chunkIndex];
-                        let offset = bytes.length - 1;
-                        while (offset >= 0 && bytes[offset] === 92) {
-                            slashes++;
-                            offset--;
-                        }
-                        if (offset >= 0)
-                            break;
-                    }
-                }
-                if (slashes % 2 === 1) {
-                    while (chunks.at(-1)?.length === 0)
-                        chunks.pop();
-                    chunks[chunks.length - 1] = chunks.at(-1).subarray(0, -1);
-                    length--;
-                }
-                else {
-                    terminated = true;
-                    break;
-                }
-            }
-        }
-        const bytes = new Uint8Array(length);
-        let offset = 0;
-        for (const chunk of chunks) {
-            bytes.set(chunk, offset);
-            offset += chunk.length;
-        }
-        const value = new TextDecoder().decode(bytes).replace(/\0/gu, "");
-        const escaped = new Set();
-        if (raw || !value.includes("\\"))
-            return { value, escaped, terminated };
-        const text = new ReadText();
-        let characters = 0;
-        for (let index = 0; index < value.length;) {
-            const slash = value.indexOf("\\", index);
-            const span = value.slice(index, slash < 0 ? value.length : slash);
-            text.append(span);
-            for (let pointOffset = 0; pointOffset < span.length; pointOffset += span.codePointAt(pointOffset) > 0xffff ? 2 : 1)
-                characters++;
-            if (slash < 0 || slash + 1 === value.length)
-                break;
-            const character = String.fromCodePoint(value.codePointAt(slash + 1));
-            escaped.add(characters++);
-            text.append(character);
-            index = slash + 1 + character.length;
-        }
-        return { value: text.finish(), escaped, terminated };
-    }
     close() {
         if (!this.#closing) {
             this.#lifetime.abort(new Error("Shell input view closed"));
-            this.#closing = this.#owned ? this.#cursor.close(this.#cleanupSignal) : Promise.resolve();
+            const pending = [...this.#reads].map(release => release());
+            if (this.#owned)
+                pending.push(this.#cursor.close(this.#cleanupSignal));
+            this.#closing = Promise.all(pending).then(() => undefined);
         }
         return this.#closing;
     }