agentic-qe 3.15.10 → 3.15.11

package/dist/optimization/early-exit-token-optimizer.js

@@ -8,6 +8,7 @@
  */
 import { detectQEDomain } from '../learning/qe-patterns.js';
 import { toErrorMessage } from '../shared/error-utils.js';
+import { createSafeRecord } from '../shared/utils/safe-record.js';
 /**
  * Default early exit configuration
  */
@@ -374,7 +375,8 @@ export class EarlyExitTokenOptimizer {
             reasonBreakdown[attempt.reason]++;
         }
         // Calculate domain breakdown
-        const domainBreakdown = {};
+        // #1157: domains come from recorded requests.
+        const domainBreakdown = createSafeRecord();
         for (const reuse of this.reuseHistory) {
             const domain = reuse.domain ?? 'unknown';
             if (!domainBreakdown[domain]) {

package/dist/planning/goap-planner.js

@@ -645,6 +645,11 @@ export class GOAPPlanner {
             if (current === null || current === undefined) {
                 return undefined;
             }
+            // #1157: goal and condition keys can come from callers; an inherited
+            // member such as `constructor` is not part of the world state.
+            if (typeof current !== 'object' || !Object.hasOwn(current, part)) {
+                return undefined;
+            }
             current = current[part];
         }
         return current;

package/dist/planning/plan-executor.js

@@ -900,6 +900,11 @@ export class PlanExecutor {
             if (current === null || current === undefined) {
                 return undefined;
             }
+            // #1157: goal and condition keys can come from callers; an inherited
+            // member such as `constructor` is not part of the world state.
+            if (typeof current !== 'object' || !Object.hasOwn(current, part)) {
+                return undefined;
+            }
             current = current[part];
         }
         return current;

package/dist/shared/io/confined-read.d.ts

@@ -0,0 +1,74 @@
+/**
+ * #1161: read a file inside the project root without a check-then-use race.
+ *
+ * The payload path guard (#1126) checks a path by name and the handler opens
+ * it again later, so a file or symlink swapped in between could be read
+ * unchecked. These readers OPEN first and validate what was opened:
+ *
+ * - the path's realpath is opened with O_NOFOLLOW (a symlink swapped onto the
+ *   final name fails the open) and O_NONBLOCK (a FIFO cannot hang the open);
+ * - the descriptor must be a regular file within the size limit (fstat);
+ * - the descriptor's real location (/proc/self/fd/N on Linux; elsewhere the
+ *   re-resolved realpath, which must be the same inode) must lie inside the
+ *   project root, so a directory component swapped for a symlink is caught;
+ * - the content is read from that same descriptor, and never past the limit,
+ *   even if the file grows after the fstat.
+ *
+ * A path spelled outside the root is refused before any filesystem call,
+ * unless the caller opts into `outsideRoot: 'allow'` for paths it accepts
+ * from a trusted source (the other checks still apply).
+ */
+import { type Stats } from 'node:fs';
+import { CallerInputError } from '../error-utils.js';
+/** Default upper bound for a confined read when the caller names none. */
+export declare const DEFAULT_MAX_CONFINED_READ_BYTES: number;
+export type ConfinedReadReason = 'not-found' | 'not-a-file' | 'outside-project-root' | 'unreadable' | 'too-large';
+export interface ConfinedReadOptions {
+    /** Project root; defaults to findProjectRoot(). */
+    projectRoot?: string;
+    /** Refuse files larger than this; defaults to DEFAULT_MAX_CONFINED_READ_BYTES. */
+    maxBytes?: number;
+    /**
+     * A path spelled outside the project root is refused ('refuse', default),
+     * or read without the containment check ('allow') when the caller already
+     * trusts it. Paths spelled inside the root are always held to the root.
+     */
+    outsideRoot?: 'refuse' | 'allow';
+}
+/**
+ * A confined read that was refused; `reason` matches the payload guard's.
+ * `code` is the errno code when the filesystem gave one (ENOENT, ELOOP, ...),
+ * otherwise the reason in errno style (OUTSIDE_PROJECT_ROOT, NOT_A_FILE,
+ * TOO_LARGE), so callers that report error codes keep working.
+ */
+export declare class ConfinedReadError extends CallerInputError {
+    readonly filePath: string;
+    readonly reason: ConfinedReadReason;
+    readonly code: string;
+    constructor(filePath: string, reason: ConfinedReadReason, errnoCode?: string);
+}
+/** Flags for opening a checked realpath: read-only, no final symlink, no FIFO wait. */
+export declare const CONFINED_OPEN_FLAGS: number;
+/** True when `candidate` is `root` or lies beneath it (both absolute). */
+export declare function isWithinRoot(root: string, candidate: string): boolean;
+/**
+ * Where an OPEN descriptor really points. On Linux, /proc/self/fd/N resolves
+ * to the opened file itself. Elsewhere, re-resolve the path and accept it only
+ * if it is the same inode as the descriptor, so a swap after the open is
+ * detected. Returns null when it cannot be proven.
+ */
+export declare function openedLocation(fd: number, lexical: string, opened: Stats): Promise<string | null>;
+/** Synchronous openedLocation, for callers that read synchronously. */
+export declare function openedLocationSync(fd: number, lexical: string, opened: Stats): string | null;
+/**
+ * Read a file by path, confined to the project root and validated on the
+ * opened descriptor (see the module comment). Throws ConfinedReadError.
+ */
+export declare function readConfinedFile(filePath: string, options?: ConfinedReadOptions): Promise<Buffer>;
+/** readConfinedFile decoded as UTF-8. */
+export declare function readConfinedText(filePath: string, options?: ConfinedReadOptions): Promise<string>;
+/** Synchronous readConfinedFile, for callers that cannot await. */
+export declare function readConfinedFileSync(filePath: string, options?: ConfinedReadOptions): Buffer;
+/** readConfinedFileSync decoded as UTF-8. */
+export declare function readConfinedTextSync(filePath: string, options?: ConfinedReadOptions): string;
+//# sourceMappingURL=confined-read.d.ts.map

package/dist/shared/io/confined-read.js

@@ -0,0 +1,256 @@
+/**
+ * #1161: read a file inside the project root without a check-then-use race.
+ *
+ * The payload path guard (#1126) checks a path by name and the handler opens
+ * it again later, so a file or symlink swapped in between could be read
+ * unchecked. These readers OPEN first and validate what was opened:
+ *
+ * - the path's realpath is opened with O_NOFOLLOW (a symlink swapped onto the
+ *   final name fails the open) and O_NONBLOCK (a FIFO cannot hang the open);
+ * - the descriptor must be a regular file within the size limit (fstat);
+ * - the descriptor's real location (/proc/self/fd/N on Linux; elsewhere the
+ *   re-resolved realpath, which must be the same inode) must lie inside the
+ *   project root, so a directory component swapped for a symlink is caught;
+ * - the content is read from that same descriptor, and never past the limit,
+ *   even if the file grows after the fstat.
+ *
+ * A path spelled outside the root is refused before any filesystem call,
+ * unless the caller opts into `outsideRoot: 'allow'` for paths it accepts
+ * from a trusted source (the other checks still apply).
+ */
+import { constants as fsConstants } from 'node:fs';
+import * as fsSync from 'node:fs';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { findProjectRoot } from '../../kernel/project-root.js';
+import { CallerInputError } from '../error-utils.js';
+/** Default upper bound for a confined read when the caller names none. */
+export const DEFAULT_MAX_CONFINED_READ_BYTES = 128 * 1024 * 1024;
+/**
+ * A confined read that was refused; `reason` matches the payload guard's.
+ * `code` is the errno code when the filesystem gave one (ENOENT, ELOOP, ...),
+ * otherwise the reason in errno style (OUTSIDE_PROJECT_ROOT, NOT_A_FILE,
+ * TOO_LARGE), so callers that report error codes keep working.
+ */
+export class ConfinedReadError extends CallerInputError {
+    filePath;
+    reason;
+    code;
+    constructor(filePath, reason, errnoCode) {
+        super(`Cannot read ${filePath}: ${reason}`);
+        this.filePath = filePath;
+        this.reason = reason;
+        this.name = 'ConfinedReadError';
+        this.code = errnoCode ?? reason.toUpperCase().replace(/-/g, '_');
+    }
+}
+/** Flags for opening a checked realpath: read-only, no final symlink, no FIFO wait. */
+export const CONFINED_OPEN_FLAGS = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0);
+/** True when `candidate` is `root` or lies beneath it (both absolute). */
+export function isWithinRoot(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+/**
+ * Where an OPEN descriptor really points. On Linux, /proc/self/fd/N resolves
+ * to the opened file itself. Elsewhere, re-resolve the path and accept it only
+ * if it is the same inode as the descriptor, so a swap after the open is
+ * detected. Returns null when it cannot be proven.
+ */
+export async function openedLocation(fd, lexical, opened) {
+    const sameFile = async (candidate) => {
+        const st = await fs.stat(candidate).catch(() => null);
+        return st !== null && st.dev === opened.dev && st.ino === opened.ino;
+    };
+    const viaProc = await fs.realpath(`/proc/self/fd/${fd}`).catch(() => null);
+    if (viaProc && path.isAbsolute(viaProc) && await sameFile(viaProc))
+        return viaProc;
+    const real = await fs.realpath(lexical).catch(() => null);
+    if (real && await sameFile(real))
+        return real;
+    return null;
+}
+/** Synchronous openedLocation, for callers that read synchronously. */
+export function openedLocationSync(fd, lexical, opened) {
+    const sameFile = (candidate) => {
+        try {
+            const st = fsSync.statSync(candidate);
+            return st.dev === opened.dev && st.ino === opened.ino;
+        }
+        catch {
+            return false;
+        }
+    };
+    const realOrNull = (p) => {
+        try {
+            return fsSync.realpathSync(p);
+        }
+        catch {
+            return null;
+        }
+    };
+    const viaProc = realOrNull(`/proc/self/fd/${fd}`);
+    if (viaProc && path.isAbsolute(viaProc) && sameFile(viaProc))
+        return viaProc;
+    const real = realOrNull(lexical);
+    if (real && sameFile(real))
+        return real;
+    return null;
+}
+function reasonFor(error) {
+    const code = error?.code;
+    if (code === 'ENOENT' || code === 'ENOTDIR')
+        return 'not-found';
+    // ELOOP: a symlink was swapped onto the checked realpath's final name.
+    if (code === 'EISDIR' || code === 'ELOOP')
+        return 'not-a-file';
+    return 'unreadable';
+}
+function fail(filePath, reason, error) {
+    return new ConfinedReadError(filePath, reason, error?.code);
+}
+function plan(filePath, rootReal, options) {
+    if (typeof filePath !== 'string' || filePath === '' || filePath.includes('\0')) {
+        throw fail(String(filePath), 'unreadable');
+    }
+    const rootLexical = path.resolve(options.projectRoot ?? findProjectRoot());
+    const lexical = path.resolve(filePath);
+    const inRoot = isWithinRoot(rootLexical, lexical) || isWithinRoot(rootReal, lexical);
+    // Spelled outside the root: refused before any filesystem call, so the
+    // reason cannot reveal whether an outside path exists.
+    if (!inRoot && options.outsideRoot !== 'allow')
+        throw fail(filePath, 'outside-project-root');
+    return { lexical, rootReal, inRoot, limit: options.maxBytes ?? DEFAULT_MAX_CONFINED_READ_BYTES };
+}
+/** Check the opened descriptor's stat before anything is read. */
+function checkOpened(filePath, st, limit) {
+    if (!st.isFile())
+        throw fail(filePath, 'not-a-file');
+    if (st.size > limit)
+        throw fail(filePath, 'too-large');
+}
+/**
+ * Read a file by path, confined to the project root and validated on the
+ * opened descriptor (see the module comment). Throws ConfinedReadError.
+ */
+export async function readConfinedFile(filePath, options = {}) {
+    const root = path.resolve(options.projectRoot ?? findProjectRoot());
+    const rootReal = await fs.realpath(root).catch(() => root);
+    const p = plan(filePath, rootReal, options);
+    let real;
+    try {
+        real = await fs.realpath(p.lexical);
+    }
+    catch (error) {
+        throw fail(filePath, reasonFor(error), error);
+    }
+    if (p.inRoot && !isWithinRoot(p.rootReal, real))
+        throw fail(filePath, 'outside-project-root');
+    let handle;
+    try {
+        handle = await fs.open(real, CONFINED_OPEN_FLAGS);
+    }
+    catch (error) {
+        throw fail(filePath, reasonFor(error), error);
+    }
+    try {
+        const st = await handle.stat();
+        checkOpened(filePath, st, p.limit);
+        if (p.inRoot) {
+            const location = await openedLocation(handle.fd, real, st);
+            if (!location || !isWithinRoot(p.rootReal, location))
+                throw fail(filePath, 'outside-project-root');
+        }
+        // Read at most limit + 1 bytes from this descriptor: a file that grew
+        // after the fstat is refused rather than read without bound.
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, p.limit + 1 - total));
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+            if (bytesRead === 0)
+                break;
+            chunks.push(chunk.subarray(0, bytesRead));
+            total += bytesRead;
+            if (total > p.limit)
+                throw fail(filePath, 'too-large');
+        }
+        return Buffer.concat(chunks, total);
+    }
+    catch (error) {
+        if (error instanceof ConfinedReadError)
+            throw error;
+        throw fail(filePath, reasonFor(error), error);
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+/** readConfinedFile decoded as UTF-8. */
+export async function readConfinedText(filePath, options = {}) {
+    return (await readConfinedFile(filePath, options)).toString('utf-8');
+}
+/** Synchronous readConfinedFile, for callers that cannot await. */
+export function readConfinedFileSync(filePath, options = {}) {
+    const root = path.resolve(options.projectRoot ?? findProjectRoot());
+    let rootReal = root;
+    try {
+        rootReal = fsSync.realpathSync(root);
+    }
+    catch { /* keep the lexical root */ }
+    const p = plan(filePath, rootReal, options);
+    let real;
+    try {
+        real = fsSync.realpathSync(p.lexical);
+    }
+    catch (error) {
+        throw fail(filePath, reasonFor(error), error);
+    }
+    if (p.inRoot && !isWithinRoot(p.rootReal, real))
+        throw fail(filePath, 'outside-project-root');
+    let fd;
+    try {
+        fd = fsSync.openSync(real, CONFINED_OPEN_FLAGS);
+    }
+    catch (error) {
+        throw fail(filePath, reasonFor(error), error);
+    }
+    try {
+        const st = fsSync.fstatSync(fd);
+        checkOpened(filePath, st, p.limit);
+        if (p.inRoot) {
+            const location = openedLocationSync(fd, real, st);
+            if (!location || !isWithinRoot(p.rootReal, location))
+                throw fail(filePath, 'outside-project-root');
+        }
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, p.limit + 1 - total));
+            const bytesRead = fsSync.readSync(fd, chunk, 0, chunk.length, null);
+            if (bytesRead === 0)
+                break;
+            chunks.push(chunk.subarray(0, bytesRead));
+            total += bytesRead;
+            if (total > p.limit)
+                throw fail(filePath, 'too-large');
+        }
+        return Buffer.concat(chunks, total);
+    }
+    catch (error) {
+        if (error instanceof ConfinedReadError)
+            throw error;
+        throw fail(filePath, reasonFor(error), error);
+    }
+    finally {
+        try {
+            fsSync.closeSync(fd);
+        }
+        catch { /* already closed */ }
+    }
+}
+/** readConfinedFileSync decoded as UTF-8. */
+export function readConfinedTextSync(filePath, options = {}) {
+    return readConfinedFileSync(filePath, options).toString('utf-8');
+}
+//# sourceMappingURL=confined-read.js.map

