rea-agents 6.3.0 → 6.5.0

package/dist/firmware/FirmwareProvider.js

@@ -3,9 +3,11 @@ import { z } from "zod";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
 import { firmwareResultSchemas, } from "../domain/firmware/firmwareAnalysis.js";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
 import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
 import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { publishFirmwareExtraction } from "./FirmwarePublication.js";
@@ -14,6 +16,19 @@ import { admitFirmwareVersion } from "./FirmwareVersion.js";
 import { firmwareToolUnavailable, resolveFirmwareCommand, runFirmwareCommand, readFirmwareCommandReport, } from "./FirmwareCommand.js";
 import { inventoryFirmwareOutput, snapshotFirmware } from "./FirmwareFiles.js";
 import { normalizeBinwalkReport, normalizeUnblobReport, } from "./FirmwareReports.js";
+const combineCleanupFailures = (failures) => {
+    if (failures.length < 2)
+        return failures[0];
+    return new ProviderCleanupError("firmware", failures.flatMap((failure) => [...failure.cleanupResources]), {
+        reason: "Multiple owned firmware resources could not be cleaned",
+        failures: failures.map((failure) => ({
+            engine: failure.providerId,
+            operation: failure.operation,
+            resources: [...failure.cleanupResources],
+            reason: failure.diagnostics?.reason ?? failure.message,
+        })),
+    }, { operation: "close_firmware", cause: new AggregateError(failures) });
+};
 const waitForPredecessor = (predecessor, operation, signal) => new Promise((resolve, reject) => {
     const abort = () => reject(new AnalysisCancelledError(operation));
     signal?.addEventListener("abort", abort, { once: true });
@@ -28,6 +43,7 @@ const limitations = [
     "Signature matches and reported sizes do not establish partition validity, encryption or runtime mappings. Binwalk may infer unknown lengths before emitting its report.",
     "Only Linux is supported by this integration. One worker, inherited per-process address-space/file-size/CPU limits and a deadline constrain execution; staging byte and entry budgets are polled and may transiently overshoot. Limits are not aggregate process-memory or filesystem quotas.",
     "Unblob's default sandbox and skip rules remain enabled. Missing external extractors, unknown chunks, encrypted chunks and depth limits yield partial coverage. Extracted code is never executed; only regular files are published, without executable permission bits.",
+    "extraction_gaps lists regions that were carved or left unextracted and names extractor dependencies the producer reported as missing. A listed gap does not mean the target is corrupt or that a retained region is empty.",
     "The actual launcher executable is hashed. Interpreter, shared libraries and installed Python package dependencies are not independently attested; source revision remains unknown for caller-supplied builds.",
 ];
 /** Queued bring-your-own firmware adapters with private snapshots and owned cleanup. */
@@ -35,13 +51,16 @@ export class FirmwareProvider {
     environment;
     launcher;
     #tail = Promise.resolve();
-    #cleanupFailure;
+    #closed = false;
+    #pendingCleanup = new Map();
     constructor(environment = process.env, launcher) {
         this.environment = environment;
         this.launcher = launcher;
     }
     /** Inspect regions or explicitly extract selected bytes without changing the source. */
     async execute(request, options) {
+        if (this.#closed)
+            return err(new AnalysisCancelledError(request.operation));
         const predecessor = this.#tail;
         let release = () => { };
         this.#tail = new Promise((resolve) => {
@@ -58,12 +77,65 @@ export class FirmwareProvider {
                 : new AnalysisCancelledError(request.operation));
         }
         try {
+            if (this.#closed)
+                return err(new AnalysisCancelledError(request.operation));
+            const cleanup = await this.#retryCleanup();
+            if (cleanup.processUnverified && cleanup.failure !== undefined)
+                return err(cleanup.failure);
             return await this.#execute(request, options);
         }
         finally {
             release();
         }
     }
+    /** Retry every retained owner, reporting failures without discarding other roots. */
+    async close() {
+        this.#closed = true;
+        await this.#tail;
+        const cleanup = await this.#retryCleanup();
+        if (cleanup.failure !== undefined)
+            throw cleanup.failure;
+    }
+    async #retryCleanup() {
+        const failures = [];
+        let processUnverified = false;
+        for (const [path, pending] of this.#pendingCleanup) {
+            try {
+                const stopped = await pending.supervisor?.stop();
+                if (stopped?.status === "incomplete") {
+                    processUnverified = true;
+                    failures.push(new ProviderCleanupError(pending.engine, [path], { reason: stopped.reason }, { operation: pending.operation }));
+                    continue;
+                }
+                delete pending.supervisor;
+            }
+            catch (cause) {
+                processUnverified = true;
+                failures.push(new ProviderCleanupError(pending.engine, [path], { reason: cause instanceof Error ? cause.message : String(cause) }, { operation: pending.operation, cause }));
+                continue;
+            }
+            try {
+                if (pending.tree !== undefined) {
+                    await pending.tree.rollback();
+                    delete pending.tree;
+                }
+            }
+            catch (cause) {
+                failures.push(new ProviderCleanupError(pending.engine, [path, pending.tree?.outputRoot ?? path], { reason: cause instanceof Error ? cause.message : String(cause) }, { operation: pending.operation, cause }));
+            }
+            try {
+                await pending.root.close();
+                if (pending.tree === undefined)
+                    this.#pendingCleanup.delete(path);
+            }
+            catch (cause) {
+                // A verified stopped process cannot use this root. Keep ownership for
+                // later removal without blocking a new operation's disjoint workspace.
+                failures.push(new ProviderCleanupError(pending.engine, [path], { reason: cause instanceof Error ? cause.message : String(cause) }, { operation: pending.operation, cause }));
+            }
+        }
+        return { failure: combineCleanupFailures(failures), processUnverified };
+    }
     async #execute(request, options) {
         let root;
         const engineName = request.operation === "inspect_firmware_regions" ? "binwalk" : "unblob";
@@ -73,12 +145,11 @@ export class FirmwareProvider {
             : AbortSignal.any([options.signal, deadline]);
         let outcome;
         try {
-            if (this.#cleanupFailure !== undefined)
-                return err(this.#cleanupFailure);
             if (signal.aborted)
                 throw new AnalysisCancelledError(request.operation);
             const command = await resolveFirmwareCommand(this.environment, engineName, request.operation);
             root = await PrivateRuntimeRoot.create({ prefix: "rea-firmware-" });
+            const ownedRoot = root;
             const target = await snapshotFirmware(request, root.path, signal);
             const run = (args, outputBudget) => runFirmwareCommand({
                 engine: engineName,
@@ -88,6 +159,14 @@ export class FirmwareProvider {
                 cwd: root?.path ?? "",
                 environment: this.environment,
                 signal,
+                retainCleanup: (supervisor) => {
+                    this.#pendingCleanup.set(ownedRoot.path, {
+                        supervisor,
+                        root: ownedRoot,
+                        engine: engineName,
+                        operation: request.operation,
+                    });
+                },
                 ...(this.launcher === undefined ? {} : { launcher: this.launcher }),
                 ...(outputBudget === undefined
                     ? {}
@@ -184,8 +263,18 @@ export class FirmwareProvider {
                     entries,
                     normalized,
                     selection: target.selection,
+                    maxDepth: request.input.max_depth,
                     engine,
                     signal,
+                    retainCleanup: (tree) => {
+                        const pending = this.#pendingCleanup.get(ownedRoot.path) ?? {
+                            root: ownedRoot,
+                            engine: engineName,
+                            operation: request.operation,
+                        };
+                        pending.tree = tree;
+                        this.#pendingCleanup.set(ownedRoot.path, pending);
+                    },
                 });
                 raw = { report, execution: processRun, version_execution: versionRun };
             }
@@ -229,36 +318,73 @@ export class FirmwareProvider {
                                             : String(cause),
                                     },
                                 }));
-            if (!outcome.ok && outcome.error.cleanupIncomplete) {
-                this.#cleanupFailure =
-                    root === undefined ||
-                        outcome.error.cleanupResources.includes(root.path)
-                        ? outcome.error
-                        : new ProviderCleanupError(engineName, [...outcome.error.cleanupResources, root.path], outcome.error instanceof ProviderAdapterError
-                            ? (outcome.error.diagnostics ?? {
-                                reason: outcome.error.message,
-                            })
-                            : { reason: outcome.error.message }, { cause: outcome.error });
-            }
         }
-        // Never remove a workspace while process ownership remains uncertain.
-        if (this.#cleanupFailure !== undefined)
-            return err(this.#cleanupFailure);
-        try {
-            await root?.close();
-        }
-        catch (cause) {
-            this.#cleanupFailure = new ProviderCleanupError(engineName, [
-                root?.path ?? "unknown",
-                ...(outcome.ok && request.operation === "extract_firmware"
-                    ? [request.input.output_directory]
-                    : []),
-            ], {
-                reason: cause instanceof Error ? cause.message : String(cause),
-                previous_result: outcome.ok ? outcome.value.result : null,
+        const finished = await finishFirmwareWorkspace(root, outcome, engineName, request);
+        if (!finished.ok &&
+            finished.error.cleanupIncomplete &&
+            root !== undefined &&
+            !this.#pendingCleanup.has(root.path))
+            this.#pendingCleanup.set(root.path, {
+                root,
+                engine: engineName,
+                operation: request.operation,
             });
-            return err(this.#cleanupFailure);
-        }
-        return outcome;
+        return finished;
     }
 }
+/** Keep a completed extraction beside cleanup failure, or skip removal when ownership is uncertain. */
+export const finishFirmwareWorkspace = async (root, outcome, engineName, request) => {
+    if (!outcome.ok && outcome.error.cleanupIncomplete) {
+        if (root === undefined ||
+            outcome.error.cleanupResources.includes(root.path))
+            return outcome;
+        return err(new ProviderCleanupError(engineName, [...outcome.error.cleanupResources, root.path], outcome.error instanceof ProviderAdapterError
+            ? (outcome.error.diagnostics ?? { reason: outcome.error.message })
+            : { reason: outcome.error.message }, {
+            cause: outcome.error,
+            operation: request.operation,
+            ...(outcome.error.partialObservation === undefined
+                ? {}
+                : { partialObservation: outcome.error.partialObservation }),
+        }));
+    }
+    try {
+        await root?.close();
+    }
+    catch (cause) {
+        const cleanup = new ProviderCleanupError(engineName, [
+            root?.path ?? "unknown",
+            ...(outcome.ok && request.operation === "extract_firmware"
+                ? [request.input.output_directory]
+                : []),
+        ], { reason: cause instanceof Error ? cause.message : String(cause) }, {
+            cause,
+            operation: request.operation,
+            ...(outcome.ok
+                ? {
+                    partialObservation: completedFirmwareObservation(outcome.value),
+                }
+                : outcome.error.partialObservation === undefined
+                    ? {}
+                    : { partialObservation: outcome.error.partialObservation }),
+        });
+        return err(outcome.ok
+            ? cleanup
+            : analysisErrorWithCleanupFailure(outcome.error, cleanup, request.operation));
+    }
+    return outcome;
+};
+const completedFirmwareObservation = (execution) => ({
+    kind: "firmware",
+    result: execution.result,
+    provenance: jsonValueSchema.parse({
+        raw_result: execution.rawResult,
+        provider: execution.provider,
+        subject: execution.subject,
+        locations: execution.locations,
+        limitations: execution.limitations,
+        ...(execution.analysisProfile === undefined
+            ? {}
+            : { analysis_profile: execution.analysisProfile }),
+    }),
+});

package/dist/firmware/FirmwarePublication.js

@@ -1,13 +1,59 @@
+import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { join } from "node:path";
 import { SafeOutputTree } from "../artifacts/SafeOutputTree.js";
+import { SafeOutputTreeCreationFailure } from "../artifacts/SafeOutputTreeCreationFailure.js";
 import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
 import { firmwareResultSchemas } from "../domain/firmware/firmwareAnalysis.js";
 import { hashFirmwareFile } from "./FirmwareFiles.js";
+/** Static, truthful continuations that use already configured capabilities. */
+const GAP_CONTINUATIONS = {
+    "missing-extractor-dependency": "REA installs nothing. Add the named dependency to your own environment and rerun extract_firmware on the same immutable input with a fresh output_directory to re-evaluate the affected region; otherwise it stays unextracted.",
+    "unknown-chunk-handler": "If Binwalk is configured with REA_BINWALK_COMMAND, run inspect_firmware_regions on the same input for signature hypotheses. Without configured Binwalk that inspection is unavailable. Alternatively, select a materially narrower range with extract_firmware and a fresh output_directory; the region is not decoded content.",
+    "encrypted-chunk": "No static extraction continues past encryption; treat the region as unexamined rather than empty or corrupt.",
+    "extractor-failure": "The producer retained this chunk's extraction problem in diagnostics. Review the reported failure, then rerun extract_firmware on the same immutable input with a fresh output_directory; the region is not decoded content.",
+    "depth-limited": "Rerun extract_firmware with a higher max_depth (up to 10) and a fresh output_directory to descend into this path.",
+    "unpublished-entry": "The entry is retained as metadata; only regular files are published, without executable permission bits.",
+};
+const UNNAMED_DEPENDENCY_CONTINUATION = "The producer reported a missing extractor dependency without naming it; its identity is unavailable in this evidence. No specific installation or rerun can be prescribed from this report. Retain the gap as unextracted unless additional provider evidence establishes the dependency. REA installs nothing.";
+import { FIRMWARE_LIMITS } from "./FirmwareRelease.js";
+/** The depth ceiling cannot be raised past the input schema maximum. */
+const MAX_EXTRACTION_DEPTH = 10;
+const depthContinuation = (maxDepth, publishedChildPaths) => maxDepth < MAX_EXTRACTION_DEPTH
+    ? GAP_CONTINUATIONS["depth-limited"]
+    : publishedChildPaths.length > 0
+        ? `This extraction already ran at the lane's maximum depth. To continue, rerun extract_firmware with path set to any eligible published child below this path and a fresh output directory; each child listed here restarts the depth budget: ${publishedChildPaths.map((path) => JSON.stringify(path)).join(", ")}.`
+        : `This extraction already ran at the lane's maximum depth, and no published child under this path is both nonempty and within the ${FIRMWARE_LIMITS.inputBytes}-byte firmware input limit, so the depth budget cannot be restarted from this output. Treat the region below this path as unexamined.`;
+// Use a different analyzer on the actual published child; repeating the same
+// whole-child extraction with unchanged handlers would reproduce this gap.
+const nestedUnknownContinuation = (publishedFile) => {
+    const base = "This unknown chunk was carved from a nested extraction, so its range is relative to the published child named by this gap's input_path, not to the original input.";
+    return publishedFile !== undefined &&
+        publishedFile.size > 0 &&
+        publishedFile.size <= FIRMWARE_LIMITS.inputBytes
+        ? `${base} Run inspect_firmware_regions with path set to that published child for signature hypotheses only if Binwalk is configured with REA_BINWALK_COMMAND. This inspection step is unavailable without configured Binwalk; retain the region as unexamined. Repeating the same whole-child extraction with unchanged handlers would not advance analysis.`
+        : `${base} That published child is not a nonempty file within the ${FIRMWARE_LIMITS.inputBytes}-byte firmware input limit, so inspect_firmware_regions cannot accept it as a fresh input; treat the region as unexamined.`;
+};
+const emptyGap = {
+    relative_path: null,
+    handler: null,
+    provider_id: null,
+    range: null,
+    root_file_range: null,
+    dependencies: [],
+};
+const gapSortKey = (gap) => [
+    gap.input_path,
+    gap.kind,
+    gap.provider_id ?? "",
+    gap.relative_path ?? "",
+].join("\u0000");
 /** Publish verified regular files, preserving links as metadata and rolling back failed writes. */
 export const publishFirmwareExtraction = async (context) => {
     let tree;
+    let result;
     try {
         const materialized = new Set(context.entries
             .filter((entry) => entry.kind === "file")
@@ -37,7 +83,7 @@ export const publishFirmwareExtraction = async (context) => {
                 (context.normalized.sizes.has(logicalPath) &&
                     context.normalized.sizes.get(logicalPath) !== entry.size))
                 throw new AnalysisOutputError("extract_firmware", `Extracted bytes disagree with provider report: ${entry.relativePath}`);
-            await tree.write(entry.relativePath, createReadStream(entry.path), sha256, context.signal);
+            await tree.write(entry.relativePath, createReadStream(entry.path), { sha256, bytes: entry.size }, context.signal);
             files.push({
                 relative_path: entry.relativePath,
                 path: join(tree.outputRoot, entry.relativePath),
@@ -50,7 +96,7 @@ export const publishFirmwareExtraction = async (context) => {
                 original_file_range: null,
             });
         }
-        const result = firmwareResultSchemas.extract_firmware.parse({
+        result = firmwareResultSchemas.extract_firmware.parse({
             engine: context.engine,
             selection: context.selection,
             output_directory: tree.outputRoot,
@@ -61,24 +107,216 @@ export const publishFirmwareExtraction = async (context) => {
             derivations: context.normalized.derivations,
             depth_limited_paths: context.normalized.depth_limited_paths,
             diagnostics: context.normalized.diagnostics,
+            ...extractionGaps(unpublished, files, context.normalized, context.maxDepth),
             published_bytes: files.reduce((sum, file) => sum + file.size, 0),
         });
         context.signal.throwIfAborted();
-        await tree.commit();
+        await tree.commit(context.signal);
         return result;
     }
     catch (cause) {
+        if (cause instanceof SafeOutputTreeCreationFailure)
+            tree = cause.tree;
         try {
             await tree?.rollback();
         }
         catch (cleanupCause) {
+            if (tree !== undefined)
+                context.retainCleanup(tree);
+            const publishedResult = tree?.published === true && result !== undefined
+                ? {
+                    kind: "firmware",
+                    result: jsonValueSchema.parse(result),
+                }
+                : undefined;
             throw new ProviderCleanupError("unblob", [context.outputDirectory], {
                 reason: cleanupCause instanceof Error
                     ? cleanupCause.message
                     : String(cleanupCause),
                 previous_error: cause instanceof Error ? cause.message : String(cause),
-            }, { cause: cleanupCause });
+            }, {
+                cause: cleanupCause,
+                operation: "extract_firmware",
+                ...(publishedResult === undefined
+                    ? {}
+                    : { partialObservation: publishedResult }),
+            });
         }
+        if (tree?.published === true && result !== undefined)
+            return result;
         throw cause;
     }
 };
+/** Derive explicit recovery rows from retained report facts; no new claims. */
+/** Gap rows for missing-dependency reports: chunk-nested rows keep their owning chunk. */
+const dependencyExtractionGaps = (normalized, continuation) => {
+    // Chunk-nested dependency reports name the chunk that could not extract;
+    // task-wide reports (standalone or multi-file) attach to the task.
+    // One index over the chunk list keeps dependency-row resolution linear.
+    const chunksByKey = new Map(normalized.chunks.map((chunk) => [
+        JSON.stringify([chunk.input_path, chunk.provider_id]),
+        chunk,
+    ]));
+    return [
+        ...normalized.chunk_missing_dependencies.flatMap(({ input_path, provider_id, dependencies }) => {
+            const affected = chunksByKey.get(JSON.stringify([input_path, provider_id]));
+            return [
+                {
+                    kind: "missing-extractor-dependency",
+                    input_path,
+                    ...emptyGap,
+                    ...(affected === undefined
+                        ? {}
+                        : {
+                            handler: affected.handler,
+                            provider_id,
+                            range: affected.range,
+                            root_file_range: affected.root_file_range,
+                        }),
+                    dependencies: [...dependencies],
+                    continuation_id: continuation(dependencies.length > 0
+                        ? GAP_CONTINUATIONS["missing-extractor-dependency"]
+                        : UNNAMED_DEPENDENCY_CONTINUATION),
+                },
+            ];
+        }),
+        ...normalized.failed_extraction_stages
+            .filter(({ kind }) => kind === "missing-extractor-dependency")
+            .map(({ input_path, provider_id, handler, dependencies, }) => ({
+            kind: "missing-extractor-dependency",
+            input_path,
+            ...emptyGap,
+            handler,
+            provider_id,
+            dependencies: [...dependencies],
+            continuation_id: continuation(dependencies.length > 0
+                ? GAP_CONTINUATIONS["missing-extractor-dependency"]
+                : UNNAMED_DEPENDENCY_CONTINUATION),
+        })),
+        // Standalone reports name only the task; do not borrow another stage's id.
+        ...normalized.missing_dependencies.map(({ input_path, dependencies }) => ({
+            kind: "missing-extractor-dependency",
+            input_path,
+            ...emptyGap,
+            dependencies: [...dependencies],
+            continuation_id: continuation(dependencies.length > 0
+                ? GAP_CONTINUATIONS["missing-extractor-dependency"]
+                : UNNAMED_DEPENDENCY_CONTINUATION),
+        })),
+    ];
+};
+const extractionGaps = (unpublished, files, normalized, maxDepth) => {
+    // Intern before row construction: N gaps retain N identities, while K unique
+    // recovery instructions consume prose only K times in the public result.
+    const instructions = new Map();
+    const continuation = (instruction) => {
+        const known = instructions.get(instruction);
+        if (known !== undefined)
+            return known;
+        const id = createHash("sha256").update(instruction).digest("hex");
+        instructions.set(instruction, id);
+        return id;
+    };
+    const dependencyGaps = dependencyExtractionGaps(normalized, continuation);
+    const publishedFiles = new Map(files.map((file) => [`$output/${file.relative_path}`, file]));
+    const nestedContinuationId = (inputPath) => {
+        return continuation(nestedUnknownContinuation(publishedFiles.get(inputPath)));
+    };
+    const chunkGaps = (kind, matches) => normalized.chunks.filter(matches).map((chunk) => ({
+        kind,
+        input_path: chunk.input_path,
+        ...emptyGap,
+        handler: chunk.handler,
+        provider_id: chunk.provider_id,
+        range: chunk.range,
+        root_file_range: chunk.root_file_range,
+        dependencies: [],
+        continuation_id: kind === "unknown-chunk-handler" &&
+            chunk.input_path.startsWith("$output/")
+            ? nestedContinuationId(chunk.input_path)
+            : continuation(GAP_CONTINUATIONS[kind]),
+    }));
+    // Chunks whose failure a dependency row already covers stay out of the
+    // generic extractor-failure emission.
+    const dependencyChunkKeys = new Set(normalized.chunk_missing_dependencies.map(({ input_path, provider_id }) => JSON.stringify([input_path, provider_id])));
+    // A depth ceiling can only be re-rooted through a published child that a
+    // fresh firmware input could actually accept; the index is only needed
+    // when a depth row will actually consult it.
+    const ceilingReached = maxDepth >= MAX_EXTRACTION_DEPTH &&
+        normalized.depth_limited_paths.length > 0;
+    const reRootablePaths = new Map();
+    if (ceilingReached)
+        for (const [filePath, file] of [...publishedFiles].sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))) {
+            const size = file.size;
+            if (size <= 0 || size > FIRMWARE_LIMITS.inputBytes)
+                continue;
+            // The published file itself can re-root a fresh run; so can every
+            // directory containing it.
+            const segments = filePath.split("/");
+            while (segments.length > 1) {
+                const ancestor = segments.join("/");
+                const childPaths = reRootablePaths.get(ancestor) ?? new Set();
+                childPaths.add(file.path);
+                reRootablePaths.set(ancestor, childPaths);
+                segments.pop();
+            }
+        }
+    const depthContinuationIds = new Map();
+    const depthContinuationId = (inputPath) => {
+        const existing = depthContinuationIds.get(inputPath);
+        if (existing !== undefined)
+            return existing;
+        const id = continuation(depthContinuation(maxDepth, [...(reRootablePaths.get(inputPath) ?? [])].sort()));
+        depthContinuationIds.set(inputPath, id);
+        return id;
+    };
+    const gaps = [
+        ...dependencyGaps,
+        ...normalized.failed_extraction_stages
+            .filter(({ kind }) => kind === "extractor-failure")
+            .map(({ input_path, provider_id, handler }) => ({
+            kind: "extractor-failure",
+            input_path,
+            ...emptyGap,
+            handler,
+            provider_id,
+            dependencies: [],
+            continuation_id: continuation("The producer retained this extraction stage's failure in diagnostics. Review the stage report and correct the reported cause before rerunning extract_firmware on the same immutable input with a fresh output_directory; this report establishes no byte-region ownership."),
+        })),
+        ...chunkGaps("unknown-chunk-handler", (chunk) => chunk.handler === null),
+        ...chunkGaps("encrypted-chunk", (chunk) => chunk.encrypted === true),
+        ...chunkGaps("extractor-failure", (chunk) => chunk.extraction_failed === true &&
+            chunk.handler !== null &&
+            chunk.encrypted !== true &&
+            // The chunk's own dependency row already carries its recovery; a
+            // task-wide dependency names no region and replaces nothing.
+            !dependencyChunkKeys.has(JSON.stringify([chunk.input_path, chunk.provider_id]))),
+        ...normalized.depth_limited_paths.map((input_path) => ({
+            kind: "depth-limited",
+            input_path,
+            ...emptyGap,
+            dependencies: [],
+            continuation_id: depthContinuationId(input_path),
+        })),
+        ...unpublished.map((entry) => ({
+            kind: "unpublished-entry",
+            input_path: `$output/${entry.relative_path}`,
+            ...emptyGap,
+            relative_path: entry.relative_path,
+            dependencies: [],
+            continuation_id: continuation(GAP_CONTINUATIONS["unpublished-entry"]),
+        })),
+    ];
+    gaps.sort((left, right) => gapSortKey(left) < gapSortKey(right)
+        ? -1
+        : gapSortKey(left) > gapSortKey(right)
+            ? 1
+            : 0);
+    return {
+        extraction_gaps: gaps,
+        extraction_continuations: [...instructions].map(([instruction, id]) => ({
+            id,
+            instruction,
+        })),
+    };
+};

package/dist/firmware/FirmwareRelease.js

@@ -27,6 +27,7 @@ export const UNBLOB_PROVIDER_IDENTITY = {
 export const FIRMWARE_LIMITS = {
     inputBytes: 128 * 1024 * 1024,
     reportBytes: 8 * 1024 * 1024,
+    diagnosticBytes: 8 * 1024 * 1024,
     addressSpaceBytes: 1024 * 1024 * 1024,
     timeoutMs: 120_000,
 };