@linxiraos/pi-utils 1.4.7 → 1.4.10

package/CHANGELOG.md

@@ -1,18 +1,16 @@
 ## [Unreleased]
 
-## [1.4.7] - 2026-10-30
-
-- Synced with upstream OMP v18.14.0; no package-specific user-visible changes.
+## [1.4.10] - 2026-11-05
 
-## [1.4.6] - 2026-10-28
+- Legacy OMP dotenv files are no longer loaded by default; set `ZETA_OMP_COMPAT=1` to opt into the read-only fallback. Zeta `.zeta` dotenv files keep precedence.
 
-### Added
+## [1.4.9] - 2026-11-03
 
-- Added `logger.withContext(fields, fn)` to attach contextual fields to all records produced during a function and its asynchronous work, plus `logger.withoutContext(fn)` for work that should not inherit caller context.
+- Synced with upstream OMP v18.16.0; no package-specific user-visible changes.
 
-### Fixed
+## [1.4.7] - 2026-10-30
 
-- Fixed `untilAborted` so promises passed to an already-aborted signal are still observed, preventing later rejections from being reported as unhandled.
+- Synced with upstream OMP v18.14.0; no package-specific user-visible changes.
 
 ## [1.4.5] - 2026-10-28
 

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/async.d.ts

@@ -16,6 +16,11 @@ export declare const MAX_TIMER_DELAY_MS = 2147483647;
  * the unelapsed duration instead of shortening the requested sleep.
  */
 export declare function sleepLong(delayMs: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Wait for a wall-clock deadline, including time spent suspended. Some platforms
+ * exclude suspend from relative timers, so recheck at least once per second.
+ */
+export declare function sleepUntil(deadlineMs: number, signal?: AbortSignal): Promise<void>;
 /**
  * Wrap a promise with a timeout and optional abort signal.
  * Rejects with the given error or a new error containing the given message if

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/color.d.ts

@@ -99,6 +99,8 @@ export interface OKLCH {
  * hues, so carrying them between colors preserves the palette's "weight".
  */
 export declare function hexToOklch(hex: string): OKLCH;
+/** Perceptual distance between two hex colors: Euclidean OKLab, 0 when identical, 1 from black to white. */
+export declare function oklabDistance(a: string, b: string): number;
 /**
  * The sRGB gamut cusp for an OKLCH hue: the lightness/chroma point where the
  * hue reaches its maximum chroma inside sRGB.

package/dist/types/env.d.ts

@@ -44,6 +44,7 @@ export declare function getDotenvEnvValues(cwd?: string, env?: Record<string, st
  * only shell-identifier names and spawn-safe values.
  */
 export declare function parseEnvFile(filePath: string): Record<string, string>;
+export declare function isOmpCompatEnabled(env?: Record<string, string | undefined>): boolean;
 /**
  * Intentional re-export of Bun.env.
  *

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

@@ -16,6 +16,12 @@ declare function getLockPath(filePath: string): string;
 declare function tryAcquireLock(lockPath: string): NativeFileLock | null;
 /** Acquire an exclusive lease without waiting; `null` while another holder owns it. */
 export declare function tryAcquireFileLock(filePath: string): FileLockHandle | null;
+/**
+ * Whether any holder, including this process, owns the lease, observed without
+ * taking it, so a concurrent `tryAcquireFileLock` never meets the probe.
+ * Throws when the lock cannot be probed.
+ */
+export declare function isFileLockHeld(filePath: string): boolean;
 /** Acquire an exclusive lease; callers must release it when their operation ends. */
 export declare function acquireFileLock(filePath: string, options?: FileLockOptions): Promise<FileLockHandle>;
 /** Run `fn` while holding an OS-backed exclusive lock for `filePath`. */

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";
@@ -23,6 +24,7 @@ export * from "./path.js";
 export * from "./path-tree.js";
 export * from "./ports.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/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/postmortem.d.ts

@@ -178,6 +178,8 @@ export declare function registerFatalRecoveryHint(provider: FatalRecoveryHintPro
  * Reports a caught top-level failure after terminal owners restore their display, then exits.
  */
 export declare function fatal(error: unknown): Promise<never>;
+/** Installs OMP's process-wide signal and fatal handlers for a CLI-owned process. */
+export declare function installProcessHandlers(): void;
 /** Controls when a registered cleanup callback participates in cleanup passes. */
 export interface CleanupRegistrationOptions {
     /**
@@ -201,8 +203,7 @@ export interface CleanupRegistrationOptions {
     waitMessage?: string;
 }
 /**
- * Registers a cleanup callback for shutdown, signals, fatal errors, and
- * repeatable manual cleanup passes.
+ * Registers a cleanup callback for manual passes and, when installed, process shutdown.
  *
  * Registrations persist across keep-alive {@link cleanup} passes and run at
  * most once per pass. Set `exitOnly` for resources the continuing process still

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": "@linxiraos/pi-utils",
-	"version": "1.4.7",
+	"version": "1.4.10",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"utilities",
@@ -54,7 +54,8 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@linxiraos/pi-natives": "1.4.7"
+		"@linxiraos/pi-natives": "1.4.10",
+		"@linxiraos/pi-omptype": "1.4.10"
 	},
 	"devDependencies": {
 		"@types/bun": "1.4.4"

package/src/acp/schema.ts

@@ -1,3 +1,4 @@
+import { type Type, type } from "@linxiraos/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;
 		}