fix(io): retain cleanup ownership and honor cancellation
Keep failed JSON read handles in the existing server resource scope and fail admission until cleanup succeeds. Thread cancellation through every process CLI input read and replace timer-driven cancellation checks with a shared first-read gate. Classify authenticated standalone Evidence as wrong-kind input while preserving tampered-record integrity failures and actionable messages across ledger, CLI, and MCP consumers. Record unrelated CS_RESTRICT process neighbors as unverified without weakening related-process ownership checks. Update stale ADB fixtures for the actual shell protocol. Validated focused CLI, MCP, filesystem, ownership, and error projection tests; static, docs, and duplication gates pass. The host-level CS_RESTRICT load reproduction was not run. Refs #2050, #2035, #2064.
This commit is contained in:
@@ -1,3 +1,5 @@
|
||||
import { resolve } from "node:path";
|
||||
|
||||
import {
|
||||
createImmutableEvidenceBundle,
|
||||
describeEvidenceBundleFailure,
|
||||
@@ -37,13 +39,15 @@ type EvidenceWriteFailure =
|
||||
export const readEvidenceBundle = (
|
||||
path: string,
|
||||
signal?: AbortSignal,
|
||||
resources?: ArtifactResourceScope,
|
||||
): Promise<Result<EvidenceBundle, EvidenceReadFailure>> =>
|
||||
readBundle(path, parseEvidenceBundle, signal);
|
||||
readBundle(path, parseEvidenceBundle, signal, resources);
|
||||
|
||||
/** Read an authenticated immutable snapshot for a subsequent session import. */
|
||||
export const readImmutableEvidenceBundle = (
|
||||
path: string,
|
||||
signal?: AbortSignal,
|
||||
resources?: ArtifactResourceScope,
|
||||
): Promise<Result<EvidenceBundle, EvidenceReadFailure>> =>
|
||||
readBundle(
|
||||
path,
|
||||
@@ -52,26 +56,30 @@ export const readImmutableEvidenceBundle = (
|
||||
return createImmutableEvidenceBundle(bundle.records, bundle.unknowns);
|
||||
},
|
||||
signal,
|
||||
resources,
|
||||
);
|
||||
|
||||
const readBundle = async (
|
||||
path: string,
|
||||
parseBundle: (input: unknown) => EvidenceBundle,
|
||||
signal?: AbortSignal,
|
||||
resources?: ArtifactResourceScope,
|
||||
): Promise<Result<EvidenceBundle, EvidenceReadFailure>> => {
|
||||
if (signal?.aborted)
|
||||
return err(new AnalysisCancelledError("import_evidence_bundle"));
|
||||
const loaded = await readJsonFile(path, signal).catch((cause: unknown) => {
|
||||
// A failed close transfers a live handle owner; preserve that failure.
|
||||
if (
|
||||
signal?.aborted === true &&
|
||||
!(cause instanceof RegularFileCleanupFailure)
|
||||
)
|
||||
return err(
|
||||
new AnalysisCancelledError("import_evidence_bundle", { cause }),
|
||||
);
|
||||
throw cause;
|
||||
});
|
||||
const loaded = await readJsonFile(path, signal, resources).catch(
|
||||
(cause: unknown) => {
|
||||
// A failed close transfers a live handle owner; preserve that failure.
|
||||
if (
|
||||
signal?.aborted === true &&
|
||||
!(cause instanceof RegularFileCleanupFailure)
|
||||
)
|
||||
return err(
|
||||
new AnalysisCancelledError("import_evidence_bundle", { cause }),
|
||||
);
|
||||
throw cause;
|
||||
},
|
||||
);
|
||||
if (!loaded.ok) return loaded;
|
||||
if (signal?.aborted)
|
||||
return err(new AnalysisCancelledError("import_evidence_bundle"));
|
||||
@@ -79,10 +87,19 @@ const readBundle = async (
|
||||
try {
|
||||
bundle = parseBundle(loaded.value);
|
||||
} catch (cause: unknown) {
|
||||
const failure = describeEvidenceBundleFailure(loaded.value, cause);
|
||||
if (failure.kind === "single-record")
|
||||
return err(
|
||||
new EvidenceFileError("read", "wrong-kind", {
|
||||
path: resolve(path),
|
||||
cause,
|
||||
userMessage: failure.message,
|
||||
}),
|
||||
);
|
||||
return err(
|
||||
new EvidenceIntegrityError("Evidence bundle validation failed", {
|
||||
cause,
|
||||
userMessage: describeEvidenceBundleFailure(loaded.value, cause),
|
||||
userMessage: failure.message,
|
||||
}),
|
||||
);
|
||||
}
|
||||
|
||||
@@ -24,6 +24,7 @@ import {
|
||||
type JsonObjectMemberReader,
|
||||
} from "./JsonInputFile.js";
|
||||
import { NonRegularFileReadError } from "../filesystem/RegularFile.js";
|
||||
import { RegularFileCleanupFailure } from "./RegularFileRead.js";
|
||||
import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
|
||||
import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
|
||||
import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
|
||||
@@ -42,12 +43,14 @@ type TextWriteResult<Failure = EvidenceFileError | AnalysisCancelledError> =
|
||||
export const readJsonFile = async (
|
||||
path: string,
|
||||
signal?: AbortSignal,
|
||||
resources?: ArtifactResourceScope,
|
||||
): Promise<
|
||||
Result<unknown, EvidenceFileError | AnalysisResourceConstraintError>
|
||||
> =>
|
||||
readJsonFileInput(
|
||||
path,
|
||||
(selected) => readJsonInputFile(selected, "read_evidence_file", signal),
|
||||
(selected) =>
|
||||
readJsonInputFile(selected, "read_evidence_file", signal, resources),
|
||||
signal,
|
||||
);
|
||||
|
||||
@@ -56,6 +59,7 @@ export const readJsonObjectMembersFile = (
|
||||
path: string,
|
||||
scans: readonly ReadonlyMap<string, JsonObjectMemberReader>[],
|
||||
signal?: AbortSignal,
|
||||
resources?: ArtifactResourceScope,
|
||||
): Promise<
|
||||
Result<
|
||||
void,
|
||||
@@ -65,7 +69,13 @@ export const readJsonObjectMembersFile = (
|
||||
readJsonFileInput(
|
||||
path,
|
||||
(selected) =>
|
||||
readJsonObjectFile(selected, "read_evidence_file", scans, signal),
|
||||
readJsonObjectFile(
|
||||
selected,
|
||||
"read_evidence_file",
|
||||
scans,
|
||||
signal,
|
||||
resources,
|
||||
),
|
||||
signal,
|
||||
);
|
||||
|
||||
@@ -103,6 +113,7 @@ const readJsonFileInput = async <Value>(
|
||||
}
|
||||
return ok(decoded.value);
|
||||
} catch (cause: unknown) {
|
||||
if (cause instanceof RegularFileCleanupFailure) throw cause;
|
||||
if (cause instanceof AnalysisResourceConstraintError) return err(cause);
|
||||
if (signal?.aborted === true) throw cause;
|
||||
return err(
|
||||
|
||||
@@ -11,6 +11,7 @@ import streamValues from "stream-json/streamers/stream-values.js";
|
||||
import streamArray from "stream-json/streamers/stream-array.js";
|
||||
|
||||
import { RegularFileChangedError } from "../filesystem/RegularFile.js";
|
||||
import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
|
||||
import { withRegularFile } from "./RegularFileRead.js";
|
||||
import {
|
||||
JSON_BYTE_ORDER_MARK_MESSAGE,
|
||||
@@ -55,6 +56,7 @@ export const readJsonObjectFile = (
|
||||
operation: string,
|
||||
scans: readonly ReadonlyMap<string, JsonObjectMemberReader>[],
|
||||
signal?: AbortSignal,
|
||||
resources?: ArtifactResourceScope,
|
||||
): Promise<Result<void, JsonInputFileFailure>> =>
|
||||
withRegularFile(
|
||||
path,
|
||||
@@ -188,7 +190,10 @@ export const readJsonObjectFile = (
|
||||
throw cause;
|
||||
}
|
||||
},
|
||||
{ signal },
|
||||
{
|
||||
signal,
|
||||
...(resources === undefined ? {} : { resources }),
|
||||
},
|
||||
);
|
||||
|
||||
const memberConsumer = (
|
||||
@@ -236,6 +241,7 @@ export const readJsonInputFile = (
|
||||
path: string,
|
||||
operation: string,
|
||||
signal?: AbortSignal,
|
||||
resources?: ArtifactResourceScope,
|
||||
): Promise<Result<unknown, JsonInputFileFailure>> =>
|
||||
withRegularFile(
|
||||
path,
|
||||
@@ -294,7 +300,10 @@ export const readJsonInputFile = (
|
||||
throw cause;
|
||||
}
|
||||
},
|
||||
{ signal },
|
||||
{
|
||||
signal,
|
||||
...(resources === undefined ? {} : { resources }),
|
||||
},
|
||||
);
|
||||
|
||||
const jsonReadFailure = (
|
||||
|
||||
@@ -95,7 +95,8 @@ const withRegularFileOwned = async <Value>(
|
||||
cause.cleanupCause,
|
||||
);
|
||||
if (options.resources === undefined) throw failure;
|
||||
await retryRegularFileCleanup(failure, options.resources);
|
||||
const retry = await retryRegularFileCleanup(failure, options.resources);
|
||||
if (retry.cleanup !== undefined) throw failure;
|
||||
throw cause.cause;
|
||||
}
|
||||
const owner = new OwnedFileHandle(handle);
|
||||
@@ -128,9 +129,10 @@ const withRegularFileOwned = async <Value>(
|
||||
cleanupCause,
|
||||
);
|
||||
if (options.resources === undefined) throw failure;
|
||||
const cleanup = await retryRegularFileCleanup(failure, options.resources);
|
||||
if (cleanup.outcome.kind === "failed") throw cleanup.outcome.cause;
|
||||
return cleanup.outcome.value;
|
||||
const retry = await retryRegularFileCleanup(failure, options.resources);
|
||||
if (retry.cleanup !== undefined) throw failure;
|
||||
if (retry.outcome.kind === "failed") throw retry.outcome.cause;
|
||||
return retry.outcome.value;
|
||||
}
|
||||
if (outcome.kind === "failed") throw outcome.cause;
|
||||
return outcome.value;
|
||||
|
||||
@@ -8,6 +8,7 @@ import {
|
||||
} from "../../domain/evidenceErrors.js";
|
||||
import { NoBinaryOpenError } from "../../domain/configurationErrors.js";
|
||||
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
|
||||
import type { AnalysisInputError } from "../../domain/analysisErrorCore.js";
|
||||
import { rebindEvidenceSubjectTargetPath } from "../../domain/evidence.js";
|
||||
import { err, ok, type Result } from "../../domain/result.js";
|
||||
import {
|
||||
@@ -190,7 +191,7 @@ export class AnalysisSnapshotCache {
|
||||
| undefined,
|
||||
mergeEvidence: (
|
||||
bundle: EvidenceBundle,
|
||||
) => Result<number, EvidenceIntegrityError>,
|
||||
) => Result<number, EvidenceIntegrityError | AnalysisInputError>,
|
||||
): Result<number, AnalysisError> {
|
||||
let validated: AnalysisSnapshot;
|
||||
try {
|
||||
|
||||
@@ -15,6 +15,7 @@ import { err, ok, type Result } from "../../domain/result.js";
|
||||
import type { AnalysisResourceConstraintError } from "../../domain/analysisErrorCore.js";
|
||||
import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
|
||||
import { readJsonObjectMembersFile, writeTextFile } from "../JsonFiles.js";
|
||||
import { RegularFileCleanupFailure } from "../RegularFileRead.js";
|
||||
import type { JsonObjectMemberReader } from "../JsonInputFile.js";
|
||||
import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
|
||||
|
||||
@@ -24,6 +25,7 @@ type SnapshotFailure = EvidenceFileError | EvidenceIntegrityError;
|
||||
export const readAnalysisSnapshot = async (
|
||||
path: string,
|
||||
signal?: AbortSignal,
|
||||
resources?: ArtifactResourceScope,
|
||||
): Promise<
|
||||
Result<
|
||||
AnalysisSnapshot,
|
||||
@@ -61,6 +63,7 @@ export const readAnalysisSnapshot = async (
|
||||
metadata,
|
||||
],
|
||||
signal,
|
||||
resources,
|
||||
);
|
||||
if (!loaded.ok) return loaded;
|
||||
signal?.throwIfAborted();
|
||||
@@ -74,6 +77,7 @@ export const readAnalysisSnapshot = async (
|
||||
signal?.throwIfAborted();
|
||||
return ok(snapshot);
|
||||
} catch (cause: unknown) {
|
||||
if (cause instanceof RegularFileCleanupFailure) throw cause;
|
||||
if (signal?.aborted === true)
|
||||
return err(new AnalysisCancelledError("read_evidence_file", { cause }));
|
||||
return err(
|
||||
|
||||
@@ -11,6 +11,7 @@ import {
|
||||
AnalysisSnapshotMismatchError,
|
||||
} from "../../domain/evidenceErrors.js";
|
||||
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
|
||||
import type { AnalysisInputError } from "../../domain/analysisErrorCore.js";
|
||||
import type { UnknownRegistryError } from "../../domain/unknownRegistryError.js";
|
||||
import type {
|
||||
RecordUnknownInput,
|
||||
@@ -129,7 +130,7 @@ export abstract class BinarySessionRecords {
|
||||
|
||||
importEvidenceBundle(
|
||||
bundle: unknown,
|
||||
): Result<number, EvidenceIntegrityError> {
|
||||
): Result<number, EvidenceIntegrityError | AnalysisInputError> {
|
||||
const imported = this.#records.mergeEvidenceBundle(bundle);
|
||||
if (!imported.ok) return imported;
|
||||
if (imported.value.metadataChanged) this.invalidateSnapshot();
|
||||
|
||||
@@ -4,6 +4,7 @@ import type { BinaryTarget } from "../../domain/binaryTargetTypes.js";
|
||||
import { createEvidence } from "../../domain/evidence.js";
|
||||
import { createEvidenceBundle } from "../../domain/evidenceBundle.js";
|
||||
import { recordUnknownInputSchema } from "../../domain/residualUnknown.js";
|
||||
import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
|
||||
import { EvidenceLedger } from "./EvidenceLedger.js";
|
||||
|
||||
const TARGET: BinaryTarget = {
|
||||
@@ -234,6 +235,32 @@ describe("evidence ledger metadata imports", () => {
|
||||
});
|
||||
|
||||
describe("evidence bundle imports", () => {
|
||||
it("classifies an authenticated Evidence record as the wrong import kind", () => {
|
||||
const record = createEvidence(TARGET, PROVIDER, {
|
||||
operation: "health",
|
||||
parameters: {},
|
||||
result: true,
|
||||
});
|
||||
const result = new EvidenceLedger().import(record);
|
||||
expect(result).toMatchObject({
|
||||
ok: false,
|
||||
error: {
|
||||
_tag: "AnalysisInputError",
|
||||
userMessage: expect.stringContaining(
|
||||
`this JSON is one Evidence record (${record.evidence_id})`,
|
||||
),
|
||||
},
|
||||
});
|
||||
if (result.ok) throw new Error("Expected a wrong-kind import failure");
|
||||
expect(projectAnalysisError(result.error)).toMatchObject({
|
||||
code: "invalid_request",
|
||||
category: "invalid_input",
|
||||
message: expect.stringContaining(
|
||||
`this JSON is one Evidence record (${record.evidence_id})`,
|
||||
),
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects conflicting duplicate IDs without mutating the ledger", () => {
|
||||
const ledger = new EvidenceLedger();
|
||||
const first = createEvidence(TARGET, PROVIDER, {
|
||||
|
||||
@@ -8,6 +8,7 @@ import {
|
||||
validateResidualUnknownAddition,
|
||||
type EvidenceBundle,
|
||||
} from "../../domain/evidenceBundle.js";
|
||||
import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
|
||||
import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
|
||||
import { UnknownRegistryError } from "../../domain/unknownRegistryError.js";
|
||||
import {
|
||||
@@ -37,7 +38,10 @@ export interface EvidenceImportDelta {
|
||||
readonly metadataChanged: boolean;
|
||||
}
|
||||
|
||||
type ImportResult = Result<EvidenceImportDelta, EvidenceLedgerFailure>;
|
||||
type ImportResult = Result<
|
||||
EvidenceImportDelta,
|
||||
EvidenceLedgerFailure | AnalysisInputError
|
||||
>;
|
||||
|
||||
/** Session-owned set of immutable evidence records. */
|
||||
export class EvidenceLedger {
|
||||
@@ -76,10 +80,18 @@ export class EvidenceLedger {
|
||||
try {
|
||||
bundle = parseEvidenceBundle(input);
|
||||
} catch (cause: unknown) {
|
||||
const failure = describeEvidenceBundleFailure(input, cause);
|
||||
if (failure.kind === "single-record")
|
||||
return err(
|
||||
new AnalysisInputError("import_evidence_bundle", {
|
||||
cause,
|
||||
userMessage: failure.message,
|
||||
}),
|
||||
);
|
||||
return err(
|
||||
new EvidenceIntegrityError("Evidence bundle validation failed", {
|
||||
cause,
|
||||
userMessage: describeEvidenceBundleFailure(input, cause),
|
||||
userMessage: failure.message,
|
||||
}),
|
||||
);
|
||||
}
|
||||
|
||||
@@ -2,6 +2,7 @@ import type { Evidence } from "../../domain/evidence.js";
|
||||
import type { EvidenceBundle } from "../../domain/evidenceBundle.js";
|
||||
import type { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
|
||||
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
|
||||
import type { AnalysisInputError } from "../../domain/analysisErrorCore.js";
|
||||
import type { UnknownRegistryError } from "../../domain/unknownRegistryError.js";
|
||||
import type {
|
||||
RecordUnknownInput,
|
||||
@@ -67,5 +68,7 @@ export interface InvestigationRecordPort
|
||||
EvidenceWriter,
|
||||
EvidenceUnknownWriter,
|
||||
UnknownRegistryPort {
|
||||
importEvidenceBundle(bundle: unknown): Result<number, EvidenceIntegrityError>;
|
||||
importEvidenceBundle(
|
||||
bundle: unknown,
|
||||
): Result<number, EvidenceIntegrityError | AnalysisInputError>;
|
||||
}
|
||||
|
||||
@@ -3,6 +3,7 @@ import type { Evidence } from "../../domain/evidence.js";
|
||||
import type { EvidenceBundle } from "../../domain/evidenceBundle.js";
|
||||
import type { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
|
||||
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
|
||||
import type { AnalysisInputError } from "../../domain/analysisErrorCore.js";
|
||||
import type { UnknownRegistryError } from "../../domain/unknownRegistryError.js";
|
||||
import type {
|
||||
RecordUnknownInput,
|
||||
@@ -65,7 +66,7 @@ export class InvestigationRecords
|
||||
/** Atomically merge a bundle and report changes for the owner's post-commit observers. */
|
||||
mergeEvidenceBundle(
|
||||
bundle: unknown,
|
||||
): Result<EvidenceImportDelta, EvidenceIntegrityError> {
|
||||
): Result<EvidenceImportDelta, EvidenceIntegrityError | AnalysisInputError> {
|
||||
return this.#evidence.import(bundle);
|
||||
}
|
||||
|
||||
|
||||
@@ -1,7 +1,10 @@
|
||||
import { z } from "zod";
|
||||
|
||||
import { AnalysisError } from "../../domain/analysisErrorBase.js";
|
||||
import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
|
||||
import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisInputError,
|
||||
} from "../../domain/analysisErrorCore.js";
|
||||
import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
|
||||
import { createEvidence, parseEvidence } from "../../domain/evidence.js";
|
||||
import { describeValidationFailure } from "../../domain/evidenceBundle.js";
|
||||
@@ -23,6 +26,7 @@ import {
|
||||
} from "../../domain/process/processEvidenceProvider.js";
|
||||
import { createProcessCaptureEvidence } from "./ProcessEvidence.js";
|
||||
import { readJsonFile } from "../JsonFiles.js";
|
||||
import { RegularFileCleanupFailure } from "../RegularFileRead.js";
|
||||
|
||||
/** Safe process-command failure returned to the CLI adapter. */
|
||||
export interface ProcessCliErrorOutput {
|
||||
@@ -51,7 +55,7 @@ export const captureProcessScenarioFile = async (
|
||||
signal?: AbortSignal,
|
||||
) => {
|
||||
try {
|
||||
const input = await readJson(path);
|
||||
const input = await readJson(path, "capture_process_scenario", signal);
|
||||
const parsed = processScenarioSchema.safeParse(input);
|
||||
if (!parsed.success)
|
||||
throw analysisInputErrorFromIssues(
|
||||
@@ -86,6 +90,7 @@ export const captureProcessScenarioFile = async (
|
||||
if (!captured.ok) return cliAnalysisError(captured.error);
|
||||
return createProcessCaptureEvidence(parsed.data, captured.value);
|
||||
} catch (cause: unknown) {
|
||||
if (cause instanceof RegularFileCleanupFailure) throw cause;
|
||||
return projectProcessCliError(cause);
|
||||
}
|
||||
};
|
||||
@@ -95,14 +100,23 @@ export const compareProcessEvidenceFiles = async (
|
||||
leftPath: string,
|
||||
rightPath: string,
|
||||
traceSpecPath?: string,
|
||||
signal?: AbortSignal,
|
||||
) => {
|
||||
try {
|
||||
const left = parseCaptureEvidence(await readJson(leftPath), "left");
|
||||
const right = parseCaptureEvidence(await readJson(rightPath), "right");
|
||||
const left = parseCaptureEvidence(
|
||||
await readJson(leftPath, "compare_process_captures", signal),
|
||||
"left",
|
||||
);
|
||||
const right = parseCaptureEvidence(
|
||||
await readJson(rightPath, "compare_process_captures", signal),
|
||||
"right",
|
||||
);
|
||||
const traceSpecification =
|
||||
traceSpecPath === undefined
|
||||
? undefined
|
||||
: parseTraceSpecification(await readJson(traceSpecPath));
|
||||
: parseTraceSpecification(
|
||||
await readJson(traceSpecPath, "compare_process_captures", signal),
|
||||
);
|
||||
const comparison =
|
||||
traceSpecification === undefined
|
||||
? compareProcessCaptures(left.capture, right.capture)
|
||||
@@ -129,6 +143,7 @@ export const compareProcessEvidenceFiles = async (
|
||||
evidenceLinks: [left.id, right.id],
|
||||
});
|
||||
} catch (cause: unknown) {
|
||||
if (cause instanceof RegularFileCleanupFailure) throw cause;
|
||||
return projectProcessCliError(cause);
|
||||
}
|
||||
};
|
||||
@@ -194,8 +209,21 @@ const invalidCaptureEvidence = (cause: unknown): ProcessCliFailure =>
|
||||
`Capture evidence is malformed (${describeValidationFailure(cause)}). Create new capture evidence, then try again.`,
|
||||
);
|
||||
|
||||
const readJson = async (path: string): Promise<unknown> => {
|
||||
const loaded = await readJsonFile(path);
|
||||
const readJson = async (
|
||||
path: string,
|
||||
operation: "capture_process_scenario" | "compare_process_captures",
|
||||
signal?: AbortSignal,
|
||||
): Promise<unknown> => {
|
||||
if (signal?.aborted) throw new AnalysisCancelledError(operation);
|
||||
const loaded = await readJsonFile(path, signal).catch((cause: unknown) => {
|
||||
if (
|
||||
signal?.aborted === true &&
|
||||
!(cause instanceof RegularFileCleanupFailure)
|
||||
)
|
||||
throw new AnalysisCancelledError(operation, { cause });
|
||||
throw cause;
|
||||
});
|
||||
if (signal?.aborted) throw new AnalysisCancelledError(operation);
|
||||
if (loaded.ok) return loaded.value;
|
||||
if (loaded.error._tag !== "EvidenceFileError") throw loaded.error;
|
||||
const detail = describeValidationFailure(loaded.error.cause);
|
||||
|
||||
@@ -40,12 +40,19 @@ export const registerProcessCommands = (
|
||||
.describe("Optional partial-order or finite-trace specification path"),
|
||||
}),
|
||||
run: ({ args }) =>
|
||||
logCliCommand(
|
||||
logger,
|
||||
"compare-process-captures",
|
||||
() =>
|
||||
compareProcessEvidenceFiles(args.left, args.right, args.traceSpec),
|
||||
isProcessCliFailure,
|
||||
withCommandCancellation((signal) =>
|
||||
logCliCommand(
|
||||
logger,
|
||||
"compare-process-captures",
|
||||
() =>
|
||||
compareProcessEvidenceFiles(
|
||||
args.left,
|
||||
args.right,
|
||||
args.traceSpec,
|
||||
signal,
|
||||
),
|
||||
isProcessCliFailure,
|
||||
),
|
||||
),
|
||||
});
|
||||
};
|
||||
|
||||
@@ -45,13 +45,15 @@ export class AnalysisProtocolError extends AnalysisError {
|
||||
/** Caller input failed provider-neutral application parsing. */
|
||||
export class AnalysisInputError extends AnalysisError {
|
||||
readonly _tag = "AnalysisInputError";
|
||||
override readonly userMessage: string | undefined;
|
||||
|
||||
constructor(
|
||||
readonly operation: string,
|
||||
options?: AnalysisErrorOptions,
|
||||
options?: AnalysisErrorOptions & { readonly userMessage?: string },
|
||||
readonly issues: readonly AnalysisInputIssue[] = [],
|
||||
) {
|
||||
super(`Invalid analysis input for ${operation}`, options);
|
||||
this.userMessage = options?.userMessage;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -148,6 +148,7 @@ export const analysisErrorCategory = (
|
||||
error instanceof EvidenceFileError &&
|
||||
(error.reason === "missing" ||
|
||||
error.reason === "not-file" ||
|
||||
error.reason === "wrong-kind" ||
|
||||
error.reason === "exists")
|
||||
)
|
||||
return "invalid_input";
|
||||
@@ -210,7 +211,10 @@ export const analysisErrorUserMessage = (error: AnalysisError): string => {
|
||||
if (error instanceof AnalysisArtifactChangedError)
|
||||
return "The selected artifact changed during acquisition; no stable snapshot was decoded.";
|
||||
if (error instanceof AnalysisInputError)
|
||||
return "Analysis input is invalid. Check the arguments and try again.";
|
||||
return (
|
||||
error.userMessage ??
|
||||
"Analysis input is invalid. Check the arguments and try again."
|
||||
);
|
||||
const hopperMessage = hopperErrorUserMessage(error);
|
||||
if (hopperMessage !== undefined) return hopperMessage;
|
||||
if (error.userMessage !== undefined) return error.userMessage;
|
||||
|
||||
@@ -5,6 +5,7 @@ import { ANALYSIS_SNAPSHOT_TARGET } from "./analysisSnapshot.fixture.js";
|
||||
import {
|
||||
createEvidenceBundle,
|
||||
createImmutableEvidenceBundle,
|
||||
describeEvidenceBundleFailure,
|
||||
evidenceBundleForTarget,
|
||||
parseEvidenceBundle,
|
||||
} from "./evidenceBundle.js";
|
||||
@@ -18,6 +19,24 @@ const provider = { id: "fixture", name: "Fixture", version: "1" };
|
||||
const targetDigest = "a".repeat(64);
|
||||
const foreignDigest = "b".repeat(64);
|
||||
|
||||
describe("evidence bundle failure classification", () => {
|
||||
it("treats only authenticated standalone Evidence as the wrong input kind", () => {
|
||||
const record = createEvidence(undefined, provider, {
|
||||
operation: "observe",
|
||||
parameters: {},
|
||||
result: { observed: true },
|
||||
});
|
||||
const single = describeEvidenceBundleFailure(record, new Error("bundle"));
|
||||
expect(single).toMatchObject({ kind: "single-record" });
|
||||
|
||||
const tampered = describeEvidenceBundleFailure(
|
||||
{ ...record, normalized_result: { observed: false } },
|
||||
new Error("bundle"),
|
||||
);
|
||||
expect(tampered).toMatchObject({ kind: "invalid-bundle" });
|
||||
});
|
||||
});
|
||||
|
||||
const makeUnknown = (
|
||||
question: string,
|
||||
scopeDigest: string,
|
||||
|
||||
@@ -208,16 +208,29 @@ const referencedEvidenceIds = (unknown: ResidualUnknown): readonly string[] => [
|
||||
* Name the bundle constraint that failed and how to recover. A single
|
||||
* Evidence record, such as one command result, is not a bundle.
|
||||
*/
|
||||
export type EvidenceBundleFailureDescription =
|
||||
| { readonly kind: "single-record"; readonly message: string }
|
||||
| { readonly kind: "invalid-bundle"; readonly message: string };
|
||||
|
||||
export const describeEvidenceBundleFailure = (
|
||||
input: unknown,
|
||||
cause: unknown,
|
||||
): string => {
|
||||
const record = evidenceSchema.safeParse(input);
|
||||
if (record.success)
|
||||
return `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record (${record.data.evidence_id}). Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`;
|
||||
return cause instanceof z.ZodError
|
||||
? `Evidence bundle does not match the bundle schema ${describeValidationFailure(cause)}. Supply an unmodified bundle written by export_evidence_bundle or rea evidence-export.`
|
||||
: `Evidence bundle validation failed: ${describeValidationFailure(cause)}. Recreate or re-export the bundle, then try again.`;
|
||||
): EvidenceBundleFailureDescription => {
|
||||
try {
|
||||
const record = parseEvidence(input);
|
||||
return {
|
||||
kind: "single-record",
|
||||
message: `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record (${record.evidence_id}). Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`,
|
||||
};
|
||||
} catch {
|
||||
return {
|
||||
kind: "invalid-bundle",
|
||||
message:
|
||||
cause instanceof z.ZodError
|
||||
? `Evidence bundle does not match the bundle schema ${describeValidationFailure(cause)}. Supply an unmodified bundle written by export_evidence_bundle or rea evidence-export.`
|
||||
: `Evidence bundle validation failed: ${describeValidationFailure(cause)}. Recreate or re-export the bundle, then try again.`,
|
||||
};
|
||||
}
|
||||
};
|
||||
|
||||
/** Locate the first schema issue, or keep a thrown constraint message. */
|
||||
|
||||
@@ -45,6 +45,7 @@ export class EvidenceReferenceError extends EvidenceIntegrityError {
|
||||
/** Evidence bundle filesystem access failed within the configured policy. */
|
||||
export class EvidenceFileError extends AnalysisError {
|
||||
readonly _tag = "EvidenceFileError";
|
||||
override readonly userMessage: string | undefined;
|
||||
|
||||
/** Caller-selected path that failed, resolved against the working directory. */
|
||||
readonly path: string | undefined;
|
||||
@@ -53,14 +54,22 @@ export class EvidenceFileError extends AnalysisError {
|
||||
|
||||
constructor(
|
||||
readonly operation: "read" | "write",
|
||||
readonly reason: "not-file" | "exists" | "invalid-json" | "missing" | "io",
|
||||
readonly reason:
|
||||
| "not-file"
|
||||
| "exists"
|
||||
| "wrong-kind"
|
||||
| "invalid-json"
|
||||
| "missing"
|
||||
| "io",
|
||||
options?: AnalysisErrorOptions & {
|
||||
readonly path?: string;
|
||||
readonly published?: PublishedEvidenceFile;
|
||||
readonly userMessage?: string;
|
||||
},
|
||||
) {
|
||||
super(`Evidence bundle ${operation} failed: ${reason}`, options);
|
||||
this.path = options?.path;
|
||||
this.published = options?.published;
|
||||
this.userMessage = options?.userMessage;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -67,81 +67,83 @@ describe("owned process-group cleanup discovery", () => {
|
||||
});
|
||||
|
||||
describe("opaque process neighbors during cleanup", () => {
|
||||
it("cleans verified run-owned groups and records a withheld unrelated neighbor", async () => {
|
||||
const processes = [
|
||||
{ pid: 100, parentPid: 1, processGroupId: 100, command: "capture" },
|
||||
{
|
||||
pid: 200,
|
||||
parentPid: 1,
|
||||
processGroupId: 200,
|
||||
command: "detached-child",
|
||||
},
|
||||
{
|
||||
pid: 900,
|
||||
parentPid: 1,
|
||||
processGroupId: 900,
|
||||
command: "/usr/bin/opaque-neighbor",
|
||||
},
|
||||
].map((process) => ({ ...process, state: "S" }));
|
||||
const signalGroup = vi.fn();
|
||||
const identities = new Map(
|
||||
processes.map(({ pid }) => [
|
||||
pid,
|
||||
{ state: "readable" as const, identity: `start-${String(pid)}` },
|
||||
]),
|
||||
);
|
||||
const adapter: ProcessOwnershipHost = {
|
||||
platform: "darwin",
|
||||
listProcesses: () => Promise.resolve(processes),
|
||||
environment: (pid) =>
|
||||
Promise.resolve({
|
||||
REA_PROCESS_RUN_ID: pid === 900 ? "unowned" : "run-token",
|
||||
}),
|
||||
processIdentities: () => Promise.resolve(identities),
|
||||
runTokens: (members) =>
|
||||
Promise.resolve(
|
||||
new Map(
|
||||
members.map(({ pid }) => [
|
||||
pid,
|
||||
pid === 900
|
||||
? {
|
||||
state: "unavailable" as const,
|
||||
reason: "platform_binary_environment_withheld",
|
||||
}
|
||||
: { state: "readable" as const, runId: "run-token" },
|
||||
]),
|
||||
),
|
||||
),
|
||||
signalGroup,
|
||||
};
|
||||
|
||||
const result = await cleanupOwnedProcessGroup(
|
||||
{
|
||||
...ownership,
|
||||
sweepTokenOwnedProcesses: true,
|
||||
captureBaseline: [],
|
||||
},
|
||||
adapter,
|
||||
);
|
||||
|
||||
expect(result).toMatchObject({
|
||||
cleaned: true,
|
||||
signaled: true,
|
||||
unverified: [
|
||||
{ pid: 900, diagnostic: "platform_binary_environment_withheld" },
|
||||
],
|
||||
});
|
||||
expect(signalGroup.mock.calls).toEqual([
|
||||
[100, "SIGKILL"],
|
||||
[200, "SIGKILL"],
|
||||
]);
|
||||
expect(signalGroup).not.toHaveBeenCalledWith(900, "SIGKILL");
|
||||
});
|
||||
|
||||
it.each([
|
||||
"environment_unavailable",
|
||||
"platform_binary_environment_withheld",
|
||||
"restricted_process_environment_withheld",
|
||||
])("fails closed for an unrelated candidate with %s", async (diagnostic) => {
|
||||
])(
|
||||
"cleans verified run-owned groups and records an unrelated %s neighbor",
|
||||
async (diagnostic) => {
|
||||
const processes = [
|
||||
{ pid: 100, parentPid: 1, processGroupId: 100, command: "capture" },
|
||||
{
|
||||
pid: 200,
|
||||
parentPid: 1,
|
||||
processGroupId: 200,
|
||||
command: "detached-child",
|
||||
},
|
||||
{
|
||||
pid: 900,
|
||||
parentPid: 1,
|
||||
processGroupId: 900,
|
||||
command: "/usr/bin/opaque-neighbor",
|
||||
},
|
||||
].map((process) => ({ ...process, state: "S" }));
|
||||
const signalGroup = vi.fn();
|
||||
const identities = new Map(
|
||||
processes.map(({ pid }) => [
|
||||
pid,
|
||||
{ state: "readable" as const, identity: `start-${String(pid)}` },
|
||||
]),
|
||||
);
|
||||
const adapter: ProcessOwnershipHost = {
|
||||
platform: "darwin",
|
||||
listProcesses: () => Promise.resolve(processes),
|
||||
environment: (pid) =>
|
||||
Promise.resolve({
|
||||
REA_PROCESS_RUN_ID: pid === 900 ? "unowned" : "run-token",
|
||||
}),
|
||||
processIdentities: () => Promise.resolve(identities),
|
||||
runTokens: (members) =>
|
||||
Promise.resolve(
|
||||
new Map(
|
||||
members.map(({ pid }) => [
|
||||
pid,
|
||||
pid === 900
|
||||
? {
|
||||
state: "unavailable" as const,
|
||||
reason: diagnostic,
|
||||
}
|
||||
: { state: "readable" as const, runId: "run-token" },
|
||||
]),
|
||||
),
|
||||
),
|
||||
signalGroup,
|
||||
};
|
||||
|
||||
const result = await cleanupOwnedProcessGroup(
|
||||
{
|
||||
...ownership,
|
||||
sweepTokenOwnedProcesses: true,
|
||||
captureBaseline: [],
|
||||
},
|
||||
adapter,
|
||||
);
|
||||
|
||||
expect(result).toMatchObject({
|
||||
cleaned: true,
|
||||
signaled: true,
|
||||
unverified: [{ pid: 900, diagnostic }],
|
||||
});
|
||||
expect(signalGroup.mock.calls).toEqual([
|
||||
[100, "SIGKILL"],
|
||||
[200, "SIGKILL"],
|
||||
]);
|
||||
expect(signalGroup).not.toHaveBeenCalledWith(900, "SIGKILL");
|
||||
},
|
||||
);
|
||||
|
||||
it("fails closed for an unrelated candidate with an ordinary unavailable environment", async () => {
|
||||
const diagnostic = "environment_unavailable";
|
||||
const processes = [
|
||||
{ pid: 100, parentPid: 1, processGroupId: 100, command: "capture" },
|
||||
{
|
||||
@@ -207,75 +209,81 @@ describe("opaque process neighbors during cleanup", () => {
|
||||
});
|
||||
|
||||
describe("related sweep candidates during cleanup", () => {
|
||||
it.each(["environment_unavailable", "platform_binary_environment_withheld"])(
|
||||
"fails closed for a related candidate with %s",
|
||||
async (diagnostic) => {
|
||||
const processes = [
|
||||
{
|
||||
pid: 100,
|
||||
parentPid: 1,
|
||||
processGroupId: 100,
|
||||
state: "S",
|
||||
command: "capture",
|
||||
},
|
||||
{
|
||||
pid: 101,
|
||||
parentPid: 100,
|
||||
processGroupId: 100,
|
||||
state: "S",
|
||||
uid: process.getuid?.() === 0 ? 1 : 0,
|
||||
command: "ready-hang",
|
||||
},
|
||||
];
|
||||
const signalGroup = vi.fn();
|
||||
const identities = new Map(
|
||||
processes.map(({ pid }) => [
|
||||
pid,
|
||||
{ state: "readable" as const, identity: `start-${String(pid)}` },
|
||||
]),
|
||||
);
|
||||
const adapter: ProcessOwnershipHost = {
|
||||
listProcesses: () => Promise.resolve(processes),
|
||||
environment: (pid) =>
|
||||
pid === 100
|
||||
? Promise.resolve({ REA_PROCESS_RUN_ID: "run-token" })
|
||||
: Promise.reject(new Error("EACCES: permission denied")),
|
||||
processIdentities: () => Promise.resolve(identities),
|
||||
runTokens: (members) =>
|
||||
Promise.resolve(
|
||||
new Map(
|
||||
members.map(({ pid }) => [
|
||||
pid,
|
||||
pid === 100
|
||||
? { state: "readable" as const, runId: "run-token" }
|
||||
: {
|
||||
state: "unavailable" as const,
|
||||
reason: diagnostic,
|
||||
},
|
||||
]),
|
||||
),
|
||||
it.each([
|
||||
"environment_unavailable",
|
||||
"platform_binary_environment_withheld",
|
||||
"restricted_process_environment_withheld",
|
||||
])("fails closed for a related candidate with %s", async (diagnostic) => {
|
||||
const processes = [
|
||||
{
|
||||
pid: 100,
|
||||
parentPid: 1,
|
||||
processGroupId: 100,
|
||||
state: "S",
|
||||
command: "capture",
|
||||
},
|
||||
{
|
||||
pid: 101,
|
||||
parentPid: 100,
|
||||
processGroupId: 100,
|
||||
state: "S",
|
||||
uid:
|
||||
diagnostic === "restricted_process_environment_withheld"
|
||||
? (process.getuid?.() ?? 0)
|
||||
: process.getuid?.() === 0
|
||||
? 1
|
||||
: 0,
|
||||
command: "ready-hang",
|
||||
},
|
||||
];
|
||||
const signalGroup = vi.fn();
|
||||
const identities = new Map(
|
||||
processes.map(({ pid }) => [
|
||||
pid,
|
||||
{ state: "readable" as const, identity: `start-${String(pid)}` },
|
||||
]),
|
||||
);
|
||||
const adapter: ProcessOwnershipHost = {
|
||||
listProcesses: () => Promise.resolve(processes),
|
||||
environment: (pid) =>
|
||||
pid === 100
|
||||
? Promise.resolve({ REA_PROCESS_RUN_ID: "run-token" })
|
||||
: Promise.reject(new Error("EACCES: permission denied")),
|
||||
processIdentities: () => Promise.resolve(identities),
|
||||
runTokens: (members) =>
|
||||
Promise.resolve(
|
||||
new Map(
|
||||
members.map(({ pid }) => [
|
||||
pid,
|
||||
pid === 100
|
||||
? { state: "readable" as const, runId: "run-token" }
|
||||
: {
|
||||
state: "unavailable" as const,
|
||||
reason: diagnostic,
|
||||
},
|
||||
]),
|
||||
),
|
||||
signalGroup,
|
||||
};
|
||||
|
||||
const result = await cleanupOwnedProcessGroup(
|
||||
{
|
||||
...ownership,
|
||||
sweepTokenOwnedProcesses: true,
|
||||
captureBaseline: [],
|
||||
},
|
||||
adapter,
|
||||
);
|
||||
|
||||
expect(result).toMatchObject({
|
||||
cleaned: false,
|
||||
reason: expect.stringContaining(
|
||||
"process ownership token could not be read",
|
||||
),
|
||||
});
|
||||
expect(signalGroup).not.toHaveBeenCalled();
|
||||
},
|
||||
);
|
||||
signalGroup,
|
||||
};
|
||||
|
||||
const result = await cleanupOwnedProcessGroup(
|
||||
{
|
||||
...ownership,
|
||||
sweepTokenOwnedProcesses: true,
|
||||
captureBaseline: [],
|
||||
},
|
||||
adapter,
|
||||
);
|
||||
|
||||
expect(result).toMatchObject({
|
||||
cleaned: false,
|
||||
reason: expect.stringContaining(
|
||||
"process ownership token could not be read",
|
||||
),
|
||||
});
|
||||
expect(signalGroup).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe("sampled detached process groups during cleanup", () => {
|
||||
|
||||
@@ -805,17 +805,21 @@ const TOKEN_READ_RETRY_DELAY_MS = 40;
|
||||
/** Darwin reports this when the kernel withholds a platform binary's environment. */
|
||||
const PLATFORM_BINARY_ENVIRONMENT_WITHHELD =
|
||||
"platform_binary_environment_withheld";
|
||||
/** Darwin reports this when the kernel withholds a restricted process environment. */
|
||||
const RESTRICTED_PROCESS_ENVIRONMENT_WITHHELD =
|
||||
"restricted_process_environment_withheld";
|
||||
|
||||
const currentProcessUid = (): number | undefined =>
|
||||
typeof process.getuid === "function" ? process.getuid() : undefined;
|
||||
|
||||
/**
|
||||
* Whether the operating system provably withheld this candidate's run token:
|
||||
* current macOS omits the environment of Apple platform binaries from
|
||||
* KERN_PROCARGS2 and fails with EINVAL for processes owned by another
|
||||
* account, and neither class can be token-verified by any caller. Such a
|
||||
* candidate is recorded as unverified instead of failing an otherwise clean
|
||||
* capture; every other unreadable candidate stays fail-closed.
|
||||
* current macOS omits the environment of Apple platform binaries and
|
||||
* CS_RESTRICT processes from KERN_PROCARGS2, and fails with EINVAL for
|
||||
* processes owned by another account. These classes cannot be token-verified
|
||||
* by this caller. An unrelated candidate is recorded as unverified instead
|
||||
* of failing an otherwise clean capture; every related or otherwise
|
||||
* unreadable candidate stays fail-closed.
|
||||
*/
|
||||
const environmentWithheldFromInspection = (
|
||||
entry: ProcessTableEntry,
|
||||
@@ -824,7 +828,10 @@ const environmentWithheldFromInspection = (
|
||||
const uid = currentProcessUid();
|
||||
if (uid !== undefined && entry.uid !== undefined && entry.uid !== uid)
|
||||
return true;
|
||||
return diagnostic === PLATFORM_BINARY_ENVIRONMENT_WITHHELD;
|
||||
return (
|
||||
diagnostic === PLATFORM_BINARY_ENVIRONMENT_WITHHELD ||
|
||||
diagnostic === RESTRICTED_PROCESS_ENVIRONMENT_WITHHELD
|
||||
);
|
||||
};
|
||||
|
||||
const scanTokenOwnedProcesses = async (
|
||||
|
||||
@@ -12,12 +12,14 @@ import { BUNDLE_COMPARISON_PROVIDER } from "../application/InvestigationProvider
|
||||
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
|
||||
import { withAdmittedAnalysis } from "./analysisAdmission.js";
|
||||
import { runAdmittedToolOperation } from "./admittedToolOperation.js";
|
||||
import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
|
||||
|
||||
/** Register canonical Evidence bundle comparison. */
|
||||
export const registerBundleComparisonTool = (
|
||||
server: EvidenceMcpServer,
|
||||
session: BinarySessionPort,
|
||||
contract: ReturnType<typeof toolContract<"compare_bundles">>,
|
||||
resources: ArtifactResourceScope,
|
||||
): void => {
|
||||
const admission = withAdmittedAnalysis({ kind: "session", session });
|
||||
server.registerTool(
|
||||
@@ -31,8 +33,16 @@ export const registerBundleComparisonTool = (
|
||||
context.mcpReq.signal,
|
||||
async () => {
|
||||
const [left, right] = await Promise.all([
|
||||
readEvidenceBundle(input.left_bundle_path, context.mcpReq.signal),
|
||||
readEvidenceBundle(input.right_bundle_path, context.mcpReq.signal),
|
||||
readEvidenceBundle(
|
||||
input.left_bundle_path,
|
||||
context.mcpReq.signal,
|
||||
resources,
|
||||
),
|
||||
readEvidenceBundle(
|
||||
input.right_bundle_path,
|
||||
context.mcpReq.signal,
|
||||
resources,
|
||||
),
|
||||
]);
|
||||
if (!left.ok) return server.delivery.toCallToolResult(left, contract);
|
||||
if (!right.ok)
|
||||
|
||||
@@ -89,6 +89,7 @@ const registerSnapshotEvidenceTool = ({
|
||||
const registerImportEvidenceTool = ({
|
||||
server,
|
||||
session,
|
||||
resources,
|
||||
importContract,
|
||||
}: EvidenceToolRegistration): void => {
|
||||
server.registerTool(
|
||||
@@ -97,7 +98,7 @@ const registerImportEvidenceTool = ({
|
||||
async (input, context) => {
|
||||
const path = input.path;
|
||||
const signal = context.mcpReq.signal;
|
||||
const loaded = await readImmutableEvidenceBundle(path, signal);
|
||||
const loaded = await readImmutableEvidenceBundle(path, signal, resources);
|
||||
if (!loaded.ok)
|
||||
return server.delivery.toCallToolResult(loaded, importContract);
|
||||
const retainedUnknownRevisions = new Set(
|
||||
|
||||
@@ -160,6 +160,7 @@ export interface LifecycleToolRegistration {
|
||||
|
||||
const registerLifecycleTools = (
|
||||
registration: LifecycleToolRegistration,
|
||||
artifactResources: ArtifactResourceScope,
|
||||
): void => {
|
||||
const {
|
||||
server,
|
||||
@@ -169,7 +170,7 @@ const registerLifecycleTools = (
|
||||
availabilityPolicy,
|
||||
androidAnalysisAvailability,
|
||||
} = registration;
|
||||
registerOpenLifecycleTool(registration);
|
||||
registerOpenLifecycleTool(registration, artifactResources);
|
||||
registerCloseLifecycleTool(registration);
|
||||
registerSessionStatusTool({
|
||||
server,
|
||||
@@ -181,12 +182,10 @@ const registerLifecycleTools = (
|
||||
});
|
||||
};
|
||||
|
||||
const registerOpenLifecycleTool = ({
|
||||
server,
|
||||
session,
|
||||
logger,
|
||||
openContract,
|
||||
}: LifecycleToolRegistration): void => {
|
||||
const registerOpenLifecycleTool = (
|
||||
{ server, session, logger, openContract }: LifecycleToolRegistration,
|
||||
artifactResources: ArtifactResourceScope,
|
||||
): void => {
|
||||
server.registerTool(
|
||||
openContract.name,
|
||||
toolRegistrationOptions(openContract),
|
||||
@@ -196,6 +195,7 @@ const registerOpenLifecycleTool = ({
|
||||
const loaded = await readAnalysisSnapshot(
|
||||
input.snapshot_path,
|
||||
context.mcpReq.signal,
|
||||
artifactResources,
|
||||
);
|
||||
if (!loaded.ok)
|
||||
return server.delivery.toCallToolResult(loaded, openContract);
|
||||
@@ -302,42 +302,45 @@ export const registerSessionTools = (
|
||||
const compareBundlesContract = toolContract("compare_bundles");
|
||||
const snapshotContract = toolContract("get_evidence_bundle");
|
||||
const processResources = new ProcessCaptureResourceScope();
|
||||
registerLifecycleTools({
|
||||
server,
|
||||
session,
|
||||
logger,
|
||||
openContract,
|
||||
closeContract,
|
||||
statusContract,
|
||||
startedAt: options.startedAt ?? new Date().toISOString(),
|
||||
availabilityPolicy: sessionAvailabilityPolicy(
|
||||
options.availabilityPolicy,
|
||||
{},
|
||||
),
|
||||
androidAnalysisAvailability:
|
||||
options.androidAnalysisAvailability ?? missingAndroidAvailability,
|
||||
closeProcessResources: async () => {
|
||||
try {
|
||||
await processResources.retryCleanup();
|
||||
return ok(null);
|
||||
} catch (cause: unknown) {
|
||||
return err(
|
||||
new ProcessCaptureError(
|
||||
"process capture cleanup remains incomplete",
|
||||
{
|
||||
cause,
|
||||
reason: "cleanup_incomplete",
|
||||
cleanupResources: ["process_capture_resources"],
|
||||
executionFailure:
|
||||
cause instanceof Error
|
||||
? cause.message || cause.name
|
||||
: String(cause),
|
||||
},
|
||||
),
|
||||
);
|
||||
}
|
||||
registerLifecycleTools(
|
||||
{
|
||||
server,
|
||||
session,
|
||||
logger,
|
||||
openContract,
|
||||
closeContract,
|
||||
statusContract,
|
||||
startedAt: options.startedAt ?? new Date().toISOString(),
|
||||
availabilityPolicy: sessionAvailabilityPolicy(
|
||||
options.availabilityPolicy,
|
||||
{},
|
||||
),
|
||||
androidAnalysisAvailability:
|
||||
options.androidAnalysisAvailability ?? missingAndroidAvailability,
|
||||
closeProcessResources: async () => {
|
||||
try {
|
||||
await processResources.retryCleanup();
|
||||
return ok(null);
|
||||
} catch (cause: unknown) {
|
||||
return err(
|
||||
new ProcessCaptureError(
|
||||
"process capture cleanup remains incomplete",
|
||||
{
|
||||
cause,
|
||||
reason: "cleanup_incomplete",
|
||||
cleanupResources: ["process_capture_resources"],
|
||||
executionFailure:
|
||||
cause instanceof Error
|
||||
? cause.message || cause.name
|
||||
: String(cause),
|
||||
},
|
||||
),
|
||||
);
|
||||
}
|
||||
},
|
||||
},
|
||||
});
|
||||
options.artifactResources,
|
||||
);
|
||||
registerEvidenceTools({
|
||||
server,
|
||||
session,
|
||||
@@ -381,7 +384,12 @@ export const registerSessionTools = (
|
||||
registerProcessComparisonTool(server, session, compareContract);
|
||||
registerArtifactComparisonTool(server, session, compareArtifactsContract);
|
||||
registerFunctionComparisonTool(server, session, compareFunctionsContract);
|
||||
registerBundleComparisonTool(server, session, compareBundlesContract);
|
||||
registerBundleComparisonTool(
|
||||
server,
|
||||
session,
|
||||
compareBundlesContract,
|
||||
options.artifactResources,
|
||||
);
|
||||
registerInvestigationTools(server, session);
|
||||
registerUnknownTools({ server, session });
|
||||
registerContextTools(server, session);
|
||||
|
||||
@@ -66,6 +66,27 @@ cliTest(
|
||||
},
|
||||
);
|
||||
|
||||
cliTest(
|
||||
"reports a standalone Evidence record as the wrong input file kind",
|
||||
async ({ cli }) => {
|
||||
const root = await createTestTempDirectory("rea-evidence-record-input-");
|
||||
const path = join(root, "record.json");
|
||||
const record = revisionBundle().records[0];
|
||||
if (record === undefined) throw new Error("Missing fixture Evidence");
|
||||
await writeFile(path, JSON.stringify(record));
|
||||
const result = await cli.run({
|
||||
arguments: ["evidence-import", path, "--json"],
|
||||
});
|
||||
expect(result.exitCode).toBe(1);
|
||||
expect(result.json).toMatchObject({
|
||||
code: "invalid_request",
|
||||
category: "invalid_input",
|
||||
details: { path },
|
||||
message: expect.stringContaining("this JSON is one Evidence record"),
|
||||
});
|
||||
},
|
||||
);
|
||||
|
||||
cliTest(
|
||||
"rejects altered Evidence and incomplete unknown history before reporting counts",
|
||||
async ({ cli }) => {
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
import { readFile, stat, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { describe, expect, it, onTestFinished, vi } from "vitest";
|
||||
|
||||
import { withArtifactResourceScope } from "../../fixtures/artifactInventory.js";
|
||||
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
|
||||
import { holdFirstFileRead } from "../../support/holdFirstFileRead.js";
|
||||
|
||||
import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js";
|
||||
import {
|
||||
@@ -29,6 +30,8 @@ import { createEvidence } from "../../../src/domain/evidence.js";
|
||||
import { createEvidenceBundle } from "../../../src/domain/evidenceBundle.js";
|
||||
import { readJsonObjectFile } from "../../../src/application/JsonInputFile.js";
|
||||
import { RegularFileChangedError } from "../../../src/filesystem/RegularFile.js";
|
||||
import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js";
|
||||
import { RegularFileCleanupFailure } from "../../../src/application/RegularFileRead.js";
|
||||
|
||||
const snapshotFixture = (): AnalysisSnapshot => {
|
||||
const target = snapshotTarget(TARGET);
|
||||
@@ -227,20 +230,67 @@ describe("analysis snapshot member decoding", () => {
|
||||
`${" ".repeat(9 * 1024 * 1024)}${JSON.stringify(snapshot)}`,
|
||||
);
|
||||
const controller = new AbortController();
|
||||
const reads = await holdFirstFileRead(path);
|
||||
onTestFinished(() => {
|
||||
controller.abort();
|
||||
reads.release();
|
||||
});
|
||||
const pending = readAnalysisSnapshot(path, controller.signal);
|
||||
const timer = setTimeout(() => controller.abort(), 1);
|
||||
await reads.firstRead;
|
||||
controller.abort();
|
||||
reads.release();
|
||||
try {
|
||||
expect(await pending).toMatchObject({
|
||||
ok: false,
|
||||
error: { _tag: "AnalysisCancelledError" },
|
||||
});
|
||||
expect(reads.readCount).toBe(1);
|
||||
} finally {
|
||||
clearTimeout(timer);
|
||||
vi.restoreAllMocks();
|
||||
}
|
||||
const loaded = await readAnalysisSnapshot(path);
|
||||
if (!loaded.ok) throw loaded.error;
|
||||
expect(loaded.value).toEqual(snapshot);
|
||||
});
|
||||
});
|
||||
|
||||
describe("analysis snapshot file ownership", () => {
|
||||
it.each([false, true])(
|
||||
"retains the file owner when snapshot close fails (cancelled: %s)",
|
||||
async (cancelDuringClose) => {
|
||||
const directory = await createTestTempDirectory("rea-snapshot-cleanup-");
|
||||
const path = join(directory, "snapshot.json");
|
||||
await writeFile(path, JSON.stringify(snapshotFixture()));
|
||||
const controller = new AbortController();
|
||||
const cleanupCause = new Error("injected snapshot file close failure");
|
||||
const close = vi
|
||||
.spyOn(OwnedFileHandle.prototype, "close")
|
||||
.mockImplementationOnce(async () => {
|
||||
if (cancelDuringClose) controller.abort();
|
||||
throw cleanupCause;
|
||||
});
|
||||
let failure: unknown;
|
||||
try {
|
||||
try {
|
||||
await readAnalysisSnapshot(
|
||||
path,
|
||||
cancelDuringClose ? controller.signal : undefined,
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
failure = cause;
|
||||
}
|
||||
expect(failure).toBeInstanceOf(RegularFileCleanupFailure);
|
||||
if (!(failure instanceof RegularFileCleanupFailure))
|
||||
throw new Error("Expected the retained snapshot file handle owner");
|
||||
expect(failure.cleanupCause).toBe(cleanupCause);
|
||||
expect(failure.owner.handle.fd).toBeGreaterThanOrEqual(0);
|
||||
} finally {
|
||||
close.mockRestore();
|
||||
if (failure instanceof RegularFileCleanupFailure)
|
||||
await failure.owner.close();
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
it("rejects changed bytes between scans on the same descriptor", async () => {
|
||||
const directory = await createTestTempDirectory("rea-snapshot-changed-");
|
||||
|
||||
@@ -434,21 +434,8 @@ describe("evidence bundle filesystem adapter", () => {
|
||||
},
|
||||
);
|
||||
|
||||
it("names the failed bundle constraint for a single record or schema mismatch", async () => {
|
||||
it("names schema mismatches that prevent bundle parsing", async () => {
|
||||
const directory = await createTestTempDirectory("rea-evidence-");
|
||||
const record = bundle().records[0];
|
||||
const single = join(directory, "record.json");
|
||||
await writeFile(single, JSON.stringify(record));
|
||||
expect(await readEvidenceBundle(single)).toMatchObject({
|
||||
ok: false,
|
||||
error: {
|
||||
_tag: "EvidenceIntegrityError",
|
||||
userMessage: expect.stringContaining(
|
||||
`this JSON is one Evidence record (${String(record?.evidence_id)})`,
|
||||
),
|
||||
},
|
||||
});
|
||||
|
||||
const partial = join(directory, "partial.json");
|
||||
await writeFile(partial, JSON.stringify({ evidence_id: "typo" }));
|
||||
const rejected = await readEvidenceBundle(partial);
|
||||
@@ -477,3 +464,38 @@ describe("evidence bundle filesystem adapter", () => {
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("standalone Evidence bundle inputs", () => {
|
||||
it("classifies a record only after authenticating it", async () => {
|
||||
const directory = await createTestTempDirectory("rea-evidence-");
|
||||
const record = bundle().records[0];
|
||||
const single = join(directory, "record.json");
|
||||
await writeFile(single, JSON.stringify(record));
|
||||
expect(await readEvidenceBundle(single)).toMatchObject({
|
||||
ok: false,
|
||||
error: {
|
||||
_tag: "EvidenceFileError",
|
||||
reason: "wrong-kind",
|
||||
path: single,
|
||||
userMessage: expect.stringContaining(
|
||||
`this JSON is one Evidence record (${String(record?.evidence_id)})`,
|
||||
),
|
||||
},
|
||||
});
|
||||
|
||||
const tamperedRecord = join(directory, "tampered-record.json");
|
||||
await writeFile(
|
||||
tamperedRecord,
|
||||
JSON.stringify({ ...record, normalized_result: "changed" }),
|
||||
);
|
||||
expect(await readEvidenceBundle(tamperedRecord)).toMatchObject({
|
||||
ok: false,
|
||||
error: {
|
||||
_tag: "EvidenceIntegrityError",
|
||||
userMessage: expect.stringContaining(
|
||||
"does not match the bundle schema",
|
||||
),
|
||||
},
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -0,0 +1,75 @@
|
||||
import { writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
|
||||
import { expect, it, vi } from "vitest";
|
||||
|
||||
import { ArtifactResourceScope } from "../../../src/artifacts/ArtifactResourceScope.js";
|
||||
import { readJsonFile } from "../../../src/application/JsonFiles.js";
|
||||
import { RegularFileCleanupFailure } from "../../../src/application/RegularFileRead.js";
|
||||
import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js";
|
||||
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
|
||||
|
||||
it("retains and retries a JSON file owner after a persistent close failure", async () => {
|
||||
const root = await createTestTempDirectory("rea-json-file-owner-");
|
||||
const path = join(root, "input.json");
|
||||
await writeFile(path, '{"value":"retained"}');
|
||||
const resources = new ArtifactResourceScope();
|
||||
const closeFailure = new Error("injected persistent close failure");
|
||||
let attempts = 0;
|
||||
const close = vi
|
||||
.spyOn(OwnedFileHandle.prototype, "close")
|
||||
.mockImplementation(async () => {
|
||||
attempts += 1;
|
||||
throw closeFailure;
|
||||
});
|
||||
let failure: unknown;
|
||||
try {
|
||||
try {
|
||||
await readJsonFile(path, undefined, resources);
|
||||
} catch (cause: unknown) {
|
||||
failure = cause;
|
||||
}
|
||||
expect(failure).toBeInstanceOf(RegularFileCleanupFailure);
|
||||
if (!(failure instanceof RegularFileCleanupFailure))
|
||||
throw new Error("Expected the failed file owner to remain visible");
|
||||
expect(failure.cleanupCause).toBe(closeFailure);
|
||||
expect(failure.outcome).toMatchObject({
|
||||
kind: "completed",
|
||||
value: { ok: true, value: { value: "retained" } },
|
||||
});
|
||||
expect(failure.owner.handle.fd).toBeGreaterThanOrEqual(0);
|
||||
expect(attempts).toBe(2);
|
||||
} finally {
|
||||
close.mockRestore();
|
||||
await resources.close();
|
||||
}
|
||||
if (!(failure instanceof RegularFileCleanupFailure))
|
||||
throw new Error("Expected the retained file owner");
|
||||
expect(failure.owner.handle.fd).toBe(-1);
|
||||
});
|
||||
|
||||
it("returns parsed JSON when a failed file close is recovered by the resource scope", async () => {
|
||||
const root = await createTestTempDirectory("rea-json-file-close-retry-");
|
||||
const path = join(root, "input.json");
|
||||
await writeFile(path, '{"value":"retained"}');
|
||||
const resources = new ArtifactResourceScope();
|
||||
const closeFailure = new Error("injected transient close failure");
|
||||
const originalClose = OwnedFileHandle.prototype.close;
|
||||
let attempts = 0;
|
||||
const close = vi
|
||||
.spyOn(OwnedFileHandle.prototype, "close")
|
||||
.mockImplementation(async function (this: OwnedFileHandle) {
|
||||
attempts += 1;
|
||||
if (attempts === 1) throw closeFailure;
|
||||
await originalClose.call(this);
|
||||
});
|
||||
try {
|
||||
const parsed = await readJsonFile(path, undefined, resources);
|
||||
if (!parsed.ok) throw parsed.error;
|
||||
expect(parsed.value).toEqual({ value: "retained" });
|
||||
expect(attempts).toBe(2);
|
||||
} finally {
|
||||
close.mockRestore();
|
||||
await resources.close();
|
||||
}
|
||||
});
|
||||
@@ -1,15 +1,22 @@
|
||||
import { writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { describe, expect, it, onTestFinished, vi } from "vitest";
|
||||
import {
|
||||
captureProcessScenarioFile,
|
||||
compareProcessEvidenceFiles,
|
||||
projectProcessCliError,
|
||||
} from "../../../src/application/process/ProcessCli.js";
|
||||
import { JSON_BYTE_ORDER_MARK_MESSAGE } from "../../../src/application/Utf8JsonInput.js";
|
||||
import { createEvidence } from "../../../src/domain/evidence.js";
|
||||
import { PROCESS_PROVIDER } from "../../../src/domain/process/processEvidenceProvider.js";
|
||||
import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../../../src/domain/process/processCaptureExample.js";
|
||||
import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js";
|
||||
import { RegularFileCleanupFailure } from "../../../src/application/RegularFileRead.js";
|
||||
|
||||
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
|
||||
import { holdFirstFileRead } from "../../support/holdFirstFileRead.js";
|
||||
|
||||
describe("process CLI input diagnostics", () => {
|
||||
describe("process CLI error projection", () => {
|
||||
it("preserves local diagnostics for unexpected process failures", () => {
|
||||
const projected = projectProcessCliError(
|
||||
new Error("SECRET internal failure /private/path"),
|
||||
@@ -22,7 +29,116 @@ describe("process CLI input diagnostics", () => {
|
||||
});
|
||||
expect(JSON.stringify(projected)).not.toContain("stack");
|
||||
});
|
||||
});
|
||||
|
||||
describe("process CLI file cancellation", () => {
|
||||
it("projects pre-aborted file reads as cancellation", async () => {
|
||||
const root = await createTestTempDirectory("rea-process-cli-cancel-");
|
||||
const controller = new AbortController();
|
||||
controller.abort();
|
||||
expect(
|
||||
await captureProcessScenarioFile(
|
||||
join(root, "missing-scenario.json"),
|
||||
process.env,
|
||||
controller.signal,
|
||||
),
|
||||
).toMatchObject({
|
||||
error: "Process command failed",
|
||||
code: "cancelled",
|
||||
category: "cancelled",
|
||||
details: { operation: "capture_process_scenario" },
|
||||
});
|
||||
expect(
|
||||
await compareProcessEvidenceFiles(
|
||||
join(root, "missing-left.json"),
|
||||
join(root, "missing-right.json"),
|
||||
join(root, "missing-trace.json"),
|
||||
controller.signal,
|
||||
),
|
||||
).toMatchObject({
|
||||
code: "cancelled",
|
||||
category: "cancelled",
|
||||
details: { operation: "compare_process_captures" },
|
||||
});
|
||||
});
|
||||
|
||||
it.each([
|
||||
{ workflow: "capture", input: "scenario" },
|
||||
{ workflow: "compare", input: "left" },
|
||||
{ workflow: "compare", input: "right" },
|
||||
{ workflow: "compare", input: "trace specification" },
|
||||
] as const)(
|
||||
"stops streamed $workflow $input reads after cancellation",
|
||||
async ({ workflow, input }) => {
|
||||
const root = await createTestTempDirectory("rea-process-cli-stream-");
|
||||
const paths = {
|
||||
scenario: join(root, "scenario.json"),
|
||||
left: join(root, "left.json"),
|
||||
right: join(root, "right.json"),
|
||||
trace: join(root, "trace.json"),
|
||||
};
|
||||
const evidence = JSON.stringify(processCaptureEvidence());
|
||||
const scenario = JSON.stringify({
|
||||
executable: process.execPath,
|
||||
arguments: [],
|
||||
});
|
||||
const traceSpecification = JSON.stringify(validTraceSpecification());
|
||||
const contentsByInput = {
|
||||
scenario: input === "scenario" ? stream(scenario) : scenario,
|
||||
left: input === "left" ? stream(evidence) : evidence,
|
||||
right: input === "right" ? stream(evidence) : evidence,
|
||||
trace:
|
||||
input === "trace specification"
|
||||
? stream(traceSpecification)
|
||||
: traceSpecification,
|
||||
};
|
||||
await Promise.all([
|
||||
writeFile(paths.scenario, contentsByInput.scenario),
|
||||
writeFile(paths.left, contentsByInput.left),
|
||||
writeFile(paths.right, contentsByInput.right),
|
||||
writeFile(paths.trace, contentsByInput.trace),
|
||||
]);
|
||||
const targetPath =
|
||||
paths[input === "trace specification" ? "trace" : input];
|
||||
const contents =
|
||||
contentsByInput[input === "trace specification" ? "trace" : input];
|
||||
const reader = await holdFirstFileRead(targetPath);
|
||||
onTestFinished(reader.release);
|
||||
const controller = new AbortController();
|
||||
try {
|
||||
const pending =
|
||||
workflow === "capture"
|
||||
? captureProcessScenarioFile(
|
||||
paths.scenario,
|
||||
process.env,
|
||||
controller.signal,
|
||||
)
|
||||
: compareProcessEvidenceFiles(
|
||||
paths.left,
|
||||
paths.right,
|
||||
paths.trace,
|
||||
controller.signal,
|
||||
);
|
||||
await reader.firstRead;
|
||||
controller.abort();
|
||||
reader.release();
|
||||
expect(await pending).toMatchObject({
|
||||
error: "Process command failed",
|
||||
code: "cancelled",
|
||||
category: "cancelled",
|
||||
});
|
||||
expect(reader.readCount).toBe(1);
|
||||
expect(reader.totalReadBytes).toBeLessThan(contents.length);
|
||||
} finally {
|
||||
controller.abort();
|
||||
reader.release();
|
||||
vi.restoreAllMocks();
|
||||
}
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
describe("process CLI input diagnostics", () => {
|
||||
it("projects missing, malformed JSON, and invalid scenario files", async () => {
|
||||
const root = await createTestTempDirectory("rea-process-cli-diagnostics-");
|
||||
const malformed = join(root, "malformed.json");
|
||||
@@ -78,6 +194,44 @@ describe("process CLI input diagnostics", () => {
|
||||
});
|
||||
});
|
||||
|
||||
it.each([false, true])(
|
||||
"preserves the open-file owner when close fails (cancelled: %s)",
|
||||
async (cancelDuringClose) => {
|
||||
const root = await createTestTempDirectory("rea-process-cli-cleanup-");
|
||||
const path = join(root, "scenario.json");
|
||||
await writeFile(path, JSON.stringify({ executable: process.execPath }));
|
||||
const controller = new AbortController();
|
||||
const cleanupCause = new Error("injected file close failure");
|
||||
const close = vi
|
||||
.spyOn(OwnedFileHandle.prototype, "close")
|
||||
.mockImplementationOnce(async () => {
|
||||
if (cancelDuringClose) controller.abort();
|
||||
throw cleanupCause;
|
||||
});
|
||||
let failure: unknown;
|
||||
try {
|
||||
try {
|
||||
await captureProcessScenarioFile(
|
||||
path,
|
||||
process.env,
|
||||
cancelDuringClose ? controller.signal : undefined,
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
failure = cause;
|
||||
}
|
||||
expect(failure).toBeInstanceOf(RegularFileCleanupFailure);
|
||||
if (!(failure instanceof RegularFileCleanupFailure))
|
||||
throw new Error("Expected the retained file handle owner");
|
||||
expect(failure.cleanupCause).toBe(cleanupCause);
|
||||
expect(failure.owner.handle.fd).toBeGreaterThanOrEqual(0);
|
||||
} finally {
|
||||
close.mockRestore();
|
||||
if (failure instanceof RegularFileCleanupFailure)
|
||||
await failure.owner.close();
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
it("names a leading byte-order mark instead of quoting it as a token", async () => {
|
||||
const path = join(
|
||||
await createTestTempDirectory("rea-process-cli-diagnostics-"),
|
||||
@@ -91,3 +245,40 @@ describe("process CLI input diagnostics", () => {
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
const processCaptureEvidence = () =>
|
||||
createEvidence(undefined, PROCESS_PROVIDER, {
|
||||
predicateType: "rea.process-capture",
|
||||
operation: "capture_process_scenario",
|
||||
parameters: {},
|
||||
result: EMPTY_PROCESS_CAPTURE_EXAMPLE,
|
||||
confidence: "observed",
|
||||
authority: "controlled-replay",
|
||||
environment: {
|
||||
id: "fixture",
|
||||
platform: "fixture",
|
||||
architecture: "fixture",
|
||||
isolation: "process",
|
||||
},
|
||||
});
|
||||
|
||||
const stream = (json: string) => " ".repeat(8 * 1024 * 1024) + json;
|
||||
|
||||
const validTraceSpecification = () => ({
|
||||
events: [
|
||||
{
|
||||
id: "started",
|
||||
source: "lifecycle",
|
||||
exact: { state: "started" },
|
||||
},
|
||||
{
|
||||
id: "finished",
|
||||
source: "lifecycle",
|
||||
exact: { state: "finished" },
|
||||
},
|
||||
],
|
||||
language: {
|
||||
kind: "partial_order",
|
||||
happens_before: [{ before: "started", after: "finished" }],
|
||||
},
|
||||
});
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
|
||||
import { open, writeFile, type FileHandle } from "node:fs/promises";
|
||||
import { writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { expect, it, onTestFinished, vi } from "vitest";
|
||||
|
||||
@@ -13,6 +13,7 @@ import { createServer } from "../../../src/server/createServer.js";
|
||||
import { ToolResultDelivery } from "../../../src/server/toolResult.js";
|
||||
import { createTestBinarySession } from "../../fixtures/binarySession.js";
|
||||
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
|
||||
import { holdFirstFileRead } from "../../support/holdFirstFileRead.js";
|
||||
|
||||
it("leaves the session unchanged after bundle comparison cancellation and permits a retry", async () => {
|
||||
const root = await createTestTempDirectory("rea-mcp-compare-cancel-");
|
||||
@@ -58,8 +59,10 @@ it("leaves the session unchanged after bundle comparison cancellation and permit
|
||||
version: "1",
|
||||
});
|
||||
const controller = new AbortController();
|
||||
let releaseRead: (() => void) | undefined;
|
||||
onTestFinished(async () => {
|
||||
controller.abort();
|
||||
releaseRead?.();
|
||||
vi.restoreAllMocks();
|
||||
await client.close();
|
||||
await server.close();
|
||||
@@ -70,8 +73,8 @@ it("leaves the session unchanged after bundle comparison cancellation and permit
|
||||
await server.connect(serverTransport);
|
||||
await client.connect(clientTransport);
|
||||
|
||||
const reader = await holdFirstRead(leftPath);
|
||||
onTestFinished(reader.release);
|
||||
const reader = await holdFirstFileRead(leftPath);
|
||||
releaseRead = reader.release;
|
||||
|
||||
let resolveDispatched: (() => void) | undefined;
|
||||
const dispatched = new Promise<void>((resolve) => {
|
||||
@@ -162,56 +165,3 @@ it("leaves the session unchanged after bundle comparison cancellation and permit
|
||||
]),
|
||||
);
|
||||
});
|
||||
|
||||
const holdFirstRead = async (path: string) => {
|
||||
// Hold the first streamed read after it reaches the operating system.
|
||||
const probe = await open(path, "r");
|
||||
const identity = await probe.stat();
|
||||
const fileHandlePrototype = Object.getPrototypeOf(probe) as {
|
||||
read(
|
||||
buffer: Buffer,
|
||||
offset: number,
|
||||
length: number,
|
||||
position: number | null,
|
||||
): Promise<{ readonly bytesRead: number; readonly buffer: Buffer }>;
|
||||
};
|
||||
await probe.close();
|
||||
let totalReadBytes = 0;
|
||||
let readCount = 0;
|
||||
let resolveFirstRead: (() => void) | undefined;
|
||||
const firstRead = new Promise<void>((resolve) => {
|
||||
resolveFirstRead = resolve;
|
||||
});
|
||||
let releaseRead: (() => void) | undefined;
|
||||
const readGate = new Promise<void>((resolve) => {
|
||||
releaseRead = resolve;
|
||||
});
|
||||
const read = fileHandlePrototype.read;
|
||||
vi.spyOn(fileHandlePrototype, "read").mockImplementation(async function (
|
||||
this: FileHandle,
|
||||
...args: [Buffer, number, number, number | null]
|
||||
) {
|
||||
const current = await this.stat();
|
||||
const isTarget =
|
||||
current.dev === identity.dev && current.ino === identity.ino;
|
||||
const result = await read.call(this, ...args);
|
||||
if (!isTarget) return result;
|
||||
totalReadBytes += result.bytesRead;
|
||||
readCount += 1;
|
||||
if (readCount === 1) {
|
||||
resolveFirstRead?.();
|
||||
await readGate;
|
||||
}
|
||||
return result;
|
||||
});
|
||||
return {
|
||||
firstRead,
|
||||
release: () => releaseRead?.(),
|
||||
get readCount() {
|
||||
return readCount;
|
||||
},
|
||||
get totalReadBytes() {
|
||||
return totalReadBytes;
|
||||
},
|
||||
};
|
||||
};
|
||||
|
||||
@@ -134,7 +134,9 @@ describe("bundle comparison MCP integration", () => {
|
||||
expect(result.isError).toBe(true);
|
||||
expect(parseMcpToolError(result)).toMatchObject({
|
||||
error: {
|
||||
code: "evidence_integrity_mismatch",
|
||||
code: "invalid_request",
|
||||
category: "invalid_input",
|
||||
details: { path: recordPath },
|
||||
message: expect.stringContaining(
|
||||
`this JSON is one Evidence record (${record.evidence_id})`,
|
||||
),
|
||||
|
||||
@@ -7,6 +7,7 @@ import { createEvidence } from "../../../src/domain/evidence.js";
|
||||
import { createEvidenceBundle } from "../../../src/domain/evidenceBundle.js";
|
||||
import { createServer } from "../../../src/server/createServer.js";
|
||||
import { ToolResultDelivery } from "../../../src/server/toolResult.js";
|
||||
import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js";
|
||||
import { createTestBinarySession } from "../../fixtures/binarySession.js";
|
||||
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
|
||||
|
||||
@@ -137,3 +138,121 @@ it("keeps the complete session unchanged after SDK import cancellation and permi
|
||||
);
|
||||
await client.ping();
|
||||
});
|
||||
|
||||
it("retains a failed import close in the server scope through SDK error projection", async () => {
|
||||
const root = await createTestTempDirectory("rea-mcp-import-close-");
|
||||
const path = join(root, "bundle.json");
|
||||
const session = createTestBinarySession(() => {
|
||||
throw new Error("Evidence import must not start a binary provider");
|
||||
});
|
||||
const provider = { id: "fixture", name: "Fixture", version: "1" };
|
||||
const existing = createEvidence(undefined, provider, {
|
||||
operation: "existing_observation",
|
||||
parameters: {},
|
||||
result: { retained: true },
|
||||
});
|
||||
const imported = createEvidence(undefined, provider, {
|
||||
operation: "imported_observation",
|
||||
parameters: {},
|
||||
result: { retained: "close failure" },
|
||||
});
|
||||
const recorded = session.recordEvidence(existing);
|
||||
if (!recorded.ok) throw recorded.error;
|
||||
await writeFile(path, JSON.stringify(createEvidenceBundle([imported])));
|
||||
|
||||
let allowClose = false;
|
||||
let retainedOwner: OwnedFileHandle | undefined;
|
||||
const originalClose = OwnedFileHandle.prototype.close;
|
||||
const close = vi
|
||||
.spyOn(OwnedFileHandle.prototype, "close")
|
||||
.mockImplementation(async function (this: OwnedFileHandle) {
|
||||
retainedOwner ??= this;
|
||||
if (!allowClose) throw new Error("persistent file close failure");
|
||||
return originalClose.call(this);
|
||||
});
|
||||
|
||||
const server = createServer({ kind: "session", session });
|
||||
const client = new Client({
|
||||
name: "evidence-import-close-failure",
|
||||
version: "1",
|
||||
});
|
||||
onTestFinished(async () => {
|
||||
allowClose = true;
|
||||
close.mockRestore();
|
||||
await client.close();
|
||||
await server.close();
|
||||
await session.close();
|
||||
});
|
||||
const [clientTransport, serverTransport] =
|
||||
InMemoryTransport.createLinkedPair();
|
||||
await server.connect(serverTransport);
|
||||
await client.connect(clientTransport);
|
||||
const before = session.exportEvidenceBundle();
|
||||
|
||||
const result = await client.callTool({
|
||||
name: "import_evidence_bundle",
|
||||
arguments: { path },
|
||||
});
|
||||
expect(result.isError).toBe(true);
|
||||
expect(session.exportEvidenceBundle()).toEqual(before);
|
||||
expect(retainedOwner).toBeDefined();
|
||||
expect(retainedOwner?.handle.fd).toBeGreaterThanOrEqual(0);
|
||||
|
||||
await client.close();
|
||||
await expect(server.close()).rejects.toThrow("REA session cleanup failed");
|
||||
expect(retainedOwner?.handle.fd).toBeGreaterThanOrEqual(0);
|
||||
allowClose = true;
|
||||
close.mockRestore();
|
||||
await server.close();
|
||||
expect(retainedOwner?.handle.fd).toBe(-1);
|
||||
await session.close();
|
||||
});
|
||||
|
||||
it("retries a transient import close failure before admitting the bundle", async () => {
|
||||
const root = await createTestTempDirectory("rea-mcp-import-close-retry-");
|
||||
const path = join(root, "bundle.json");
|
||||
const session = createTestBinarySession(() => {
|
||||
throw new Error("Evidence import must not start a binary provider");
|
||||
});
|
||||
const imported = createEvidence(
|
||||
undefined,
|
||||
{ id: "fixture", name: "Fixture", version: "1" },
|
||||
{
|
||||
operation: "imported_observation",
|
||||
parameters: {},
|
||||
result: { retained: "retry succeeded" },
|
||||
},
|
||||
);
|
||||
await writeFile(path, JSON.stringify(createEvidenceBundle([imported])));
|
||||
|
||||
const originalClose = OwnedFileHandle.prototype.close;
|
||||
const close = vi
|
||||
.spyOn(OwnedFileHandle.prototype, "close")
|
||||
.mockImplementationOnce(async () => {
|
||||
throw new Error("one transient file close failure");
|
||||
});
|
||||
const server = createServer({ kind: "session", session });
|
||||
const client = new Client({
|
||||
name: "evidence-import-close-retry",
|
||||
version: "1",
|
||||
});
|
||||
onTestFinished(async () => {
|
||||
close.mockRestore();
|
||||
await client.close();
|
||||
await server.close();
|
||||
await session.close();
|
||||
});
|
||||
const [clientTransport, serverTransport] =
|
||||
InMemoryTransport.createLinkedPair();
|
||||
await server.connect(serverTransport);
|
||||
await client.connect(clientTransport);
|
||||
|
||||
const result = await client.callTool({
|
||||
name: "import_evidence_bundle",
|
||||
arguments: { path },
|
||||
});
|
||||
close.mockRestore();
|
||||
expect(result.isError).not.toBe(true);
|
||||
expect(session.exportEvidenceBundle().records).toContainEqual(imported);
|
||||
await client.ping();
|
||||
});
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
import { open, type FileHandle } from "node:fs/promises";
|
||||
import { vi } from "vitest";
|
||||
|
||||
/** Pause after one selected file chunk reaches the operating system. */
|
||||
export const holdFirstFileRead = async (path: string) => {
|
||||
const probe = await open(path, "r");
|
||||
const identity = await probe.stat();
|
||||
const fileHandlePrototype = Object.getPrototypeOf(probe) as {
|
||||
read(
|
||||
buffer: Buffer,
|
||||
offset: number,
|
||||
length: number,
|
||||
position: number | null,
|
||||
): Promise<{ readonly bytesRead: number; readonly buffer: Buffer }>;
|
||||
};
|
||||
await probe.close();
|
||||
let totalReadBytes = 0;
|
||||
let readCount = 0;
|
||||
let resolveFirstRead: (() => void) | undefined;
|
||||
const firstRead = new Promise<void>((resolve) => {
|
||||
resolveFirstRead = resolve;
|
||||
});
|
||||
let releaseRead: (() => void) | undefined;
|
||||
const readGate = new Promise<void>((resolve) => {
|
||||
releaseRead = resolve;
|
||||
});
|
||||
const read = fileHandlePrototype.read;
|
||||
vi.spyOn(fileHandlePrototype, "read").mockImplementation(async function (
|
||||
this: FileHandle,
|
||||
...args: [Buffer, number, number, number | null]
|
||||
) {
|
||||
const current = await this.stat();
|
||||
const isTarget =
|
||||
current.dev === identity.dev && current.ino === identity.ino;
|
||||
const result = await read.call(this, ...args);
|
||||
if (!isTarget) return result;
|
||||
totalReadBytes += result.bytesRead;
|
||||
readCount += 1;
|
||||
if (readCount === 1) {
|
||||
resolveFirstRead?.();
|
||||
await readGate;
|
||||
}
|
||||
return result;
|
||||
});
|
||||
return {
|
||||
firstRead,
|
||||
release: () => releaseRead?.(),
|
||||
get readCount() {
|
||||
return readCount;
|
||||
},
|
||||
get totalReadBytes() {
|
||||
return totalReadBytes;
|
||||
},
|
||||
};
|
||||
};
|
||||
Reference in New Issue
Block a user