reverseport 0.0.0-stage → 1.2.0

package/dist/evm/EvmoleInterfaceProvider.js

@@ -0,0 +1,339 @@
+import { createHash, randomUUID } from "node:crypto";
+import { access, readFile, stat, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { readStableArtifact } from "../artifacts/readStableArtifact.js";
+import { OwnedCommandFailure } from "../process/OwnedCommand.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisUnsupportedTargetError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { evmInterfaceSchema } from "../domain/evm/evmInterface.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { err, ok } from "../domain/result.js";
+import { runOwnedCommand } from "../process/OwnedCommand.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+import { evmInterfaceFailure, capturedEvmOutput, } from "./EvmoleFailures.js";
+import { evmoleInterfaceReplySchema, projectEvmoleInterface, } from "./EvmoleInterfaceAdapter.js";
+import { EVMOLE_PROVIDER_IDENTITY, EVM_INTERFACE_LIMITS, EVM_FILE_SIZE_FAILURE_EXIT, } from "./EvmoleRelease.js";
+import { decodeEvmBytecodeCarrier } from "./EvmBytecodeCarrier.js";
+import { selectEvmWorkerLimits, } from "./EvmWorkerLimits.js";
+const OPERATION = "inspect_evm_interface";
+const HOST_REQUIREMENT = "Initial real-verified offline EVM interface profile supports Linux x64 only.";
+const replySchema = z.discriminatedUnion("ok", [
+    z.strictObject({
+        ok: z.literal(true),
+        version: z.literal("0.9.3"),
+        bytecode: z.strictObject({
+            sha256: z.string().regex(/^[a-f0-9]{64}$/),
+            bytes: z.number().int().nonnegative(),
+            hex: z.string().regex(/^(?:[a-f0-9]{2})*$/),
+        }),
+        raw: evmoleInterfaceReplySchema,
+    }),
+    z.strictObject({
+        ok: z.literal(false),
+        reason: z.enum(["format", "decoder", "output-limit", "unsupported"]),
+        message: z.string(),
+    }),
+]);
+/** Run unchanged EVMole/WASM in an owned worker; no target, chain or network execution. */
+export class EvmoleInterfaceProvider {
+    environment;
+    launcher;
+    createRuntime;
+    #tail = Promise.resolve();
+    #closing = false;
+    #closePromise;
+    #pendingCleanup;
+    constructor(environment = process.env, launcher, createRuntime = () => PrivateRuntimeRoot.create({ prefix: "rea-evm-interface-" })) {
+        this.environment = environment;
+        this.launcher = launcher;
+        this.createRuntime = createRuntime;
+    }
+    /** Bind recovered interface candidates to both original carrier and decoded byte identity. */
+    inspect(input, options) {
+        if (this.#closing)
+            return Promise.resolve(err(this.#closedError()));
+        const operation = this.#tail.then(() => this.#closing ? err(this.#closedError()) : this.#inspect(input, options));
+        this.#tail = operation.then(() => undefined, () => undefined);
+        return operation;
+    }
+    async #inspect(input, options) {
+        const pending = await this.#retire();
+        if (pending !== undefined)
+            return err(pending);
+        let root;
+        let processOwner;
+        let retainedOutput;
+        let phase = "configuration";
+        let workerLimits;
+        const limiter = this.environment.REA_EVM_PRLIMIT_COMMAND ?? "/usr/bin/prlimit";
+        let result;
+        try {
+            if (options?.signal?.aborted)
+                throw new AnalysisCancelledError(OPERATION);
+            if (process.platform !== "linux" || process.arch !== "x64")
+                throw new AnalysisCapabilityUnavailableError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, HOST_REQUIREMENT, { userMessage: HOST_REQUIREMENT });
+            try {
+                if (!isAbsolute(limiter))
+                    throw new Error("REA_EVM_PRLIMIT_COMMAND must be an absolute executable path.");
+                await access(limiter, constants.X_OK);
+                if (!(await stat(limiter)).isFile())
+                    throw new Error("Configured prlimit must be a regular executable file, not a directory.");
+            }
+            catch (cause) {
+                const reason = `Offline EVM interface inspection requires caller-supplied util-linux prlimit: ${limiter}; ${cause instanceof Error ? cause.message : String(cause)}`;
+                throw new AnalysisCapabilityUnavailableError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, reason, { cause, userMessage: reason });
+            }
+            let inheritedLimits;
+            try {
+                inheritedLimits = await readFile("/proc/self/limits", "utf8");
+            }
+            catch (cause) {
+                const reason = `Could not read inherited Linux resource limits at /proc/self/limits: ${cause instanceof Error ? cause.message : String(cause)}`;
+                throw new AnalysisCapabilityUnavailableError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, reason, { cause, userMessage: reason });
+            }
+            const limits = selectEvmWorkerLimits(inheritedLimits);
+            if (!limits.ok)
+                throw new AnalysisCapabilityUnavailableError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, limits.error, { userMessage: limits.error });
+            workerLimits = limits.value;
+            phase = "artifact-read";
+            const carrier = await readStableArtifact(input.path, EVM_INTERFACE_LIMITS.inputBytes, options?.signal);
+            phase = "worker";
+            root = await this.createRuntime();
+            const snapshotPath = join(root.path, "carrier.snapshot");
+            const requestPath = join(root.path, "request.json");
+            const replyPath = join(root.path, "reply.json");
+            await writeFile(snapshotPath, carrier.bytes, {
+                flag: "wx",
+                mode: 0o600,
+                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+            });
+            await writeFile(requestPath, JSON.stringify({
+                snapshot_path: snapshotPath,
+                reply_path: replyPath,
+                failure_marker_path: join(root.path, "resource.failure"),
+                encoding: input.encoding,
+            }), { flag: "wx", mode: 0o600 });
+            const { NODE_OPTIONS: _ambientNodeOptions, ...environment } = this.environment;
+            const execution = await runOwnedCommand({
+                command: limiter,
+                arguments: [
+                    `--as=${String(workerLimits.addressSpaceBytes)}:`,
+                    `--fsize=${String(workerLimits.fileSizeBytes)}:`,
+                    "--core=0:",
+                    `--cpu=${String(workerLimits.cpuSeconds)}:`,
+                    "--",
+                    process.execPath,
+                    "--max-old-space-size=256",
+                    "--v8-pool-size=1",
+                    "--disable-wasm-trap-handler",
+                    fileURLToPath(new URL("./EvmoleInterfaceWorker.js", import.meta.url)),
+                    requestPath,
+                ],
+                cwd: root.path,
+                expectedCommand: null,
+                runId: `rea-evm-interface-${randomUUID()}`,
+                hostEnvironment: environment,
+            }, {
+                timeoutMs: EVM_INTERFACE_LIMITS.timeoutMs,
+                diagnosticBytes: EVM_INTERFACE_LIMITS.diagnosticBytes,
+            }, {
+                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+                ...(this.launcher === undefined ? {} : { launcher: this.launcher }),
+            });
+            const capturedOutput = capturedEvmOutput(execution);
+            retainedOutput = capturedOutput;
+            let reply;
+            try {
+                const file = await readStableArtifact(replyPath, EVM_INTERFACE_LIMITS.outputBytes, options?.signal);
+                reply = replySchema.parse(JSON.parse(file.bytes.toString("utf8")));
+            }
+            catch (cause) {
+                if (options?.signal?.aborted)
+                    throw new AnalysisCancelledError(OPERATION, { capturedOutput });
+                throw new AnalysisOutputError(OPERATION, `Owned interface worker reply failed for ${input.path}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause, capturedOutput });
+            }
+            if (!reply.ok) {
+                if (reply.reason === "unsupported")
+                    throw new AnalysisUnsupportedTargetError(OPERATION, input.path, reply.message, { capturedOutput });
+                if (reply.reason === "format")
+                    throw new AnalysisInputError(OPERATION, { capturedOutput }, [
+                        {
+                            path: ["path"],
+                            reason: "invalid_format",
+                            message: reply.message,
+                        },
+                    ]);
+                if (reply.reason === "output-limit")
+                    throw new AnalysisOutputError(OPERATION, reply.message, {
+                        capturedOutput,
+                    });
+                throw new ProviderAdapterError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, {
+                    diagnostics: {
+                        phase,
+                        failure_kind: reply.reason,
+                        reason: reply.message,
+                        stdout: execution.stdout.text,
+                        stderr: execution.stderr.text,
+                        captured_output: { ...capturedOutput },
+                    },
+                });
+            }
+            const selectedBytes = decodeEvmBytecodeCarrier(carrier.bytes, input.encoding);
+            const selectedHex = Buffer.from(selectedBytes).toString("hex");
+            const decodedHash = createHash("sha256")
+                .update(selectedBytes)
+                .digest("hex");
+            if (decodedHash !== reply.bytecode.sha256 ||
+                selectedHex !== reply.bytecode.hex ||
+                selectedBytes.length !== reply.bytecode.bytes)
+                throw new AnalysisOutputError(OPERATION, "Decoded bytecode representation does not match the selected carrier, encoding or reported SHA-256.", { capturedOutput });
+            const limitations = [
+                `Configured worker resource soft limits: address_space_bytes=${String(workerLimits.addressSpaceBytes)}, cpu_seconds=${String(workerLimits.cpuSeconds)}, file_size_bytes=${String(workerLimits.fileSizeBytes)}. Selected from inherited tighter limits; original hard limits are retained. Effective worker limits are not independently probed.`,
+                "Upstream may also report terminal metadata while recovering selectors. Its reported values are retained in raw_result, but integer precision and non-text-key coverage are unknown in the JS binding; complete original bytecode remains available.",
+                "Recovered selectors, argument strings and mutability are upstream inferences, not verified ABI signatures or names. Empty results do not prove the absence of callable dispatch.",
+                "Bytecode kind, hardfork and deployed-contract authenticity are unknown. This inspection performs no target runtime execution, chain/RPC lookup or network request.",
+                "Original carrier and decoded bytecode SHA-256 are distinct identities; SHA-256 is not the Ethereum Keccak code hash.",
+                "The owned worker has a 256 MiB JavaScript heap, 3 GiB virtual address-space limit and 30-second deadline. Virtual address space is distinct from resident memory; limits fail without partial success.",
+            ];
+            const validated = evmInterfaceSchema.safeParse({
+                artifact: {
+                    path: input.path,
+                    sha256: carrier.sha256,
+                    bytes: carrier.bytes.length,
+                    encoding: input.encoding,
+                },
+                bytecode: {
+                    ...reply.bytecode,
+                    digest_algorithm: "sha256",
+                    kind: "unknown",
+                    deployment_authenticity: "unknown",
+                    hardfork: "unknown",
+                },
+                evidence_kind: "inferred",
+                functions: projectEvmoleInterface(reply.raw).functions,
+                discovery_completeness: "unknown",
+                runtime_execution: "not-performed",
+                diagnostics: {
+                    stdout: execution.stdout.text,
+                    stderr: execution.stderr.text,
+                    truncated: capturedOutput.truncated,
+                },
+                limitations,
+            });
+            if (!validated.success)
+                throw new AnalysisOutputError(OPERATION, `Interface worker returned invalid bytecode-relative evidence: ${validated.error.issues[0]?.message ?? "schema mismatch"}`, { capturedOutput });
+            const report = validated.data;
+            result = ok(createAnalysisExecution(report, EVMOLE_PROVIDER_IDENTITY, {
+                rawResult: reply.raw,
+                subject: { path: input.path, format: "file", sha256: carrier.sha256 },
+                locations: [{ kind: "artifact-path", path: input.path }],
+                limitations,
+            }));
+        }
+        catch (cause) {
+            if (cause instanceof OwnedCommandFailure)
+                processOwner = cause.cleanupOwner;
+            let fileFailure;
+            if (cause instanceof OwnedCommandFailure &&
+                cause.snapshot?.exitCode === EVM_FILE_SIZE_FAILURE_EXIT &&
+                cause.snapshot.signal === null &&
+                root !== undefined) {
+                try {
+                    const marker = await readStableArtifact(join(root.path, "resource.failure"), 1);
+                    if (!marker.bytes.equals(Buffer.from("F")))
+                        throw new Error("Private worker failure marker does not match the observed exit status.");
+                    fileFailure = { verified: true, failure: null };
+                }
+                catch (markerFailure) {
+                    fileFailure = {
+                        verified: false,
+                        failure: markerFailure instanceof Error
+                            ? markerFailure.message
+                            : String(markerFailure),
+                    };
+                }
+            }
+            result = err(options?.signal?.aborted &&
+                (cause === options.signal.reason ||
+                    (cause instanceof Error && cause.name === "AbortError"))
+                ? new AnalysisCancelledError(OPERATION, retainedOutput === undefined
+                    ? undefined
+                    : { capturedOutput: retainedOutput })
+                : evmInterfaceFailure(cause, phase, input.path, workerLimits, limiter, fileFailure));
+        }
+        if (processOwner !== undefined) {
+            this.#pendingCleanup = { root, process: processOwner };
+            // The command failure already owns this cleanup diagnostic and its resources.
+            return result;
+        }
+        if (root !== undefined) {
+            try {
+                await root.close();
+            }
+            catch (cause) {
+                const retainedRoot = root;
+                this.#pendingCleanup = { root: retainedRoot, process: undefined };
+                root = undefined;
+                return err(new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, [retainedRoot.path], {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                    previous_error: result.ok
+                        ? null
+                        : projectAnalysisError(result.error),
+                    ...(retainedOutput === undefined
+                        ? {}
+                        : { captured_output: { ...retainedOutput } }),
+                }, { operation: OPERATION }));
+            }
+        }
+        return result.ok && options?.signal?.aborted
+            ? err(new AnalysisCancelledError(OPERATION, retainedOutput === undefined
+                ? undefined
+                : { capturedOutput: retainedOutput }))
+            : result;
+    }
+    async close() {
+        this.#closing = true;
+        this.#closePromise ??= this.#tail
+            .then(async () => {
+            const failure = await this.#retire();
+            if (failure !== undefined)
+                throw failure;
+        })
+            .catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
+        return this.#closePromise;
+    }
+    #closedError() {
+        return new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, [], { reason: "Provider is closing" }, { operation: OPERATION });
+    }
+    async #retire() {
+        const pending = this.#pendingCleanup;
+        if (pending === undefined)
+            return undefined;
+        if (pending.process !== undefined) {
+            const stopped = await pending.process.stop();
+            if (stopped.status === "incomplete")
+                return new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, [pending.process.launch.ownership?.runId ?? "owned-worker"], { reason: stopped.reason }, { operation: OPERATION });
+            pending.process = undefined;
+        }
+        if (pending.root !== undefined) {
+            const root = pending.root;
+            try {
+                await root.close();
+                pending.root = undefined;
+            }
+            catch (cause) {
+                return new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, [root.path], { reason: cause instanceof Error ? cause.message : String(cause) }, { operation: OPERATION, cause });
+            }
+        }
+        this.#pendingCleanup = undefined;
+        return undefined;
+    }
+}

package/dist/evm/EvmoleInterfaceWorker.js

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { z } from "zod";
+import { decodeEvmBytecodeCarrier, EvmCarrierFailure, } from "./EvmBytecodeCarrier.js";
+import { projectEvmoleInterface } from "./EvmoleInterfaceAdapter.js";
+import { EVM_INTERFACE_LIMITS, EVM_FILE_SIZE_FAILURE_EXIT, } from "./EvmoleRelease.js";
+const requestSchema = z.strictObject({
+    snapshot_path: z.string(),
+    reply_path: z.string(),
+    failure_marker_path: z.string(),
+    encoding: z.enum(["raw", "hex"]),
+});
+class UnsupportedContainer extends Error {
+}
+const main = async () => {
+    const requestPath = process.argv[2];
+    if (requestPath === undefined)
+        throw new Error("Owned worker request path missing.");
+    const request = requestSchema.parse(JSON.parse(await readFile(requestPath, "utf8")));
+    let reply;
+    try {
+        const bytes = decodeEvmBytecodeCarrier(await readFile(request.snapshot_path), request.encoding);
+        if (bytes[0] === 0xef && bytes[1] === 0x00)
+            throw new UnsupportedContainer("Container marker EF00 is outside the verified flat-bytecode interface profile.");
+        const modulePath = import.meta.resolve("evmole/no_tla");
+        const metadata = z
+            .object({ version: z.literal("0.9.3") })
+            .parse(JSON.parse(await readFile(new URL("../package.json", modulePath), "utf8")));
+        const engine = await import("evmole/no_tla");
+        engine.initSync({
+            module: await readFile(new URL(import.meta.resolve("evmole/evmole_bg.wasm"))),
+        });
+        const inferred = projectEvmoleInterface(engine.contractInfo(Buffer.from(bytes).toString("hex"), {
+            selectors: true,
+            arguments: true,
+            stateMutability: true,
+        }));
+        reply = {
+            ok: true,
+            version: metadata.version,
+            bytecode: {
+                sha256: createHash("sha256").update(bytes).digest("hex"),
+                bytes: bytes.length,
+                hex: Buffer.from(bytes).toString("hex"),
+            },
+            raw: inferred.raw,
+        };
+    }
+    catch (cause) {
+        reply = {
+            ok: false,
+            reason: cause instanceof EvmCarrierFailure
+                ? "format"
+                : cause instanceof UnsupportedContainer
+                    ? "unsupported"
+                    : "decoder",
+            message: cause instanceof Error ? cause.message : String(cause),
+        };
+    }
+    let encoded = JSON.stringify(reply);
+    if (Buffer.byteLength(encoded) > EVM_INTERFACE_LIMITS.outputBytes)
+        encoded = JSON.stringify({
+            ok: false,
+            reason: "output-limit",
+            message: "Complete interface evidence exceeds the 16 MiB reply budget.",
+        });
+    try {
+        await writeFile(request.reply_path, encoded, { flag: "wx", mode: 0o600 });
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "EFBIG") {
+            try {
+                await writeFile(request.failure_marker_path, "F", {
+                    flag: "wx",
+                    mode: 0o600,
+                });
+            }
+            catch (markerFailure) {
+                process.stderr.write(`File-size failure marker unavailable: ${markerFailure instanceof Error ? markerFailure.message : String(markerFailure)}\n`);
+            }
+            process.exitCode = EVM_FILE_SIZE_FAILURE_EXIT;
+        }
+        else
+            throw cause;
+    }
+};
+await main();

package/dist/evm/EvmoleRelease.js

@@ -0,0 +1,16 @@
+/** Unchanged locked npm/WASM profile; provenance is independent of chain deployment authenticity. */
+export const EVMOLE_PROVIDER_IDENTITY = {
+    id: "evmole-interface",
+    name: "REA EVM interface adapter",
+    version: "evmole@0.9.3",
+};
+/** Worker-reserved status for an observed EFBIG write without a complete reply. */
+export const EVM_FILE_SIZE_FAILURE_EXIT = 76;
+/** Complete offline inspection budgets; worker JavaScript heap is bounded separately. */
+export const EVM_INTERFACE_LIMITS = {
+    inputBytes: 4 * 1024 * 1024,
+    outputBytes: 16 * 1024 * 1024,
+    timeoutMs: 30_000,
+    diagnosticBytes: 1024 * 1024,
+    addressSpaceBytes: 3 * 1024 * 1024 * 1024,
+};

package/dist/filesystem/OwnedDirectoryHandle.js

@@ -0,0 +1,29 @@
+/** Dir.close invalidates Node's private handle before its native close settles. */
+export class OwnedDirectoryHandle {
+    handle;
+    #state = { kind: "open" };
+    constructor(handle) {
+        this.handle = handle;
+    }
+    close() {
+        if (this.#state.kind === "closed")
+            return Promise.resolve();
+        if (this.#state.kind === "closing")
+            return this.#state.attempt;
+        if (this.#state.kind === "failed")
+            return Promise.reject(this.#state.cause);
+        const attempt = Promise.resolve().then(async () => {
+            try {
+                await this.handle.close();
+                this.#state = { kind: "closed" };
+            }
+            catch (cause) {
+                // Dir has no public validity signal with which to authorize a retry.
+                this.#state = { kind: "failed", cause };
+                throw cause;
+            }
+        });
+        this.#state = { kind: "closing", attempt };
+        return attempt;
+    }
+}

package/dist/filesystem/OwnedFileHandle.js

@@ -0,0 +1,36 @@
+/** One file handle whose close result must remain truthful across retries. */
+export class OwnedFileHandle {
+    handle;
+    #state = { kind: "open" };
+    constructor(handle) {
+        this.handle = handle;
+    }
+    /** Close the owned handle, retaining an unconfirmed close as a sticky failure. */
+    close() {
+        if (this.#state.kind === "closed")
+            return Promise.resolve();
+        if (this.#state.kind === "closing")
+            return this.#state.attempt;
+        if (this.#state.kind === "failed")
+            return Promise.reject(this.#state.cause);
+        if (this.handle.fd < 0) {
+            const cause = new Error("File handle was invalidated before this owner confirmed its close");
+            this.#state = { kind: "failed", cause };
+            return Promise.reject(cause);
+        }
+        const attempt = Promise.resolve().then(() => this.#attemptClose());
+        this.#state = { kind: "closing", attempt };
+        return attempt;
+    }
+    async #attemptClose() {
+        try {
+            await this.handle.close();
+            this.#state = { kind: "closed" };
+        }
+        catch (cause) {
+            this.#state =
+                this.handle.fd < 0 ? { kind: "failed", cause } : { kind: "open" };
+            throw cause;
+        }
+    }
+}

package/dist/filesystem/OwnedStagedOutput.js

@@ -0,0 +1,138 @@
+import { lstat, readdir, rmdir, unlink } from "node:fs/promises";
+import { OwnedFileHandle } from "./OwnedFileHandle.js";
+const identityOf = (stats) => ({
+    dev: stats.dev,
+    ino: stats.ino,
+});
+const sameIdentity = (stats, identity) => stats.dev === identity.dev && stats.ino === identity.ino;
+/** One atomically staged file and directory retained through verified cleanup. */
+export class OwnedStagedOutput {
+    directory;
+    directoryIdentity;
+    #file;
+    #fileIdentity;
+    #fileRemovedByOwner = false;
+    #publishedRename = false;
+    #closeAttempt;
+    #closed = false;
+    #identityFailure;
+    constructor(directory, directoryIdentity) {
+        this.directory = directory;
+        this.directoryIdentity = directoryIdentity;
+    }
+    static async create(directory) {
+        try {
+            const stats = await lstat(directory);
+            if (!stats.isDirectory() || stats.isSymbolicLink())
+                return new OwnedStagedOutput(directory, undefined);
+            return new OwnedStagedOutput(directory, identityOf(stats));
+        }
+        catch (cause) {
+            // Keep an owner that refuses deletion when creation identity is unknown.
+            const owner = new OwnedStagedOutput(directory, undefined);
+            owner.#identityFailure = cause;
+            return owner;
+        }
+    }
+    async setFile(file) {
+        if (this.#file !== undefined)
+            throw new Error("Staged output already owns a file handle");
+        this.#file = file;
+        try {
+            this.#fileIdentity = identityOf(await file.handle.stat());
+        }
+        catch (cause) {
+            // The handle remains owned; cleanup will close it and refuse pathname removal.
+            this.#identityFailure = cause;
+        }
+    }
+    /** Verify that the path still names the exact closed file before publication. */
+    async assertReadyForPublication(content) {
+        await this.#verifiedDirectory();
+        if (this.#fileIdentity === undefined)
+            throw new Error("Cannot verify staged file identity", {
+                cause: this.#identityFailure,
+            });
+        const stagedFile = await lstat(content);
+        if (!stagedFile.isFile() ||
+            stagedFile.isSymbolicLink() ||
+            !sameIdentity(stagedFile, this.#fileIdentity))
+            throw new Error(`Staged file identity changed: ${content}`);
+    }
+    closeFile() {
+        return this.#file?.close() ?? Promise.resolve();
+    }
+    /** Record that the staged file moved to the published destination by rename. */
+    recordPublishedRename() {
+        this.#publishedRename = true;
+    }
+    /** Close the owned descriptor and remove only the exact staged entries. */
+    close() {
+        if (this.#closed)
+            return Promise.resolve();
+        if (this.#closeAttempt !== undefined)
+            return this.#closeAttempt;
+        const attempt = Promise.resolve().then(() => this.#cleanup());
+        this.#closeAttempt = attempt;
+        void attempt.then(() => {
+            this.#closed = true;
+            this.#closeAttempt = undefined;
+        }, () => {
+            this.#closeAttempt = undefined;
+        });
+        return attempt;
+    }
+    async #cleanup() {
+        await this.closeFile();
+        await this.#verifiedDirectory();
+        const content = `${this.directory}/content`;
+        let stagedFile;
+        try {
+            stagedFile = await lstat(content);
+        }
+        catch (cause) {
+            if (errorCode(cause) === "ENOENT" &&
+                (this.#file === undefined ||
+                    this.#fileRemovedByOwner ||
+                    this.#publishedRename)) {
+                stagedFile = undefined;
+            }
+            else if (errorCode(cause) === "ENOENT") {
+                throw new Error(`Owned staged file disappeared: ${content}`, {
+                    cause,
+                });
+            }
+            else {
+                throw cause;
+            }
+        }
+        if (stagedFile !== undefined) {
+            if (!stagedFile.isFile() ||
+                stagedFile.isSymbolicLink() ||
+                this.#fileIdentity === undefined ||
+                !sameIdentity(stagedFile, this.#fileIdentity))
+                throw new Error(`Staged file identity changed: ${content}`);
+            await unlink(content);
+            this.#fileRemovedByOwner = true;
+        }
+        const remaining = await readdir(this.directory);
+        if (remaining.length > 0)
+            throw new Error(`Unexpected staging entries remain in ${this.directory}: ${remaining.join(", ")}`);
+        await this.#verifiedDirectory();
+        await rmdir(this.directory);
+    }
+    async #verifiedDirectory() {
+        if (this.directoryIdentity === undefined)
+            throw new Error(`Cannot verify staging directory ownership: ${this.directory}`, {
+                cause: this.#identityFailure,
+            });
+        const directory = await lstat(this.directory);
+        if (!directory.isDirectory() ||
+            directory.isSymbolicLink() ||
+            !sameIdentity(directory, this.directoryIdentity))
+            throw new Error(`Staging directory identity changed: ${this.directory}`);
+    }
+}
+const errorCode = (cause) => typeof cause === "object" && cause !== null && "code" in cause
+    ? cause.code
+    : undefined;