exoproc-accessors 0.1.0

package/dist/middleware-accessor.js

@@ -0,0 +1,1870 @@
+import { randomUUID } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { NativeMemory, normalizeType, resolveAddress, alignUp, computeNearAllocRange, freeRegionCandidate, AllocNearRangeError, Kernel32Impl, MsvcrtImpl, MsvcrtLibrary, MemoryBasicInformation, PROCESSENTRY32W_SIZE, MemoryState, MemoryProtection, MemoryFreeType, ToolhelpSnapshotFlag, ProcessAccess, DEFAULT_MACHINECODE_ALIGNMENT, memmem, memmem1, memmem2, memmem4, memmem8, memmemWithoutBuffer, Pattern, Scanner, verifyCoreModules, verifyCoreModulesSync, isModuleLoadedInProcess, isModuleLoadedInProcessSync, MiddlewareAccessor, InittableMiddlewareAccessor, isMiddlewareAccessor, } from 'bun-xffi';
+export class MsvcrtDependentMiddlewareAccessor extends InittableMiddlewareAccessor {
+    async onInit() {
+        if (this.isLocal)
+            return;
+        const msvcrtBase = MsvcrtLibrary.baseAddress;
+        const isMsvcrtLoaded = await isModuleLoadedInProcess(this.root, msvcrtBase);
+        if (!isMsvcrtLoaded) {
+            throw new Error('Target process does not have msvcrt.dll loaded.');
+        }
+    }
+    onInitSync() {
+        if (this.isLocal)
+            return;
+        const msvcrtBase = MsvcrtLibrary.baseAddress;
+        const isMsvcrtLoaded = isModuleLoadedInProcessSync(this.root, msvcrtBase);
+        if (!isMsvcrtLoaded) {
+            throw new Error('Target process does not have msvcrt.dll loaded.');
+        }
+    }
+}
+/**
+ * HostAccessor is a base class that automatically initializes all nested InittableMiddlewareAccessors
+ * in the backend decorator chain.
+ */
+export class HostAccessor extends InittableMiddlewareAccessor {
+    get processId() {
+        return this._processId;
+    }
+    constructor(backend, root) {
+        super(backend, root ?? null);
+        if (!root) {
+            this.root = this;
+        }
+        let b = backend;
+        while (isMiddlewareAccessor(b)) {
+            b = b.backend;
+        }
+        if (b) {
+            this._processId = b.processId;
+        }
+    }
+    async onInit() {
+        // No-op. Chain initialization is automatically propagated by init().
+    }
+    onInitSync() {
+        // No-op. Chain initialization is automatically propagated by initSync().
+    }
+}
+/**
+ * A HostAccessor that forwards all operations to a dynamically changeable target HostAccessor.
+ * This is useful for resolving circular dependencies in middleware chains where the root
+ * reference is readonly and needs to be set after construction.
+ *
+ * Usage:
+ *   const redirector = new RedirectorHostAccessor(pid);
+ *   // ... build middleware chain using redirector as root ...
+ *   redirector.target = actualHostAccessor; // wire it up later
+ */
+/**
+ * HostAccessor that throws an error for all operations. Used as the default/unconfigured target for redirectors.
+ */
+export class ThrowingHostAccessor extends HostAccessor {
+    constructor(processId, root) {
+        super(new ThrowingMemoryAccessor(processId), root);
+    }
+}
+/**
+ * A HostAccessor that forwards all operations to a dynamically changeable target HostAccessor.
+ * If target is set to `this`, it delegates calls directly to its own backend (acting like a normal HostAccessor).
+ */
+export class RedirectorHostAccessor extends HostAccessor {
+    _target;
+    constructor(processId, root) {
+        super(new ThrowingMemoryAccessor(processId), root);
+        this._target = new ThrowingHostAccessor(processId, this.root);
+    }
+    get target() {
+        return this._target;
+    }
+    set target(value) {
+        this._target = value;
+        this._processId = value.processId;
+    }
+    getTarget() {
+        return this._target;
+    }
+    async read(address, size, offset = 0) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.read(address, size, offset);
+        }
+        return t.read(address, size, offset);
+    }
+    async write(address, data, offset = 0) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.write(address, data, offset);
+        }
+        return t.write(address, data, offset);
+    }
+    async alloc(size, address = null, protection, allocationType) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.alloc(size, address, protection, allocationType);
+        }
+        return t.alloc(size, address, protection, allocationType);
+    }
+    async free(address, size = 0, freeType) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.free(address, size, freeType);
+        }
+        return t.free(address, size, freeType);
+    }
+    async protect(address, size, newProtect) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.protect(address, size, newProtect);
+        }
+        return t.protect(address, size, newProtect);
+    }
+    async query(address) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.query(address);
+        }
+        return t.query(address);
+    }
+    async call(func, ...args) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.call(func, ...args);
+        }
+        return t.call(func, ...args);
+    }
+    async machineCode(machineCode) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.machineCode(machineCode);
+        }
+        return t.machineCode(machineCode);
+    }
+    async *scan(address, size, pattern) {
+        const t = this.getTarget();
+        if (t === this) {
+            yield* super.scan(address, size, pattern);
+        }
+        else {
+            yield* t.scan(address, size, pattern);
+        }
+    }
+    // ── Sync twins of the overrides above -- same getTarget()-redirect, for
+    //    callers (e.g. NThread.callSync) that need the *Sync family routed
+    //    through `root` all the way to whatever `target` ends up wired to,
+    //    instead of silently hitting the placeholder ThrowingMemoryAccessor
+    //    this class starts with as its own `backend`. ─────────────────────────
+    readSync(address, size, offset = 0) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.readSync(address, size, offset);
+        }
+        return t.readSync(address, size, offset);
+    }
+    writeSync(address, data, offset = 0) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.writeSync(address, data, offset);
+        }
+        return t.writeSync(address, data, offset);
+    }
+    allocSync(size, address = null, protection, allocationType) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.allocSync(size, address, protection, allocationType);
+        }
+        return t.allocSync(size, address, protection, allocationType);
+    }
+    freeSync(address, size = 0, freeType) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.freeSync(address, size, freeType);
+        }
+        return t.freeSync(address, size, freeType);
+    }
+    protectSync(address, size, newProtect) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.protectSync(address, size, newProtect);
+        }
+        return t.protectSync(address, size, newProtect);
+    }
+    querySync(address) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.querySync(address);
+        }
+        return t.querySync(address);
+    }
+    callSync(func, ...args) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.callSync(func, ...args);
+        }
+        return t.callSync(func, ...args);
+    }
+    machineCodeSync(machineCode) {
+        const t = this.getTarget();
+        if (t === this) {
+            return super.machineCodeSync(machineCode);
+        }
+        return t.machineCodeSync(machineCode);
+    }
+    *scanSync(address, size, pattern) {
+        const t = this.getTarget();
+        if (t === this) {
+            yield* super.scanSync(address, size, pattern);
+        }
+        else {
+            yield* t.scanSync(address, size, pattern);
+        }
+    }
+    close() {
+        if (this._target && this._target !== this) {
+            this._target.close();
+        }
+    }
+    async onInit() {
+        // No-op. The target is initialized separately.
+    }
+    onInitSync() {
+        // No-op. The target is initialized separately.
+    }
+}
+/**
+ * BootstrapHostAccessor is a specialized RedirectorHostAccessor designed to resolve circular dependencies
+ * during the initialization of decorator/middleware chains.
+ * It acts as a temporary root, redirecting calls to itself (direct backend execution)
+ * during initialization, and then automatically switches to the actual root once its backend is initialized.
+ */
+export class BootstrapHostAccessor extends RedirectorHostAccessor {
+    constructor(processId, root) {
+        super(processId, root);
+        this.target = this;
+    }
+    async onInit() {
+        await this.initNext();
+        this.target = this.root;
+    }
+    onInitSync() {
+        this.initNextSync();
+        this.target = this.root;
+    }
+}
+/**
+ * Advanced Middleware Accessor that redirects virtual memory operations
+ * (alloc, free, protect, query) to run inside the target process's context via the call method.
+ * This performs memory operations directly in the target process's thread context, optimizing access and avoiding cross-process overhead.
+ */
+export class CallRedirectorAccessor extends MiddlewareAccessor {
+    async alloc(size, address = null, protection = MemoryProtection.READWRITE, allocationType = MemoryState.COMMIT | MemoryState.RESERVE) {
+        const addressVal = address ? resolveAddress(address) : null;
+        const result = await this.root.call(Kernel32Impl.VirtualAlloc, addressVal, size, allocationType, protection);
+        if (!result || Number(result) === 0) {
+            throw new Error(`VirtualAlloc failed in remote process for size ${size}`);
+        }
+        return result;
+    }
+    allocSync(size, address = null, protection = MemoryProtection.READWRITE, allocationType = MemoryState.COMMIT | MemoryState.RESERVE) {
+        const addressVal = address ? resolveAddress(address) : null;
+        const result = this.root.callSync(Kernel32Impl.VirtualAlloc, addressVal, size, allocationType, protection);
+        if (!result || Number(result) === 0) {
+            throw new Error(`VirtualAlloc failed in remote process for size ${size}`);
+        }
+        return result;
+    }
+    async free(address, size = 0, freeType = MemoryFreeType.RELEASE) {
+        const success = await this.root.call(Kernel32Impl.VirtualFree, resolveAddress(address), size, freeType);
+        return success !== 0 && success !== false;
+    }
+    freeSync(address, size = 0, freeType = MemoryFreeType.RELEASE) {
+        const success = this.root.callSync(Kernel32Impl.VirtualFree, resolveAddress(address), size, freeType);
+        return success !== 0 && success !== false;
+    }
+    async protect(address, size, newProtect) {
+        // Allocate a temporary 4-byte buffer in the target process using root.alloc
+        // to store the old protection value returned by VirtualProtect
+        const tempAddr = await this.root.alloc(4);
+        try {
+            const success = await this.root.call(Kernel32Impl.VirtualProtect, resolveAddress(address), size, newProtect, tempAddr);
+            if (!success || success === 0) {
+                throw new Error(`VirtualProtect failed in remote process at address ${resolveAddress(address)}`);
+            }
+            const oldProtect = await this.root.readUInt32(tempAddr);
+            return oldProtect;
+        }
+        finally {
+            await this.root.free(tempAddr);
+        }
+    }
+    protectSync(address, size, newProtect) {
+        // Sync twin of protect() -- see its comment for the temp-buffer rationale.
+        const tempAddr = this.root.allocSync(4);
+        try {
+            const success = this.root.callSync(Kernel32Impl.VirtualProtect, resolveAddress(address), size, newProtect, tempAddr);
+            if (!success || success === 0) {
+                throw new Error(`VirtualProtect failed in remote process at address ${resolveAddress(address)}`);
+            }
+            return this.root.readUInt32Sync(tempAddr);
+        }
+        finally {
+            this.root.freeSync(tempAddr);
+        }
+    }
+    async query(address) {
+        const info = new MemoryBasicInformation();
+        // Allocate a temporary 48-byte buffer in the target process using root.alloc
+        // to store the MEMORY_BASIC_INFORMATION structure
+        const tempAddr = await this.root.alloc(info.size);
+        try {
+            const bytesReturned = await this.root.call(Kernel32Impl.VirtualQuery, resolveAddress(address), tempAddr, info.size);
+            if (!bytesReturned || Number(bytesReturned) === 0) {
+                throw new Error(`VirtualQuery failed in remote process at address ${resolveAddress(address)}`);
+            }
+            const buffer = await this.root.read(tempAddr, info.size);
+            info.writeSync(buffer, 0);
+            return info;
+        }
+        finally {
+            await this.root.free(tempAddr);
+        }
+    }
+    querySync(address) {
+        // Sync twin of query() -- see its comment for the temp-buffer rationale.
+        const info = new MemoryBasicInformation();
+        const tempAddr = this.root.allocSync(info.size);
+        try {
+            const bytesReturned = this.root.callSync(Kernel32Impl.VirtualQuery, resolveAddress(address), tempAddr, info.size);
+            if (!bytesReturned || Number(bytesReturned) === 0) {
+                throw new Error(`VirtualQuery failed in remote process at address ${resolveAddress(address)}`);
+            }
+            const buffer = this.root.readSync(tempAddr, info.size);
+            info.writeSync(buffer, 0);
+            return info;
+        }
+        finally {
+            this.root.freeSync(tempAddr);
+        }
+    }
+    /**
+     * Same principle as this class's alloc/free/protect/query: the *target*
+     * process does the work itself via `call` (in-process VirtualQuery /
+     * VirtualAlloc), not VirtualQueryEx/VirtualAllocEx reaching in from ours.
+     *
+     * `allocNear` is a search loop rather than a single Win32 call, so this
+     * override drives it entirely through the sibling `this.query()` /
+     * `this.alloc()` (each already a remote `call`, and each still composed with
+     * subclasses like {@link IndirectCallRedirectorAccessor}). Because every probe
+     * is an expensive round-trip here, it walks one region per `VirtualQuery`
+     * using the reported `RegionSize`, instead of the base accessor's naive
+     * fixed 64KB grid steps.
+     */
+    async allocNear(target, size, options = {}) {
+        const range = computeNearAllocRange(target, options);
+        const protection = options.protection ?? MemoryProtection.EXECUTE_READWRITE;
+        const allocationType = (MemoryState.COMMIT |
+            MemoryState.RESERVE);
+        // Try to claim a free region: VirtualAlloc runs in the target (sibling
+        // override) at the exact granularity-aligned candidate -- the allocation
+        // is made by the process itself.
+        const tryRegion = async (info) => {
+            const candidate = freeRegionCandidate(info, size, range);
+            if (candidate === null)
+                return null;
+            try {
+                return await this.alloc(size, candidate, protection, allocationType);
+            }
+            catch {
+                // Region got claimed/rejected between query and alloc -- skip it.
+                return null;
+            }
+        };
+        // Probe the target's own region once, then walk outward from its edges.
+        const first = await this.query(range.target);
+        const firstHit = await tryRegion(first);
+        if (firstHit !== null)
+            return firstHit;
+        const firstBase = BigInt(resolveAddress(first.BaseAddress));
+        const firstSize = BigInt(first.RegionSize) || 0x10000n;
+        // Downward: each VirtualQuery jumps to the region just below the last.
+        let cursor = firstBase - 1n;
+        while (cursor >= range.minAddr) {
+            const info = await this.query(cursor);
+            const hit = await tryRegion(info);
+            if (hit !== null)
+                return hit;
+            const base = BigInt(resolveAddress(info.BaseAddress));
+            const next = base - 1n;
+            if (next >= cursor)
+                break; // no downward progress -- stop
+            cursor = next;
+        }
+        // Upward: each VirtualQuery jumps to the first address past the last region.
+        cursor = firstBase + firstSize;
+        while (cursor <= range.maxAddr) {
+            const info = await this.query(cursor);
+            const hit = await tryRegion(info);
+            if (hit !== null)
+                return hit;
+            const base = BigInt(resolveAddress(info.BaseAddress));
+            const regionSize = BigInt(info.RegionSize) || 0x10000n;
+            const next = base + regionSize;
+            if (next <= cursor)
+                break; // no upward progress -- stop
+            cursor = next;
+        }
+        throw new AllocNearRangeError(range.target, range.maxDistance);
+    }
+    allocNearSync(target, size, options = {}) {
+        // Sync twin of allocNear() -- same walk, same shared computeNearAllocRange/
+        // freeRegionCandidate helpers, driven with querySync/allocSync instead.
+        const range = computeNearAllocRange(target, options);
+        const protection = options.protection ?? MemoryProtection.EXECUTE_READWRITE;
+        const allocationType = (MemoryState.COMMIT |
+            MemoryState.RESERVE);
+        const tryRegion = (info) => {
+            const candidate = freeRegionCandidate(info, size, range);
+            if (candidate === null)
+                return null;
+            try {
+                return this.allocSync(size, candidate, protection, allocationType);
+            }
+            catch {
+                return null;
+            }
+        };
+        const first = this.querySync(range.target);
+        const firstHit = tryRegion(first);
+        if (firstHit !== null)
+            return firstHit;
+        const firstBase = BigInt(resolveAddress(first.BaseAddress));
+        const firstSize = BigInt(first.RegionSize) || 0x10000n;
+        let cursor = firstBase - 1n;
+        while (cursor >= range.minAddr) {
+            const info = this.querySync(cursor);
+            const hit = tryRegion(info);
+            if (hit !== null)
+                return hit;
+            const base = BigInt(resolveAddress(info.BaseAddress));
+            const next = base - 1n;
+            if (next >= cursor)
+                break;
+            cursor = next;
+        }
+        cursor = firstBase + firstSize;
+        while (cursor <= range.maxAddr) {
+            const info = this.querySync(cursor);
+            const hit = tryRegion(info);
+            if (hit !== null)
+                return hit;
+            const base = BigInt(resolveAddress(info.BaseAddress));
+            const regionSize = BigInt(info.RegionSize) || 0x10000n;
+            const next = base + regionSize;
+            if (next <= cursor)
+                break;
+            cursor = next;
+        }
+        throw new AllocNearRangeError(range.target, range.maxDistance);
+    }
+}
+/**
+ * Indirect variant of CallRedirectorAccessor that redirects read-write memory allocations
+ * to malloc on the process's CRT heap instead of VirtualAlloc.
+ * It tracks these heap allocations locally and intercepts free, protect, and query operations
+ * on them to optimize compatibility with external diagnostic and memory analysis tools.
+ */
+export class IndirectCallRedirectorAccessor extends CallRedirectorAccessor {
+    mallocs = new Map(); // Map<address, size>
+    findMallocBlock(address) {
+        for (const [base, size] of this.mallocs.entries()) {
+            if (address >= base && address < base + size) {
+                return { base, size };
+            }
+        }
+        return null;
+    }
+    /** Shared by query()/querySync() -- pure, no I/O, so no need for two copies. */
+    buildMallocBlockInfo(block) {
+        const info = new MemoryBasicInformation();
+        info.assign({
+            BaseAddress: block.base,
+            AllocationBase: block.base,
+            AllocationProtect: MemoryProtection.READWRITE,
+            PartitionId: 0,
+            RegionSize: BigInt(block.size),
+            State: MemoryState.COMMIT,
+            Protect: MemoryProtection.READWRITE,
+            Type: 0x20000, // MEM_PRIVATE
+        });
+        return info;
+    }
+    async alloc(size, address = null, protection = MemoryProtection.READWRITE, allocationType = MemoryState.COMMIT | MemoryState.RESERVE) {
+        // If it's standard READWRITE memory without a specific requested address, use malloc for maximum redirection!
+        if (protection === MemoryProtection.READWRITE &&
+            (address === null || address === undefined)) {
+            const result = await this.root.call(MsvcrtImpl.malloc, size);
+            if (!result || Number(result) === 0) {
+                throw new Error(`malloc failed in remote process for size ${size}`);
+            }
+            const allocatedAddr = Number(result);
+            this.mallocs.set(allocatedAddr, size);
+            return allocatedAddr;
+        }
+        // Otherwise, fall back to VirtualAlloc (e.g. for executable memory blocks)
+        return super.alloc(size, address, protection, allocationType);
+    }
+    allocSync(size, address = null, protection = MemoryProtection.READWRITE, allocationType = MemoryState.COMMIT | MemoryState.RESERVE) {
+        if (protection === MemoryProtection.READWRITE &&
+            (address === null || address === undefined)) {
+            const result = this.root.callSync(MsvcrtImpl.malloc, size);
+            if (!result || Number(result) === 0) {
+                throw new Error(`malloc failed in remote process for size ${size}`);
+            }
+            const allocatedAddr = Number(result);
+            this.mallocs.set(allocatedAddr, size);
+            return allocatedAddr;
+        }
+        return super.allocSync(size, address, protection, allocationType);
+    }
+    async free(address, size = 0, freeType = MemoryFreeType.RELEASE) {
+        const addrVal = Number(resolveAddress(address));
+        if (this.mallocs.has(addrVal)) {
+            await this.root.call(MsvcrtImpl.free, addrVal);
+            this.mallocs.delete(addrVal);
+            return true;
+        }
+        return super.free(address, size, freeType);
+    }
+    freeSync(address, size = 0, freeType = MemoryFreeType.RELEASE) {
+        const addrVal = Number(resolveAddress(address));
+        if (this.mallocs.has(addrVal)) {
+            this.root.callSync(MsvcrtImpl.free, addrVal);
+            this.mallocs.delete(addrVal);
+            return true;
+        }
+        return super.freeSync(address, size, freeType);
+    }
+    async protect(address, size, newProtect) {
+        const addrVal = Number(resolveAddress(address));
+        const block = this.findMallocBlock(addrVal);
+        if (block) {
+            if (newProtect !== MemoryProtection.READWRITE) {
+                throw new Error(`Cannot change protection of indirect heap block at 0x${addrVal.toString(16)} to ${newProtect}. Only READWRITE is allowed.`);
+            }
+            return MemoryProtection.READWRITE; // Already READWRITE
+        }
+        return super.protect(address, size, newProtect);
+    }
+    protectSync(address, size, newProtect) {
+        const addrVal = Number(resolveAddress(address));
+        const block = this.findMallocBlock(addrVal);
+        if (block) {
+            if (newProtect !== MemoryProtection.READWRITE) {
+                throw new Error(`Cannot change protection of indirect heap block at 0x${addrVal.toString(16)} to ${newProtect}. Only READWRITE is allowed.`);
+            }
+            return MemoryProtection.READWRITE;
+        }
+        return super.protectSync(address, size, newProtect);
+    }
+    async query(address) {
+        const addrVal = Number(resolveAddress(address));
+        const block = this.findMallocBlock(addrVal);
+        if (block) {
+            return this.buildMallocBlockInfo(block);
+        }
+        return super.query(address);
+    }
+    querySync(address) {
+        const addrVal = Number(resolveAddress(address));
+        const block = this.findMallocBlock(addrVal);
+        if (block) {
+            return this.buildMallocBlockInfo(block);
+        }
+        return super.querySync(address);
+    }
+}
+/**
+ * Middleware Accessor that automatically intercepts call arguments,
+ * marshals complex types (strings, buffers) to remotely allocated memory blocks,
+ * executes the native call, and cleans up the temporary allocations.
+ */
+export class MarshallingCallableAccessor extends MiddlewareAccessor {
+    /**
+     * Shared by call()/callSync() -- pure decision of "does this argument need
+     * marshalling to a remote buffer, and if so, what bytes", with no I/O.
+     * Returns `null` for args that pass through unmodified.
+     */
+    static bufferToMarshal(type, val) {
+        const normType = normalizeType(type);
+        if (normType === 'cstring' && typeof val === 'string') {
+            return Buffer.from(val + '\0', 'utf8');
+        }
+        else if (normType === 'cwstring' && typeof val === 'string') {
+            return Buffer.from(val + '\0', 'utf16le');
+        }
+        else if (val && typeof val === 'object' && Buffer.isBuffer(val)) {
+            return val;
+        }
+        return null;
+    }
+    async call(func, ...args) {
+        const modifiedArgs = [...args];
+        const tempAllocations = [];
+        try {
+            const signatureArgs = func.args || [];
+            for (let i = 0; i < signatureArgs.length; i++) {
+                const buf = MarshallingCallableAccessor.bufferToMarshal(signatureArgs[i], args[i]);
+                if (!buf)
+                    continue;
+                const remoteAddr = Number(await this.root.alloc(buf.length));
+                await this.root.write(remoteAddr, buf);
+                tempAllocations.push({ address: remoteAddr, size: buf.length });
+                modifiedArgs[i] = remoteAddr;
+            }
+            return await this.backend.call(func, ...modifiedArgs);
+        }
+        finally {
+            for (const alloc of tempAllocations) {
+                try {
+                    await this.root.free(alloc.address, alloc.size);
+                }
+                catch {
+                    // ignore cleanup errors
+                }
+            }
+        }
+    }
+    callSync(func, ...args) {
+        const modifiedArgs = [...args];
+        const tempAllocations = [];
+        try {
+            const signatureArgs = func.args || [];
+            for (let i = 0; i < signatureArgs.length; i++) {
+                const buf = MarshallingCallableAccessor.bufferToMarshal(signatureArgs[i], args[i]);
+                if (!buf)
+                    continue;
+                const remoteAddr = Number(this.root.allocSync(buf.length));
+                this.root.writeSync(remoteAddr, buf);
+                tempAllocations.push({ address: remoteAddr, size: buf.length });
+                modifiedArgs[i] = remoteAddr;
+            }
+            return this.backend.callSync(func, ...modifiedArgs);
+        }
+        finally {
+            for (const alloc of tempAllocations) {
+                try {
+                    this.root.freeSync(alloc.address, alloc.size);
+                }
+                catch {
+                    // ignore cleanup errors
+                }
+            }
+        }
+    }
+}
+/**
+ * Middleware Accessor that redirects write operations to run inside the target process's context
+ * by executing msvcrt!memset calls. This is useful to optimize in-process memory initialization and avoid cross-process handle locks.
+ * It optimizes writes by scanning the buffer for contiguous identical byte blocks
+ * and writing them with a single memset call.
+ */
+export class MemsetWriteAccessor extends MsvcrtDependentMiddlewareAccessor {
+    _isExecuting = false;
+    /**
+     * Shared by writeAfterInit()/writeAfterInitSync() -- pure run-length scan
+     * over the buffer, no I/O, so no need for two copies.
+     */
+    static computeRuns(buffer) {
+        const runs = [];
+        let i = 0;
+        while (i < buffer.length) {
+            const val = buffer[i];
+            if (val === undefined)
+                break;
+            let runLength = 1;
+            while (i + runLength < buffer.length && buffer[i + runLength] === val) {
+                runLength++;
+            }
+            runs.push({ startOffset: i, value: val, count: runLength });
+            i += runLength;
+        }
+        return runs;
+    }
+    async writeAfterInit(address, data, offset = 0) {
+        if (this.isInitializing || this._isExecuting) {
+            return super.writeAfterInit(address, data, offset);
+        }
+        this._isExecuting = true;
+        try {
+            const baseAddress = resolveAddress(address) + offset;
+            const buffer = data instanceof Buffer ? data : Buffer.from(data);
+            const runs = MemsetWriteAccessor.computeRuns(buffer);
+            let totalWritten = 0;
+            for (const run of runs) {
+                const targetAddr = baseAddress + run.startOffset;
+                await this.root.call(MsvcrtImpl.memset, targetAddr, run.value, run.count);
+                totalWritten += run.count;
+            }
+            return totalWritten;
+        }
+        finally {
+            this._isExecuting = false;
+        }
+    }
+    writeAfterInitSync(address, data, offset = 0) {
+        if (this.isInitializingSync || this._isExecuting) {
+            return super.writeAfterInitSync(address, data, offset);
+        }
+        this._isExecuting = true;
+        try {
+            const baseAddress = resolveAddress(address) + offset;
+            const buffer = data instanceof Buffer ? data : Buffer.from(data);
+            const runs = MemsetWriteAccessor.computeRuns(buffer);
+            let totalWritten = 0;
+            for (const run of runs) {
+                const targetAddr = baseAddress + run.startOffset;
+                this.root.callSync(MsvcrtImpl.memset, targetAddr, run.value, run.count);
+                totalWritten += run.count;
+            }
+            return totalWritten;
+        }
+        finally {
+            this._isExecuting = false;
+        }
+    }
+}
+/**
+ * Middleware Accessor that reads memory using remote memcmp binary search.
+ * This completely avoids ReadProcessMemory, making it extremely low-overhead
+ * and independent of any custom machineCode execution.
+ */
+export class MemcmpReadAccessor extends MsvcrtDependentMiddlewareAccessor {
+    _isExecuting = false;
+    async readAfterInit(address, size, offset = 0) {
+        if (this.isInitializing || this._isExecuting) {
+            return super.readAfterInit(address, size, offset);
+        }
+        this._isExecuting = true;
+        const baseAddress = resolveAddress(address) + offset;
+        const candidateAddr = Number(resolveAddress(await this.root.alloc(1)));
+        const candidateBuf = Buffer.alloc(1);
+        try {
+            const result = Buffer.alloc(size);
+            for (let i = 0; i < size; i++) {
+                let low = 0;
+                let high = 255;
+                let foundByte = 0;
+                while (low <= high) {
+                    const mid = (low + high) >> 1;
+                    candidateBuf[0] = mid;
+                    await this.root.write(candidateAddr, candidateBuf);
+                    const cmp = await this.root.call(MsvcrtImpl.memcmp, baseAddress + i, candidateAddr, 1);
+                    const cmpVal = Number(cmp);
+                    if (cmpVal === 0) {
+                        foundByte = mid;
+                        break;
+                    }
+                    else if (cmpVal < 0) {
+                        high = mid - 1;
+                    }
+                    else {
+                        low = mid + 1;
+                    }
+                }
+                result[i] = foundByte;
+            }
+            return result;
+        }
+        finally {
+            this._isExecuting = false;
+            await this.root.free(candidateAddr).catch(() => { });
+        }
+    }
+    readAfterInitSync(address, size, offset = 0) {
+        if (this.isInitializingSync || this._isExecuting) {
+            return super.readAfterInitSync(address, size, offset);
+        }
+        this._isExecuting = true;
+        const baseAddress = resolveAddress(address) + offset;
+        const candidateAddr = Number(resolveAddress(this.root.allocSync(1)));
+        const candidateBuf = Buffer.alloc(1);
+        try {
+            const result = Buffer.alloc(size);
+            for (let i = 0; i < size; i++) {
+                let low = 0;
+                let high = 255;
+                let foundByte = 0;
+                while (low <= high) {
+                    const mid = (low + high) >> 1;
+                    candidateBuf[0] = mid;
+                    this.root.writeSync(candidateAddr, candidateBuf);
+                    const cmp = this.root.callSync(MsvcrtImpl.memcmp, baseAddress + i, candidateAddr, 1);
+                    const cmpVal = Number(cmp);
+                    if (cmpVal === 0) {
+                        foundByte = mid;
+                        break;
+                    }
+                    else if (cmpVal < 0) {
+                        high = mid - 1;
+                    }
+                    else {
+                        low = mid + 1;
+                    }
+                }
+                result[i] = foundByte;
+            }
+            return result;
+        }
+        finally {
+            this._isExecuting = false;
+            try {
+                this.root.freeSync(candidateAddr);
+            }
+            catch {
+                /* ignore cleanup errors */
+            }
+        }
+    }
+}
+/**
+ * Dead-end fallback accessor that throws an error for every single memory operation.
+ * Used as a strict base definition or safety guard for middleware accessor pipelines
+ * to ensure unsupported operations are explicitly caught rather than silently ignored.
+ */
+export class ThrowingMemoryAccessor {
+    isLocal = false;
+    processId;
+    constructor(processId) {
+        this.processId = processId;
+    }
+    throwError(method) {
+        throw new Error(`ThrowingMemoryAccessor: '${method}' is not implemented or permitted.`);
+    }
+    enableDebug() { }
+    disableDebug() { }
+    async read(_address, _size, _offset = 0) {
+        this.throwError('read');
+    }
+    readSync(_address, _size, _offset = 0) {
+        this.throwError('readSync');
+    }
+    async write(_address, _data, _offset = 0) {
+        this.throwError('write');
+    }
+    writeSync(_address, _data, _offset = 0) {
+        this.throwError('writeSync');
+    }
+    async alloc(_size, _address = null, _protection, _allocationType) {
+        this.throwError('alloc');
+    }
+    allocSync(_size, _address = null, _protection, _allocationType) {
+        this.throwError('allocSync');
+    }
+    async allocNear(_target, _size, _options) {
+        this.throwError('allocNear');
+    }
+    allocNearSync(_target, _size, _options) {
+        this.throwError('allocNearSync');
+    }
+    async free(_address, _size = 0, _freeType) {
+        this.throwError('free');
+    }
+    freeSync(_address, _size = 0, _freeType) {
+        this.throwError('freeSync');
+    }
+    async protect(_address, _size, _newProtect) {
+        this.throwError('protect');
+    }
+    protectSync(_address, _size, _newProtect) {
+        this.throwError('protectSync');
+    }
+    async query(_address) {
+        this.throwError('query');
+    }
+    querySync(_address) {
+        this.throwError('querySync');
+    }
+    async call(_func, ..._args) {
+        this.throwError('call');
+    }
+    callSync(_func, ..._args) {
+        this.throwError('callSync');
+    }
+    // eslint-disable-next-line require-yield
+    async *scan(_address, _size, _pattern) {
+        this.throwError('scan');
+    }
+    // eslint-disable-next-line require-yield
+    *scanSync(_address, _size, _pattern) {
+        this.throwError('scanSync');
+    }
+    async readInt8(_address, _offset = 0) {
+        this.throwError('readInt8');
+    }
+    readInt8Sync(_address, _offset = 0) {
+        this.throwError('readInt8Sync');
+    }
+    async readUInt8(_address, _offset = 0) {
+        this.throwError('readUInt8');
+    }
+    readUInt8Sync(_address, _offset = 0) {
+        this.throwError('readUInt8Sync');
+    }
+    async readInt16(_address, _offset = 0) {
+        this.throwError('readInt16');
+    }
+    readInt16Sync(_address, _offset = 0) {
+        this.throwError('readInt16Sync');
+    }
+    async readUInt16(_address, _offset = 0) {
+        this.throwError('readUInt16');
+    }
+    readUInt16Sync(_address, _offset = 0) {
+        this.throwError('readUInt16Sync');
+    }
+    async readInt32(_address, _offset = 0) {
+        this.throwError('readInt32');
+    }
+    readInt32Sync(_address, _offset = 0) {
+        this.throwError('readInt32Sync');
+    }
+    async readUInt32(_address, _offset = 0) {
+        this.throwError('readUInt32');
+    }
+    readUInt32Sync(_address, _offset = 0) {
+        this.throwError('readUInt32Sync');
+    }
+    async readInt64(_address, _offset = 0) {
+        this.throwError('readInt64');
+    }
+    readInt64Sync(_address, _offset = 0) {
+        this.throwError('readInt64Sync');
+    }
+    async readUInt64(_address, _offset = 0) {
+        this.throwError('readUInt64');
+    }
+    readUInt64Sync(_address, _offset = 0) {
+        this.throwError('readUInt64Sync');
+    }
+    async readFloat(_address, _offset = 0) {
+        this.throwError('readFloat');
+    }
+    readFloatSync(_address, _offset = 0) {
+        this.throwError('readFloatSync');
+    }
+    async readDouble(_address, _offset = 0) {
+        this.throwError('readDouble');
+    }
+    readDoubleSync(_address, _offset = 0) {
+        this.throwError('readDoubleSync');
+    }
+    async readPointer(_address, _offset = 0) {
+        this.throwError('readPointer');
+    }
+    readPointerSync(_address, _offset = 0) {
+        this.throwError('readPointerSync');
+    }
+    async writeInt8(_address, _value, _offset = 0) {
+        this.throwError('writeInt8');
+    }
+    writeInt8Sync(_address, _value, _offset = 0) {
+        this.throwError('writeInt8Sync');
+    }
+    async writeUInt8(_address, _value, _offset = 0) {
+        this.throwError('writeUInt8');
+    }
+    writeUInt8Sync(_address, _value, _offset = 0) {
+        this.throwError('writeUInt8Sync');
+    }
+    async writeInt16(_address, _value, _offset = 0) {
+        this.throwError('writeInt16');
+    }
+    writeInt16Sync(_address, _value, _offset = 0) {
+        this.throwError('writeInt16Sync');
+    }
+    async writeUInt16(_address, _value, _offset = 0) {
+        this.throwError('writeUInt16');
+    }
+    writeUInt16Sync(_address, _value, _offset = 0) {
+        this.throwError('writeUInt16Sync');
+    }
+    async writeInt32(_address, _value, _offset = 0) {
+        this.throwError('writeInt32');
+    }
+    writeInt32Sync(_address, _value, _offset = 0) {
+        this.throwError('writeInt32Sync');
+    }
+    async writeUInt32(_address, _value, _offset = 0) {
+        this.throwError('writeUInt32');
+    }
+    writeUInt32Sync(_address, _value, _offset = 0) {
+        this.throwError('writeUInt32Sync');
+    }
+    async writeInt64(_address, _value, _offset = 0) {
+        this.throwError('writeInt64');
+    }
+    writeInt64Sync(_address, _value, _offset = 0) {
+        this.throwError('writeInt64Sync');
+    }
+    async writeUInt64(_address, _value, _offset = 0) {
+        this.throwError('writeUInt64');
+    }
+    writeUInt64Sync(_address, _value, _offset = 0) {
+        this.throwError('writeUInt64Sync');
+    }
+    async writeFloat(_address, _value, _offset = 0) {
+        this.throwError('writeFloat');
+    }
+    writeFloatSync(_address, _value, _offset = 0) {
+        this.throwError('writeFloatSync');
+    }
+    async writeDouble(_address, _value, _offset = 0) {
+        this.throwError('writeDouble');
+    }
+    writeDoubleSync(_address, _value, _offset = 0) {
+        this.throwError('writeDoubleSync');
+    }
+    async writePointer(_address, _value, _offset = 0) {
+        this.throwError('writePointer');
+    }
+    writePointerSync(_address, _value, _offset = 0) {
+        this.throwError('writePointerSync');
+    }
+    async machineCode(_machineCode) {
+        this.throwError('machineCode');
+    }
+    machineCodeSync(_machineCode) {
+        this.throwError('machineCodeSync');
+    }
+}
+/**
+ * Middleware Accessor that redirects memory reads to transfer via a temporary file,
+ * using standard C library calls (fopen, fwrite, fclose) in the target process.
+ * This is useful to perform high-volume structured memory extraction through file I/O instead of raw memory streaming.
+ */
+export class FileTransferReadAccessor extends MsvcrtDependentMiddlewareAccessor {
+    // The temp file is opened ONCE (fopen "wb") and the FILE* reused for every
+    // transfer. Opening is lazy (first transfer) rather than in onInit: during
+    // the init cascade the upper chain isn't ready yet, so a remote fopen/free
+    // there triggers nested re-init and deadlocks the redirect thread. By first
+    // transfer the chain is fully up. The path/mode buffers are written, fed to
+    // fopen and freed immediately -- no per-transfer path re-spelling (the
+    // dominant redirection overhead) and no lingering remote buffers. Closed in onDeinit.
+    hFile;
+    tempFilePath;
+    async onInit() {
+        await super.onInit();
+        this.tempFilePath = path.join(os.tmpdir(), `exoproc-read-${randomUUID()}.tmp`);
+    }
+    onInitSync() {
+        super.onInitSync();
+        this.tempFilePath = path.join(os.tmpdir(), `exoproc-read-${randomUUID()}.tmp`);
+    }
+    // Every internal call below goes through `this.backend` (the next stage
+    // down the chain), never `this.root` -- `this.root` climbs back to the
+    // *top* of the chain and back down through this very accessor, so a plain
+    // plumbing write (the fopen path/mode strings) would re-enter
+    // readAfterInit()/readAfterInitSync() while it's already running. Routing
+    // through `this.backend` only ever moves further down the chain, so it
+    // can't loop back into this class (or any class above it) at all --
+    // no reentrancy is possible, so no reentrancy flag is needed either.
+    async ensureOpen() {
+        if (this.hFile)
+            return;
+        const pathBuf = Buffer.from(this.tempFilePath + '\0', 'utf8');
+        const modeBuf = Buffer.from('wb\0', 'utf8');
+        const pathPtr = await this.backend.alloc(pathBuf.length);
+        const modePtr = await this.backend.alloc(modeBuf.length);
+        await this.backend.write(pathPtr, pathBuf);
+        await this.backend.write(modePtr, modeBuf);
+        this.hFile = await this.backend.call(MsvcrtImpl.fopen, pathPtr, modePtr);
+        // fopen copied the path/mode strings, so the buffers can go right away.
+        await this.backend.free(pathPtr).catch(() => { });
+        await this.backend.free(modePtr).catch(() => { });
+        if (!this.hFile || Number(this.hFile) === 0) {
+            this.hFile = undefined;
+            throw new Error(`fopen failed to open temp file in write mode: ${this.tempFilePath}`);
+        }
+    }
+    ensureOpenSync() {
+        if (this.hFile)
+            return;
+        const pathBuf = Buffer.from(this.tempFilePath + '\0', 'utf8');
+        const modeBuf = Buffer.from('wb\0', 'utf8');
+        const pathPtr = this.backend.allocSync(pathBuf.length);
+        const modePtr = this.backend.allocSync(modeBuf.length);
+        this.backend.writeSync(pathPtr, pathBuf);
+        this.backend.writeSync(modePtr, modeBuf);
+        this.hFile = this.backend.callSync(MsvcrtImpl.fopen, pathPtr, modePtr);
+        try {
+            this.backend.freeSync(pathPtr);
+        }
+        catch {
+            /* ignore cleanup errors */
+        }
+        try {
+            this.backend.freeSync(modePtr);
+        }
+        catch {
+            /* ignore cleanup errors */
+        }
+        if (!this.hFile || Number(this.hFile) === 0) {
+            this.hFile = undefined;
+            throw new Error(`fopen failed to open temp file in write mode: ${this.tempFilePath}`);
+        }
+    }
+    async onDeinit() {
+        // Close via `this.backend` (not `this.root`): during teardown the chain
+        // deinits top-down, so `this.root` is already deinitialized here and a
+        // root.call would re-init the whole redirect chain via call()'s init guard.
+        // `this.backend` is still initialized at onDeinit time (it deinits after us).
+        if (this.hFile) {
+            await this.backend.call(MsvcrtImpl.fclose, this.hFile).catch(() => { });
+            this.hFile = undefined;
+        }
+        if (this.tempFilePath) {
+            try {
+                fs.unlinkSync(this.tempFilePath);
+            }
+            catch {
+                /* ignore cleanup errors */
+            }
+            this.tempFilePath = undefined;
+        }
+    }
+    onDeinitSync() {
+        if (this.hFile) {
+            try {
+                this.backend.callSync(MsvcrtImpl.fclose, this.hFile);
+            }
+            catch {
+                /* ignore cleanup errors */
+            }
+            this.hFile = undefined;
+        }
+        if (this.tempFilePath) {
+            try {
+                fs.unlinkSync(this.tempFilePath);
+            }
+            catch {
+                /* ignore cleanup errors */
+            }
+            this.tempFilePath = undefined;
+        }
+    }
+    async readAfterInit(address, size, offset = 0) {
+        if (this.isInitializing || !this.tempFilePath) {
+            return super.readAfterInit(address, size, offset);
+        }
+        await this.ensureOpen();
+        const targetAddr = resolveAddress(address) + offset;
+        // Rewind so we overwrite from the start, dump target memory into the
+        // file, then flush so the local read below sees the fresh bytes.
+        await this.backend.call(MsvcrtImpl.rewind, this.hFile);
+        const written = await this.backend.call(MsvcrtImpl.fwrite, targetAddr, 1, size, this.hFile);
+        if (Number(written) !== size) {
+            throw new Error(`fwrite failed to write entire memory block of size ${size} (wrote ${written})`);
+        }
+        await this.backend.call(MsvcrtImpl.fflush, this.hFile);
+        // The file may still carry trailing bytes from a larger previous
+        // transfer, so take only the `size` bytes we just wrote.
+        return fs.readFileSync(this.tempFilePath).subarray(0, size);
+    }
+    readAfterInitSync(address, size, offset = 0) {
+        if (this.isInitializingSync || !this.tempFilePath) {
+            return super.readAfterInitSync(address, size, offset);
+        }
+        this.ensureOpenSync();
+        const targetAddr = resolveAddress(address) + offset;
+        this.backend.callSync(MsvcrtImpl.rewind, this.hFile);
+        const written = this.backend.callSync(MsvcrtImpl.fwrite, targetAddr, 1, size, this.hFile);
+        if (Number(written) !== size) {
+            throw new Error(`fwrite failed to write entire memory block of size ${size} (wrote ${written})`);
+        }
+        this.backend.callSync(MsvcrtImpl.fflush, this.hFile);
+        return fs.readFileSync(this.tempFilePath).subarray(0, size);
+    }
+}
+/**
+ * Middleware Accessor that redirects memory writes to transfer via a temporary file,
+ * using standard C library calls (fopen, fread, fclose) in the target process.
+ * This is useful to perform structured memory staging via file systems to handle large block updates safely.
+ */
+export class FileTransferWriteAccessor extends MsvcrtDependentMiddlewareAccessor {
+    // The temp file is opened ONCE in onInit (fopen "rb") and the FILE* reused for
+    // every transfer (see FileTransferReadAccessor). Each write drops the payload
+    // into the file locally, rewinds the shared handle, and freads it into target.
+    hFile;
+    tempFilePath;
+    async onInit() {
+        await super.onInit();
+        this.tempFilePath = path.join(os.tmpdir(), `exoproc-write-${randomUUID()}.tmp`);
+    }
+    onInitSync() {
+        super.onInitSync();
+        this.tempFilePath = path.join(os.tmpdir(), `exoproc-write-${randomUUID()}.tmp`);
+    }
+    // Lazy open on first transfer -- see FileTransferReadAccessor.ensureOpen for
+    // why this can't run in onInit. The temp file must already exist on disk (the
+    // caller writes the payload before calling this) so fopen("rb") succeeds.
+    //
+    // Every internal call below goes through `this.backend` (the next stage
+    // down the chain), never `this.root` -- `this.root` climbs back to the
+    // *top* of the chain and back down through this very accessor, so a plain
+    // plumbing write (the fopen path/mode strings) would re-enter
+    // writeAfterInit()/writeAfterInitSync() while it's already running. Routing
+    // through `this.backend` only ever moves further down the chain, so it
+    // can't loop back into this class (or any class above it) at all -- no
+    // reentrancy is possible, so no reentrancy flag is needed either.
+    async ensureOpen() {
+        if (this.hFile)
+            return;
+        const pathBuf = Buffer.from(this.tempFilePath + '\0', 'utf8');
+        const modeBuf = Buffer.from('rb\0', 'utf8');
+        const pathPtr = await this.backend.alloc(pathBuf.length);
+        const modePtr = await this.backend.alloc(modeBuf.length);
+        await this.backend.write(pathPtr, pathBuf);
+        await this.backend.write(modePtr, modeBuf);
+        this.hFile = await this.backend.call(MsvcrtImpl.fopen, pathPtr, modePtr);
+        await this.backend.free(pathPtr).catch(() => { });
+        await this.backend.free(modePtr).catch(() => { });
+        if (!this.hFile || Number(this.hFile) === 0) {
+            this.hFile = undefined;
+            throw new Error(`fopen failed to open temp file in read mode: ${this.tempFilePath}`);
+        }
+    }
+    ensureOpenSync() {
+        if (this.hFile)
+            return;
+        const pathBuf = Buffer.from(this.tempFilePath + '\0', 'utf8');
+        const modeBuf = Buffer.from('rb\0', 'utf8');
+        const pathPtr = this.backend.allocSync(pathBuf.length);
+        const modePtr = this.backend.allocSync(modeBuf.length);
+        this.backend.writeSync(pathPtr, pathBuf);
+        this.backend.writeSync(modePtr, modeBuf);
+        this.hFile = this.backend.callSync(MsvcrtImpl.fopen, pathPtr, modePtr);
+        try {
+            this.backend.freeSync(pathPtr);
+        }
+        catch {
+            /* ignore cleanup errors */
+        }
+        try {
+            this.backend.freeSync(modePtr);
+        }
+        catch {
+            /* ignore cleanup errors */
+        }
+        if (!this.hFile || Number(this.hFile) === 0) {
+            this.hFile = undefined;
+            throw new Error(`fopen failed to open temp file in read mode: ${this.tempFilePath}`);
+        }
+    }
+    async onDeinit() {
+        // Close via `this.backend` -- see FileTransferReadAccessor.onDeinit.
+        if (this.hFile) {
+            await this.backend.call(MsvcrtImpl.fclose, this.hFile).catch(() => { });
+            this.hFile = undefined;
+        }
+        if (this.tempFilePath) {
+            try {
+                fs.unlinkSync(this.tempFilePath);
+            }
+            catch {
+                /* ignore cleanup errors */
+            }
+            this.tempFilePath = undefined;
+        }
+    }
+    onDeinitSync() {
+        if (this.hFile) {
+            try {
+                this.backend.callSync(MsvcrtImpl.fclose, this.hFile);
+            }
+            catch {
+                /* ignore cleanup errors */
+            }
+            this.hFile = undefined;
+        }
+        if (this.tempFilePath) {
+            try {
+                fs.unlinkSync(this.tempFilePath);
+            }
+            catch {
+                /* ignore cleanup errors */
+            }
+            this.tempFilePath = undefined;
+        }
+    }
+    async writeAfterInit(address, data, offset = 0) {
+        if (this.isInitializing || !this.tempFilePath) {
+            return super.writeAfterInit(address, data, offset);
+        }
+        const targetAddr = resolveAddress(address) + offset;
+        const buffer = data instanceof Buffer ? data : Buffer.from(data);
+        // Put the payload in the file (local, truncating write) BEFORE opening so
+        // fopen("rb") sees a valid file, then rewind the shared FILE* so fread
+        // re-reads the freshly written bytes from offset 0.
+        fs.writeFileSync(this.tempFilePath, buffer);
+        await this.ensureOpen();
+        await this.backend.call(MsvcrtImpl.rewind, this.hFile);
+        const readBytes = await this.backend.call(MsvcrtImpl.fread, targetAddr, 1, buffer.length, this.hFile);
+        if (Number(readBytes) !== buffer.length) {
+            throw new Error(`fread failed to read entire file block of size ${buffer.length} (read ${readBytes})`);
+        }
+        return Number(readBytes);
+    }
+    writeAfterInitSync(address, data, offset = 0) {
+        if (this.isInitializingSync || !this.tempFilePath) {
+            return super.writeAfterInitSync(address, data, offset);
+        }
+        const targetAddr = resolveAddress(address) + offset;
+        const buffer = data instanceof Buffer ? data : Buffer.from(data);
+        fs.writeFileSync(this.tempFilePath, buffer);
+        this.ensureOpenSync();
+        this.backend.callSync(MsvcrtImpl.rewind, this.hFile);
+        const readBytes = this.backend.callSync(MsvcrtImpl.fread, targetAddr, 1, buffer.length, this.hFile);
+        if (Number(readBytes) !== buffer.length) {
+            throw new Error(`fread failed to read entire file block of size ${buffer.length} (read ${readBytes})`);
+        }
+        return Number(readBytes);
+    }
+}
+/**
+ * Middleware Accessor that caches target process metadata (bitness, process name, core modules status)
+ * on demand, and intercepts dynamic module queries to cache returned module handles.
+ */
+export class ProcessCacheAccessor extends InittableMiddlewareAccessor {
+    static TARGET_MODULE_NAMES = new Set([
+        'msvcrt',
+        'msvcrt.dll',
+        'user32',
+        'user32.dll',
+    ]);
+    /** Pure, no I/O -- shared by every place that needs to trim/lowercase a module name buffer. */
+    static extractModuleName(buf) {
+        let len = buf.indexOf(0);
+        if (len === -1)
+            len = buf.length;
+        return buf.subarray(0, len).toString('utf8').toLowerCase();
+    }
+    /** Pure, no I/O -- shared by callAfterInit()/callAfterInitSync(). */
+    static resolveTrackedAddrs() {
+        return {
+            getModuleHandleExAAddr: resolveAddress(Kernel32Impl.GetModuleHandleExA.ptr),
+            getModuleHandleAAddr: resolveAddress(Kernel32Impl.GetModuleHandleA.ptr),
+            getCurrentProcessAddr: resolveAddress(Kernel32Impl.GetCurrentProcess.ptr),
+            getCurrentProcessIdAddr: resolveAddress(Kernel32Impl.GetCurrentProcessId.ptr),
+        };
+    }
+    /** Pure, no I/O -- shared by getIs64Bit()/getIs64BitSync() to find an already-open handle in the chain. */
+    static findOpenHandleInChain(backend) {
+        let curr = backend;
+        while (curr) {
+            if (curr.handle !== undefined &&
+                curr.handle !== null &&
+                Number(curr.handle) !== 0) {
+                return curr.handle;
+            }
+            curr = curr.backend;
+        }
+        return null;
+    }
+    writeMemoryCache = new Map();
+    moduleHandleCache = new Map();
+    cachedIs64Bit = null;
+    cachedProcessName = null;
+    cachedCoreModules = null;
+    async onInit() {
+        // Empty JIT initialization since metadata is queried on demand
+    }
+    onInitSync() {
+        // Empty JIT initialization since metadata is queried on demand
+    }
+    /** Core of getIs64Bit()/getIs64BitSync() -- entirely local/synchronous Win32 calls already, so both share this verbatim. */
+    getIs64BitCore() {
+        if (this.cachedIs64Bit !== null) {
+            return this.cachedIs64Bit;
+        }
+        const handle = ProcessCacheAccessor.findOpenHandleInChain(this.backend);
+        const hProcess = handle ||
+            Kernel32Impl.OpenProcess(ProcessAccess.QUERY_INFORMATION | ProcessAccess.VM_READ, 0, this.processId);
+        const ownsHandle = !handle && hProcess && Number(hProcess) !== 0;
+        if (hProcess && Number(hProcess) !== 0) {
+            try {
+                const wow64Buf = Buffer.alloc(4);
+                const success = Kernel32Impl.IsWow64Process(hProcess, wow64Buf);
+                if (Number(success) !== 0) {
+                    const is32Bit = wow64Buf.readUInt32LE(0) !== 0;
+                    this.cachedIs64Bit = !is32Bit;
+                }
+                else {
+                    this.cachedIs64Bit = true; // Default to 64-bit on failure
+                }
+            }
+            finally {
+                if (ownsHandle) {
+                    Kernel32Impl.CloseHandle(hProcess);
+                }
+            }
+        }
+        else {
+            this.cachedIs64Bit = true;
+        }
+        return this.cachedIs64Bit;
+    }
+    async getIs64Bit() {
+        await this.init();
+        return this.getIs64BitCore();
+    }
+    /** Sync twin of getIs64Bit() -- initializes the chain via initSync() if it hasn't run yet. */
+    getIs64BitSync() {
+        if (!this.isInitializingSync) {
+            this.initSync();
+        }
+        return this.getIs64BitCore();
+    }
+    /** Core of getProcessName()/getProcessNameSync() -- entirely local/synchronous Win32 calls already, so both share this verbatim. */
+    getProcessNameCore() {
+        if (this.cachedProcessName !== null) {
+            return this.cachedProcessName;
+        }
+        const hSnapshot = Kernel32Impl.CreateToolhelp32Snapshot(ToolhelpSnapshotFlag.PROCESS, 0);
+        if (hSnapshot && Number(hSnapshot) !== 0 && Number(hSnapshot) !== -1) {
+            try {
+                const size = PROCESSENTRY32W_SIZE;
+                const buf = Buffer.alloc(size);
+                buf.writeUInt32LE(size, 0);
+                let ok = Kernel32Impl.Process32FirstW(hSnapshot, buf);
+                while (Number(ok) !== 0) {
+                    const pid = buf.readUInt32LE(8);
+                    if (pid === this.processId) {
+                        const nameBuf = buf.subarray(44, 44 + 520);
+                        let len = 0;
+                        for (let i = 0; i < nameBuf.length; i += 2) {
+                            if (nameBuf[i] === 0 && nameBuf[i + 1] === 0) {
+                                len = i;
+                                break;
+                            }
+                        }
+                        this.cachedProcessName = nameBuf
+                            .subarray(0, len)
+                            .toString('utf16le');
+                        break;
+                    }
+                    buf.writeUInt32LE(size, 0);
+                    ok = Kernel32Impl.Process32NextW(hSnapshot, buf);
+                }
+            }
+            finally {
+                Kernel32Impl.CloseHandle(hSnapshot);
+            }
+        }
+        return this.cachedProcessName ?? '';
+    }
+    async getProcessName() {
+        await this.init();
+        return this.getProcessNameCore();
+    }
+    /** Sync twin of getProcessName() -- initializes the chain via initSync() if it hasn't run yet. */
+    getProcessNameSync() {
+        if (!this.isInitializingSync) {
+            this.initSync();
+        }
+        return this.getProcessNameCore();
+    }
+    async getCoreModules() {
+        await this.init();
+        if (this.cachedCoreModules !== null) {
+            return this.cachedCoreModules;
+        }
+        this.cachedCoreModules = await verifyCoreModules(this);
+        return this.cachedCoreModules;
+    }
+    /** Sync twin of getCoreModules() -- initializes the chain via initSync() if it hasn't run yet. */
+    getCoreModulesSync() {
+        if (!this.isInitializingSync) {
+            this.initSync();
+        }
+        if (this.cachedCoreModules !== null) {
+            return this.cachedCoreModules;
+        }
+        this.cachedCoreModules = verifyCoreModulesSync(this);
+        return this.cachedCoreModules;
+    }
+    async writeAfterInit(address, data, offset = 0) {
+        const addrVal = resolveAddress(address) + offset;
+        const buf = data instanceof Buffer ? data : Buffer.from(data);
+        this.writeMemoryCache.set(addrVal, buf);
+        return super.writeAfterInit(address, data, offset);
+    }
+    writeAfterInitSync(address, data, offset = 0) {
+        const addrVal = resolveAddress(address) + offset;
+        const buf = data instanceof Buffer ? data : Buffer.from(data);
+        this.writeMemoryCache.set(addrVal, buf);
+        return super.writeAfterInitSync(address, data, offset);
+    }
+    /** Cache lookup for a module name buffer at `namePtr` -- pure, no I/O; `null` means the caller must read it remotely. */
+    cachedModuleName(namePtr) {
+        const writtenBuf = this.writeMemoryCache.get(namePtr);
+        return writtenBuf
+            ? ProcessCacheAccessor.extractModuleName(writtenBuf)
+            : null;
+    }
+    async resolveModuleName(namePtr) {
+        const cached = this.cachedModuleName(namePtr);
+        if (cached !== null)
+            return cached;
+        try {
+            const buf = await this.root.read(namePtr, 256);
+            return ProcessCacheAccessor.extractModuleName(buf);
+        }
+        catch {
+            return '';
+        }
+    }
+    resolveModuleNameSync(namePtr) {
+        const cached = this.cachedModuleName(namePtr);
+        if (cached !== null)
+            return cached;
+        try {
+            const buf = this.root.readSync(namePtr, 256);
+            return ProcessCacheAccessor.extractModuleName(buf);
+        }
+        catch {
+            return '';
+        }
+    }
+    async callAfterInit(func, args) {
+        const funcAddr = resolveAddress(func.ptr);
+        const { getModuleHandleExAAddr, getModuleHandleAAddr, getCurrentProcessAddr, getCurrentProcessIdAddr, } = ProcessCacheAccessor.resolveTrackedAddrs();
+        if (funcAddr === getCurrentProcessAddr) {
+            return 0xffffffffffffffffn;
+        }
+        else if (funcAddr === getCurrentProcessIdAddr) {
+            return this.processId;
+        }
+        if (funcAddr === getModuleHandleExAAddr && args.length >= 3) {
+            const flags = Number(args[0]);
+            const namePtr = resolveAddress(args[1]);
+            const outPtr = resolveAddress(args[2]);
+            const isFromAddress = (flags & 4) !== 0;
+            if (!isFromAddress && BigInt(namePtr) !== 0n) {
+                const moduleName = await this.resolveModuleName(namePtr);
+                const isTargetModule = ProcessCacheAccessor.TARGET_MODULE_NAMES.has(moduleName);
+                if (isTargetModule && this.moduleHandleCache.has(moduleName)) {
+                    const cachedHModule = this.moduleHandleCache.get(moduleName);
+                    const hModuleBuf = Buffer.alloc(8);
+                    hModuleBuf.writeBigUInt64LE(cachedHModule, 0);
+                    await this.root.write(outPtr, hModuleBuf);
+                    return 1;
+                }
+                const result = await this.backend.call(func, args);
+                if (isTargetModule && Number(result) !== 0) {
+                    const hModuleBuf = await this.root.read(outPtr, 8);
+                    const hModule = hModuleBuf.readBigUInt64LE(0);
+                    this.moduleHandleCache.set(moduleName, hModule);
+                }
+                return result;
+            }
+        }
+        else if (funcAddr === getModuleHandleAAddr && args.length >= 1) {
+            const namePtr = resolveAddress(args[0]);
+            if (BigInt(namePtr) !== 0n) {
+                const moduleName = await this.resolveModuleName(namePtr);
+                const isTargetModule = ProcessCacheAccessor.TARGET_MODULE_NAMES.has(moduleName);
+                if (isTargetModule && this.moduleHandleCache.has(moduleName)) {
+                    return this.moduleHandleCache.get(moduleName);
+                }
+                const result = await this.backend.call(func, args);
+                if (isTargetModule && result && Number(result) !== 0) {
+                    this.moduleHandleCache.set(moduleName, BigInt(result));
+                }
+                return result;
+            }
+        }
+        return super.callAfterInit(func, args);
+    }
+    callAfterInitSync(func, args) {
+        const funcAddr = resolveAddress(func.ptr);
+        const { getModuleHandleExAAddr, getModuleHandleAAddr, getCurrentProcessAddr, getCurrentProcessIdAddr, } = ProcessCacheAccessor.resolveTrackedAddrs();
+        if (funcAddr === getCurrentProcessAddr) {
+            return 0xffffffffffffffffn;
+        }
+        else if (funcAddr === getCurrentProcessIdAddr) {
+            return this.processId;
+        }
+        if (funcAddr === getModuleHandleExAAddr && args.length >= 3) {
+            const flags = Number(args[0]);
+            const namePtr = resolveAddress(args[1]);
+            const outPtr = resolveAddress(args[2]);
+            const isFromAddress = (flags & 4) !== 0;
+            if (!isFromAddress && BigInt(namePtr) !== 0n) {
+                const moduleName = this.resolveModuleNameSync(namePtr);
+                const isTargetModule = ProcessCacheAccessor.TARGET_MODULE_NAMES.has(moduleName);
+                if (isTargetModule && this.moduleHandleCache.has(moduleName)) {
+                    const cachedHModule = this.moduleHandleCache.get(moduleName);
+                    const hModuleBuf = Buffer.alloc(8);
+                    hModuleBuf.writeBigUInt64LE(cachedHModule, 0);
+                    this.root.writeSync(outPtr, hModuleBuf);
+                    return 1;
+                }
+                const result = this.backend.callSync(func, args);
+                if (isTargetModule && Number(result) !== 0) {
+                    const hModuleBuf = this.root.readSync(outPtr, 8);
+                    const hModule = hModuleBuf.readBigUInt64LE(0);
+                    this.moduleHandleCache.set(moduleName, hModule);
+                }
+                return result;
+            }
+        }
+        else if (funcAddr === getModuleHandleAAddr && args.length >= 1) {
+            const namePtr = resolveAddress(args[0]);
+            if (BigInt(namePtr) !== 0n) {
+                const moduleName = this.resolveModuleNameSync(namePtr);
+                const isTargetModule = ProcessCacheAccessor.TARGET_MODULE_NAMES.has(moduleName);
+                if (isTargetModule && this.moduleHandleCache.has(moduleName)) {
+                    return this.moduleHandleCache.get(moduleName);
+                }
+                const result = this.backend.callSync(func, args);
+                if (isTargetModule && result && Number(result) !== 0) {
+                    this.moduleHandleCache.set(moduleName, BigInt(result));
+                }
+                return result;
+            }
+        }
+        return super.callAfterInitSync(func, args);
+    }
+    async freeAfterInit(address, size, freeType) {
+        const addrVal = resolveAddress(address);
+        this.writeMemoryCache.delete(addrVal);
+        return super.freeAfterInit(address, size, freeType);
+    }
+    freeAfterInitSync(address, size, freeType) {
+        const addrVal = resolveAddress(address);
+        this.writeMemoryCache.delete(addrVal);
+        return super.freeAfterInitSync(address, size, freeType);
+    }
+}
+export class MachineCodePoolMiddleware extends MiddlewareAccessor {
+    blocks = [];
+    alignment = DEFAULT_MACHINECODE_ALIGNMENT;
+    defaultBlockSize = 4096;
+    /**
+     * Shared by getOrAllocBlock()/getOrAllocBlockSync() -- pure scan for
+     * existing space, no I/O, so no need for two copies. `null` means the
+     * caller must allocate a fresh block itself (the only part that needs I/O).
+     */
+    findBlockWithSpace(needed) {
+        for (let i = 0; i < this.blocks.length; i++) {
+            const block = this.blocks[i];
+            const alignedUsed = alignUp(block.used, this.alignment);
+            if (block.size - alignedUsed >= needed) {
+                return { address: block.address, offset: alignedUsed, blockIdx: i };
+            }
+        }
+        return null;
+    }
+    async getOrAllocBlock(needed) {
+        const existing = this.findBlockWithSpace(needed);
+        if (existing)
+            return existing;
+        const blockSize = Math.max(this.defaultBlockSize, needed);
+        const blockAddr = await this.root.alloc(blockSize, null, MemoryProtection.EXECUTE_READWRITE);
+        const address = Number(resolveAddress(blockAddr));
+        this.blocks.push({ address, size: blockSize, used: 0 });
+        return { address, offset: 0, blockIdx: this.blocks.length - 1 };
+    }
+    getOrAllocBlockSync(needed) {
+        const existing = this.findBlockWithSpace(needed);
+        if (existing)
+            return existing;
+        const blockSize = Math.max(this.defaultBlockSize, needed);
+        const blockAddr = this.root.allocSync(blockSize, null, MemoryProtection.EXECUTE_READWRITE);
+        const address = Number(resolveAddress(blockAddr));
+        this.blocks.push({ address, size: blockSize, used: 0 });
+        return { address, offset: 0, blockIdx: this.blocks.length - 1 };
+    }
+    async machineCode(machineCode) {
+        const size = machineCode.size;
+        const bytes = Array.isArray(machineCode.bytes)
+            ? new Uint8Array(machineCode.bytes)
+            : machineCode.bytes;
+        const { address, offset, blockIdx } = await this.getOrAllocBlock(size);
+        const targetAddr = address + offset;
+        await this.root.write(targetAddr, bytes);
+        this.blocks[blockIdx].used = offset + size;
+        return targetAddr;
+    }
+    machineCodeSync(machineCode) {
+        const size = machineCode.size;
+        const bytes = Array.isArray(machineCode.bytes)
+            ? new Uint8Array(machineCode.bytes)
+            : machineCode.bytes;
+        const { address, offset, blockIdx } = this.getOrAllocBlockSync(size);
+        const targetAddr = address + offset;
+        this.root.writeSync(targetAddr, bytes);
+        this.blocks[blockIdx].used = offset + size;
+        return targetAddr;
+    }
+}
+export class ScannerMiddleware extends MiddlewareAccessor {
+    /**
+     * Shared by scan()/scanSync() -- pure decision of which memmemN machineCode
+     * to upload and how to encode the needle for a given pattern width, no I/O.
+     * `sc` still needs uploading (await machineCode() vs machineCodeSync()) by
+     * the caller; `needleVal`/`isWithoutBuffer` are used directly once uploaded.
+     */
+    static pickMemmemVariant(n, patBytes) {
+        if (n === 1) {
+            return {
+                sc: memmem1,
+                needleVal: BigInt(patBytes.readUInt8(0)),
+                isWithoutBuffer: true,
+            };
+        }
+        else if (n === 2) {
+            return {
+                sc: memmem2,
+                needleVal: BigInt(patBytes.readUInt16LE(0)),
+                isWithoutBuffer: true,
+            };
+        }
+        else if (n === 3 || n === 5 || n === 6 || n === 7) {
+            let val = 0n;
+            for (let i = 0; i < n; i++) {
+                val |= BigInt(patBytes[i]) << BigInt(i * 8);
+            }
+            return { sc: memmemWithoutBuffer, needleVal: val, isWithoutBuffer: true };
+        }
+        else if (n === 4) {
+            return {
+                sc: memmem4,
+                needleVal: BigInt(patBytes.readUInt32LE(0)),
+                isWithoutBuffer: true,
+            };
+        }
+        else if (n === 8) {
+            return {
+                sc: memmem8,
+                needleVal: patBytes.readBigUInt64LE(0),
+                isWithoutBuffer: true,
+            };
+        }
+        return { sc: memmem, needleVal: 0n, isWithoutBuffer: false };
+    }
+    async *scan(address, size, pattern) {
+        const pat = typeof pattern === 'string' ? new Pattern(pattern) : pattern;
+        const startAddr = BigInt(resolveAddress(address));
+        const end = startAddr + BigInt(size);
+        let current = startAddr;
+        while (current < end) {
+            const mbi = await this.root.query(current);
+            const regionBase = BigInt(resolveAddress(mbi.BaseAddress));
+            const regionSize = BigInt(mbi.RegionSize);
+            const regionEnd = regionBase + regionSize;
+            const isReadable = mbi.State === MemoryState.COMMIT &&
+                !(mbi.Protect & MemoryProtection.GUARD) &&
+                !!(mbi.Protect & pat.protect);
+            if (isReadable) {
+                const scanStart = current > regionBase ? current : regionBase;
+                const scanEnd = end < regionEnd ? end : regionEnd;
+                const scanSize = Number(scanEnd - scanStart);
+                if (scanSize >= pat.length) {
+                    const n = pat.length;
+                    const { sc, needleVal, isWithoutBuffer } = ScannerMiddleware.pickMemmemVariant(n, pat.bytes);
+                    const addr = await this.root.machineCode(sc);
+                    const memmemFnRemote = sc.cloneForAddress(addr);
+                    let needleRemoteAddr = 0n;
+                    if (!isWithoutBuffer) {
+                        needleRemoteAddr = await this.root.alloc(n);
+                        await this.root.write(needleRemoteAddr, pat.bytes);
+                    }
+                    try {
+                        const memmemFn = async (haystack, haystackLen) => {
+                            const callArgs = [
+                                haystack,
+                                haystackLen,
+                                isWithoutBuffer ? needleVal : needleRemoteAddr,
+                            ];
+                            if (n !== 1 && n !== 2 && n !== 4 && n !== 8) {
+                                callArgs.push(BigInt(n));
+                            }
+                            const res = await this.root.call(memmemFnRemote, ...callArgs);
+                            return BigInt(resolveAddress(res));
+                        };
+                        yield* Scanner.scan(new NativeMemory(scanStart, scanSize), pat, memmemFn);
+                    }
+                    finally {
+                        if (BigInt(resolveAddress(needleRemoteAddr)) !== 0n) {
+                            await this.root.free(needleRemoteAddr, n);
+                        }
+                    }
+                }
+            }
+            if (regionEnd <= current)
+                break;
+            current = regionEnd;
+        }
+    }
+    *scanSync(address, size, pattern) {
+        const pat = typeof pattern === 'string' ? new Pattern(pattern) : pattern;
+        const startAddr = BigInt(resolveAddress(address));
+        const end = startAddr + BigInt(size);
+        let current = startAddr;
+        while (current < end) {
+            const mbi = this.root.querySync(current);
+            const regionBase = BigInt(resolveAddress(mbi.BaseAddress));
+            const regionSize = BigInt(mbi.RegionSize);
+            const regionEnd = regionBase + regionSize;
+            const isReadable = mbi.State === MemoryState.COMMIT &&
+                !(mbi.Protect & MemoryProtection.GUARD) &&
+                !!(mbi.Protect & pat.protect);
+            if (isReadable) {
+                const scanStart = current > regionBase ? current : regionBase;
+                const scanEnd = end < regionEnd ? end : regionEnd;
+                const scanSize = Number(scanEnd - scanStart);
+                if (scanSize >= pat.length) {
+                    const n = pat.length;
+                    const { sc, needleVal, isWithoutBuffer } = ScannerMiddleware.pickMemmemVariant(n, pat.bytes);
+                    const addr = this.root.machineCodeSync(sc);
+                    const memmemFnRemote = sc.cloneForAddress(addr);
+                    let needleRemoteAddr = 0n;
+                    if (!isWithoutBuffer) {
+                        needleRemoteAddr = this.root.allocSync(n);
+                        this.root.writeSync(needleRemoteAddr, pat.bytes);
+                    }
+                    try {
+                        const memmemFn = (haystack, haystackLen) => {
+                            const callArgs = [
+                                haystack,
+                                haystackLen,
+                                isWithoutBuffer ? needleVal : needleRemoteAddr,
+                            ];
+                            if (n !== 1 && n !== 2 && n !== 4 && n !== 8) {
+                                callArgs.push(BigInt(n));
+                            }
+                            const res = this.root.callSync(memmemFnRemote, ...callArgs);
+                            return BigInt(resolveAddress(res));
+                        };
+                        yield* Scanner.scanSync(new NativeMemory(scanStart, scanSize), pat, memmemFn);
+                    }
+                    finally {
+                        if (BigInt(resolveAddress(needleRemoteAddr)) !== 0n) {
+                            this.root.freeSync(needleRemoteAddr, n);
+                        }
+                    }
+                }
+            }
+            if (regionEnd <= current)
+                break;
+            current = regionEnd;
+        }
+    }
+}
+//# sourceMappingURL=middleware-accessor.js.map