package/dist/shared/io/file-reader.d.ts

@@ -74,12 +74,12 @@ export declare class FileReader {
      */
     private inProjectRoot;
     /**
-     * #1021 round 2b: read an in-root path without a check-then-use race.
-     * The file is OPENED first and the open descriptor is verified — its real
-     * location (/proc/self/fd/N on Linux; otherwise the re-resolved realpath,
-     * which must be the same inode) must lie inside the root — and the content
-     * is read from that same descriptor. Swapping a symlink (file or directory
-     * component) between the check and the read can no longer redirect it.
+     * #1021 round 2b / #1161: read an in-root path without a check-then-use
+     * race. readConfinedText opens the path once and verifies the opened
+     * descriptor (a regular file whose real location lies inside the root) and
+     * reads from that same descriptor, so swapping a symlink (file or directory
+     * component) between a check and the read cannot redirect it, and a FIFO or
+     * device cannot hang or flood the read.
      */
     private readContained;
     /**

package/dist/shared/io/file-reader.js

@@ -7,6 +7,7 @@ import * as path from 'node:path';
 import { ok, err } from '../types/index.js';
 import { validatePath } from '../security/path-traversal-validator.js';
 import { safeJsonParse } from '../safe-json.js';
+import { ConfinedReadError, readConfinedText } from './confined-read.js';
 /** Extensions never read, inside or outside the project root. */
 const DENIED_EXTENSIONS = ['.exe', '.bat', '.cmd', '.ps1', '.dll', '.so'];
 export class FileReadError extends Error {
@@ -65,25 +66,6 @@ function readError(error, absolutePath) {
     }
     return new FileReadError(message, absolutePath, nodeError.code, nodeError);
 }
-/**
- * #1021 round 2b: where an OPEN descriptor really points. On Linux,
- * /proc/self/fd/N resolves to the opened file itself. Elsewhere, re-resolve
- * the path and accept it only if it is the same inode as the descriptor, so
- * a swap after the open is detected. Returns null when it cannot be proven.
- */
-async function openedLocation(fd, lexical, opened) {
-    const sameFile = async (candidate) => {
-        const st = await fs.stat(candidate).catch(() => null);
-        return st !== null && st.dev === opened.dev && st.ino === opened.ino;
-    };
-    const viaProc = await fs.realpath(`/proc/self/fd/${fd}`).catch(() => null);
-    if (viaProc && path.isAbsolute(viaProc) && await sameFile(viaProc))
-        return viaProc;
-    const real = await fs.realpath(lexical).catch(() => null);
-    if (real && await sameFile(real))
-        return real;
-    return null;
-}
 /** True when `candidate` is `root` or lies beneath it (both absolute). */
 function isWithin(root, candidate) {
     const relative = path.relative(root, candidate);
@@ -341,38 +323,30 @@ export class FileReader {
         return { lexical, rootReal };
     }
     /**
-     * #1021 round 2b: read an in-root path without a check-then-use race.
-     * The file is OPENED first and the open descriptor is verified — its real
-     * location (/proc/self/fd/N on Linux; otherwise the re-resolved realpath,
-     * which must be the same inode) must lie inside the root — and the content
-     * is read from that same descriptor. Swapping a symlink (file or directory
-     * component) between the check and the read can no longer redirect it.
+     * #1021 round 2b / #1161: read an in-root path without a check-then-use
+     * race. readConfinedText opens the path once and verifies the opened
+     * descriptor (a regular file whose real location lies inside the root) and
+     * reads from that same descriptor, so swapping a symlink (file or directory
+     * component) between a check and the read cannot redirect it, and a FIFO or
+     * device cannot hang or flood the read.
      */
     async readContained(filePath, lexical, rootReal) {
         this.stats.totalReads++;
-        let handle;
         try {
-            handle = await fs.open(lexical, 'r');
+            // The lexical root, so a path spelled under a symlinked root still
+            // counts as inside; the primitive resolves the root's realpath itself.
+            return ok(await readConfinedText(lexical, { projectRoot: this.projectRoot ?? rootReal }));
         }
         catch (error) {
-            return err(readError(error, lexical));
-        }
-        try {
-            const opened = await handle.stat();
-            const location = await openedLocation(handle.fd, lexical, opened);
-            if (!location || !isWithin(rootReal, location)) {
+            if (!(error instanceof ConfinedReadError))
+                return err(readError(error, lexical));
+            if (error.reason === 'outside-project-root') {
                 return err(new PathTraversalError(filePath, ['Path resolves outside the project root'], 'critical'));
             }
-            if (!opened.isFile()) {
-                return err(new FileReadError('Path is a directory: ' + lexical, lexical, 'EISDIR'));
+            if (error.reason === 'not-a-file') {
+                return err(new FileReadError('Not a regular file: ' + lexical, lexical, error.code === 'NOT_A_FILE' ? 'EISDIR' : error.code));
             }
-            return ok(await handle.readFile('utf-8'));
-        }
-        catch (error) {
-            return err(readError(error, lexical));
-        }
-        finally {
-            await handle.close().catch(() => undefined);
+            return err(readError({ code: error.reason === 'not-found' ? 'ENOENT' : error.code }, lexical));
         }
     }
     /**

package/dist/shared/llm/providers/claude-code.js

@@ -16,6 +16,7 @@
 import { spawn } from 'node:child_process';
 import { createLLMError, } from '../interfaces.js';
 import { TokenMetricsCollector } from '../../../learning/token-tracker.js';
+import { redactLogText } from '../../../logging/redaction.js';
 /** Env vars whose presence flips the CLI from subscription to API billing. */
 export const API_BILLING_ENV_VARS = [
     'ANTHROPIC_API_KEY',
@@ -108,7 +109,9 @@ export class ClaudeCodeProvider {
             data = JSON.parse(stdout);
         }
         catch {
-            throw createLLMError(`Could not parse claude -p JSON output: ${stdout.slice(0, 200)}`, 'PROVIDER_UNAVAILABLE', { provider: 'claude-code', model, retryable: true });
+            throw createLLMError(
+            // #1150: redact, then cut, so a cut secret leaves no fragment behind.
+            `Could not parse claude -p JSON output: ${redactLogText(stdout, Number.POSITIVE_INFINITY).slice(0, 200)}`, 'PROVIDER_UNAVAILABLE', { provider: 'claude-code', model, retryable: true });
         }
         if (data.is_error) {
             throw this.classifyError(data.result ?? data.api_error_status ?? 'claude error', model);

package/dist/shared/native-module-errors.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Native module load-failure diagnostics (issue #1173).
+ *
+ * better-sqlite3 ships a native addon whose binary is fetched/compiled by its
+ * `install` script. npm 12 blocks dependency install scripts unless they are
+ * allowed (`allowScripts`), so a plain `npm install -g agentic-qe` leaves the
+ * addon missing and the first `new Database()` throws "Could not locate the
+ * bindings file". Other installs hit the same wall via a Node upgrade
+ * (NODE_MODULE_VERSION mismatch) or an arch mismatch.
+ *
+ * These helpers recognise those failures and turn them into a message that
+ * names the cause and the exact command that fixes it, instead of a 20-line
+ * list of probed paths (or, in `aqe init`, nothing at all).
+ */
+export type NativeModuleFailureReason = 'missing-binding' | 'abi-mismatch' | 'load-failed';
+export interface NativeModuleFailure {
+    /** npm package whose native addon failed to load */
+    readonly moduleName: string;
+    readonly reason: NativeModuleFailureReason;
+    /** First line of the original error, without the probed-path list */
+    readonly detail: string;
+}
+/** Marker present in every remedy we emit; used to avoid double-wrapping. */
+export declare const NATIVE_MODULE_REMEDY_MARKER = "native module could not be loaded";
+/** Packages with install scripts that a global agentic-qe install needs allowed. */
+export declare const AQE_INSTALL_SCRIPT_PACKAGES = "agentic-qe,better-sqlite3,hnswlib-node";
+/**
+ * Classify `error` as a native-addon load failure, or return null when it is
+ * something else (I/O error, corrupt DB, lock contention, ...).
+ */
+export declare function diagnoseNativeModuleError(error: unknown, moduleName?: string): NativeModuleFailure | null;
+/** Multi-line, actionable explanation for a diagnosed native-module failure. */
+export declare function formatNativeModuleRemedy(failure: NativeModuleFailure): string;
+/**
+ * Error raised when a native addon cannot be loaded. The message carries the
+ * remedy; the original error is preserved as `cause`.
+ */
+export declare class NativeModuleLoadError extends Error {
+    readonly moduleName: string;
+    readonly reason: NativeModuleFailureReason;
+    constructor(failure: NativeModuleFailure, cause: unknown);
+}
+/**
+ * Return a NativeModuleLoadError for native-load failures, or the original
+ * error unchanged otherwise. Idempotent: an error that already carries the
+ * remedy is returned as-is.
+ */
+export declare function withNativeModuleRemedy(error: unknown, moduleName?: string): unknown;
+/** True when `error` (or its message, after re-wrapping) is a native-load failure. */
+export declare function isNativeModuleLoadFailure(error: unknown): boolean;
+//# sourceMappingURL=native-module-errors.d.ts.map