@oh-my-pi/pi-utils 18.15.0 → 18.17.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## [Unreleased]
 
+## [18.17.0] - 2026-11-06
+
+### Added
+
+- Added `getUpdateStateDir()`, returning the auto-update state directory (`~/.omp/update`).
+- Added `logger.setLogForwarder()` and `logger.emitForeign()` to forward log records across threads, preserving context and timestamps.
+- Added `expandTilde()` to expand a leading `~` to the home directory.
+
+### Fixed
+
+- Fixed `spawn`/`exec` timeouts never firing when the command's root exited before `spawn()` returned, which let a descendant holding stdout or stderr stall output reads until it exited.
+- `ptree` commands with `subreaper: true` now reliably terminate all descendants on graceful shutdown.
+- `fatal()` in a worker thread now reaches the parent's `error` listeners instead of only exiting with code 1.
+- Fixed the terminal stderr guard leaking a copy of the terminal into processes spawned from native code.
+
+## [18.16.0] - 2026-11-02
+
+### Added
+
+- Added `isPidAlive` (signal-0 liveness probe) and `asStrictBytes` (a `Uint8Array` narrowed to its own `ArrayBuffer` for WebCrypto)
+- Added `ensureSqliteLockShim()`, which `openSqliteDatabase`/`openSqliteDatabaseSync` call before opening a store, so on Linux the process's SQLite locks are open-file-description locks that other closes of the file cannot release ([#15586](https://github.com/can1357/oh-my-pi/issues/15586))
+- Added `assertNotHeldOpen(path)` (`@oh-my-pi/pi-utils/held-file`), which throws `EBUSY` for a SQLite database or `-shm` this process holds open ([#15586](https://github.com/can1357/oh-my-pi/issues/15586))
+
+### Changed
+
+- `acp` runtime validators (`zNewSessionResponse`, `zSessionNotification`, …) now report each failing field's path and reason in `error.issues` instead of a single `Invalid <label>`; `ValidationError` issue paths are typed `PropertyKey[]` ([#17699](https://github.com/can1357/oh-my-pi/pull/17699))
+
 ## [18.15.0] - 2026-11-01
 
 ### Added

package/dist/types/acp/schema.d.ts

@@ -2,7 +2,7 @@ import type { ForkSessionResponse, LoadSessionResponse, NewSessionResponse, Prom
 /** Validation failure compatible with the used Zod error surface. */
 export interface ValidationError {
     issues: Array<{
-        path: Array<string | number>;
+        path: PropertyKey[];
         message: string;
     }>;
 }

package/dist/types/ar/codecs/xz.d.ts

@@ -1,3 +1,7 @@
+/** Undo the delta filter (shared by XZ and 7z) in place. */
+export declare function deltaDecode(bytes: Uint8Array, distance: number): void;
+/** Undo the x86 BCJ filter (shared by XZ and 7z) in place; `startOffset` is the stream position of `bytes[0]`. */
+export declare function x86Decode(bytes: Uint8Array, startOffset: number): void;
 /** Whether bytes begin with the XZ stream-header magic. */
 export declare function isXz(bytes: Uint8Array): boolean;
 /** Decompress all concatenated streams in an XZ container within `maxOutput`. */

package/dist/types/ar/lzh.d.ts

@@ -1,6 +1,8 @@
 import type { FormatReader } from "./types.js";
 /** @internal Decode the static-Huffman LZSS stream shared by LZH and ARJ methods 1-3. */
 export declare function decompressLhStatic(packed: Uint8Array, outSize: number, dictionarySize: number, positionBits: number, positionSymbols: number, label: string): Uint8Array;
+/** MS-DOS packed date/time as UTC milliseconds; `undefined` for 0 or an out-of-range field. */
+export declare function dosTimeToMs(value: number): number | undefined;
 /** Probe whether bytes begin with an LZH/LHA member header. */
 export declare function sniffLzh(bytes: Uint8Array): boolean;
 /** Index an LZH/LHA archive and lazily decode its members from the bounded archive buffer. */

package/dist/types/bytes.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Narrow `bytes` to a view over its own whole `ArrayBuffer`, which is what
+ * `crypto.subtle.{digest,sign,importKey,encrypt,decrypt}` require under the
+ * strict TS DOM typings. Returns `bytes` itself when it already is one,
+ * otherwise a copy.
+ */
+export declare function asStrictBytes(bytes: Uint8Array): Uint8Array<ArrayBuffer>;

package/dist/types/dirs.d.ts

@@ -142,6 +142,12 @@ export declare function getAgentDir(): string;
 export declare function getProjectAgentDir(cwd?: string): string;
 /** Get the reports directory (~/.omp/reports). */
 export declare function getReportsDir(): string;
+/**
+ * Get the self-update state directory (~/.omp/update): the background
+ * auto-update's status file and worker log, and the lock that keeps two
+ * installs (`omp update`, auto-update) from running at once.
+ */
+export declare function getUpdateStateDir(): string;
 /**
  * Get the logs directory (~/.omp/logs). `bun test` processes get
  * `<tmpdir>/omp-test-logs-<uid>` instead, so suites never write into the

package/dist/types/held-file.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Throws an `EBUSY` error when `filePath` is a file this process holds open with
+ * locks: a SQLite database or `-shm` of a live connection. Always passes outside Linux.
+ */
+export declare function assertNotHeldOpen(filePath: string): void;

package/dist/types/index.d.ts

@@ -1,6 +1,7 @@
 export { once, untilAborted } from "./abortable.js";
 export * from "./async.js";
 export * from "./binary.js";
+export * from "./bytes.js";
 export * from "./color.js";
 export * from "./dirs.js";
 export * from "./env.js";
@@ -22,6 +23,7 @@ export * from "./mime.js";
 export * from "./path.js";
 export * from "./path-tree.js";
 export * from "./peek-file.js";
+export * from "./pid.js";
 export * as postmortem from "./postmortem.js";
 export * from "./process-name.js";
 export * as procmgr from "./procmgr.js";

package/dist/types/logger.d.ts

@@ -9,6 +9,35 @@ export interface LogEvent {
 }
 /** Receives each structured log event after the local transport path runs. */
 export type LogSink = (event: LogEvent) => void;
+/**
+ * Destination that takes this thread's log records in place of its own
+ * transports and sinks (a worker thread routing records to the main thread's
+ * logger); see {@link setLogForwarder}.
+ */
+export interface LogForwarder {
+    /**
+     * Take one record. Its context is already merged over the enclosing
+     * {@link withContext} fields and reduced to plain JSON data, so it survives
+     * a structured clone; `timestamp` is when the record was logged.
+     */
+    emit(event: LogEvent): void;
+    /** Write every record emitted so far on the receiving side; backs {@link flush}. */
+    flush(): void;
+}
+/**
+ * Route every later record logged on this thread to `forwarder` instead of the
+ * local transports and sinks, which then stay unused (no log file is opened);
+ * {@link flush} asks the forwarder to flush. `undefined` restores local logging.
+ * For worker threads, whose main thread owns the process log file.
+ */
+export declare function setLogForwarder(forwarder: LogForwarder | undefined): void;
+/**
+ * Log a record another thread forwarded (see {@link setLogForwarder}): written
+ * to the local transports with its own timestamp, then handed to the sinks. Its
+ * context is taken as is; the caller's enclosing {@link withContext} is not
+ * merged in. On a thread that forwards itself, the record is forwarded on.
+ */
+export declare function emitForeign(event: LogEvent): void;
 /** Register an out-of-band log sink and return a disposer. */
 export declare function registerLogSink(sink: LogSink): () => void;
 /**

package/dist/types/path.d.ts

@@ -8,3 +8,5 @@ export declare function stripWindowsExtendedLengthPathPrefix(filePath: string, p
  * On POSIX, requires an absolute path.
  */
 export declare function isFullyQualifiedPath(filePath: string, platform?: NodeJS.Platform): boolean;
+/** Expands a leading `~` (`~`, `~/…`, `~\…`, `~name`) to `home`, the user's home directory by default. */
+export declare function expandTilde(filePath: string, home?: string): string;

package/dist/types/pid.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Signal-0 liveness probe: true unless the OS reports the pid as gone
+ * (`ESRCH`) or invalid (`EINVAL`). Any other failure, notably `EPERM` (alive
+ * but owned by another user), reads as alive, so callers never reclaim a
+ * resource a live process may still hold. Unlike `procmgr.isPidRunning`, this
+ * does not consult the process table's run state.
+ */
+export declare function isPidAlive(pid: number): boolean;

package/dist/types/procmgr.d.ts

@@ -40,7 +40,7 @@ export declare function resolveBasicShell(): string | undefined;
  * Resolve the external shell to advertise on Windows.
  *
  * A host bash is OPTIONAL: bash tool commands always execute in the embedded
- * brush-core shell. The resolved binary only serves the spawn-a-shell paths
+ * bash engine (pi-shell). The resolved binary only serves the spawn-a-shell paths
  * (interactive PTY sessions, ACP client terminals, SHELL env), so this
  * prefers a real Git Bash when one exists and otherwise falls back to
  * cmd.exe — it never fails.

package/dist/types/sqlite.d.ts

@@ -1,5 +1,17 @@
 /** Shared SQLite opening, error attribution, and result-code classification for persistent stores. */
 import { Database } from "bun:sqlite";
+/**
+ * Moves this process's SQLite locks onto open-file-description locks (Linux), once.
+ *
+ * SQLite's POSIX record locks belong to the process, so any close of another
+ * descriptor of a database or its `-shm` released them, including Bun's own file
+ * APIs and the bash tool's builtins; a peer omp then unlinked the WAL under the live
+ * connection (issue #15586). Call before the process opens its first database: a
+ * connection opened earlier keeps POSIX locks. Returns whether the shim is active; a
+ * Linux build where it cannot be installed (Bun's SQLite layout changed) logs a warning
+ * once, and callers with a UI surface it.
+ */
+export declare function ensureSqliteLockShim(): boolean;
 /**
  * A store's identity as `dev:ino:birthtimeMs`, `null` when the path holds no
  * file, or `undefined` when the stat itself failed and no conclusion is safe.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.15.0",
+	"version": "18.17.0",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -49,14 +49,15 @@
 	},
 	"scripts": {
 		"check": "oxlint . && oxfmt --check --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts' && bun run check:types",
-		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"check:types": "bun check --no-script -p tsconfig.json",
 		"lint": "oxlint .",
 		"test": "bun test --parallel",
 		"fix": "oxlint --fix --fix-suggestions . && bun run fmt",
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.15.0"
+		"@oh-my-pi/omptype": "18.17.0",
+		"@oh-my-pi/pi-natives": "18.17.0"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/acp/schema.ts

@@ -1,3 +1,4 @@
+import { type Type, type } from "@oh-my-pi/omptype";
 import type {
 	ForkSessionResponse,
 	LoadSessionResponse,
@@ -8,7 +9,7 @@ import type {
 
 /** Validation failure compatible with the used Zod error surface. */
 export interface ValidationError {
-	issues: Array<{ path: Array<string | number>; message: string }>;
+	issues: Array<{ path: PropertyKey[]; message: string }>;
 }
 /** Successful validation result. */
 export interface ValidationSuccess<T> {
@@ -26,129 +27,74 @@ export interface Validator<T> {
 	parse(value: unknown): T;
 }
 
-function validator<T>(check: (value: unknown) => boolean, label: string): Validator<T> {
+/**
+ * Wraps a structural schema in the Zod call shape. Schemas check the fields
+ * ACP consumers read and keep every other key, so the result is the full
+ * protocol value.
+ */
+function validator<T>(schema: Type, label: string): Validator<T> {
 	return {
 		safeParse(value) {
-			return check(value)
-				? { success: true, data: value as T }
-				: { success: false, error: { issues: [{ path: [], message: `Invalid ${label}` }] } };
+			const result = schema(value);
+			if (!(result instanceof type.errors)) return { success: true, data: result as T };
+			return {
+				success: false,
+				error: { issues: result.map(issue => ({ path: [...issue.path], message: issue.message })) },
+			};
 		},
 		parse(value) {
-			if (!check(value)) throw new Error(`Invalid ${label}`);
-			return value as T;
+			const result = schema(value);
+			if (result instanceof type.errors) throw new Error(`Invalid ${label}: ${result.summary}`);
+			return result as T;
 		},
 	};
 }
 
-function objectWithString(value: unknown, key: string): boolean {
-	return typeof value === "object" && value !== null && typeof (value as Record<string, unknown>)[key] === "string";
-}
-
-function validModes(value: unknown): boolean {
-	if (value === undefined || value === null) return true;
-	if (typeof value !== "object" || value === null) return false;
-	const modes = value as Record<string, unknown>;
-	return (
-		typeof modes.currentModeId === "string" &&
-		Array.isArray(modes.availableModes) &&
-		modes.availableModes.every(mode => objectWithString(mode, "id") && objectWithString(mode, "name"))
-	);
-}
+const Modes = type({
+	currentModeId: "string",
+	availableModes: type({ id: "string", name: "string" }).array(),
+}).or("null | undefined");
 
-function sessionResponse(value: unknown, needsId: boolean): boolean {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-	const response = value as Record<string, unknown>;
-	if (needsId && typeof response.sessionId !== "string") return false;
-	if (!validModes(response.modes)) return false;
-	return (
-		response.configOptions === undefined || response.configOptions === null || Array.isArray(response.configOptions)
-	);
-}
+// Responses and notifications are also checked in-process, where absent optionals may be explicit `undefined`.
+const sessionResponseFields = { "modes?": Modes, "configOptions?": "unknown[] | null | undefined" } as const;
+const notArray = (value: object): boolean => !Array.isArray(value);
+const SessionResponse = type(sessionResponseFields).narrow(notArray);
+const IdentifiedSessionResponse = type({ sessionId: "string", ...sessionResponseFields }).narrow(notArray);
 
-function contentBlock(value: unknown): boolean {
-	if (typeof value !== "object" || value === null) return false;
-	const block = value as Record<string, unknown>;
-	switch (block.type) {
-		case "text":
-			return typeof block.text === "string";
-		case "image":
-		case "audio":
-			return typeof block.data === "string" && typeof block.mimeType === "string";
-		case "resource_link":
-			return typeof block.uri === "string" && typeof block.name === "string";
-		case "resource":
-			return typeof block.resource === "object" && block.resource !== null;
-		default:
-			return false;
-	}
-}
+const ContentBlock = type({ type: "'text'", text: "string" })
+	.or({ type: "'image' | 'audio'", data: "string", mimeType: "string" })
+	.or({ type: "'resource_link'", uri: "string", name: "string" })
+	.or({ type: "'resource'", resource: "object" });
 
-function sessionNotification(value: unknown): boolean {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-	const notification = value as Record<string, unknown>;
-	if (
-		typeof notification.sessionId !== "string" ||
-		typeof notification.update !== "object" ||
-		notification.update === null
-	)
-		return false;
-	const update = notification.update as Record<string, unknown>;
-	if (typeof update.sessionUpdate !== "string") return false;
-	switch (update.sessionUpdate) {
-		case "agent_message_chunk":
-		case "agent_thought_chunk":
-		case "user_message_chunk":
-			return contentBlock(update.content);
-		case "tool_call":
-			return typeof update.toolCallId === "string" && typeof update.title === "string";
-		case "tool_call_update":
-			return typeof update.toolCallId === "string";
-		case "plan":
-			return Array.isArray(update.entries);
-		case "current_mode_update":
-			return typeof update.currentModeId === "string";
-		case "available_commands_update":
-			return Array.isArray(update.availableCommands);
-		case "config_option_update":
-			return Array.isArray(update.configOptions);
-		case "session_info_update":
-			return update.title === undefined || update.title === null || typeof update.title === "string";
-		case "usage_update":
-			return typeof update.size === "number" && typeof update.used === "number";
-		default:
-			return false;
-	}
-}
+const SessionUpdate = type({
+	sessionUpdate: "'agent_message_chunk' | 'agent_thought_chunk' | 'user_message_chunk'",
+	content: ContentBlock,
+})
+	.or({ sessionUpdate: "'tool_call'", toolCallId: "string", title: "string" })
+	.or({ sessionUpdate: "'tool_call_update'", toolCallId: "string" })
+	.or({ sessionUpdate: "'plan'", entries: "unknown[]" })
+	.or({ sessionUpdate: "'current_mode_update'", currentModeId: "string" })
+	.or({ sessionUpdate: "'available_commands_update'", availableCommands: "unknown[]" })
+	.or({ sessionUpdate: "'config_option_update'", configOptions: "unknown[]" })
+	.or({ sessionUpdate: "'session_info_update'", "title?": "string | null | undefined" })
+	.or({ sessionUpdate: "'usage_update'", size: "number", used: "number" });
 
 /** Validator for new-session responses. */
-export const zNewSessionResponse = validator<NewSessionResponse>(
-	value => sessionResponse(value, true),
-	"new session response",
-);
+export const zNewSessionResponse = validator<NewSessionResponse>(IdentifiedSessionResponse, "new session response");
 /** Validator for load-session responses. */
-export const zLoadSessionResponse = validator<LoadSessionResponse>(
-	value => sessionResponse(value, false),
-	"load session response",
-);
+export const zLoadSessionResponse = validator<LoadSessionResponse>(SessionResponse, "load session response");
 /** Validator for fork-session responses. */
-export const zForkSessionResponse = validator<ForkSessionResponse>(
-	value => sessionResponse(value, true),
-	"fork session response",
-);
+export const zForkSessionResponse = validator<ForkSessionResponse>(IdentifiedSessionResponse, "fork session response");
 /** Validator for prompt responses. */
-export const zPromptResponse = validator<PromptResponse>(value => {
-	if (typeof value !== "object" || value === null) return false;
-	const stopReason = (value as Record<string, unknown>).stopReason;
-	return (
-		stopReason === "end_turn" ||
-		stopReason === "max_tokens" ||
-		stopReason === "max_turn_requests" ||
-		stopReason === "refusal" ||
-		stopReason === "cancelled"
-	);
-}, "prompt response");
+export const zPromptResponse = validator<PromptResponse>(
+	type({ stopReason: "'end_turn' | 'max_tokens' | 'max_turn_requests' | 'refusal' | 'cancelled'" }),
+	"prompt response",
+);
 /** Validator for session notifications. */
-export const zSessionNotification = validator<SessionNotification>(sessionNotification, "session notification");
+export const zSessionNotification = validator<SessionNotification>(
+	type({ sessionId: "string", update: SessionUpdate }).narrow(notArray),
+	"session notification",
+);
 
 /** ACP runtime validators. */
 export const schema = {

package/src/ar/arj.ts

@@ -1,7 +1,8 @@
+import { readUInt16LE, readUInt32LE } from "./bytes";
 import { crc32 } from "./checksums";
 import { ArchiveError } from "./error";
 import { assertArchiveMemberSize, assertEntryCount, assertIndexSize, assertInMemorySize } from "./limits";
-import { decompressLhStatic } from "./lzh";
+import { decompressLhStatic, dosTimeToMs } from "./lzh";
 import { assertArchivePathBytes, assertArchivePathString, normalizeArchiveEntryPath } from "./paths";
 import { type ByteSource, readAllBytes } from "./source";
 import type { ArchiveIndexEntry, FormatReader, FormatReadOptions, MemberSource } from "./types";
@@ -11,14 +12,6 @@ const ARJ_SIGNATURE_1 = 0xea;
 const ARJ_MAX_BASIC_HEADER = 2600;
 const LEGACY_DECODER = new TextDecoder("windows-1252");
 
-function u16(bytes: Uint8Array, offset: number): number {
-	return bytes[offset]! | (bytes[offset + 1]! << 8);
-}
-
-function u32(bytes: Uint8Array, offset: number): number {
-	return (bytes[offset]! | (bytes[offset + 1]! << 8) | (bytes[offset + 2]! << 16) | (bytes[offset + 3]! << 24)) >>> 0;
-}
-
 function assertRange(bytes: Uint8Array, start: number, end: number, what: string): void {
 	if (
 		!Number.isSafeInteger(start) ||
@@ -31,18 +24,6 @@ function assertRange(bytes: Uint8Array, start: number, end: number, what: string
 	}
 }
 
-function dosTimeToMs(value: number): number | undefined {
-	if (value === 0) return undefined;
-	const year = 1980 + ((value >>> 25) & 0x7f);
-	const month = (value >>> 21) & 0x0f;
-	const day = (value >>> 16) & 0x1f;
-	const hour = (value >>> 11) & 0x1f;
-	const minute = (value >>> 5) & 0x3f;
-	const second = (value & 0x1f) * 2;
-	if (month < 1 || month > 12 || day < 1 || day > 31 || hour > 23 || minute > 59 || second > 59) return undefined;
-	return Date.UTC(year, month - 1, day, hour, minute, second);
-}
-
 function readCString(bytes: Uint8Array, start: number, end: number, field: string): { value: string; next: number } {
 	let terminator = start;
 	while (terminator < end && bytes[terminator] !== 0) terminator++;
@@ -63,26 +44,26 @@ function parseArjBlock(bytes: Uint8Array, offset: number, options: FormatReadOpt
 	if (bytes[offset] !== ARJ_SIGNATURE_0 || bytes[offset + 1] !== ARJ_SIGNATURE_1) {
 		throw new ArchiveError("Invalid ARJ header signature");
 	}
-	const bodySize = u16(bytes, offset + 2);
+	const bodySize = readUInt16LE(bytes, offset + 2);
 	if (bodySize === 0)
 		return { bodyStart: offset + 4, bodySize: 0, nextOffset: offset + 4, metadataSize: 4, isEnd: true };
 	if (bodySize < 30 || bodySize > ARJ_MAX_BASIC_HEADER) throw new ArchiveError("Invalid ARJ basic header size");
 	const bodyStart = offset + 4;
 	const bodyEnd = bodyStart + bodySize;
 	assertRange(bytes, bodyStart, bodyEnd + 4, "basic header");
-	if (crc32(bytes.subarray(bodyStart, bodyEnd)) !== u32(bytes, bodyEnd)) {
+	if (crc32(bytes.subarray(bodyStart, bodyEnd)) !== readUInt32LE(bytes, bodyEnd)) {
 		throw new ArchiveError("Invalid ARJ basic header CRC32");
 	}
 	let cursor = bodyEnd + 4;
 	let extensionCount = 0;
 	for (;;) {
 		assertRange(bytes, cursor, cursor + 2, "extended header size");
-		const extensionSize = u16(bytes, cursor);
+		const extensionSize = readUInt16LE(bytes, cursor);
 		cursor += 2;
 		if (extensionSize === 0) break;
 		if (++extensionCount > 65_535) throw new ArchiveError("Invalid ARJ archive: too many extended headers");
 		assertRange(bytes, cursor, cursor + extensionSize + 4, "extended header");
-		if (crc32(bytes.subarray(cursor, cursor + extensionSize)) !== u32(bytes, cursor + extensionSize)) {
+		if (crc32(bytes.subarray(cursor, cursor + extensionSize)) !== readUInt32LE(bytes, cursor + extensionSize)) {
 			throw new ArchiveError("Invalid ARJ extended header CRC32");
 		}
 		cursor += extensionSize + 4;
@@ -216,10 +197,10 @@ function normalizeHostPath(rawPath: string, hostOs: number): string {
 /** Probe whether bytes begin with a CRC-framed ARJ main header. */
 export function sniffArj(bytes: Uint8Array): boolean {
 	if (bytes.byteLength < 34 || bytes[0] !== ARJ_SIGNATURE_0 || bytes[1] !== ARJ_SIGNATURE_1) return false;
-	const size = u16(bytes, 2);
+	const size = readUInt16LE(bytes, 2);
 	if (size < 30 || size > ARJ_MAX_BASIC_HEADER || bytes.byteLength < size + 8) return false;
 	const body = bytes.subarray(4, 4 + size);
-	return body[0]! >= 30 && body[0]! <= size && body[6] === 2 && crc32(body) === u32(bytes, 4 + size);
+	return body[0]! >= 30 && body[0]! <= size && body[6] === 2 && crc32(body) === readUInt32LE(bytes, 4 + size);
 }
 
 /** Index an ARJ archive and lazily decode stored, static-Huffman, and fast-LZSS members. */
@@ -266,10 +247,10 @@ export const readArj: FormatReader = async (
 		const fileType = bytes[block.bodyStart + 6]!;
 		if ((flags & 0x01) !== 0) throw new ArchiveError("Encrypted ARJ members are unsupported");
 		if ((flags & 0x0c) !== 0) throw new ArchiveError("Multi-volume ARJ members are unsupported");
-		const packedSize = u32(bytes, block.bodyStart + 12);
-		const size = u32(bytes, block.bodyStart + 16);
-		const fileCrc = u32(bytes, block.bodyStart + 20);
-		const accessMode = u16(bytes, block.bodyStart + 26);
+		const packedSize = readUInt32LE(bytes, block.bodyStart + 12);
+		const size = readUInt32LE(bytes, block.bodyStart + 16);
+		const fileCrc = readUInt32LE(bytes, block.bodyStart + 20);
+		const accessMode = readUInt16LE(bytes, block.bodyStart + 26);
 		const filename = readCString(
 			bytes,
 			block.bodyStart + firstHeaderSize,
@@ -295,7 +276,7 @@ export const readArj: FormatReader = async (
 		if ((hostOs === 2 || hostOs === 8) && accessMode !== 0) {
 			mode = (isDirectory ? 0x4000 : 0x8000) | (accessMode & 0x0fff);
 		}
-		const rawMtime = u32(bytes, block.bodyStart + 8);
+		const rawMtime = readUInt32LE(bytes, block.bodyStart + 8);
 		const mtimeMs =
 			hostOs === 2 || hostOs === 8 ? (rawMtime === 0 ? undefined : rawMtime * 1000) : dosTimeToMs(rawMtime);
 		entries.push({

package/src/ar/asar.ts

@@ -2,6 +2,7 @@ import * as path from "node:path";
 import { readUInt32LE, writeUInt32LE } from "./bytes";
 import { ArchiveError } from "./error";
 import { assertArchiveMemberSize, assertEntryCount, assertIndexSize } from "./limits";
+import { isRecord } from "../type-guards";
 import {
 	assertArchivePathBytes,
 	assertArchivePathString,
@@ -55,14 +56,10 @@ function alignAsarPayload(size: number): number {
 	return size + ((4 - (size % 4)) % 4);
 }
 
-function isArchiveRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function parseIntegrity(value: unknown, entryPath: string, size: number): AsarIntegrity | undefined {
 	if (value === undefined) return undefined;
 	const label = formatArchivePathForError(entryPath);
-	if (!isArchiveRecord(value)) {
+	if (!isRecord(value)) {
 		throw invalidAsar(`file '${label}' has an invalid integrity record`);
 	}
 	if (value.algorithm !== "SHA256") {
@@ -228,7 +225,7 @@ async function readAsarIndex(source: ByteSource, options: FormatReadOptions): Pr
 	} catch {
 		throw invalidAsar("header is not valid JSON");
 	}
-	if (!isArchiveRecord(header) || !isArchiveRecord(header.files)) {
+	if (!isRecord(header) || !isRecord(header.files)) {
 		throw invalidAsar("root must contain a files object");
 	}
 
@@ -257,7 +254,7 @@ async function readAsarIndex(source: ByteSource, options: FormatReadOptions): Pr
 		) {
 			throw invalidAsar(`invalid entry name '${formatArchivePathForError(current.name)}'`);
 		}
-		if (!isArchiveRecord(current.node)) {
+		if (!isRecord(current.node)) {
 			throw invalidAsar(`entry '${formatArchivePathForError(current.name)}' must be an object`);
 		}
 		const entryPathBytes = current.parentPathBytes + (current.parentPath ? 1 : 0) + nameBytes;
@@ -295,7 +292,7 @@ async function readAsarIndex(source: ByteSource, options: FormatReadOptions): Pr
 		}
 
 		if ("files" in current.node) {
-			if (!isArchiveRecord(current.node.files)) {
+			if (!isRecord(current.node.files)) {
 				throw invalidAsar(`directory '${entryLabel}' must contain a files object`);
 			}
 			entries.push({ path: entryPath, isDirectory: true, size: 0 });

package/src/ar/codecs/xz.ts

@@ -1,3 +1,4 @@
+import { readUInt32BE } from "../bytes";
 import { crc32, crc64 } from "../checksums";
 import { ArchiveError } from "../error";
 import { lzma2Decompress } from "./lzma";
@@ -16,10 +17,6 @@ function write32LE(bytes: Uint8Array, offset: number, value: number): void {
 	bytes[offset + 3] = value >>> 24;
 }
 
-function read32BE(bytes: Uint8Array, offset: number): number {
-	return ((bytes[offset]! << 24) | (bytes[offset + 1]! << 16) | (bytes[offset + 2]! << 8) | bytes[offset + 3]!) >>> 0;
-}
-
 function write32BE(bytes: Uint8Array, offset: number, value: number): void {
 	bytes[offset] = value >>> 24;
 	bytes[offset + 1] = (value >>> 16) & 0xff;
@@ -155,7 +152,8 @@ interface XzFilter {
 	properties: Uint8Array;
 }
 
-function deltaDecode(bytes: Uint8Array, distance: number): void {
+/** Undo the delta filter (shared by XZ and 7z) in place. */
+export function deltaDecode(bytes: Uint8Array, distance: number): void {
 	const history = new Uint8Array(256);
 	let position = 0;
 	for (let index = 0; index < bytes.byteLength; index++) {
@@ -166,7 +164,8 @@ function deltaDecode(bytes: Uint8Array, distance: number): void {
 	}
 }
 
-function x86Decode(bytes: Uint8Array, startOffset: number): void {
+/** Undo the x86 BCJ filter (shared by XZ and 7z) in place; `startOffset` is the stream position of `bytes[0]`. */
+export function x86Decode(bytes: Uint8Array, startOffset: number): void {
 	const maskToBitNumber = [0, 1, 2, 2, 3] as const;
 	let previousMask = 0;
 	let previousPosition = 0xfffffffb;
@@ -267,7 +266,7 @@ function sparcDecode(bytes: Uint8Array, startOffset: number): void {
 			)
 		)
 			continue;
-		const source = (read32BE(bytes, index) << 2) >>> 0;
+		const source = (readUInt32BE(bytes, index) << 2) >>> 0;
 		let destination = (source - startOffset - index) >>> 2;
 		destination = (((0 - ((destination >>> 22) & 1)) << 22) & 0x3fffffff) | (destination & 0x3fffff) | 0x40000000;
 		write32BE(bytes, index, destination >>> 0);
@@ -356,7 +355,7 @@ function riscvDecode(bytes: Uint8Array, startOffset: number): void {
 				index += 2;
 				continue;
 			}
-			const address = (read32BE(bytes, index + 4) - startOffset - index) >>> 0;
+			const address = (readUInt32BE(bytes, index + 4) - startOffset - index) >>> 0;
 			instruction2 = ((instruction >>> 12) | (address << 20)) >>> 0;
 			instruction = (0x17 | (register << 7) | ((address + 0x800) & 0xfffff000)) >>> 0;
 		}