rea-agents 6.4.0 → 6.7.0

package/dist/application/HermesConfigurationYaml.js

@@ -0,0 +1,312 @@
+import { isMap, isNode, isScalar, isSeq, parseDocument, Document, Schema, } from "yaml";
+const SOURCE_SCALAR_TAGS = new Set([
+    "tag:yaml.org,2002:int",
+    "tag:yaml.org,2002:float",
+    "tag:yaml.org,2002:timestamp",
+]);
+// Hermes's ruamel reader resolves dates even with an explicit YAML 1.2 directive.
+const timestampTag = new Schema({ schema: "yaml-1.1" }).tags.find((tag) => tag.tag === "tag:yaml.org,2002:timestamp" && tag.collection === undefined);
+if (timestampTag === undefined)
+    throw new Error("The YAML 1.1 schema must provide its timestamp tag");
+const timestampSource = /^(\d{4})-(\d{1,2})-(\d{1,2})(?:(?:[Tt]|[ \t]+)(\d{1,2}):(\d{2}):(\d{2})(?:\.([0-9]*))?(?:[ \t]*(Z|([-+])(\d{1,2})(?::(\d{2}))?))?)?$/;
+const hermesTimestampImplicit = /^(?:\d{4}-\d{2}-\d{2}|\d{4}-\d{1,2}-\d{1,2}(?:[Tt]|[ \t]+)\d{1,2}:\d{2}:\d{2}(?:\.[0-9]*)?(?:[ \t]*(?:Z|[-+]\d{1,2}(?::\d{2})?))?)$/;
+const floorDivide = (value, divisor) => Math.floor(value / divisor);
+/** Days since 1970-01-01 using the proleptic Gregorian calendar. */
+const civilDay = (year, month, day) => {
+    const adjustedYear = year - (month <= 2 ? 1 : 0);
+    const era = floorDivide(adjustedYear, 400);
+    const yearOfEra = adjustedYear - era * 400;
+    const adjustedMonth = month + (month > 2 ? -3 : 9);
+    const dayOfYear = floorDivide(153 * adjustedMonth + 2, 5) + day - 1;
+    const dayOfEra = yearOfEra * 365 +
+        floorDivide(yearOfEra, 4) -
+        floorDivide(yearOfEra, 100) +
+        dayOfYear;
+    return era * 146097 + dayOfEra - 719468;
+};
+/** Parse the exact timestamp forms and values accepted by ruamel's safe loader. */
+const parseHermesTimestamp = (source) => {
+    const match = timestampSource.exec(source);
+    if (match === null)
+        return undefined;
+    const [, yearText, monthText, dayText, hourText, minuteText, secondText, fraction, zone, sign, zoneHourText, zoneMinuteText,] = match;
+    if (yearText === undefined ||
+        monthText === undefined ||
+        dayText === undefined)
+        return undefined;
+    const year = Number(yearText);
+    const month = Number(monthText);
+    const dayOfMonth = Number(dayText);
+    if (year < 1 || year > 9999 || month < 1 || month > 12)
+        return undefined;
+    const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const monthDays = [
+        31,
+        leapYear ? 29 : 28,
+        31,
+        30,
+        31,
+        30,
+        31,
+        31,
+        30,
+        31,
+        30,
+        31,
+    ];
+    if (dayOfMonth < 1 || dayOfMonth > (monthDays[month - 1] ?? 0))
+        return undefined;
+    const date = `${yearText}-${monthText.padStart(2, "0")}-${dayText.padStart(2, "0")}`;
+    const day = civilDay(year, month, dayOfMonth);
+    if (hourText === undefined) {
+        const micros = BigInt(day) * 86400000000n;
+        return { key: `date:${date}`, value: new Date(Number(micros / 1000n)) };
+    }
+    const hour = Number(hourText);
+    const minute = Number(minuteText);
+    const second = Number(secondText);
+    if (hour > 23 || minute > 59 || second > 59)
+        return undefined;
+    const zoneHour = Number(zoneHourText ?? 0);
+    const zoneMinute = Number(zoneMinuteText ?? 0);
+    if (zoneHour > 23 || zoneMinute > 59)
+        return undefined;
+    let microseconds = 0;
+    if (fraction !== undefined && fraction.length > 0) {
+        microseconds = Number((fraction.slice(0, 6) + "000000").slice(0, 6));
+        if (fraction.length > 6 && Number(fraction[6]) > 4)
+            microseconds += 1;
+    }
+    const wholeSeconds = hour * 3600 + minute * 60 + second;
+    if (year === 9999 &&
+        month === 12 &&
+        dayOfMonth === 31 &&
+        wholeSeconds === 86_399 &&
+        microseconds === 1_000_000)
+        return undefined;
+    let micros = BigInt(day) * 86400000000n +
+        BigInt(wholeSeconds) * 1000000n +
+        BigInt(microseconds);
+    if (zone !== undefined && zone !== "Z") {
+        const offset = (zoneHour * 60 + zoneMinute) * (sign === "+" ? 1 : -1);
+        micros -= BigInt(offset) * 60000000n;
+    }
+    return {
+        key: zone === undefined
+            ? `datetime-local:${micros}`
+            : `datetime-utc:${micros}`,
+        value: new Date(Number(micros / 1000n - (micros % 1000n < 0n ? 1n : 0n))),
+    };
+};
+const numericValue = (value) => {
+    if (typeof value === "boolean")
+        return value ? 1n : 0n;
+    if (typeof value === "bigint" || typeof value === "number")
+        return value;
+    return undefined;
+};
+const numericValuesEqual = (left, right) => {
+    if (typeof left === "bigint" && typeof right === "bigint")
+        return left === right;
+    if (typeof left === "number" && typeof right === "number")
+        return left === right || (Number.isNaN(left) && Number.isNaN(right));
+    const integer = typeof left === "bigint" ? left : right;
+    const number = typeof left === "number" ? left : right;
+    return (Number.isFinite(number) &&
+        Number.isInteger(number) &&
+        BigInt(number) === integer);
+};
+const sameResolvedScalarValue = (left, right) => Object.is(left, right) ||
+    (left instanceof Date &&
+        right instanceof Date &&
+        left.getTime() === right.getTime());
+/**
+ * Write a parsed scalar with its source spelling while that spelling still
+ * reads as the node's value. Hermes reads config.yaml as YAML 1.1 with exact
+ * integers, so re-printing a JavaScript number changes what it reads: a
+ * Discord channel ID loses its low digits, `0600` (octal) becomes `600`, and
+ * `0.0000001` becomes `1e-7`, which YAML 1.1 does not define as a float.
+ * Timestamp source also retains precision and offsets absent from JS Dates.
+ */
+const keepScalarSource = (tag) => {
+    if (typeof tag === "string" || tag.collection !== undefined)
+        return tag;
+    const { stringify } = tag;
+    if (!SOURCE_SCALAR_TAGS.has(tag.tag) || stringify === undefined)
+        return tag;
+    return {
+        ...tag,
+        stringify: (item, context, ...rest) => {
+            const { source } = item;
+            if (source === undefined)
+                return stringify(item, context, ...rest);
+            const reader = context.doc.schema.tags.find((candidate) => candidate.default === true && candidate.test?.test(source) === true);
+            const read = reader?.resolve(source, () => undefined, context.doc.options);
+            return sameResolvedScalarValue(isScalar(read) ? read.value : read, item.value)
+                ? source
+                : stringify(item, context, ...rest);
+        },
+    };
+};
+const createHermesYamlOptions = () => {
+    const timestamps = new Map();
+    const timestampFacts = (source) => {
+        if (timestamps.has(source))
+            return timestamps.get(source);
+        const facts = parseHermesTimestamp(source);
+        timestamps.set(source, facts);
+        return facts;
+    };
+    const hermesTimestampTag = {
+        ...timestampTag,
+        test: hermesTimestampImplicit,
+        resolve: (source) => {
+            const facts = timestampFacts(source);
+            if (facts === undefined)
+                throw new Error(`Invalid Hermes YAML timestamp: ${source}`);
+            return facts.value;
+        },
+    };
+    const keyFacts = new WeakMap();
+    const hermesKey = (node) => {
+        const cached = keyFacts.get(node);
+        if (cached !== undefined)
+            return cached;
+        if (!isScalar(node))
+            return { kind: "other", value: node };
+        const numeric = numericValue(node.value);
+        const key = numeric !== undefined
+            ? { kind: "numeric", value: numeric }
+            : node.value instanceof Date
+                ? {
+                    kind: "timestamp",
+                    value: timestampFacts(node.source ?? "")?.key ??
+                        `invalid:${node.source ?? ""}`,
+                }
+                : { kind: "other", value: node.value };
+        keyFacts.set(node, key);
+        return key;
+    };
+    /** Python dict key equality is Hermes' duplicate-key behavior (bool is int). */
+    const hermesKeysEqual = (leftNode, rightNode) => {
+        const left = hermesKey(leftNode);
+        const right = hermesKey(rightNode);
+        if (left.kind !== right.kind)
+            return false;
+        if (left.kind === "numeric" && right.kind === "numeric")
+            return numericValuesEqual(left.value, right.value);
+        return left.value === right.value;
+    };
+    return {
+        // Hermes defaults to YAML 1.1; an explicit document directive still wins.
+        // Use the same schema to interpret existing values and quote new strings.
+        version: "1.1",
+        // Keep integer key identity exact; parseHermesConfigurationYaml's reviver
+        // restores the existing number-valued consumer contract.
+        intAsBigInt: true,
+        customTags: (tags) => {
+            const hasTimestamp = tags.some((tag) => typeof tag !== "string" && tag.tag === timestampTag.tag);
+            const withHermesTimestamp = hasTimestamp
+                ? tags.map((tag) => typeof tag !== "string" && tag.tag === timestampTag.tag
+                    ? hermesTimestampTag
+                    : tag)
+                : [...tags, hermesTimestampTag];
+            return withHermesTimestamp.map(keepScalarSource);
+        },
+        uniqueKeys: hermesKeysEqual,
+    };
+};
+/** Create a Hermes config using the same scalar rules as edits and readback. */
+export const stringifyHermesConfigurationYaml = (document) => new Document(document, createHermesYamlOptions()).toString({ lineWidth: 0 });
+// A comment-only document has no root; a bare marker has an unwritten null
+// scalar. Explicit null values, tags and anchors remain actual values.
+const isEmptyYamlRoot = (root) => root === null ||
+    (isScalar(root) &&
+        root.value === null &&
+        root.source === "" &&
+        root.tag === undefined &&
+        root.anchor === undefined);
+const parseHermesDocument = (text) => {
+    const document = parseDocument(text, createHermesYamlOptions());
+    const error = document.errors[0];
+    if (error !== undefined)
+        throw error;
+    return document;
+};
+/** Parse a Hermes `config.yaml`, preserving the distinction between no root and explicit null. */
+export const parseHermesConfigurationYaml = (text) => {
+    const document = parseHermesDocument(text);
+    return isEmptyYamlRoot(document.contents)
+        ? {}
+        : document.toJS({
+            reviver: (_key, value) => typeof value === "bigint" ? Number(value) : value,
+        });
+};
+/** Keep unchanged scalar nodes, including their quoting and explicit tags. */
+const retainHermesScalarSource = (previous, next) => {
+    if (isScalar(previous) && isScalar(next) && previous.value === next.value)
+        return previous;
+    if (isMap(previous) && isMap(next)) {
+        const entries = new Map(previous.items.flatMap((pair) => isScalar(pair.key) && typeof pair.key.value === "string"
+            ? [[pair.key.value, pair]]
+            : []));
+        for (const pair of next.items) {
+            const key = isScalar(pair.key) ? pair.key.value : undefined;
+            const prior = typeof key === "string" ? entries.get(key) : undefined;
+            if (prior === undefined)
+                continue;
+            pair.key = prior.key;
+            if (isNode(pair.value))
+                pair.value = retainHermesScalarSource(prior.value, pair.value);
+        }
+    }
+    else if (isSeq(previous) && isSeq(next)) {
+        next.items = next.items.map((item, index) => isNode(item)
+            ? retainHermesScalarSource(previous.items[index], item)
+            : item);
+    }
+    return next;
+};
+/** Set or delete one value in a Hermes `config.yaml`, keeping the rest as written. */
+export const editHermesConfigurationYaml = (text, path, value) => {
+    // A plain Document, so a bare `---` root can be replaced by a new map.
+    const document = parseHermesDocument(text);
+    const root = document.contents;
+    if (isEmptyYamlRoot(root)) {
+        const map = document.createNode({});
+        if (isScalar(root))
+            map.commentBefore = [root.commentBefore, root.comment]
+                .filter((comment) => comment !== undefined)
+                .join("\n");
+        document.contents = map;
+    }
+    if (value === undefined)
+        document.deleteIn(path);
+    else {
+        // setIn's implicit JS Map parents serialize as !!omap in YAML 1.1.
+        // Config settings are ordinary mappings, including absent server tables.
+        for (let length = 1; length < path.length; length++) {
+            const parent = path.slice(0, length);
+            if (!document.hasIn(parent))
+                document.setIn(parent, document.createNode({}));
+        }
+        const previous = document.getIn(path, true);
+        // Let YAML's scalar update preserve numeric formats for a direct edit.
+        // Replacing containers needs explicit retention of unchanged child nodes.
+        document.setIn(path, isMap(previous) || isSeq(previous)
+            ? retainHermesScalarSource(previous, document.createNode(value))
+            : value);
+    }
+    // Editing REA must not reflow unrelated user prompts or other YAML scalars.
+    return document.toString({
+        lineWidth: 0,
+        // Hermes tries the YAML 1.1 C loader before its directive-aware pure
+        // fallback. Quote new strings to avoid introducing YAML 1.1 coercions.
+        ...(document.directives?.yaml.version === "1.2"
+            ? {
+                defaultStringType: "QUOTE_DOUBLE",
+                defaultKeyType: "QUOTE_DOUBLE",
+            }
+            : {}),
+    });
+};

