Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(providers): preserve observations and primary cleanup failures
morluto0696bde2660b
diff --git a/src/artifacts/ArtifactProvider.ts b/src/artifacts/ArtifactProvider.tsindex 9263ebd47..0fa89bdb2 100644--- a/src/artifacts/ArtifactProvider.ts+++ b/src/artifacts/ArtifactProvider.ts@@ -221,7 +221,7 @@ class ArtifactClient implements AnalysisClient {}),);} catch (cause: unknown) {- return err(translateFailure(operation, cause));+ return err(translateArtifactFailure(operation, cause));}}@@ -378,7 +378,8 @@ const isArtifactOperation = (operation as (typeof ARTIFACT_ANALYSIS_OPERATIONS)[number],);-const translateFailure = (+/** Translate one artifact boundary failure while retaining cleanup evidence. */+export const translateArtifactFailure = (operation: ArtifactAnalysisOperation,cause: unknown,): AnalysisError => {@@ -388,6 +389,12 @@ const translateFailure = (cause.reason,cause.details,cause.message,+ {+ ...(cause.cleanup === undefined ? {} : { cleanup: cause.cleanup }),+ ...(cause.partialObservation === undefined+ ? {}+ : { partialObservation: cause.partialObservation }),+ },);// Caller-selection and unsupported-target failures are already typed; keep// their correction details instead of reducing them to an I/O failure.diff --git a/src/artifacts/ArtifactReader.ts b/src/artifacts/ArtifactReader.tsindex 67e3548d5..78723823a 100644--- a/src/artifacts/ArtifactReader.ts+++ b/src/artifacts/ArtifactReader.ts@@ -1,6 +1,15 @@import type { Readable } from "node:stream";import type { ArtifactCommand } from "../domain/artifactGraph.js";import type { ZipPackageFormat } from "../domain/zipPackageFormat.js";+import type {+ AnalysisCleanupObservation,+ AnalysisPartialObservation,+} from "../domain/analysisErrorBase.js";++export interface ArtifactReaderFailureOptions extends ErrorOptions {+ readonly cleanup?: AnalysisCleanupObservation;+ readonly partialObservation?: AnalysisPartialObservation;+}/** Archive-neutral entry metadata. Reader adapters never choose output paths. */export interface ArtifactEntry {@@ -33,6 +42,9 @@ export interface ArtifactReader {/** Typed adapter failure translated at provider boundary. */export class ArtifactReaderFailure extends Error {+ readonly cleanup: AnalysisCleanupObservation | undefined;+ readonly partialObservation: AnalysisPartialObservation | undefined;+constructor(readonly reason:| "cancelled"@@ -43,7 +55,7 @@ export class ArtifactReaderFailure extends Error {| "path"| "unavailable",message: string,- options?: ErrorOptions,+ options?: ArtifactReaderFailureOptions,readonly details?: Readonly<{logicalPath: string;declaredSha256: string | null;@@ -53,5 +65,56 @@ export class ArtifactReaderFailure extends Error {) {super(message, options);this.name = "ArtifactReaderFailure";+ this.cleanup = options?.cleanup;+ this.partialObservation = options?.partialObservation;+ }++ /** Preserve the primary failure while attaching cleanup and any complete observation. */+ static withCleanup(+ cause: unknown,+ cleanup: AnalysisCleanupObservation,+ partialObservation?: AnalysisPartialObservation,+ ): ArtifactReaderFailure {+ const primary =+ cause instanceof ArtifactReaderFailure+ ? cause+ : new ArtifactReaderFailure("io", errorMessage(cause), { cause });+ const mergedObservation = partialObservation ?? primary.partialObservation;+ return new ArtifactReaderFailure(+ primary.reason,+ primary.message,+ {+ cause: primary,+ cleanup: combineCleanup(primary.cleanup, cleanup),+ ...(mergedObservation === undefined+ ? {}+ : { partialObservation: mergedObservation }),+ },+ primary.details,+ );+ }++ /** Give otherwise opaque cleanup failures a concrete owned resource. */+ static cleanupObservation(+ cause: unknown,+ resource: string,+ ): AnalysisCleanupObservation {+ if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined)+ return cause.cleanup;+ return { reason: errorMessage(cause), resources: [resource] };}}++const combineCleanup = (+ primary: AnalysisCleanupObservation | undefined,+ cleanup: AnalysisCleanupObservation,+): AnalysisCleanupObservation =>+ primary === undefined || primary === cleanup+ ? cleanup+ : {+ reason: `${primary.reason}; ${cleanup.reason}`,+ resources: [...new Set([...primary.resources, ...cleanup.resources])],+ };++const errorMessage = (cause: unknown): string =>+ cause instanceof Error ? cause.message : String(cause);diff --git a/src/artifacts/NativeDmgArtifactReader.ts b/src/artifacts/NativeDmgArtifactReader.tsindex 931488815..c087f987f 100644--- a/src/artifacts/NativeDmgArtifactReader.ts+++ b/src/artifacts/NativeDmgArtifactReader.ts@@ -188,7 +188,18 @@ export class NativeDmgArtifactReader implements ArtifactReader {throw new ArtifactReaderFailure("unavailable",`DMG detach or mount-root cleanup failed for ${JSON.stringify(this.path)}: ${failureMessage(detachFailure)}`,- { cause: detachFailure },+ {+ cause: detachFailure,+ cleanup: {+ reason: failureMessage(detachFailure),+ resources: [+ ...this.#devices.map((device) => `DMG device ${device}`),+ ...(this.#mountRoot === undefined+ ? []+ : [`DMG mount root ${this.#mountRoot}`]),+ ],+ },+ },);}@@ -298,10 +309,12 @@ export class NativeDmgArtifactReader implements ArtifactReader {cleanupFailure = cleanupCause;}if (cleanupFailure !== undefined)- throw new ArtifactReaderFailure(- "unavailable",- `DMG attach failed and cleanup could not detach every device: ${failureMessage(cause)}; cleanup: ${failureMessage(cleanupFailure)}`,- { cause: new AggregateError([cause, cleanupFailure]) },+ throw ArtifactReaderFailure.withCleanup(+ cause,+ ArtifactReaderFailure.cleanupObservation(+ cleanupFailure,+ `DMG mount root ${this.#mountRoot ?? this.path}`,+ ),);throw cause;}diff --git a/src/artifacts/SafeOutputTree.ts b/src/artifacts/SafeOutputTree.tsindex 67731f443..fafb6fee4 100644--- a/src/artifacts/SafeOutputTree.ts+++ b/src/artifacts/SafeOutputTree.ts@@ -208,7 +208,12 @@ export class SafeOutputTree {/** Remove only this operation's unsealed tree and verify absence. */async rollback(): Promise<SafeOutputCleanup> {if (this.#published) return structuredClone(this.#cleanup);- await rm(this.#outputRoot, { recursive: true, force: true });+ let removalFailure: unknown;+ try {+ await rm(this.#outputRoot, { recursive: true, force: true });+ } catch (cause: unknown) {+ removalFailure = cause;+ }const absent = await isAbsent(this.#outputRoot);this.#cleanup = absent? { status: "complete", residualPaths: [] }@@ -219,7 +224,17 @@ export class SafeOutputTree {if (!absent)throw new ArtifactReaderFailure("integrity",- "Extraction output cleanup could not be verified",+ `Extraction output cleanup could not be verified${removalFailure === undefined ? "" : `: ${removalFailure instanceof Error ? removalFailure.message : String(removalFailure)}`}`,+ {+ cause: removalFailure,+ cleanup: {+ reason:+ removalFailure instanceof Error+ ? removalFailure.message+ : "Extraction output root remains after rollback",+ resources: [this.#outputRoot],+ },+ },);return structuredClone(this.#cleanup);}diff --git a/src/artifacts/extraction/ArtifactExtraction.ts b/src/artifacts/extraction/ArtifactExtraction.tsindex c0df7abeb..9a481f393 100644--- a/src/artifacts/extraction/ArtifactExtraction.ts+++ b/src/artifacts/extraction/ArtifactExtraction.ts@@ -1,5 +1,6 @@import { lstat, realpath } from "node:fs/promises";+import { compareCodePoints } from "../../domain/canonicalOrdering.js";import { canonicalDigest } from "../../domain/comparisonSemantics.js";import { AsarArtifactReader } from "../AsarArtifactReader.js";import {@@ -136,10 +137,12 @@ const materializeSelection = async ({selected.map((item) => [item.occurrence.logical_path, item]),);const reader = await createReader(sourcePath, input);- const output = await SafeOutputTree.create(input.outputRoot);+ let output: SafeOutputTree | undefined;+ let readerCloseAttempted = false;let readerClosed = false;const extracted: ExtractedOccurrence[] = [];try {+ output = await SafeOutputTree.create(input.outputRoot);const materialized: SelectedOccurrence[] = [];const registry = new ArtifactPathRegistry();for await (const entry of reader.entries(signal)) {@@ -171,10 +174,11 @@ const materializeSelection = async ({});materialized.push(selectedItem);}+ readerCloseAttempted = true;await reader.close();readerClosed = true;extracted.sort((left, right) =>- left.relative_path.localeCompare(right.relative_path, "en"),+ compareCodePoints(left.relative_path, right.relative_path),);const result = createExtractionResult(input,@@ -185,12 +189,48 @@ const materializeSelection = async ({await output.commit();return result;} catch (cause: unknown) {- if (!readerClosed)- await reader.close().catch((cause: unknown) => {- // best-effort cleanup: reader close must not mask the extraction failure.- void cause;+ const cleanupFailures: {+ readonly cause: unknown;+ readonly resource: string;+ }[] = [];+ if (readerCloseAttempted && !readerClosed)+ cleanupFailures.push({+ cause,+ resource: `artifact reader for ${sourcePath}`,});- await output.rollback();+ if (!readerCloseAttempted) {+ try {+ readerCloseAttempted = true;+ await reader.close();+ } catch (cleanupCause: unknown) {+ cleanupFailures.push({+ cause: cleanupCause,+ resource: `artifact reader for ${sourcePath}`,+ });+ }+ }+ if (output !== undefined) {+ try {+ await output.rollback();+ } catch (cleanupCause: unknown) {+ cleanupFailures.push({+ cause: cleanupCause,+ resource: input.outputRoot,+ });+ }+ }+ if (cleanupFailures.length > 0) {+ const observations = cleanupFailures.map(+ ({ cause: cleanupCause, resource }) =>+ ArtifactReaderFailure.cleanupObservation(cleanupCause, resource),+ );+ throw ArtifactReaderFailure.withCleanup(cause, {+ reason: observations.map(({ reason }) => reason).join("; "),+ resources: [+ ...new Set(observations.flatMap(({ resources }) => resources)),+ ],+ });+ }throw cause;}};@@ -205,7 +245,7 @@ const createExtractionResult = (source_manifest_id: inventory.manifest.manifest_id,selected_occurrence_ids: selected.map(({ occurrence }) => occurrence.occurrence_id)- .sort((left, right) => left.localeCompare(right)),+ .sort(compareCodePoints),files_sha256: canonicalDigest(extracted, "Artifact"),output_root_alias: "$OUTPUT_ROOT" as const,};diff --git a/src/artifacts/inventory/scanCanonical.ts b/src/artifacts/inventory/scanCanonical.tsindex 6358394fa..9e3e48b36 100644--- a/src/artifacts/inventory/scanCanonical.ts+++ b/src/artifacts/inventory/scanCanonical.ts@@ -45,6 +45,7 @@ import {export const scanCanonicalArtifactInventory = async (path: string,options: ArtifactInventoryOptions = {},+ readerFactory: typeof createReader = createReader,): Promise<ArtifactInventorySnapshot> => {const integrity = options.integrity ?? STRICT_INTEGRITY_POLICY;const metadata = await lstat(path);@@ -52,33 +53,59 @@ export const scanCanonicalArtifactInventory = async (const rootDigest = metadata.isDirectory()? null: await hashReadable(createReadStream(path), options.signal);- const reader = await createReader(+ const reader = await readerFactory(path,rootFormat,options.environment ?? {},options.signal,);-+ let outcome:+ | {+ readonly kind: "completed";+ readonly snapshot: ArtifactInventorySnapshot;+ }+ | { readonly kind: "failed"; readonly cause: unknown };try {const { nodes, occurrences, pendingContradictions } = await scanReader(reader,options.signal,integrity,);- return await buildInventorySnapshot({- path,- metadata,- rootFormat,- rootDigest,- reader,- signal: options.signal,- nodes,- occurrences,- pendingContradictions,- });- } finally {+ outcome = {+ kind: "completed",+ snapshot: await buildInventorySnapshot({+ path,+ metadata,+ rootFormat,+ rootDigest,+ reader,+ signal: options.signal,+ nodes,+ occurrences,+ pendingContradictions,+ }),+ };+ } catch (cause: unknown) {+ outcome = { kind: "failed", cause };+ }+ try {await reader?.close();+ } catch (cleanupCause: unknown) {+ const cleanup = ArtifactReaderFailure.cleanupObservation(+ cleanupCause,+ `artifact reader for ${path}`,+ );+ const primary = outcome.kind === "failed" ? outcome.cause : cleanupCause;+ throw ArtifactReaderFailure.withCleanup(+ primary,+ cleanup,+ outcome.kind === "completed"+ ? { kind: "artifact-inventory", inventory: outcome.snapshot }+ : undefined,+ );}+ if (outcome.kind === "failed") throw outcome.cause;+ return outcome.snapshot;};interface SnapshotBuildInput {diff --git a/src/domain/analysisErrorBase.ts b/src/domain/analysisErrorBase.tsindex 3b9087390..6c9178c55 100644--- a/src/domain/analysisErrorBase.ts+++ b/src/domain/analysisErrorBase.ts@@ -87,10 +87,14 @@ import type {import type { FileOffsetPartialObservation } from "./native/fileOffsetPartialObservation.js";import type { NativeCallPartialObservation } from "./native/nativeCallPartialObservation.js";import type { ElectronActivePartialObservation } from "./javascript/electronActiveObservation.js";+import type { JavaScriptRuntimeObservation } from "./javascript/javascriptRuntimeObservation.js";+import type { ArtifactInventoryPartialObservation } from "./artifactPartialObservation.js";/** Provider-neutral evidence collected before a typed analysis failure. */export type AnalysisPartialObservation =| PartialProcessCaptureObservation| NativeCallPartialObservation| FileOffsetPartialObservation- | ElectronActivePartialObservation;+ | ElectronActivePartialObservation+ | JavaScriptRuntimeObservation+ | ArtifactInventoryPartialObservation;diff --git a/src/domain/artifactOperationError.ts b/src/domain/artifactOperationError.tsindex 76c94f348..54ed89d15 100644--- a/src/domain/artifactOperationError.ts+++ b/src/domain/artifactOperationError.ts@@ -1,4 +1,7 @@-import { AnalysisError } from "./analysisErrorBase.js";+import {+ AnalysisError,+ type AnalysisErrorOptions,+} from "./analysisErrorBase.js";/** Artifact inventory or extraction failed a typed safety boundary. */export class ArtifactOperationError extends AnalysisError {@@ -33,11 +36,13 @@ export class ArtifactOperationError extends AnalysisError {}>,/** The specific constraint that failed, such as the colliding path. */readonly detail?: string,+ options?: AnalysisErrorOptions,) {super(artifactDetails === undefined? `Artifact ${operation} failed: ${reason}`: `Artifact ${operation} failed: ${reason} at ${artifactDetails.logicalPath} (declared_sha256=${artifactDetails.declaredSha256 ?? "unavailable"}, calculated_sha256=${artifactDetails.calculatedSha256 ?? "unavailable"}, unpacked=${String(artifactDetails.unpacked)})`,+ options,);}}diff --git a/src/domain/artifactPartialObservation.ts b/src/domain/artifactPartialObservation.tsnew file mode 100644index 000000000..d813788c0--- /dev/null+++ b/src/domain/artifactPartialObservation.ts@@ -0,0 +1,7 @@+import type { ArtifactInventorySnapshot } from "./artifactInventorySnapshot.js";++/** A complete inventory retained when releasing its provider resources fails. */+export interface ArtifactInventoryPartialObservation {+ readonly kind: "artifact-inventory";+ readonly inventory: ArtifactInventorySnapshot;+}diff --git a/src/inspector/V8InspectorProvider.cleanup.test.ts b/src/inspector/V8InspectorProvider.cleanup.test.tsindex a552fff49..ac3f429c7 100644--- a/src/inspector/V8InspectorProvider.cleanup.test.ts+++ b/src/inspector/V8InspectorProvider.cleanup.test.ts@@ -4,6 +4,9 @@ import {closeInspectorConnection,inspectorCleanupError,} from "./V8InspectorProvider.js";+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";+import { analysisErrorProjectionSchema } from "../contracts/errorSchemas.js";+import { javascriptRuntimeObservationSchema } from "../domain/javascript/javascriptRuntimeObservation.js";it("returns promptly on cancellation while a V8 socket close is hung", async () => {const controller = new AbortController();@@ -32,6 +35,59 @@ it("maps a rejected close to incomplete cleanup and preserves the primary failurexpect(error.cleanupIncomplete).toBe(true);expect(error.cleanupResources).toEqual(["browser_transport"]);expect(error.cause).toBeInstanceOf(AggregateError);- if (!(error.cause instanceof AggregateError)) return;- expect(error.cause.errors).toEqual([primary, cleanup]);+ expect(error.cause).toMatchObject({ errors: [primary, cleanup] });+});++it("projects a completed runtime observation with the cleanup failure", () => {+ const observation = javascriptRuntimeObservationSchema.parse({+ runtime: {+ product: "Node.js",+ protocol_version: "1.3",+ v8_version: "12.0",+ },+ target: {+ target_id: "target-1",+ protocol_type: "node",+ attached: false,+ location: { kind: "file", file_path: "/fixture.js" },+ runtime_kind: "node",+ runtime_kind_authority: "caller-declared-unverified",+ },+ capture: {+ observation_ms: 0,+ events_observed: 0,+ events_retained: 0,+ events_dropped: 0,+ metadata_bytes_retained: 0,+ truncated: false,+ truncation_reasons: [],+ },+ scripts: {+ items: [],+ observed_total: 0,+ excluded: { unsupported_location: 0, invalid_protocol_value: 0 },+ },+ execution_contexts: [],+ directly_observed: ["Inspector target attached and queried."],+ unavailable_without_instrumentation: [],+ unknowns: [],+ limitations: [],+ });+ const primary = new Error("observation failed");+ const cleanup = new Error("socket close failed");+ const error = inspectorCleanupError(primary, cleanup, true, observation);+ const cause = error.cause;+ expect(cause).toBeInstanceOf(AggregateError);+ expect(cause).toMatchObject({ errors: [primary, cleanup] });++ const projected = projectAnalysisError(error);+ expect(analysisErrorProjectionSchema.safeParse(projected).success).toBe(true);+ expect(projected).toMatchObject({+ code: "cleanup_incomplete",+ details: {+ cleanup_reason: "socket close failed",+ resources: ["browser_transport"],+ partial_observation: observation,+ },+ });});diff --git a/src/inspector/V8InspectorProvider.ts b/src/inspector/V8InspectorProvider.tsindex e9fe3a3c3..9c3736711 100644--- a/src/inspector/V8InspectorProvider.ts+++ b/src/inspector/V8InspectorProvider.ts@@ -13,6 +13,7 @@ import {} from "../domain/javascript/javascriptRuntimeObservation.js";import { AnalysisError } from "../domain/analysisErrorBase.js";import { BrowserObservationError } from "../domain/browserObservationError.js";+import type { AnalysisPartialObservation } from "../domain/analysisErrorBase.js";import { ProviderAdapterError } from "../domain/providerAdapterError.js";import { type BrowserObservationOperation } from "../domain/browserObservationErrors.js";import { err, ok, type Result } from "../domain/result.js";@@ -190,7 +191,18 @@ export class V8InspectorProvider implements JavaScriptRuntimeObservationPort {}}if (cleanupFailed) {- return err(inspectorCleanupError(primaryFailure, cleanupFailure, failed));+ return err(+ inspectorCleanupError(+ primaryFailure,+ cleanupFailure,+ failed,+ outcome?.ok === true+ ? outcome.value+ : outcome?.ok === false+ ? outcome.error.partialObservation+ : undefined,+ ),+ );}return (outcome ??@@ -232,6 +244,7 @@ export const inspectorCleanupError = (primaryFailure: unknown,cleanupFailure: unknown,hasPrimaryFailure: boolean,+ partialObservation?: AnalysisPartialObservation,): BrowserObservationError => {const cause = hasPrimaryFailure? new AggregateError(@@ -239,10 +252,21 @@ export const inspectorCleanupError = ("Inspector observation and cleanup both failed",): cleanupFailure;+ const cleanupReason =+ cleanupFailure instanceof Error+ ? cleanupFailure.message+ : String(cleanupFailure);return new BrowserObservationError("observe_javascript_runtime","cleanup_failed",- { cause },+ {+ cause,+ cleanup: {+ reason: cleanupReason,+ resources: ["browser_transport"],+ },+ ...(partialObservation === undefined ? {} : { partialObservation }),+ },);};diff --git a/tests/boundary/filesystem/artifactInventorySnapshot.test.ts b/tests/boundary/filesystem/artifactInventorySnapshot.test.tsindex bd0201d67..e55f01971 100644--- a/tests/boundary/filesystem/artifactInventorySnapshot.test.ts+++ b/tests/boundary/filesystem/artifactInventorySnapshot.test.ts@@ -5,7 +5,15 @@ import { describe, expect, it } from "vitest";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { translateArtifactFailure } from "../../../src/artifacts/ArtifactProvider.js";+import {+ ArtifactReaderFailure,+ type ArtifactReader,+} from "../../../src/artifacts/ArtifactReader.js";+import { DirectoryArtifactReader } from "../../../src/artifacts/DirectoryArtifactReader.js";+import { scanCanonicalArtifactInventory } from "../../../src/artifacts/inventory/scanCanonical.js";import { scanArtifactInventory } from "../../../src/artifacts/inventory/ArtifactInventory.js";+import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";describe("artifact inventory snapshot", () => {it("retains the complete scan after the source directory changes", async () => {@@ -22,4 +30,54 @@ describe("artifact inventory snapshot", () => {]);expect(snapshot.manifest.occurrence_count).toBe(3);});++ it("projects the complete inventory when reader cleanup fails after scanning", async () => {+ const root = await createTestTempDirectory("rea-inventory-cleanup-");+ await writeFile(join(root, "observed.txt"), "observed");+ const directory = new DirectoryArtifactReader(root);+ const reader: ArtifactReader = {+ format: directory.format,+ entries: (signal) => directory.entries(signal),+ open: (entry, signal) => directory.open(entry, signal),+ provenance: () => directory.provenance(),+ async close() {+ await directory.close();+ throw new ArtifactReaderFailure("unavailable", "mount still attached", {+ cleanup: {+ reason: "DMG detach failed",+ resources: ["/dev/disk-test", "/tmp/rea-mount-test"],+ },+ });+ },+ };+ const failure = await scanCanonicalArtifactInventory(+ root,+ {},+ async () => reader,+ ).catch((cause: unknown) => cause);+ expect(failure).toBeInstanceOf(ArtifactReaderFailure);+ if (!(failure instanceof ArtifactReaderFailure))+ throw failure instanceof Error+ ? failure+ : new Error("Expected the reader cleanup failure", { cause: failure });+ const projection = projectAnalysisError(+ translateArtifactFailure("inventory_artifact", failure),+ );+ expect(projection).toMatchObject({+ code: "cleanup_incomplete",+ details: {+ execution_failure: "artifact_operation_failed",+ resources: ["/dev/disk-test", "/tmp/rea-mount-test"],+ partial_observation: {+ kind: "artifact-inventory",+ inventory: {+ manifest: { occurrence_count: 2 },+ occurrences: expect.arrayContaining([+ expect.objectContaining({ logical_path: "observed.txt" }),+ ]),+ },+ },+ },+ });+ });});diff --git a/tests/boundary/filesystem/safeOutputTree.test.ts b/tests/boundary/filesystem/safeOutputTree.test.tsindex b22636dc0..32e3c3d32 100644--- a/tests/boundary/filesystem/safeOutputTree.test.ts+++ b/tests/boundary/filesystem/safeOutputTree.test.ts@@ -1,5 +1,12 @@import { createHash } from "node:crypto";-import { access, readFile, readdir, readlink, rm } from "node:fs/promises";+import {+ access,+ chmod,+ readFile,+ readdir,+ readlink,+ rm,+} from "node:fs/promises";import { join } from "node:path";import { Readable } from "node:stream";@@ -8,6 +15,7 @@ import { describe, expect, it } from "vitest";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";import { SafeOutputTree } from "../../../src/artifacts/SafeOutputTree.js";+import { ArtifactReaderFailure } from "../../../src/artifacts/ArtifactReader.js";describe("safe artifact output tree", () => {it.skipIf(process.platform !== "linux")(@@ -49,6 +57,32 @@ describe("safe artifact output tree", () => {expect(await readdir(parent)).toEqual([]);});+ it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(+ "reports the owned residual root when rollback lacks directory permissions",+ async () => {+ const parent = await createTestTempDirectory("rea-safe-output-rollback-");+ const output = join(parent, "published");+ const tree = await SafeOutputTree.create(output);+ const bytes = Buffer.from("retained until rollback can retry");+ await tree.write(+ "nested/file.txt",+ Readable.from(bytes),+ createHash("sha256").update(bytes).digest("hex"),+ );+ try {+ await chmod(output, 0o500);+ const failure = await tree.rollback().catch((cause: unknown) => cause);+ expect(failure).toBeInstanceOf(ArtifactReaderFailure);+ expect(failure).toMatchObject({+ cleanup: { resources: [output] },+ });+ } finally {+ await chmod(output, 0o700).catch(() => undefined);+ await tree.rollback();+ }+ },+ );+it("publishes files while building and preserves them after sealing", async () => {const parent = await createTestTempDirectory("rea-safe-output-");const output = join(parent, "published");diff --git a/tests/boundary/inspector/javascriptRuntimeObservation.test.ts b/tests/boundary/inspector/javascriptRuntimeObservation.test.tsindex b86260ed5..5a6b84de3 100644--- a/tests/boundary/inspector/javascriptRuntimeObservation.test.ts+++ b/tests/boundary/inspector/javascriptRuntimeObservation.test.ts@@ -113,143 +113,141 @@ describe("Inspector execution-context lifecycle metadata", () => {});});-describe("passive V8 Inspector provider", () => {- test("rejects unknown runtime observation fields", () => {- expect(- observeJavaScriptRuntimeInputSchema.safeParse({- inspector_endpoint: "http://127.0.0.1:9229",- target_id: "target-1",- unknown_field: true,- }).success,- ).toBe(false);+test("rejects unknown runtime observation fields", () => {+ expect(+ observeJavaScriptRuntimeInputSchema.safeParse({+ inspector_endpoint: "http://127.0.0.1:9229",+ target_id: "target-1",+ unknown_field: true,+ }).success,+ ).toBe(false);+});++test("returns every target exposed by the selected Inspector endpoint inline", async () => {+ const fixture = await runtimeFixture();+ const fake = await startFakeV8Inspector({+ targetUrl: pathToFileURL(fixture.entry).href,+ additionalTargetCount: 205,});+ try {+ const listed = await new V8InspectorProvider().listTargets({+ inspector_endpoint: fake.endpoint,+ });+ if (!listed.ok) throw listed.error;+ expect(listed.value.targets).toHaveLength(206);+ expect(listed.value.targets[0]?.target_id).toBe(fake.targetId);+ } finally {+ await fake.close();+ }+});- test("returns every target exposed by the selected Inspector endpoint inline", async () => {- const fixture = await runtimeFixture();- const fake = await startFakeV8Inspector({- targetUrl: pathToFileURL(fixture.entry).href,- additionalTargetCount: 205,+test("includes targets outside the old caller root filter", async () => {+ const fixture = await runtimeFixture();+ const outside = await temporaryFile("outside.js");+ const fake = await startFakeV8Inspector({+ targetUrl: pathToFileURL(fixture.entry).href,+ additionalTargetUrl: pathToFileURL(outside).href,+ });+ try {+ const result = await new V8InspectorProvider().listTargets({+ inspector_endpoint: fake.endpoint,});- try {- const listed = await new V8InspectorProvider().listTargets({- inspector_endpoint: fake.endpoint,- });- if (!listed.ok) throw listed.error;- expect(listed.value.targets).toHaveLength(206);- expect(listed.value.targets[0]?.target_id).toBe(fake.targetId);- } finally {- await fake.close();- }+ if (!result.ok) throw result.error;+ expect(result.value.targets).toHaveLength(2);+ expect(result.value.targets.map(({ location }) => location)).toContainEqual(+ expect.objectContaining({ file_path: outside }),+ );+ } finally {+ await fake.close();+ }+});++test("captures complete metadata with two enable commands", async () => {+ const fixture = await runtimeFixture();+ const outside = await temporaryFile("secret.js");+ const fake = await startFakeV8Inspector({+ targetUrl: pathToFileURL(fixture.entry).href,+ scriptUrls: [+ pathToFileURL(fixture.entry).href,+ "node:fs",+ pathToFileURL(outside).href,+ ],});+ try {+ const result = await new V8InspectorProvider().observe(+ observeInput(fake.endpoint, fake.targetId, "node"),+ );+ if (!result.ok) throw result.error;+ expect(result.value.scripts.items).toHaveLength(3);+ expect(result.value.scripts.excluded.unsupported_location).toBe(0);+ expect(result.value.execution_contexts).toEqual([+ {+ context_key: "1",+ state: "created",+ name: "node[fixture]",+ origin: "",+ },+ ]);+ expect(new Set(fake.commands.map(({ method }) => method))).toEqual(+ new Set(["Runtime.enable", "Debugger.enable"]),+ );+ expect(JSON.stringify(result.value)).toContain(outside);+ expect(result.value.unavailable_without_instrumentation).toContain(+ "Electron IPC messages and handlers",+ );+ } finally {+ await fake.close();+ }+});- test("includes targets outside the old caller root filter", async () => {- const fixture = await runtimeFixture();- const outside = await temporaryFile("outside.js");- const fake = await startFakeV8Inspector({- targetUrl: pathToFileURL(fixture.entry).href,- additionalTargetUrl: pathToFileURL(outside).href,- });- try {- const result = await new V8InspectorProvider().listTargets({- inspector_endpoint: fake.endpoint,- });- if (!result.ok) throw result.error;- expect(result.value.targets).toHaveLength(2);- expect(- result.value.targets.map(({ location }) => location),- ).toContainEqual(expect.objectContaining({ file_path: outside }));- } finally {- await fake.close();- }+test("excludes an Electron main target that reports only bare file://", async () => {+ const fixture = await runtimeFixture();+ const fake = await startFakeV8Inspector({+ targetUrl: "file://",+ scriptUrls: [pathToFileURL(fixture.entry).href],});+ try {+ const provider = new V8InspectorProvider();+ const listed = await provider.listTargets({+ inspector_endpoint: fake.endpoint,+ });+ if (!listed.ok) throw listed.error;+ expect(listed.value.targets).toEqual([]);++ const observed = await provider.observe(+ observeInput(fake.endpoint, fake.targetId, "electron-main"),+ );+ expect(observed.ok).toBe(false);+ if (observed.ok) return;+ expect(observed.error.message).toMatch(/target/u);+ } finally {+ await fake.close();+ }+});- test("captures complete metadata with two enable commands", async () => {+test.each([+ ["node", "node"],+ ["electron-main", "node"],+ ["electron-preload", "page"],+ ["electron-renderer", "page"],+] as const)(+ "admits declared %s only on its protocol target family",+ async (runtimeKind, targetType) => {const fixture = await runtimeFixture();- const outside = await temporaryFile("secret.js");const fake = await startFakeV8Inspector({targetUrl: pathToFileURL(fixture.entry).href,- scriptUrls: [- pathToFileURL(fixture.entry).href,- "node:fs",- pathToFileURL(outside).href,- ],+ targetType,});try {const result = await new V8InspectorProvider().observe(- observeInput(fake.endpoint, fake.targetId, "node"),- );- if (!result.ok) throw result.error;- expect(result.value.scripts.items).toHaveLength(3);- expect(result.value.scripts.excluded.unsupported_location).toBe(0);- expect(result.value.execution_contexts).toEqual([- {- context_key: "1",- state: "created",- name: "node[fixture]",- origin: "",- },- ]);- expect(new Set(fake.commands.map(({ method }) => method))).toEqual(- new Set(["Runtime.enable", "Debugger.enable"]),- );- expect(JSON.stringify(result.value)).toContain(outside);- expect(result.value.unavailable_without_instrumentation).toContain(- "Electron IPC messages and handlers",+ observeInput(fake.endpoint, fake.targetId, runtimeKind),);+ expect(result.ok).toBe(true);} finally {await fake.close();}- });-- test("excludes an Electron main target that reports only bare file://", async () => {- const fixture = await runtimeFixture();- const fake = await startFakeV8Inspector({- targetUrl: "file://",- scriptUrls: [pathToFileURL(fixture.entry).href],- });- try {- const provider = new V8InspectorProvider();- const listed = await provider.listTargets({- inspector_endpoint: fake.endpoint,- });- if (!listed.ok) throw listed.error;- expect(listed.value.targets).toEqual([]);-- const observed = await provider.observe(- observeInput(fake.endpoint, fake.targetId, "electron-main"),- );- expect(observed.ok).toBe(false);- if (observed.ok) return;- expect(observed.error.message).toMatch(/target/u);- } finally {- await fake.close();- }- });-- test.each([- ["node", "node"],- ["electron-main", "node"],- ["electron-preload", "page"],- ["electron-renderer", "page"],- ] as const)(- "admits declared %s only on its protocol target family",- async (runtimeKind, targetType) => {- const fixture = await runtimeFixture();- const fake = await startFakeV8Inspector({- targetUrl: pathToFileURL(fixture.entry).href,- targetType,- });- try {- const result = await new V8InspectorProvider().observe(- observeInput(fake.endpoint, fake.targetId, runtimeKind),- );- expect(result.ok).toBe(true);- } finally {- await fake.close();- }- },- );-});+ },+);describe("complete Inspector script hashes", () => {test("keeps more than one hundred long script hashes distinct", async () => {diff --git a/tests/boundary/providers/native/artifactProvider.extraction.test.ts b/tests/boundary/providers/native/artifactProvider.extraction.test.tsindex 7d07ae113..f6d0e0847 100644--- a/tests/boundary/providers/native/artifactProvider.extraction.test.ts+++ b/tests/boundary/providers/native/artifactProvider.extraction.test.ts@@ -1,11 +1,4 @@-import {- access,- mkdir,- readFile,- readdir,- symlink,- writeFile,-} from "node:fs/promises";+import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";import { join } from "node:path";import { describe, expect, it } from "vitest";@@ -14,7 +7,6 @@ import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.jsimport { ArtifactProvider } from "../../../../src/artifacts/ArtifactProvider.js";import { artifactExtractionExecutionSchema } from "../../../../src/contracts/artifactToolContracts.js";-import { TOOL_EFFECTS } from "../../../../src/contracts/toolEffects.js";import {artifactExtractionResultSchema,artifactInventoryResultSchema,@@ -22,33 +14,6 @@ import {import type { BinaryTarget } from "../../../../src/domain/binaryTarget.js";describe("artifact extraction", () => {- it("declares possible native mounts and fresh extraction directories", () => {- for (const platform of ["linux", "darwin"] as const) {- const provider = new ArtifactProvider(process.env, platform);- for (const operation of [- "inventory_artifact",- "inspect_artifact",- "extract_artifact",- ] as const) {- expect(- provider- .capabilities()- .find((capability) => capability.operation === operation)?.effects,- ).toMatchObject({ launchesProcess: true, mayWriteFilesystem: true });- }- }- expect(TOOL_EFFECTS.inspect_artifact).toMatchObject({- launchesProcess: true,- writesFilesystem: true,- mutatesTarget: false,- });- expect(TOOL_EFFECTS.extract_artifact).toMatchObject({- launchesProcess: true,- writesFilesystem: true,- idempotent: false,- mutatesTarget: false,- });- });it("extracts all regular occurrences through an exclusively owned output tree", async () => {const root = await createTestTempDirectory("rea-extract-");const source = join(root, "source");@@ -140,39 +105,6 @@ describe("artifact extraction", () => {"source",]);});- it("refuses a format without an extraction reader before inventory or output", async () => {- const root = await createTestTempDirectory("rea-extract-dmg-");- const image = join(root, "Image.dmg");- await writeFile(image, "not mounted");- // A caller-specific alias must be the path the refusal reports.- const alias = join(root, "Alias.dmg");- await symlink(image, alias);- const output = join(root, "output");- const extract = (signal?: AbortSignal) =>- new ArtifactProvider(process.env)- .createClient(target(alias, "dmg"))- .execute(- "extract_artifact",- artifactExtractionExecutionSchema.parse({ output_root: output }),- signal === undefined ? undefined : { signal },- );- expect(await extract()).toMatchObject({- ok: false,- error: {- _tag: "AnalysisUnsupportedTargetError",- operation: "extract_artifact",- path: alias,- reason: "Artifact format has no extraction reader: dmg",- },- });- const controller = new AbortController();- controller.abort();- expect(await extract(controller.signal)).toMatchObject({- ok: false,- error: { _tag: "ArtifactOperationError", reason: "cancelled" },- });- await expect(access(output)).rejects.toThrow();- });});const inventory = async (targetValue: BinaryTarget) => {const result = await new ArtifactProvider(process.env)diff --git a/tests/boundary/providers/native/artifactProvider.extractionFormat.test.ts b/tests/boundary/providers/native/artifactProvider.extractionFormat.test.tsnew file mode 100644index 000000000..527e5faf0--- /dev/null+++ b/tests/boundary/providers/native/artifactProvider.extractionFormat.test.ts@@ -0,0 +1,56 @@+import { access, symlink, writeFile } from "node:fs/promises";+import { join } from "node:path";++import { describe, expect, it } from "vitest";++import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js";++import { ArtifactProvider } from "../../../../src/artifacts/ArtifactProvider.js";+import { artifactExtractionExecutionSchema } from "../../../../src/contracts/artifactToolContracts.js";+import type { BinaryTarget } from "../../../../src/domain/binaryTarget.js";++describe("artifact extraction format support", () => {+ it("refuses unsupported formats before inventory or output", async () => {+ const root = await createTestTempDirectory("rea-extract-format-");+ const image = join(root, "Image.dmg");+ await writeFile(image, "not mounted");+ const alias = join(root, "Alias.dmg");+ await symlink(image, alias);+ const output = join(root, "output");+ const extract = (signal?: AbortSignal) =>+ new ArtifactProvider(process.env)+ .createClient(archiveTarget(alias, "dmg"))+ .execute(+ "extract_artifact",+ artifactExtractionExecutionSchema.parse({ output_root: output }),+ signal === undefined ? undefined : { signal },+ );+ expect(await extract()).toMatchObject({+ ok: false,+ error: {+ _tag: "AnalysisUnsupportedTargetError",+ operation: "extract_artifact",+ path: alias,+ reason: "Artifact format has no extraction reader: dmg",+ },+ });+ const controller = new AbortController();+ controller.abort();+ expect(await extract(controller.signal)).toMatchObject({+ ok: false,+ error: { _tag: "ArtifactOperationError", reason: "cancelled" },+ });+ await expect(access(output)).rejects.toThrow();+ });+});++const archiveTarget = (+ path: string,+ format: Extract<BinaryTarget, { kind: "archive" }>["format"],+): BinaryTarget => ({+ path,+ sourcePath: path,+ sha256: "0".repeat(64),+ kind: "archive",+ format,+});diff --git a/tests/boundary/providers/native/artifactProvider.extractionIdentity.test.ts b/tests/boundary/providers/native/artifactProvider.extractionIdentity.test.tsnew file mode 100644index 000000000..cf63dbd6c--- /dev/null+++ b/tests/boundary/providers/native/artifactProvider.extractionIdentity.test.ts@@ -0,0 +1,45 @@+import { mkdir, writeFile } from "node:fs/promises";+import { join } from "node:path";++import { describe, expect, it } from "vitest";++import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js";++import { ArtifactProvider } from "../../../../src/artifacts/ArtifactProvider.js";+import { artifactExtractionExecutionSchema } from "../../../../src/contracts/artifactToolContracts.js";+import { artifactExtractionResultSchema } from "../../../../src/domain/artifactGraph.js";+import type { BinaryTarget } from "../../../../src/domain/binaryTarget.js";++describe("artifact extraction identity", () => {+ it("uses code-point order for path-independent extraction identities", async () => {+ const root = await createTestTempDirectory("rea-extract-order-");+ const source = join(root, "source");+ await mkdir(source);+ for (const name of ["ä.js", "a.js", "Z.js"])+ await writeFile(join(source, name), `${name}\n`);+ const result = await new ArtifactProvider(process.env)+ .createClient(directoryTarget(source))+ .execute(+ "extract_artifact",+ artifactExtractionExecutionSchema.parse({+ output_root: join(root, "output"),+ }),+ );+ if (!result.ok) throw result.error;+ const extracted = artifactExtractionResultSchema.parse(result.value.result);+ expect(+ extracted.artifacts.map(({ relative_path }) => relative_path),+ ).toEqual(["Z.js", "a.js", "ä.js"]);+ expect(extracted.extraction_manifest.selected_occurrence_ids).toEqual(+ [...extracted.extraction_manifest.selected_occurrence_ids].sort(),+ );+ });+});++const directoryTarget = (path: string): BinaryTarget => ({+ path,+ sourcePath: path,+ sha256: "0".repeat(64),+ kind: "archive",+ format: "asar",+});diff --git a/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts b/tests/boundary/providers/native/nativeDmgArtifactReader.test.tsindex 588f8bd4b..beb17922e 100644--- a/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts+++ b/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts@@ -121,7 +121,14 @@ describe("native DMG artifact reader", () => {undefined,host,),- ).rejects.toThrow("cleanup could not detach every device");+ ).rejects.toMatchObject({+ cleanup: {+ resources: expect.arrayContaining([+ "DMG device /dev/disk-fixture",+ expect.stringMatching(/^DMG mount root /u),+ ]),+ },+ });});});@@ -570,6 +577,12 @@ describe("APFS disk image detach", () => {await expect(reader.close()).rejects.toMatchObject({reason: "unavailable",message: expect.stringContaining("No such file or directory"),+ cleanup: {+ resources: expect.arrayContaining([+ "DMG device /dev/disk4",+ expect.stringMatching(/^DMG mount root /u),+ ]),+ },});});