Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(providers): preserve observations and primary cleanup failures

morluto0696bde2660b
diff --git a/src/artifacts/ArtifactProvider.ts b/src/artifacts/ArtifactProvider.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 failur
expect(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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.js
import { 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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),
+ ]),
+ },
});
});