package/dist/application/HopperDownload.js

@@ -2,7 +2,15 @@
 export const HOPPER_DOWNLOAD_BYTES = 100_000_000;
 /** Bound observed response bytes before retaining them, including chunked bodies. */
 export const downloadHopperPackage = async (url, options = {}) => {
-    const deadline = AbortSignal.timeout(120_000);
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120_000)
+        throw new RangeError("Invalid Hopper response time budget");
+    const deadline = AbortSignal.timeout(timeoutMs);
+    const maxBytes = options.maxBytes ?? HOPPER_DOWNLOAD_BYTES;
+    if (!Number.isSafeInteger(maxBytes) ||
+        maxBytes < 1 ||
+        maxBytes > HOPPER_DOWNLOAD_BYTES)
+        throw new RangeError("Invalid Hopper response byte budget");
     const response = await fetch(url, {
         headers: { accept: "application/json", "user-agent": "rea-installer" },
         signal: options.signal === undefined
@@ -11,7 +19,7 @@ export const downloadHopperPackage = async (url, options = {}) => {
     });
     const refused = { ok: false, bytes: new Uint8Array() };
     if (!response.ok ||
-        Number(response.headers.get("content-length")) > HOPPER_DOWNLOAD_BYTES) {
+        Number(response.headers.get("content-length")) > maxBytes) {
         await response.body?.cancel();
         return refused;
     }
@@ -25,7 +33,7 @@ export const downloadHopperPackage = async (url, options = {}) => {
             const chunk = await reader.read();
             if (chunk.done)
                 return { ok: true, bytes: Buffer.concat(chunks, bytes) };
-            if (chunk.value.byteLength > HOPPER_DOWNLOAD_BYTES - bytes) {
+            if (chunk.value.byteLength > maxBytes - bytes) {
                 await reader.cancel();
                 return refused;
             }

package/dist/application/HopperReleaseFeed.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { err, ok } from "../domain/result.js";
+import { HOPPER_DOWNLOAD_BYTES } from "./HopperDownload.js";
+/** Vendor endpoints, shared by installation and existing-build inspection. */
+export const HOPPER_RELEASES_URL = "https://www.hopperapp.com/include/files-api.php?request=releases&public=true";
+export const HOPPER_PUBLIC_KEY_URL = "https://www.hopperapp.com/hopper-public-key.asc";
+export const HOPPER_DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
+/** Stable publisher identity; signing subkeys are admitted through this primary. */
+export const HOPPER_LINUX_PRIMARY_FINGERPRINT = "7C2D73BAFAF5B9A710A69DA1A26DF815099B1BCD";
+const platforms = {
+    deb: "Ubuntu / Mint",
+    rpm: "Fedora",
+    arch: "Arch",
+};
+const suffixes = { deb: ".deb", rpm: ".rpm", arch: ".pkg.tar.xz" };
+export class HopperReleaseError extends Error {
+    reason;
+    _tag = "HopperReleaseError";
+    constructor(reason, message, options) {
+        super(message, options);
+        this.reason = reason;
+        this.name = this._tag;
+    }
+}
+const sha256 = z.string().regex(/^[a-f0-9]{64}$/u);
+const releaseSchema = z
+    .object({
+    version: z.string().min(1),
+    filename: z.string().url(),
+    file_length: z
+        .string()
+        .regex(/^[1-9]\d*$/u)
+        .refine((text) => {
+        const count = Number(text);
+        return Number.isSafeInteger(count) && count <= HOPPER_DOWNLOAD_BYTES;
+    }),
+    file_hash: z.string().regex(/^[a-f0-9]{40}$/u),
+    main_exe_hash: sha256,
+    signature: z
+        .string()
+        .min(1)
+        .refine((text) => Buffer.from(text, "base64").toString("base64") === text),
+    public: z.literal("1"),
+    beta: z.literal("0"),
+})
+    .passthrough();
+export const parseLinuxHopperRelease = (raw, family) => {
+    const parsed = releaseSchema.safeParse(raw);
+    if (!parsed.success)
+        return err(new HopperReleaseError("release_metadata", "The Hopper release omitted valid package identity or signature metadata."));
+    const url = new URL(parsed.data.filename);
+    if (url.origin !== "https://www.hopperapp.com" ||
+        url.username !== "" ||
+        url.password !== "" ||
+        url.search !== "" ||
+        url.hash !== "" ||
+        !url.pathname.startsWith("/downloader/public/Hopper-") ||
+        !url.pathname.endsWith(`-Linux-demo${suffixes[family]}`))
+        return err(new HopperReleaseError("release_metadata", "The Hopper release is outside the official public Linux demo channel."));
+    return ok(parsed.data);
+};
+export const parseLinuxHopperReleases = (raw) => {
+    const feed = z.record(z.string(), z.unknown()).safeParse(raw);
+    if (!feed.success)
+        return err(new HopperReleaseError("release_metadata", "The Hopper releases response is not an object."));
+    return ok({
+        deb: parseLinuxHopperRelease(feed.data[platforms.deb], "deb"),
+        rpm: parseLinuxHopperRelease(feed.data[platforms.rpm], "rpm"),
+        arch: parseLinuxHopperRelease(feed.data[platforms.arch], "arch"),
+    });
+};

package/dist/application/InventoryProjectionEvidence.js

@@ -1,6 +1,5 @@
 import { z } from "zod";
 import { AnalysisProtocolError } from "../domain/analysisErrorCore.js";
-import {} from "../domain/analysisErrorBase.js";
 import { createEvidence, } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";

package/dist/application/InvestigationProviders.js

@@ -8,9 +8,14 @@ export const REA_WORKFLOW_PROVIDER = {
 /** Commit a workflow result to its upstream profile and applicable semantic revision. */
 export const workflowAnalysisProfile = (upstream, operation) => createAnalysisProfile(REA_WORKFLOW_PROVIDER, {
     upstream_analysis_profile: upstream,
-    ...(operation === "binary_overview" || operation === "batch_decompile"
-        ? { workflow_revision: 2 }
-        : {}),
+    source_limitations: "provider-operation-caveats-v1",
+    ...(operation === "binary_overview"
+        ? { workflow_revision: 4 }
+        : operation === "batch_decompile" ||
+            operation === "get_call_graph" ||
+            operation === "trace_feature"
+            ? { workflow_revision: 3 }
+            : { workflow_revision: 1 }),
 });
 /** Provider identity for deterministic artifact inventories. */
 export const ARTIFACT_GRAPH_PROVIDER = Object.freeze({
@@ -48,6 +53,12 @@ export const ANDROID_APPLICATION_PROVIDER = {
     name: "REA Android application workflows",
     version: "1",
 };
+/** Provider identity for deterministic HarmonyOS application projections. */
+export const HARMONY_APPLICATION_PROVIDER = {
+    id: "rea-harmony-application",
+    name: "REA HarmonyOS application workflows",
+    version: "1",
+};
 /** Provider identity for verified publication of retained website scripts. */
 export const WEB_SCRIPT_EXPORT_PROVIDER = {
     id: "rea-web-script-export",

package/dist/application/JsonFiles.js

@@ -1,15 +1,22 @@
-import { link, lstat, mkdtemp, open, realpath, rename, rm, } from "node:fs/promises";
+import { link, lstat, mkdtemp, open, realpath, rename, } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
-import { EvidenceFileError } from "../domain/evidenceErrors.js";
+import { EvidenceFileError, } from "../domain/evidenceErrors.js";
 import { AnalysisCancelledError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
 import { err, ok } from "../domain/result.js";
-import { readJsonInputFile } from "./JsonInputFile.js";
+import { readJsonInputFile, readJsonObjectFile, } from "./JsonInputFile.js";
 import { NonRegularFileReadError } from "../filesystem/RegularFile.js";
+import { RegularFileCleanupFailure } from "./RegularFileRead.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { OwnedStagedOutput } from "../filesystem/OwnedStagedOutput.js";
 /** Read JSON data from a regular file at the caller-supplied path. */
-export const readJsonFile = async (path) => {
+export const readJsonFile = async (path, signal, resources) => readJsonFileInput(path, (selected) => readJsonInputFile(selected, "read_evidence_file", signal, resources), signal);
+/** Read selected JSON members through the same regular-file error boundary. */
+export const readJsonObjectMembersFile = (path, scans, signal, resources) => readJsonFileInput(path, (selected) => readJsonObjectFile(selected, "read_evidence_file", scans, signal, resources), signal);
+const readJsonFileInput = async (path, read, signal) => {
     const requestedPath = resolve(path);
     try {
-        const decoded = await readJsonInputFile(requestedPath, "read_evidence_file");
+        const decoded = await read(requestedPath);
         if (!decoded.ok) {
             if (decoded.error instanceof AnalysisResourceConstraintError)
                 return err(decoded.error);
@@ -22,8 +29,12 @@ export const readJsonFile = async (path) => {
         return ok(decoded.value);
     }
     catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
         if (cause instanceof AnalysisResourceConstraintError)
             return err(cause);
+        if (signal?.aborted === true)
+            throw cause;
         return err(new EvidenceFileError("read", cause instanceof NonRegularFileReadError
             ? "not-file"
             : missingOrIo(cause), {
@@ -33,8 +44,22 @@ export const readJsonFile = async (path) => {
     }
 };
 /** Atomically write text to the caller-supplied path. */
-export const writeTextFile = async (encoded, path, overwrite) => writeTextParts([encoded], path, overwrite);
-export async function writeTextParts(parts, path, overwrite, cancellation) {
+export const writeTextFile = async (encoded, path, overwrite, resources) => writeTextParts([encoded], path, overwrite, resources);
+export function writeTextParts(parts, path, overwrite, resources, cancellation) {
+    return resources
+        .run(() => writeTextPartsOwned(parts, path, overwrite, resources, cancellation))
+        .catch((cause) => {
+        const cleanup = cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined
+            ? cause.cleanup
+            : undefined;
+        return err(new EvidenceFileError("write", "io", {
+            cause,
+            path: resolve(path),
+            ...(cleanup === undefined ? {} : { cleanup }),
+        }));
+    });
+}
+const writeTextPartsOwned = async (parts, path, overwrite, resources, cancellation) => {
     const requestedPath = resolve(path);
     try {
         assertWriteActive(cancellation);
@@ -52,10 +77,33 @@ export async function writeTextParts(parts, path, overwrite, cancellation) {
                 return err(new EvidenceFileError("write", "not-file", { path: requestedPath }));
         }
         assertWriteActive(cancellation);
-        const bytes = await publishFile(destination, parts, overwrite, cancellation);
+        const bytes = await publishFile(destination, parts, overwrite, resources, cancellation);
         return ok({ path: requestedPath, bytes });
     }
     catch (cause) {
+        if (cause instanceof StagedOutputCleanupFailure) {
+            const cleanup = {
+                reason: failureMessage(cause.cleanupCause),
+                resources: [cause.owner.directory],
+            };
+            if (cause.outcome.ok)
+                return err(new EvidenceFileError("write", "io", {
+                    cause,
+                    path: requestedPath,
+                    cleanup,
+                    published: { ...cause.outcome.value, path: requestedPath },
+                }));
+            if (cause.outcome.error instanceof AnalysisCancelledError)
+                return err(new AnalysisCancelledError(cause.outcome.error.operation, {
+                    cause,
+                    cleanup,
+                }));
+            return err(new EvidenceFileError("write", missingOrIo(cause.outcome.error), {
+                cause,
+                path: requestedPath,
+                cleanup,
+            }));
+        }
         if (cancellation?.signal.aborted === true &&
             cause instanceof AnalysisCancelledError &&
             cause.operation === cancellation.operation)
@@ -70,39 +118,81 @@ export async function writeTextParts(parts, path, overwrite, cancellation) {
             path: requestedPath,
         }));
     }
-}
+};
 /** A missing path or parent is a selection error, not a permission failure. */
 const missingOrIo = (cause) => {
     const code = fileErrorCode(cause);
     return code === "ENOENT" || code === "ENOTDIR" ? "missing" : "io";
 };
-const publishFile = async (destination, parts, overwrite, cancellation) => {
+const publishFile = async (destination, parts, overwrite, resources, cancellation) => {
     const stagingDirectory = await mkdtemp(resolve(dirname(destination), ".rea-write-"));
+    const owner = await OwnedStagedOutput.create(stagingDirectory);
+    let outcome;
+    const staged = resolve(stagingDirectory, "content");
     try {
-        const staged = resolve(stagingDirectory, "content");
         const file = await open(staged, "wx", 0o600);
-        let bytes = 0;
+        owner.setFile(new OwnedFileHandle(file));
+        let written;
         try {
-            bytes = await writeStagedParts(file, parts, cancellation);
+            const bytes = await writeStagedParts(file, parts, cancellation);
             assertWriteActive(cancellation);
             await file.sync();
+            written = ok(bytes);
         }
-        finally {
-            await file.close();
+        catch (cause) {
+            written = err(cause);
         }
-        // Once submitted, the atomic publication can win a later cancellation race.
+        try {
+            await owner.closeFile();
+        }
+        catch (cause) {
+            if (written.ok)
+                written = err(cause);
+        }
+        if (!written.ok)
+            throw written.error;
+        // Once submitted, atomic publication can win a later cancellation race.
         assertWriteActive(cancellation);
-        if (overwrite)
+        await owner.assertReadyForPublication(staged);
+        assertWriteActive(cancellation);
+        if (overwrite) {
             await rename(staged, destination);
+            owner.recordPublishedRename();
+        }
         // A hard link publishes complete bytes atomically and cannot replace an existing name.
         else
             await link(staged, destination);
-        return bytes;
+        outcome = ok({ path: destination, bytes: written.value });
     }
-    finally {
-        await rm(stagingDirectory, { recursive: true, force: true });
+    catch (cause) {
+        outcome = err(cause);
     }
+    // One cleanup phase owns both the open descriptor (if any) and its staging directory.
+    const released = await resources.release({
+        kind: "staged-output",
+        resource: owner.directory,
+        output: owner,
+    });
+    if (released.kind === "failed")
+        throw new StagedOutputCleanupFailure(outcome, released.cause, owner);
+    if (!outcome.ok)
+        throw outcome.error;
+    return outcome.value.bytes;
 };
+class StagedOutputCleanupFailure extends Error {
+    outcome;
+    cleanupCause;
+    owner;
+    constructor(outcome, cleanupCause, owner) {
+        super("Staged output cleanup failed", {
+            cause: outcome.ok ? cleanupCause : outcome.error,
+        });
+        this.outcome = outcome;
+        this.cleanupCause = cleanupCause;
+        this.owner = owner;
+    }
+}
+const failureMessage = (cause) => cause instanceof Error ? cause.message || cause.name : String(cause);
 const writeStagedParts = async (file, parts, cancellation) => {
     assertWriteActive(cancellation);
     const iterator = parts[Symbol.iterator]();