feat(core): add typed policy and integrity contracts

This commit is contained in:
morluto
2026-07-14 01:37:43 +00:00
parent 87e66c381f
commit 6540d64848
52 changed files with 4159 additions and 181 deletions
+3 -1
View File
@@ -9,9 +9,11 @@ import type { Result } from "../domain/result.js";
import type { EvidenceLocation } from "../domain/evidence.js";
import type { EvidenceSubjectTarget } from "../domain/evidence.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import type { ProgressReporter } from "./ProgressReporter.js";
interface ExecutionOptions {
export interface ExecutionOptions {
readonly signal?: AbortSignal;
readonly progress?: ProgressReporter;
}
/** Closed operations accepted by provider-backed analysis sessions. */
+2 -1
View File
@@ -134,6 +134,7 @@ export const createArtifactNode = (input: {
readonly format: ArtifactNode["format"];
readonly executable: boolean;
readonly contentState: ArtifactNode["content_state"];
readonly limitations?: readonly string[];
}): ArtifactNode => ({
artifact_id: `art_${digestCanonical({ schema_version: 1, sha256: input.sha256 })}`,
kind: input.kind,
@@ -144,7 +145,7 @@ export const createArtifactNode = (input: {
architecture: null,
executable: input.executable,
content_state: input.contentState,
limitations: [],
limitations: [...(input.limitations ?? [])],
});
export const rootOccurrenceFor = (
+156 -23
View File
@@ -23,6 +23,7 @@ import {
artifactInventoryResultSchema,
type ArtifactInventoryResult,
type ArtifactNode,
type IntegrityContradiction,
} from "../domain/artifactGraph.js";
import {
classifyArtifactPath,
@@ -61,6 +62,21 @@ const NATIVE_MOUNT_DISABLED: ArtifactNativeMountPolicy = {
nativeMountEnabled: false,
};
/** Explicit caller approval bounded by operator-owned integrity policy. */
export interface ArtifactIntegrityPolicy {
readonly mode: "fail" | "record-and-continue";
readonly approved: boolean;
readonly enabled: boolean;
readonly maxMismatches: number;
}
const STRICT_INTEGRITY_POLICY: ArtifactIntegrityPolicy = {
mode: "fail",
approved: false,
enabled: false,
maxMismatches: 1,
};
/** Immutable inventory produced by one complete artifact scan. */
export interface ArtifactInventorySnapshot {
readonly manifest: ArtifactInventoryResult["manifest"];
@@ -71,6 +87,7 @@ export interface ArtifactInventorySnapshot {
readonly provenance: ReadonlyArray<
ArtifactInventoryResult["provenance"][number]
>;
readonly integrity_contradictions: readonly IntegrityContradiction[];
readonly limitations: readonly string[];
}
@@ -82,6 +99,7 @@ export const inventoryArtifact = async (
options: {
readonly signal?: AbortSignal;
readonly nativeMount?: ArtifactNativeMountPolicy;
readonly integrity?: ArtifactIntegrityPolicy;
} = {},
): Promise<ArtifactInventoryResult> => {
const snapshot = await scanArtifactInventory(
@@ -89,6 +107,7 @@ export const inventoryArtifact = async (
limits,
options.signal,
options.nativeMount ?? NATIVE_MOUNT_DISABLED,
options.integrity ?? STRICT_INTEGRITY_POLICY,
);
return paginateArtifactInventory(snapshot, page);
};
@@ -99,10 +118,17 @@ export const scanArtifactInventory = async (
limits: ArtifactLimits,
signal?: AbortSignal,
nativeMount: ArtifactNativeMountPolicy = NATIVE_MOUNT_DISABLED,
integrity: ArtifactIntegrityPolicy = STRICT_INTEGRITY_POLICY,
): Promise<ArtifactInventorySnapshot> => {
abortIfNeeded(signal);
const path = await realpath(inputPath);
return scanCanonicalArtifactInventory(path, limits, signal, nativeMount);
return scanCanonicalArtifactInventory(
path,
limits,
signal,
nativeMount,
integrity,
);
};
/** Scan one already-canonical artifact path without resolving it again. */
@@ -111,7 +137,16 @@ export const scanCanonicalArtifactInventory = async (
limits: ArtifactLimits,
signal?: AbortSignal,
nativeMount: ArtifactNativeMountPolicy = NATIVE_MOUNT_DISABLED,
integrity: ArtifactIntegrityPolicy = STRICT_INTEGRITY_POLICY,
): Promise<ArtifactInventorySnapshot> => {
if (
integrity.mode === "record-and-continue" &&
(!integrity.approved || !integrity.enabled)
)
throw new ArtifactReaderFailure(
"unavailable",
"Integrity continuation requires explicit approval and operator policy",
);
const metadata = await lstat(path);
const rootFormat = await classifyRoot(path, metadata.isDirectory());
const rootDigest = metadata.isDirectory()
@@ -120,7 +155,12 @@ export const scanCanonicalArtifactInventory = async (
const reader = await createReader(path, rootFormat, nativeMount, signal);
try {
const { nodes, occurrences } = await scanReader(reader, limits, signal);
const { nodes, occurrences, pendingContradictions } = await scanReader(
reader,
limits,
signal,
integrity,
);
materializeDirectoryNodes(occurrences, nodes);
const rootNode = createRootNode({
@@ -137,6 +177,46 @@ export const scanCanonicalArtifactInventory = async (
if (occurrence.parent_occurrence_id === null)
occurrence.parent_occurrence_id = rootOccurrence.occurrence_id;
occurrences.unshift(rootOccurrence);
const occurrenceById = new Map(
occurrences.map((occurrence) => [occurrence.occurrence_id, occurrence]),
);
const integrityContradictions = pendingContradictions.map(
(contradiction): IntegrityContradiction => {
const occurrence = occurrences.find(
({ logical_path: path }) => path === contradiction.logicalPath,
);
if (occurrence === undefined)
throw new ArtifactReaderFailure(
"integrity",
"Integrity contradiction lost its graph occurrence",
);
const parent =
occurrence.parent_occurrence_id === null
? undefined
: occurrenceById.get(occurrence.parent_occurrence_id);
const parentArtifactId = parent?.artifact_id ?? rootNode.artifact_id;
return {
contradiction_id: `ic_${digestCanonical({
root_artifact_id: rootNode.artifact_id,
logical_path: contradiction.logicalPath,
declared_sha256: contradiction.declaredSha256,
observed_sha256: contradiction.observedSha256,
})}`,
occurrence_id: occurrence.occurrence_id,
parent_artifact_id: parentArtifactId,
logical_path: contradiction.logicalPath,
declared_sha256: contradiction.declaredSha256,
observed_sha256: contradiction.observedSha256,
entry_kind: contradiction.entryKind,
unpacked: contradiction.unpacked,
trust: "observed-untrusted",
provenance: "container-integrity-metadata-versus-observed-bytes",
limitations: [
"Observed bytes contradict declared integrity metadata and cannot support equivalence.",
],
};
},
);
const edges = createArtifactEdges(
rootNode.artifact_id,
occurrences,
@@ -170,6 +250,7 @@ export const scanCanonicalArtifactInventory = async (
nodes: orderedNodes,
occurrences: orderedOccurrences,
edges: orderedEdges,
integrity_contradictions: integrityContradictions,
});
const manifestId = `agm_${digestCanonical({
schema_version: 1,
@@ -193,7 +274,15 @@ export const scanCanonicalArtifactInventory = async (
edges: orderedEdges,
limits: toOutputLimits(limits),
provenance: reader?.provenance() ?? [],
limitations: inventoryLimitations(rootFormat, reader),
integrity_contradictions: integrityContradictions,
limitations: [
...inventoryLimitations(rootFormat, reader),
...(integrityContradictions.length === 0
? []
: [
`${String(integrityContradictions.length)} integrity contradiction(s) were recorded; mismatched content is observed-untrusted.`,
]),
],
};
} finally {
await reader?.close();
@@ -283,18 +372,30 @@ const isExpandableAsar = (entry: ArtifactEntry, logicalPath: string): boolean =>
const emptyScan = (): {
readonly nodes: Map<string, ArtifactNode>;
readonly occurrences: MutableOccurrence[];
} => ({ nodes: new Map(), occurrences: [] });
readonly pendingContradictions: PendingIntegrityContradiction[];
} => ({ nodes: new Map(), occurrences: [], pendingContradictions: [] });
interface PendingIntegrityContradiction {
readonly logicalPath: string;
readonly declaredSha256: string;
readonly observedSha256: string;
readonly entryKind: "file" | "slice";
readonly unpacked: boolean;
}
const scanReader = async (
reader: ArtifactReader | undefined,
limits: ArtifactLimits,
signal?: AbortSignal,
integrity: ArtifactIntegrityPolicy = STRICT_INTEGRITY_POLICY,
): Promise<{
readonly nodes: Map<string, ArtifactNode>;
readonly occurrences: MutableOccurrence[];
readonly pendingContradictions: PendingIntegrityContradiction[];
}> => {
const { nodes, occurrences } = emptyScan();
if (reader === undefined) return { nodes, occurrences };
const { nodes, occurrences, pendingContradictions } = emptyScan();
if (reader === undefined)
return { nodes, occurrences, pendingContradictions };
const occurrenceByPath = new Map<string, MutableOccurrence>();
const registry = new ArtifactPathRegistry();
let totalBytes = 0;
@@ -302,7 +403,9 @@ const scanReader = async (
currentReader: ArtifactReader,
entry: ArtifactEntry,
logicalPath: string,
): Promise<ArtifactNode | undefined> => {
): Promise<
{ readonly node: ArtifactNode; readonly mismatched: boolean } | undefined
> => {
if ((entry.kind !== "file" && entry.kind !== "slice") || entry.encrypted)
return undefined;
const remainingBytes = limits.maxTotalBytes - totalBytes;
@@ -322,7 +425,9 @@ const scanReader = async (
signal,
);
totalBytes += digest.bytes;
if (entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256)
const mismatched =
entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256;
if (mismatched && integrity.mode === "fail")
throw new ArtifactReaderFailure(
"integrity",
`Artifact integrity metadata disagrees with content: ${logicalPath}`,
@@ -334,18 +439,40 @@ const scanReader = async (
unpacked: entry.unpacked,
},
);
if (mismatched && entry.declaredSha256 !== null) {
if (pendingContradictions.length >= integrity.maxMismatches)
throw new ArtifactReaderFailure(
"limit",
"Artifact integrity mismatch limit exceeded",
);
pendingContradictions.push({
logicalPath,
declaredSha256: entry.declaredSha256,
observedSha256: digest.sha256,
entryKind: entry.kind,
unpacked: entry.unpacked,
});
}
const classified =
entry.kind === "slice"
? ({ kind: "universal-slice", format: "mach-o" } as const)
: classifyArtifactContent(logicalPath, digest.prefix);
return createArtifactNode({
sha256: digest.sha256,
size: digest.bytes,
kind: classified.kind,
format: classified.format,
executable: entry.executable,
contentState: "embedded",
});
return {
node: createArtifactNode({
sha256: digest.sha256,
size: digest.bytes,
kind: classified.kind,
format: classified.format,
executable: entry.executable,
contentState: "embedded",
limitations: mismatched
? [
"Observed content contradicts declared integrity metadata and is untrusted.",
]
: [],
}),
mismatched,
};
};
const visit = async (
currentReader: ArtifactReader,
@@ -370,20 +497,26 @@ const scanReader = async (
logicalPath,
parent?.occurrence_id ?? null,
);
const node = await digestEntry(currentReader, entry, logicalPath);
if (node !== undefined) {
nodes.set(node.artifact_id, node);
occurrence.artifact_id = node.artifact_id;
occurrence.hash_status = "verified";
const digested = await digestEntry(currentReader, entry, logicalPath);
if (digested !== undefined) {
nodes.set(digested.node.artifact_id, digested.node);
occurrence.artifact_id = digested.node.artifact_id;
occurrence.hash_status = digested.mismatched
? "mismatched"
: "verified";
if (digested.mismatched)
occurrence.limitations.push(
"Declared integrity metadata contradicts observed bytes.",
);
}
occurrences.push(occurrence);
occurrenceByPath.set(logicalPath, occurrence);
if (expandableAsar)
if (expandableAsar && digested?.mismatched !== true)
await visitNestedAsar(entry.adapterKey, logicalPath, visit);
}
};
await visit(reader, "");
return { nodes, occurrences };
return { nodes, occurrences, pendingContradictions };
};
const classifyRoot = async (
@@ -5,6 +5,7 @@ import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
import { withinRoot } from "../reference/ReferenceSourceReaderPaths.js";
import {
scanCanonicalArtifactInventory,
type ArtifactIntegrityPolicy,
type ArtifactInventorySnapshot,
} from "./ArtifactInventory.js";
@@ -14,6 +15,7 @@ export const scanAuthorizedArtifactInventory = async (
roots: readonly string[],
limits: ArtifactLimits,
signal?: AbortSignal,
integrity?: ArtifactIntegrityPolicy,
): Promise<ArtifactInventorySnapshot> => {
if (roots.length === 0)
throw new ArtifactReaderFailure(
@@ -29,5 +31,11 @@ export const scanAuthorizedArtifactInventory = async (
"path",
"Artifact path is outside approved input roots",
);
return scanCanonicalArtifactInventory(path, limits, signal);
return scanCanonicalArtifactInventory(
path,
limits,
signal,
undefined,
integrity,
);
};
+113
View File
@@ -46,6 +46,10 @@ import {
unknownMutationEvidence,
} from "./UnknownEvidence.js";
import type { BinarySessionPort } from "./BinarySessionPort.js";
import {
parseInvestigationWorkspace,
type InvestigationWorkspace,
} from "../domain/investigationWorkspace.js";
export type { BinarySessionPort } from "./BinarySessionPort.js";
const OFFICIAL_OPERATIONS: ReadonlySet<string> = new Set(
OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name),
@@ -73,6 +77,12 @@ export class BinarySession implements BinarySessionPort {
maxBytes: 64 * 1024 * 1024,
});
readonly #snapshot = new AnalysisSnapshotCache();
readonly #investigationWorkspaces = new Map<string, InvestigationWorkspace>();
readonly #runtimeAvailability = new Map<
string,
{ readonly available: boolean; readonly reason: string | null }
>();
readonly #availabilityListeners = new Set<() => void>();
readonly #snapshotsEnabled: boolean;
#snapshotInvalidated = false;
@@ -121,6 +131,12 @@ export class BinarySession implements BinarySessionPort {
return this.#providerIdentity;
}
/** Observe runtime provider-health changes that affect discovery metadata. */
onAvailabilityChanged(listener: () => void): () => void {
this.#availabilityListeners.add(listener);
return () => this.#availabilityListeners.delete(listener);
}
/** Add one successful public observation to the session ledger. */
recordEvidence(
evidence: Evidence,
@@ -191,6 +207,36 @@ export class BinarySession implements BinarySessionPort {
);
}
/** Retain one validated immutable workspace revision for session resources. */
retainInvestigationWorkspace(
workspace: InvestigationWorkspace,
): "added" | "duplicate" {
const parsed = parseInvestigationWorkspace(workspace);
const key = `${parsed.workspace_id}:${String(parsed.revision)}`;
if (this.#investigationWorkspaces.has(key)) return "duplicate";
this.#investigationWorkspaces.set(key, parsed);
return "added";
}
/** Read one session-retained immutable workspace revision. */
investigationWorkspace(
workspaceId: string,
revision: number,
): InvestigationWorkspace | undefined {
return this.#investigationWorkspaces.get(
`${workspaceId}:${String(revision)}`,
);
}
/** List retained workspace revisions in canonical identity order. */
investigationWorkspaces(): readonly InvestigationWorkspace[] {
return [...this.#investigationWorkspaces.values()].sort(
(left, right) =>
left.workspace_id.localeCompare(right.workspace_id) ||
left.revision - right.revision,
);
}
/** Create an approved residual unknown and immutable mutation evidence. */
recordUnknown(
input: RecordUnknownInput,
@@ -323,6 +369,7 @@ export class BinarySession implements BinarySessionPort {
return err(new AnalysisCancelledError("open_binary"));
}
this.#active = { target: parsed.value, client };
this.#clearRuntimeAvailability();
this.#snapshot.select(parsed.value);
if (options.snapshot !== undefined) {
const imported = this.importAnalysisSnapshot(options.snapshot);
@@ -348,6 +395,7 @@ export class BinarySession implements BinarySessionPort {
this.#evidence.clear();
this.#snapshot.clear();
this.#snapshotInvalidated = false;
this.#clearRuntimeAvailability();
return ok(null);
});
}
@@ -375,6 +423,10 @@ export class BinarySession implements BinarySessionPort {
.sort((left, right) =>
left.operation.localeCompare(right.operation),
)
.map((descriptor) => ({
...descriptor,
...this.#runtimeAvailability.get(descriptor.operation),
}))
.map((descriptor) => ({
operation: descriptor.operation,
available: descriptor.available,
@@ -456,6 +508,7 @@ export class BinarySession implements BinarySessionPort {
this.#calls.add(call);
try {
const result = await call;
this.#observeRuntimeAvailability(name, result);
if (result.ok && cacheable)
this.#snapshot.record(active.target, name, arguments_, result.value);
else if (result.ok && capability?.effects.mutatesArtifact === true) {
@@ -468,6 +521,66 @@ export class BinarySession implements BinarySessionPort {
}
}
#observeRuntimeAvailability(
operation: AnalysisOperation,
result: Result<AnalysisExecution, AnalysisError>,
): void {
if (result.ok) {
if (this.#setRuntimeAvailability(operation, true, null))
this.#emitAvailabilityChanged();
return;
}
if (result.error._tag === "AnalysisCapabilityUnavailableError") {
if (this.#setRuntimeAvailability(operation, false, result.error.message))
this.#emitAvailabilityChanged();
return;
}
if (
[
"ProviderAdapterError",
"HopperProcessError",
"HopperStartError",
"HopperRemoteError",
].includes(result.error._tag)
) {
const providerId = this.#capabilities?.get(operation)?.provider.id;
let changed = false;
for (const descriptor of this.#capabilities?.values() ?? [])
if (providerId !== undefined && descriptor.provider.id === providerId)
changed =
this.#setRuntimeAvailability(
descriptor.operation,
false,
"Provider became unavailable during this session.",
) || changed;
if (changed) this.#emitAvailabilityChanged();
}
}
#setRuntimeAvailability(
operation: string,
available: boolean,
reason: string | null,
): boolean {
const current = this.#runtimeAvailability.get(operation);
if (current?.available === available && current.reason === reason)
return false;
if (available && current === undefined) return false;
if (available) this.#runtimeAvailability.delete(operation);
else this.#runtimeAvailability.set(operation, { available, reason });
return true;
}
#clearRuntimeAvailability(): void {
if (this.#runtimeAvailability.size === 0) return;
this.#runtimeAvailability.clear();
this.#emitAvailabilityChanged();
}
#emitAvailabilityChanged(): void {
for (const listener of this.#availabilityListeners) listener();
}
#serialize<T>(operation: () => Promise<T>): Promise<T> {
const result = this.#transition.then(operation, operation);
this.#transition = result.then(
+10
View File
@@ -16,6 +16,7 @@ import type {
UnknownStatus,
UpdateUnknownInput,
} from "../domain/residualUnknown.js";
import type { InvestigationWorkspace } from "../domain/investigationWorkspace.js";
import type {
AnalysisOperation,
AnalysisOperationPort,
@@ -48,6 +49,14 @@ export interface BinarySessionPort extends AnalysisOperationPort {
importAnalysisSnapshot(
snapshot: AnalysisSnapshot,
): Result<number, AnalysisError>;
retainInvestigationWorkspace(
workspace: InvestigationWorkspace,
): "added" | "duplicate";
investigationWorkspace(
workspaceId: string,
revision: number,
): InvestigationWorkspace | undefined;
investigationWorkspaces(): readonly InvestigationWorkspace[];
recordUnknown(
input: RecordUnknownInput,
): Result<ResidualUnknown, AnalysisError>;
@@ -72,4 +81,5 @@ export interface BinarySessionPort extends AnalysisOperationPort {
UnknownRegistryError
>;
providerIdentity(operation?: AnalysisOperation): ProviderIdentity;
onAvailabilityChanged?(listener: () => void): () => void;
}
+20 -9
View File
@@ -15,6 +15,7 @@ import { jsonValueSchema } from "../domain/jsonValue.js";
import { err, ok, type Result } from "../domain/result.js";
import {
paginateArtifactInventory,
type ArtifactIntegrityPolicy,
type ArtifactInventorySnapshot,
} from "./ArtifactInventory.js";
import { scanAuthorizedArtifactInventory } from "./AuthorizedArtifactInventory.js";
@@ -38,22 +39,31 @@ export const scanVersions = async (
input: CrossVersionInvestigationInput,
inputRoots: readonly string[],
signal?: AbortSignal,
integrityContinueEnabled = false,
): Promise<Result<VersionSnapshots, AnalysisError>> => {
try {
if (signal?.aborted === true)
return err(new AnalysisCancelledError("find_changed_behavior"));
const limits = artifactLimits(input.options);
const integrity: ArtifactIntegrityPolicy = {
mode: input.integrity_policy,
approved: input.integrity_continue_approved,
enabled: integrityContinueEnabled,
maxMismatches: input.max_integrity_mismatches,
};
const left = await scanAuthorizedArtifactInventory(
input.left_path,
inputRoots,
limits,
signal,
integrity,
);
const right = await scanAuthorizedArtifactInventory(
input.right_path,
inputRoots,
limits,
signal,
integrity,
);
return ok({ left, right });
} catch (cause: unknown) {
@@ -74,12 +84,8 @@ export const createInventoryEvidencePages = (
input: CrossVersionInvestigationInput,
snapshots: VersionSnapshots,
): Result<InventoryEvidencePages, AnalysisError> => {
const left = inventoryPages(input.left_path, snapshots.left, input.options);
const right = inventoryPages(
input.right_path,
snapshots.right,
input.options,
);
const left = inventoryPages(input.left_path, snapshots.left, input);
const right = inventoryPages(input.right_path, snapshots.right, input);
if (left.length > 100 || right.length > 100)
return err(new ArtifactOperationError("inventory_artifact", "limit"));
return ok({ left, right });
@@ -108,8 +114,9 @@ export const runLimitations = (snapshots: VersionSnapshots): string[] =>
const inventoryPages = (
path: string,
snapshot: ArtifactInventorySnapshot,
options: InvestigationRunOptions,
input: CrossVersionInvestigationInput,
): Evidence[] => {
const options = input.options;
const count = Math.max(
1,
Math.ceil(snapshot.nodes.length / options.page_size),
@@ -117,16 +124,17 @@ const inventoryPages = (
Math.ceil(snapshot.edges.length / options.page_size),
);
return Array.from({ length: count }, (_, index) =>
inventoryPage(path, snapshot, options, index * options.page_size),
inventoryPage(path, snapshot, input, index * options.page_size),
);
};
const inventoryPage = (
path: string,
snapshot: ArtifactInventorySnapshot,
options: InvestigationRunOptions,
input: CrossVersionInvestigationInput,
offset: number,
): Evidence => {
const options = input.options;
const result = paginateArtifactInventory(snapshot, {
nodeOffset: offset,
nodeLimit: options.page_size,
@@ -157,6 +165,9 @@ const inventoryPage = (
max_compression_ratio: options.max_compression_ratio,
max_depth: options.max_depth,
max_path_bytes: options.max_path_bytes,
integrity_policy: input.integrity_policy,
integrity_continue_approved: input.integrity_continue_approved,
max_integrity_mismatches: input.max_integrity_mismatches,
},
result: jsonValueSchema.parse(result),
rawResult: null,
+62 -1
View File
@@ -6,6 +6,7 @@ import {
type EvidenceFilePolicy,
} from "../domain/evidenceBundle.js";
import {
AnalysisCancelledError,
AnalysisInputError,
EvidenceIntegrityError,
InvestigationWorkspaceError,
@@ -25,6 +26,7 @@ import {
import { jsonValueSchema } from "../domain/jsonValue.js";
import { err, ok, type Result } from "../domain/result.js";
import type { BinarySessionPort } from "./BinarySession.js";
import type { ProgressReporter } from "./ProgressReporter.js";
import {
AUTOMATIC_RUN_LIMITATION,
createInventoryEvidencePages,
@@ -54,6 +56,8 @@ export interface CrossVersionInvestigationExecution {
readonly inputRoots: readonly string[];
readonly session?: BinarySessionPort;
readonly signal?: AbortSignal;
readonly progress?: ProgressReporter;
readonly integrityContinueEnabled?: boolean;
}
/** Run or resume a deterministic cross-version artifact investigation. */
@@ -76,19 +80,36 @@ export const runCrossVersionInvestigation = async (
if (!initial.ok) return initial;
const preflight = validateWorkspaceRequest(initial.value, parsed.data);
if (!preflight.ok) return preflight;
if (isCancelled(execution.signal))
return err(new AnalysisCancelledError("find_changed_behavior"));
await execution.progress?.report({
phase: "scan_versions",
completed: 0,
total: 4,
message: "Scanning both version inputs",
});
const snapshots = await scanVersions(
parsed.data,
execution.inputRoots,
execution.signal,
execution.integrityContinueEnabled,
);
if (!snapshots.ok) return snapshots;
await execution.progress?.report({
phase: "scan_versions",
completed: 1,
total: 4,
message: "Version inputs scanned",
});
return continueInvestigation({
input: parsed.data,
initial: initial.value,
snapshots: snapshots.value,
policy,
session: execution.session,
signal: execution.signal,
progress: execution.progress,
});
};
@@ -103,6 +124,8 @@ const continueInvestigation = async (context: {
readonly snapshots: VersionSnapshots;
readonly policy: EvidenceFilePolicy;
readonly session: BinarySessionPort | undefined;
readonly signal: AbortSignal | undefined;
readonly progress: ProgressReporter | undefined;
}): Promise<Result<CrossVersionInvestigationOutcome, AnalysisError>> => {
const left = targetFor(context.snapshots.left);
const right = targetFor(context.snapshots.right);
@@ -110,6 +133,9 @@ const continueInvestigation = async (context: {
left,
right,
options: context.input.options,
integrity_policy: context.input.integrity_policy,
integrity_continue_approved: context.input.integrity_continue_approved,
max_integrity_mismatches: context.input.max_integrity_mismatches,
});
const existing = context.initial?.runs.find(
({ run_id: id }) => id === identity.runId,
@@ -118,6 +144,8 @@ const continueInvestigation = async (context: {
return completeOutcome(context.initial, existing, true, context.session);
const pages = createInventoryEvidencePages(context.input, context.snapshots);
if (!pages.ok) return pages;
if (isCancelled(context.signal))
return err(new AnalysisCancelledError("find_changed_behavior"));
const inventoried = await ensureInventoryCheckpoint({
input: context.input,
current: context.initial,
@@ -127,20 +155,47 @@ const continueInvestigation = async (context: {
policy: context.policy,
});
if (!inventoried.ok) return inventoried;
await context.progress?.report({
phase: "inventory_versions",
completed: 2,
total: 4,
message: "Both artifact inventories checkpointed",
});
if (isCancelled(context.signal))
return err(new AnalysisCancelledError("find_changed_behavior"));
const compared = await ensureComparisonCheckpoint(
context.input,
inventoried.value,
context.policy,
);
if (!compared.ok) return compared;
return finalizeInvestigation(
await context.progress?.report({
phase: "compare_artifacts",
completed: 3,
total: 4,
message: "Artifact comparison checkpointed",
});
if (isCancelled(context.signal))
return err(new AnalysisCancelledError("find_changed_behavior"));
const finalized = await finalizeInvestigation(
context.input,
compared.value,
context.policy,
context.session,
);
await context.progress?.report({
phase: "changed_behavior",
completed: 4,
total: 4,
message: finalized.ok ? "Investigation completed" : "Investigation failed",
terminal: true,
});
return finalized;
};
const isCancelled = (signal: AbortSignal | undefined): boolean =>
signal?.aborted === true;
const ensureInventoryCheckpoint = async (input: {
readonly input: CrossVersionInvestigationInput;
readonly current: InvestigationWorkspace | null;
@@ -162,6 +217,9 @@ const ensureInventoryCheckpoint = async (input: {
left,
right,
options: input.input.options,
integrity_policy: input.input.integrity_policy,
integrity_continue_approved: input.input.integrity_continue_approved,
max_integrity_mismatches: input.input.max_integrity_mismatches,
});
const run = investigationRunSchema.parse({
schema_version: 1,
@@ -170,6 +228,9 @@ const ensureInventoryCheckpoint = async (input: {
left,
right,
options: input.input.options,
integrity_policy: input.input.integrity_policy,
integrity_continue_approved: input.input.integrity_continue_approved,
max_integrity_mismatches: input.input.max_integrity_mismatches,
status: "running",
completed_stages: ["inventory_left", "inventory_right"],
left_inventory_evidence_ids: evidenceIds(input.pages.left),
+140 -10
View File
@@ -1,4 +1,6 @@
import { parseConfig } from "../config.js";
import { jsonObjectSchema } from "../domain/jsonValue.js";
import { createServerIdentity } from "../serverIdentity.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { EnhancedTools } from "./EnhancedTools.js";
import { createBinarySession } from "./runtime.js";
@@ -9,6 +11,8 @@ import type { NativeToolName } from "../contracts/nativeToolContracts.js";
import type { ArtifactToolName } from "../contracts/artifactToolContracts.js";
import {
EvidenceIntegrityError,
AnalysisProtocolError,
PermissionRequiredError,
projectAnalysisError,
type AnalysisError,
} from "../domain/errors.js";
@@ -24,6 +28,8 @@ import {
} from "../domain/analysisSnapshot.js";
import { err, ok, type Result } from "../domain/result.js";
import type { AnalysisSnapshot } from "../domain/analysisSnapshot.js";
import { loadConfiguredPermissionAuthority } from "./PermissionConfiguration.js";
import type { PermissionAuthority } from "./PermissionAuthority.js";
const WORKFLOW_PROVIDER = {
id: "rea-workflow",
@@ -52,12 +58,16 @@ export const runDirectAnalysis = async (
options: {
readonly logger?: Logger;
readonly snapshotPath?: string | undefined;
readonly signal?: AbortSignal;
} = {},
): Promise<JsonValue> =>
runAnalysis(path, tool, arguments_, {
logger: options.logger ?? silentLogger,
snapshotPath: options.snapshotPath,
});
withProcessCancellation(options.signal, (signal) =>
runAnalysis(path, tool, arguments_, {
logger: options.logger ?? silentLogger,
snapshotPath: options.snapshotPath,
signal,
}),
);
/** Execute one provider-native semantic operation with atomic provenance. */
export const runProviderAnalysis = async (
@@ -65,8 +75,15 @@ export const runProviderAnalysis = async (
tool: NativeToolName | ArtifactToolName,
arguments_: Readonly<Record<string, JsonValue>>,
logger: Logger = silentLogger,
signal?: AbortSignal,
): Promise<JsonValue> =>
runAnalysis(path, tool, arguments_, { logger, snapshotPath: undefined });
withProcessCancellation(signal, (operationSignal) =>
runAnalysis(path, tool, arguments_, {
logger,
snapshotPath: undefined,
signal: operationSignal,
}),
);
/** Describe configured providers without opening a target or launching Hopper. */
export const runSessionStatus = async (
@@ -76,12 +93,94 @@ export const runSessionStatus = async (
if (!config.ok) return cliError(config.error);
const session = createBinarySession(config.value, logger);
try {
return session.status();
return {
...jsonObjectSchema.parse(session.status()),
server_identity: createServerIdentity({
startedAt: new Date().toISOString(),
}),
};
} finally {
await session.close();
}
};
const authorizeAnalysis = async (
authority: PermissionAuthority,
tool: NativeToolName | ArtifactToolName | DirectAnalysisTool,
arguments_: Readonly<Record<string, JsonValue>>,
snapshotPath: string | undefined,
): Promise<Result<null, AnalysisError>> => {
const requests = [];
if (snapshotPath !== undefined) {
requests.push(
{
capability: "snapshot_read" as const,
path: snapshotPath,
access: "write" as const,
},
{
capability: "snapshot_write" as const,
path: snapshotPath,
access: "write" as const,
},
);
}
if (tool === "extract_artifact" && typeof arguments_.output_root === "string")
requests.push({
capability: "artifact_extract" as const,
path: arguments_.output_root,
access: "write" as const,
});
for (const request of requests) {
const result = await authority.authorize(
{
capability: request.capability,
roots: [request.path],
executables: [],
environment_names: [],
network: "none",
mount: false,
operation_identity: `${tool}:${request.capability}:${request.path}`,
},
request.access,
);
if (!result.ok)
return err(
result.error instanceof PermissionRequiredError
? result.error
: new AnalysisProtocolError(result.error.message, {
cause: result.error,
}),
);
}
if (
tool === "inventory_artifact" &&
arguments_.native_mount_approved === true
) {
const result = await authority.authorize(
{
capability: "native_mount",
roots: [],
executables: [],
environment_names: [],
network: "none",
mount: true,
operation_identity: "inventory_artifact:native_mount",
},
"read",
);
if (!result.ok)
return err(
result.error instanceof PermissionRequiredError
? result.error
: new AnalysisProtocolError(result.error.message, {
cause: result.error,
}),
);
}
return ok(null);
};
const runAnalysis = async (
path: string,
tool: NativeToolName | ArtifactToolName | DirectAnalysisTool,
@@ -89,11 +188,23 @@ const runAnalysis = async (
options: {
readonly logger: Logger;
readonly snapshotPath: string | undefined;
readonly signal: AbortSignal;
},
): Promise<JsonValue> => {
const { logger, snapshotPath } = options;
const { logger, signal, snapshotPath } = options;
const config = parseConfig(process.env);
if (!config.ok) return cliError(config.error);
const permissionAuthority = await loadConfiguredPermissionAuthority(
config.value,
);
if (!permissionAuthority.ok) return cliError(permissionAuthority.error);
const authorized = await authorizeAnalysis(
permissionAuthority.value,
tool,
arguments_,
snapshotPath,
);
if (!authorized.ok) return cliError(authorized.error);
const unavailable = snapshotUnavailable(
snapshotPath,
config.value.hopperLoaderArgs,
@@ -114,7 +225,7 @@ const runAnalysis = async (
const { snapshot } = prepared.value;
const opened = await session.open(
path,
snapshot === undefined ? {} : { snapshot },
snapshot === undefined ? { signal } : { signal, snapshot },
);
if (!opened.ok) return cliError(opened.error);
let output: JsonValue;
@@ -124,7 +235,11 @@ const runAnalysis = async (
tool === "analyze_function" ||
tool === "trace_feature"
) {
const result = await new EnhancedTools(session).execute(tool, arguments_);
const result = await new EnhancedTools(session).execute(
tool,
arguments_,
signal,
);
if (!result.ok) output = cliError(result.error);
else {
evidence = createEvidence(
@@ -143,7 +258,7 @@ const runAnalysis = async (
output = evidence;
}
} else {
const result = await session.execute(tool, arguments_);
const result = await session.execute(tool, arguments_, { signal });
if (!result.ok) output = cliError(result.error);
else {
evidence = createEvidence(
@@ -179,6 +294,21 @@ const runAnalysis = async (
}
};
const withProcessCancellation = async <Value>(
suppliedSignal: AbortSignal | undefined,
operation: (signal: AbortSignal) => Promise<Value>,
): Promise<Value> => {
if (suppliedSignal !== undefined) return operation(suppliedSignal);
const controller = new AbortController();
const cancel = (): void => controller.abort();
process.once("SIGINT", cancel);
try {
return await operation(controller.signal);
} finally {
process.off("SIGINT", cancel);
}
};
const prepareSnapshot = async (options: {
readonly path: string;
readonly tool: string;
+278
View File
@@ -0,0 +1,278 @@
import { realpath } from "node:fs/promises";
import { basename, dirname, join, resolve } from "node:path";
import type {
PermissionCeiling,
PermissionDecision,
PermissionGrant,
PermissionPolicy,
PermissionRequest,
PermissionScope,
} from "../domain/permissionPolicy.js";
import {
consumePermission,
clearSessionPermissions,
createPermissionPolicy,
evaluatePermission,
grantPermission,
reloadPermissionCeilings,
revokePermission,
} from "../domain/permissionPolicy.js";
import { PermissionRequiredError } from "../domain/errors.js";
import { err, ok, type Result } from "../domain/result.js";
/** Failure to establish a filesystem object's canonical authorization identity. */
export class PermissionPathError extends Error {
readonly _tag = "PermissionPathError" as const;
constructor(
readonly path: string,
readonly reason: "not_found" | "io",
options?: ErrorOptions,
) {
super(`Cannot canonicalize permission path: ${path}`, options);
}
}
/** Canonicalize administrator ceilings before they become authorization state. */
export const canonicalizePermissionCeilings = async (
ceilings: readonly PermissionCeiling[],
): Promise<Result<readonly PermissionCeiling[], PermissionPathError>> => {
const normalized: PermissionCeiling[] = [];
for (const ceiling of ceilings) {
const canonical = await canonicalizeScope(ceiling, "read");
if (!canonical.ok) return canonical;
normalized.push(canonical.value);
}
return ok(normalized);
};
/** Canonicalize one exact operation request before subset evaluation. */
export const canonicalizePermissionRequest = async (
request: PermissionRequest,
access: "read" | "write",
): Promise<Result<PermissionRequest, PermissionPathError>> => {
const canonical = await canonicalizeScope(request, access);
return canonical.ok
? ok({ ...canonical.value, operation_identity: request.operation_identity })
: canonical;
};
const canonicalizeScope = async (
scope: PermissionScope,
access: "read" | "write",
): Promise<Result<PermissionScope, PermissionPathError>> => {
const roots = await canonicalizePaths(scope.roots, access);
if (!roots.ok) return roots;
const executables = await canonicalizePaths(scope.executables, "read");
if (!executables.ok) return executables;
return ok({ ...scope, roots: roots.value, executables: executables.value });
};
const canonicalizePaths = async (
paths: readonly string[],
access: "read" | "write",
): Promise<Result<readonly string[], PermissionPathError>> => {
const canonical: string[] = [];
for (const path of paths) {
const result = await canonicalizePath(path, access);
if (!result.ok) return result;
canonical.push(result.value);
}
return ok(canonical);
};
const canonicalizePath = async (
path: string,
access: "read" | "write",
): Promise<Result<string, PermissionPathError>> => {
const requested = resolve(path);
try {
return ok(await realpath(requested));
} catch (cause: unknown) {
if (access !== "write" || !isNotFound(cause))
return err(new PermissionPathError(path, errorReason(cause), { cause }));
}
try {
const parent = await realpath(dirname(requested));
return ok(join(parent, basename(requested)));
} catch (cause: unknown) {
return err(new PermissionPathError(path, errorReason(cause), { cause }));
}
};
const isNotFound = (error: unknown): boolean =>
error instanceof Error && "code" in error && error.code === "ENOENT";
const errorReason = (error: unknown): PermissionPathError["reason"] =>
isNotFound(error) ? "not_found" : "io";
/** Stateful owner for permission evaluation, consumption, reload, and revoke. */
export class PermissionAuthority {
private policy: PermissionPolicy;
constructor(policy: PermissionPolicy) {
this.policy = policy;
}
/** Canonicalize and authorize one exact operation before its side effect. */
async authorize(
request: PermissionRequest,
access: "read" | "write",
options: {
readonly elicitationSupported?: boolean;
readonly restartRequired?: boolean;
} = {},
): Promise<
Result<PermissionDecision, PermissionPathError | PermissionRequiredError>
> {
const evaluated = await this.explain(request, access, options);
if (!evaluated.ok) return evaluated;
const decision = evaluated.value;
this.policy = consumePermission(this.policy, decision);
return ok(decision);
}
/** Dry-run the exact shared evaluation without consuming a once grant. */
async explain(
request: PermissionRequest,
access: "read" | "write",
options: {
readonly elicitationSupported?: boolean;
readonly restartRequired?: boolean;
} = {},
): Promise<
Result<
PermissionDecision & { readonly allowed: true },
PermissionPathError | PermissionRequiredError
>
> {
const canonical = await canonicalizePermissionRequest(request, access);
if (!canonical.ok) return canonical;
const decision = evaluatePermission(this.policy, canonical.value);
if (!decision.allowed)
return err(
new PermissionRequiredError(
canonical.value,
decision.missing,
ceilingFor(this.policy, canonical.value.capability),
options.elicitationSupported ?? false,
options.restartRequired ?? false,
),
);
return ok(decision);
}
/** Add authority beneath the administrator ceiling. */
grant(grant: PermissionGrant): ReturnType<typeof grantPermission> {
const result = grantPermission(this.policy, grant);
if (result.ok) this.policy = result.value;
return result;
}
/** Revoke authority immediately for subsequent operations. */
revoke(grantId: string): void {
this.policy = revokePermission(this.policy, grantId);
}
/** Drop once/session authority when its owning connection ends. */
clearSessionGrants(): void {
this.policy = clearSessionPermissions(this.policy);
}
/** Atomically replace optional persisted project grants. */
async replaceProjectGrants(
grants: readonly PermissionGrant[],
): Promise<Result<null, PermissionPathError>> {
let candidate: PermissionPolicy = {
...this.policy,
grants: this.policy.grants.filter(
({ lifetime }) => lifetime !== "project",
),
};
for (const grant of grants) {
const canonical = await canonicalizeGrant(grant);
if (!canonical.ok) return canonical;
const added = grantPermission(candidate, canonical.value);
if (!added.ok)
return err(
new PermissionPathError(grant.grant_id, "io", {
cause: added.error,
}),
);
candidate = added.value;
}
this.policy = candidate;
return ok(null);
}
/** Replace grants derived from the currently loaded administrator ceiling. */
async replaceAdministratorGrants(
grants: readonly PermissionGrant[],
): Promise<Result<null, PermissionPathError>> {
let candidate: PermissionPolicy = {
...this.policy,
grants: this.policy.grants.filter(
({ lifetime }) => lifetime !== "administrator",
),
};
for (const grant of grants) {
const canonical = await canonicalizeGrant(grant);
if (!canonical.ok) return canonical;
const added = grantPermission(candidate, canonical.value);
if (!added.ok)
return err(
new PermissionPathError(grant.grant_id, "io", {
cause: added.error,
}),
);
candidate = added.value;
}
this.policy = candidate;
return ok(null);
}
/** Replace ceilings without restarting the MCP process. */
async reload(
ceilings: readonly PermissionCeiling[],
): Promise<Result<null, PermissionPathError>> {
const canonical = await canonicalizePermissionCeilings(ceilings);
if (!canonical.ok) return canonical;
this.policy = reloadPermissionCeilings(this.policy, canonical.value);
return ok(null);
}
}
/** Create one canonical policy and optional grants at the composition root. */
export const createPermissionAuthority = async (
ceilings: readonly PermissionCeiling[],
grants: readonly PermissionGrant[] = [],
): Promise<Result<PermissionAuthority, PermissionPathError>> => {
const canonical = await canonicalizePermissionCeilings(ceilings);
if (!canonical.ok) return canonical;
let policy = createPermissionPolicy(canonical.value);
for (const grant of grants) {
const canonicalGrant = await canonicalizeGrant(grant);
if (!canonicalGrant.ok) return canonicalGrant;
const added = grantPermission(policy, canonicalGrant.value);
if (!added.ok)
return err(
new PermissionPathError(grant.grant_id, "io", { cause: added.error }),
);
policy = added.value;
}
return ok(new PermissionAuthority(policy));
};
const canonicalizeGrant = async (
grant: PermissionGrant,
): Promise<Result<PermissionGrant, PermissionPathError>> => {
const scope = await canonicalizeScope(grant, "read");
return scope.ok ? ok({ ...grant, ...scope.value }) : scope;
};
const ceilingFor = (
policy: PermissionPolicy,
capability: PermissionRequest["capability"],
): PermissionScope | null =>
policy.ceilings.find((ceiling) => ceiling.capability === capability) ?? null;
@@ -0,0 +1,52 @@
import type { AppConfig } from "../config.js";
import { ConfigurationError } from "../domain/errors.js";
import { err, ok, type Result } from "../domain/result.js";
import {
createPermissionAuthority,
type PermissionAuthority,
} from "./PermissionAuthority.js";
import { readProjectPermissionStore } from "./ProjectPermissionStore.js";
/** Load the same administrator and optional project policy for CLI and MCP. */
export const loadConfiguredPermissionAuthority = async (
config: AppConfig,
): Promise<Result<PermissionAuthority, ConfigurationError>> => {
const authority = await createPermissionAuthority(
config.permissionCeilings,
config.administratorPermissionGrants,
);
if (!authority.ok)
return err(
new ConfigurationError("Permission policy could not be loaded", {
cause: authority.error,
}),
);
if (
config.permissionProjectRoot === undefined ||
config.permissionProjectStore === undefined
)
return ok(authority.value);
const project = await readProjectPermissionStore(
config.permissionProjectStore,
config.permissionProjectRoot,
);
if (!project.ok)
return err(
new ConfigurationError("Project permission policy could not be loaded", {
cause: project.error,
}),
);
const replaced = await authority.value.replaceProjectGrants(
project.value?.grants ?? [],
);
return replaced.ok
? ok(authority.value)
: err(
new ConfigurationError(
"Project permission policy could not be applied",
{
cause: replaced.error,
},
),
);
};
+19
View File
@@ -3,6 +3,12 @@ import { AnalysisError } from "../domain/errors.js";
interface ProcessCaptureErrorOptions extends ErrorOptions {
readonly userMessage?: string;
readonly userCategory?: "permission_required" | "cancelled";
readonly reason?:
| "capture_failed"
| "cleanup_incomplete"
| "permission_required"
| "cancelled";
readonly cleanupResources?: readonly string[];
}
/** Typed application failure produced by controlled process capture. */
@@ -14,11 +20,23 @@ export class ProcessCaptureError extends AnalysisError {
| "permission_required"
| "cancelled"
| undefined;
readonly reason: NonNullable<ProcessCaptureErrorOptions["reason"]>;
override readonly cleanupIncomplete: boolean;
override readonly cleanupResources: readonly string[];
constructor(message: string, options?: ProcessCaptureErrorOptions) {
super(message, options);
this.userMessage = options?.userMessage;
this.userCategory = options?.userCategory;
this.reason =
options?.reason ??
(options?.userCategory === "permission_required"
? "permission_required"
: options?.userCategory === "cancelled"
? "cancelled"
: "capture_failed");
this.cleanupIncomplete = this.reason === "cleanup_incomplete";
this.cleanupResources = options?.cleanupResources ?? [];
}
}
@@ -26,5 +44,6 @@ export class ProcessCaptureError extends AnalysisError {
export const processCaptureCancelled = (): ProcessCaptureError =>
new ProcessCaptureError("process capture was cancelled", {
userCategory: "cancelled",
reason: "cancelled",
userMessage: "Process capture was cancelled. Start it again when ready.",
});
+3 -1
View File
@@ -389,7 +389,9 @@ export const resolveProcessResult = (
cause: executionFailure,
});
if (cleanupFailure !== undefined)
throw new ProcessCaptureError(cleanupFailure);
throw new ProcessCaptureError(cleanupFailure, {
reason: "cleanup_incomplete",
});
if (capture === undefined)
throw new ProcessCaptureError("process capture produced no result");
return capture;
+32 -1
View File
@@ -1,7 +1,12 @@
import { readFile } from "node:fs/promises";
import { parseConfig } from "../config.js";
import { AnalysisError, projectAnalysisError } from "../domain/errors.js";
import {
AnalysisError,
AnalysisProtocolError,
PermissionRequiredError,
projectAnalysisError,
} from "../domain/errors.js";
import { createEvidence, parseEvidence } from "../domain/evidence.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import {
@@ -15,6 +20,7 @@ import {
PROCESS_PROVIDER,
createProcessCaptureEvidence,
} from "./ProcessEvidence.js";
import { loadConfiguredPermissionAuthority } from "./PermissionConfiguration.js";
const MAX_INPUT_BYTES = 64 * 1024 * 1024;
@@ -40,6 +46,31 @@ export const captureProcessScenarioFile = async (path: string) => {
}
const config = parseConfig(process.env);
if (!config.ok) return cliAnalysisError(config.error);
const authority = await loadConfiguredPermissionAuthority(config.value);
if (!authority.ok) return cliAnalysisError(authority.error);
const authorized = await authority.value.authorize(
{
capability: "process_capture",
roots: [scenario.working_directory, ...scenario.filesystem_roots],
executables: [scenario.executable],
environment_names: [
...Object.keys(scenario.environment),
...scenario.inherit_environment,
],
network: scenario.network_access === "host" ? "external" : "none",
mount: false,
operation_identity: `capture_process_scenario:${scenario.executable}`,
},
"read",
);
if (!authorized.ok)
return cliAnalysisError(
authorized.error instanceof PermissionRequiredError
? authorized.error
: new AnalysisProtocolError(authorized.error.message, {
cause: authorized.error,
}),
);
const captured = await captureProcessScenario(
scenario,
config.value.processExecutionPolicy,
+4 -1
View File
@@ -174,7 +174,10 @@ const cleanupFailedStartup = async (options: {
sampledProcessGroupIds: [],
});
if (cleanupFailure !== undefined)
throw new ProcessCaptureError(cleanupFailure, { cause: options.cause });
throw new ProcessCaptureError(cleanupFailure, {
cause: options.cause,
reason: "cleanup_incomplete",
});
throw options.cause;
};
+55
View File
@@ -0,0 +1,55 @@
/** Provider-neutral progress observation for one ordinary request. */
export interface ProgressUpdate {
readonly phase: string;
readonly completed: number;
readonly total: number | null;
readonly message: string;
readonly terminal?: boolean;
}
/** Progress boundary shared by CLI, MCP, application workflows, and providers. */
export interface ProgressReporter {
report(update: ProgressUpdate): Promise<void>;
}
/** Create a monotonic, rate-bounded reporter around a surface-specific sink. */
export const createProgressReporter = (
sink: (
update: ProgressUpdate & { readonly sequence: number },
) => Promise<void>,
options: {
readonly minimumIntervalMs?: number;
readonly now?: () => number;
} = {},
): ProgressReporter => {
const minimumIntervalMs = options.minimumIntervalMs ?? 100;
const now = options.now ?? Date.now;
let lastCompleted = -1;
let lastSentAt = Number.NEGATIVE_INFINITY;
let sequence = 0;
return {
async report(update) {
if (!Number.isFinite(update.completed) || update.completed < 0)
throw new TypeError("Progress completed must be a nonnegative number");
if (update.total !== null && update.total < update.completed)
throw new TypeError("Progress total cannot be less than completed");
if (update.completed < lastCompleted)
throw new TypeError("Progress cannot move backwards");
lastCompleted = update.completed;
const observedAt = now();
if (
update.terminal !== true &&
observedAt - lastSentAt < minimumIntervalMs
)
return;
lastSentAt = observedAt;
sequence += 1;
await sink({ ...update, sequence });
},
};
};
/** Surface that deliberately ignores progress while preserving one workflow API. */
export const silentProgressReporter: ProgressReporter = {
report: () => Promise.resolve(),
};
+145
View File
@@ -0,0 +1,145 @@
import { createHash } from "node:crypto";
import { mkdir, readFile, realpath, stat } from "node:fs/promises";
import { dirname } from "node:path";
import writeFileAtomic from "write-file-atomic";
import { z } from "zod";
import type { PermissionGrant } from "../domain/permissionPolicy.js";
import { err, ok, type Result } from "../domain/result.js";
const grantSchema = z.object({
grant_id: z.string().min(1),
capability: z.enum([
"process_capture",
"evidence_read",
"evidence_write",
"investigation_input",
"investigation_workspace_read",
"investigation_workspace_write",
"snapshot_read",
"snapshot_write",
"artifact_extract",
"native_mount",
"reference_read",
]),
roots: z.array(z.string()),
executables: z.array(z.string()),
environment_names: z.array(z.string()),
network: z.enum(["none", "loopback", "external"]),
mount: z.boolean(),
lifetime: z.literal("project"),
operation_identity: z.string().nullable(),
expires_at: z.iso.datetime().nullable(),
});
const storeSchema = z.object({
schema_version: z.literal(1),
project_id: z.string().regex(/^project_[a-f0-9]{64}$/u),
project_root: z.string(),
grants: z.array(grantSchema).max(1_000),
});
export type ProjectPermissionStore = z.infer<typeof storeSchema>;
/** Owner-only project policy persistence failure. */
export class ProjectPermissionStoreError extends Error {
readonly _tag = "ProjectPermissionStoreError" as const;
constructor(
readonly reason: "project_not_found" | "not_owner_only" | "invalid" | "io",
options?: ErrorOptions,
) {
super(`Project permission store failed: ${reason}`, options);
}
}
/** Derive relocation-explicit project identity from its canonical root. */
const identifyPermissionProject = async (
projectRoot: string,
): Promise<
Result<
{ readonly id: string; readonly root: string },
ProjectPermissionStoreError
>
> => {
try {
const root = await realpath(projectRoot);
return ok({
id: `project_${createHash("sha256").update(root).digest("hex")}`,
root,
});
} catch (cause: unknown) {
return err(new ProjectPermissionStoreError("project_not_found", { cause }));
}
};
/** Read and validate an owner-only store bound to the requested project. */
export const readProjectPermissionStore = async (
path: string,
projectRoot: string,
): Promise<
Result<ProjectPermissionStore | null, ProjectPermissionStoreError>
> => {
const project = await identifyPermissionProject(projectRoot);
if (!project.ok) return project;
try {
const metadata = await stat(path);
if ((metadata.mode & 0o077) !== 0)
return err(new ProjectPermissionStoreError("not_owner_only"));
const parsed = storeSchema.safeParse(
JSON.parse(await readFile(path, "utf8")),
);
if (
!parsed.success ||
parsed.data.project_id !== project.value.id ||
parsed.data.project_root !== project.value.root
)
return err(new ProjectPermissionStoreError("invalid"));
return ok(parsed.data);
} catch (cause: unknown) {
if (isNotFound(cause)) return ok(null);
return err(new ProjectPermissionStoreError("io", { cause }));
}
};
/** Atomically replace explicit project grants with owner-only permissions. */
export const writeProjectPermissionStore = async (
path: string,
projectRoot: string,
grants: readonly PermissionGrant[],
): Promise<Result<ProjectPermissionStore, ProjectPermissionStoreError>> => {
const project = await identifyPermissionProject(projectRoot);
if (!project.ok) return project;
const candidate = storeSchema.safeParse({
schema_version: 1,
project_id: project.value.id,
project_root: project.value.root,
grants,
});
if (!candidate.success)
return err(
new ProjectPermissionStoreError("invalid", { cause: candidate.error }),
);
try {
await mkdir(dirname(path), { recursive: true, mode: 0o700 });
await writeFileAtomic(
path,
`${JSON.stringify(candidate.data, null, 2)}\n`,
{
encoding: "utf8",
mode: 0o600,
},
);
const metadata = await stat(path);
if ((metadata.mode & 0o077) !== 0) {
return err(new ProjectPermissionStoreError("not_owner_only"));
}
return ok(candidate.data);
} catch (cause: unknown) {
return err(new ProjectPermissionStoreError("io", { cause }));
}
};
const isNotFound = (cause: unknown): boolean =>
cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+4 -1
View File
@@ -17,7 +17,10 @@ export const createBinarySession = (
): BinarySession => {
return new BinarySession(
new CompositeProvider([
new ArtifactProvider(config.artifactNativeMountEnabled),
new ArtifactProvider(
config.artifactNativeMountEnabled,
config.artifactIntegrityContinueEnabled,
),
new NativeMacOSProvider(),
new HopperProvider(config, logger),
]),
+18 -3
View File
@@ -5,6 +5,7 @@ import {
type AnalysisProvider,
type CapabilityDescriptor,
type ProviderIdentity,
type ExecutionOptions,
} from "../application/AnalysisProvider.js";
import { inventoryArtifact } from "../application/ArtifactInventory.js";
import { extractArtifact } from "../application/ArtifactExtraction.js";
@@ -32,7 +33,10 @@ const IDENTITY: ProviderIdentity = Object.freeze(ARTIFACT_GRAPH_PROVIDER);
/** Read-only inventory and exclusively owned extraction provider. */
export class ArtifactProvider implements AnalysisProvider {
constructor(private readonly nativeMountEnabled = false) {}
constructor(
private readonly nativeMountEnabled = false,
private readonly integrityContinueEnabled = false,
) {}
readonly #capabilities: readonly CapabilityDescriptor[] = Object.freeze(
ARTIFACT_TOOL_CONTRACTS.map((contract) =>
@@ -76,7 +80,11 @@ export class ArtifactProvider implements AnalysisProvider {
}
createClient(target: BinaryTarget): AnalysisClient {
return new ArtifactClient(target, this.nativeMountEnabled);
return new ArtifactClient(
target,
this.nativeMountEnabled,
this.integrityContinueEnabled,
);
}
}
@@ -84,12 +92,13 @@ class ArtifactClient implements AnalysisClient {
constructor(
private readonly target: BinaryTarget,
private readonly nativeMountEnabled: boolean,
private readonly integrityContinueEnabled: boolean,
) {}
async execute(
operation: AnalysisOperation,
parameters: Readonly<Record<string, JsonValue>>,
options?: { readonly signal?: AbortSignal },
options?: ExecutionOptions,
) {
if (operation === "health")
return ok(createAnalysisExecution(null, IDENTITY));
@@ -151,6 +160,12 @@ class ArtifactClient implements AnalysisClient {
nativeMountApproved: parsed.native_mount_approved === true,
nativeMountEnabled: this.nativeMountEnabled,
},
integrity: {
mode: parsed.integrity_policy,
approved: parsed.integrity_continue_approved === true,
enabled: this.integrityContinueEnabled,
maxMismatches: parsed.max_integrity_mismatches,
},
},
);
return ok(
+54 -3
View File
@@ -19,8 +19,14 @@ import { importReferenceSource } from "./application/ReferenceSourceImport.js";
import { registerEvidenceCommands } from "./cliEvidenceCommands.js";
import { registerProcessCommands } from "./cliProcessCommands.js";
import { registerInvestigationCommands } from "./cliInvestigationCommands.js";
import { projectAnalysisError } from "./domain/errors.js";
import {
AnalysisProtocolError,
PermissionRequiredError,
projectAnalysisError,
} from "./domain/errors.js";
import { projectReferenceSourceImportError } from "./application/ReferenceSourceImportTypes.js";
import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
import { registerPolicyCommands } from "./cliPolicyCommands.js";
/**
* Build the one-shot Incur CLI without starting Hopper at import time.
@@ -35,7 +41,7 @@ export const createCli = (): ReturnType<typeof Cli.create> => {
: parseLogLevel(process.env.REA_LOG_LEVEL),
);
const cli = Cli.create(PRODUCT_IDENTITY.cliBinary, {
version: process.env.REA_PACKAGE_VERSION ?? "0.0.0-development",
version: PRODUCT_IDENTITY.packageVersion,
description: "Reverse engineer anything from your terminal or agent.",
mcp: {
command: PRODUCT_IDENTITY.mcpCommand,
@@ -66,6 +72,7 @@ export const createCli = (): ReturnType<typeof Cli.create> => {
registerEvidenceCommands(cli, logger);
registerReferenceSourceCommand(cli, logger);
registerProcessCommands(cli, logger);
registerPolicyCommands(cli, logger);
return cli;
};
@@ -190,7 +197,7 @@ const registerSetupCommands = (
run: ({ formatExplicit }) =>
logCliCommand(logger, "upgrade", () =>
runUpgrade(
process.env.REA_PACKAGE_VERSION ?? "0.0.0-development",
PRODUCT_IDENTITY.packageVersion,
systemUpgradeHost(),
formatExplicit ? "structured" : "human",
),
@@ -391,6 +398,36 @@ const registerReferenceSourceCommand = (
error: "Import failed",
...projectAnalysisError(config.error),
};
const authority = await loadConfiguredPermissionAuthority(config.value);
if (!authority.ok)
return {
error: "Import failed",
...projectAnalysisError(authority.error),
};
const authorized = await authority.value.authorize(
{
capability: "reference_read",
roots: [args.root],
executables: [],
environment_names: [],
network: "none",
mount: false,
operation_identity: `import_reference_source:${args.root}`,
},
"read",
);
if (!authorized.ok) {
const error =
authorized.error instanceof PermissionRequiredError
? authorized.error
: new AnalysisProtocolError(authorized.error.message, {
cause: authorized.error,
});
return {
error: "Import failed",
...projectAnalysisError(error),
};
}
const imported = await importReferenceSource({
root: args.root,
caller: "rea-cli",
@@ -420,7 +457,17 @@ const registerArtifactCommands = (
options: z.object({
offset: z.number().int().min(0).default(0),
limit: z.number().int().min(1).max(500).default(100),
integrityPolicy: z.enum(["fail", "record-and-continue"]).default("fail"),
integrityContinueApproved: z.boolean().default(false),
maxIntegrityMismatches: z.number().int().min(1).max(100).default(10),
nativeMountApproved: z.boolean().default(false),
}),
alias: {
integrityPolicy: "integrity-policy",
integrityContinueApproved: "integrity-continue-approved",
maxIntegrityMismatches: "max-integrity-mismatches",
nativeMountApproved: "native-mount-approved",
},
run: ({ args, options }) =>
logCliCommand(logger, "inventory-artifact", () =>
runProviderAnalysis(
@@ -433,6 +480,10 @@ const registerArtifactCommands = (
occurrence_limit: options.limit,
edge_offset: options.offset,
edge_limit: options.limit,
integrity_policy: options.integrityPolicy,
integrity_continue_approved: options.integrityContinueApproved,
max_integrity_mismatches: options.maxIntegrityMismatches,
native_mount_approved: options.nativeMountApproved,
},
logger,
),
+55 -1
View File
@@ -9,7 +9,14 @@ import { parseConfig } from "./config.js";
import { logCliCommand } from "./cliLogging.js";
import type { Logger } from "./logger.js";
import type { JsonValue } from "./domain/jsonValue.js";
import { projectAnalysisError, type AnalysisError } from "./domain/errors.js";
import {
AnalysisProtocolError,
PermissionRequiredError,
projectAnalysisError,
type AnalysisError,
} from "./domain/errors.js";
import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
import type { AppConfig } from "./config.js";
/** Register filesystem-gated Evidence v2 commands. */
export const registerEvidenceCommands = (
@@ -25,6 +32,10 @@ export const registerEvidenceCommands = (
logCliCommand(logger, "evidence-import", async () => {
const config = parseConfig(process.env);
if (!config.ok) return cliError(config.error);
const denied = await authorizeEvidence(config.value, [
{ capability: "evidence_read", path: args.path, access: "read" },
]);
if (denied !== undefined) return cliError(denied);
const imported = await importEvidenceBundleCommand(
args.path,
config.value.evidenceFilePolicy,
@@ -45,6 +56,11 @@ export const registerEvidenceCommands = (
logCliCommand(logger, "evidence-export", async () => {
const config = parseConfig(process.env);
if (!config.ok) return cliError(config.error);
const denied = await authorizeEvidence(config.value, [
{ capability: "evidence_read", path: args.source, access: "read" },
{ capability: "evidence_write", path: args.output, access: "write" },
]);
if (denied !== undefined) return cliError(denied);
const exported = await exportEvidenceBundleCommand(
args.source,
args.output,
@@ -69,6 +85,11 @@ export const registerEvidenceCommands = (
logCliCommand(logger, "compare", async () => {
const config = parseConfig(process.env);
if (!config.ok) return cliError(config.error);
const denied = await authorizeEvidence(config.value, [
{ capability: "evidence_read", path: args.left, access: "read" },
{ capability: "evidence_read", path: args.right, access: "read" },
]);
if (denied !== undefined) return cliError(denied);
const compared = await compareEvidenceBundlesCommand({
leftPath: args.left,
rightPath: args.right,
@@ -81,6 +102,39 @@ export const registerEvidenceCommands = (
});
};
const authorizeEvidence = async (
config: AppConfig,
requests: readonly {
readonly capability: "evidence_read" | "evidence_write";
readonly path: string;
readonly access: "read" | "write";
}[],
): Promise<AnalysisError | undefined> => {
const authority = await loadConfiguredPermissionAuthority(config);
if (!authority.ok) return authority.error;
for (const request of requests) {
const result = await authority.value.authorize(
{
capability: request.capability,
roots: [request.path],
executables: [],
environment_names: [],
network: "none",
mount: false,
operation_identity: `cli:${request.capability}:${request.path}`,
},
request.access,
);
if (!result.ok)
return result.error instanceof PermissionRequiredError
? result.error
: new AnalysisProtocolError(result.error.message, {
cause: result.error,
});
}
return undefined;
};
const cliError = (error: AnalysisError): JsonValue => ({
error: "Analysis failed",
...projectAnalysisError(error),
+60 -2
View File
@@ -3,8 +3,14 @@ import { Cli, z } from "incur";
import { runCrossVersionInvestigation } from "./application/CrossVersionInvestigation.js";
import { logCliCommand } from "./cliLogging.js";
import { parseConfig } from "./config.js";
import { projectAnalysisError, type AnalysisError } from "./domain/errors.js";
import {
AnalysisProtocolError,
PermissionRequiredError,
projectAnalysisError,
type AnalysisError,
} from "./domain/errors.js";
import type { Logger } from "./logger.js";
import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
const investigationOptionsSchema = z.object({
yes: z
@@ -28,6 +34,9 @@ const investigationOptionsSchema = z.object({
.default(268_435_456),
pageSize: z.number().int().min(1).max(500).default(500),
changeLimit: z.number().int().min(1).max(500).default(500),
integrityPolicy: z.enum(["fail", "record-and-continue"]).default("fail"),
integrityContinueApproved: z.boolean().default(false),
maxIntegrityMismatches: z.number().int().min(1).max(100).default(10),
});
/** Register the persistent cross-version CLI workflow. */
@@ -52,6 +61,9 @@ export const registerInvestigationCommands = (
maxEntryBytes: "max-entry-bytes",
pageSize: "page-size",
changeLimit: "change-limit",
integrityPolicy: "integrity-policy",
integrityContinueApproved: "integrity-continue-approved",
maxIntegrityMismatches: "max-integrity-mismatches",
yes: "y",
},
run: ({ args, options }) =>
@@ -76,6 +88,46 @@ const runInvestigation = async (
};
const config = parseConfig(process.env);
if (!config.ok) return cliError(config.error);
const authority = await loadConfiguredPermissionAuthority(config.value);
if (!authority.ok) return cliError(authority.error);
for (const scope of [
{
capability: "investigation_workspace_read" as const,
roots: [args.workspacePath],
access: "write" as const,
},
{
capability: "investigation_workspace_write" as const,
roots: [args.workspacePath],
access: "write" as const,
},
{
capability: "investigation_input" as const,
roots: [args.leftPath, args.rightPath],
access: "read" as const,
},
]) {
const authorized = await authority.value.authorize(
{
capability: scope.capability,
roots: scope.roots,
executables: [],
environment_names: [],
network: "none",
mount: false,
operation_identity: `investigate_versions:${scope.capability}:${scope.roots.join(":")}`,
},
scope.access,
);
if (!authorized.ok)
return cliError(
authorized.error instanceof PermissionRequiredError
? authorized.error
: new AnalysisProtocolError(authorized.error.message, {
cause: authorized.error,
}),
);
}
const investigated = await runCrossVersionInvestigation(
{
approved: true,
@@ -86,6 +138,9 @@ const runInvestigation = async (
: { expected_workspace_revision: options.expectedRevision }),
left_path: args.leftPath,
right_path: args.rightPath,
integrity_policy: options.integrityPolicy,
integrity_continue_approved: options.integrityContinueApproved,
max_integrity_mismatches: options.maxIntegrityMismatches,
options: {
max_entries: options.maxEntries,
max_total_bytes: options.maxTotalBytes,
@@ -98,7 +153,10 @@ const runInvestigation = async (
},
},
config.value.evidenceFilePolicy,
{ inputRoots: config.value.investigationInputRoots },
{
inputRoots: config.value.investigationInputRoots,
integrityContinueEnabled: config.value.artifactIntegrityContinueEnabled,
},
);
return investigated.ok
? investigated.value.evidence
+160
View File
@@ -0,0 +1,160 @@
import { Cli, z } from "incur";
import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
import {
readProjectPermissionStore,
writeProjectPermissionStore,
} from "./application/ProjectPermissionStore.js";
import { logCliCommand } from "./cliLogging.js";
import { parseConfig, type AppConfig } from "./config.js";
import {
PermissionRequiredError,
projectAnalysisError,
} from "./domain/errors.js";
import type { PermissionCapability } from "./domain/permissionPolicy.js";
import type { Logger } from "./logger.js";
const capabilitySchema = z.enum([
"process_capture",
"evidence_read",
"evidence_write",
"investigation_input",
"investigation_workspace_read",
"investigation_workspace_write",
"snapshot_read",
"snapshot_write",
"artifact_extract",
"native_mount",
"reference_read",
]);
/** Register inspectable, dry-run, and revocation policy UX for the CLI. */
export const registerPolicyCommands = (
cli: ReturnType<typeof Cli.create>,
logger: Logger,
): void => {
cli.command("policy", {
description: "Inspect, explain, or revoke unified local permission grants",
args: z.object({
action: z.enum(["status", "list", "explain", "revoke"]),
value: z.string().optional(),
}),
options: z.object({
root: z.string().optional(),
executable: z.string().optional(),
environmentNames: z.array(z.string()).default([]),
network: z.enum(["none", "loopback", "external"]).default("none"),
mount: z.boolean().default(false),
write: z.boolean().default(false),
}),
alias: { environmentNames: "environment-names" },
run: ({ args, options }) =>
logCliCommand(logger, "policy", async () => {
const config = parseConfig(process.env);
if (!config.ok) return failure(config.error);
if (args.action === "status")
return {
reload: "SIGHUP",
restart_required: false,
administrator_ceilings: config.value.permissionCeilings,
project_store: config.value.permissionProjectStore ?? null,
};
if (args.action === "list")
return readProjectGrants(config.value).then((result) =>
result.ok ? { grants: result.grants } : result.error,
);
if (args.action === "revoke") {
if (args.value === undefined)
return { error: "Grant ID is required for policy revoke" };
const result = await readProjectGrants(config.value);
if (!result.ok) return result.error;
const retained = result.grants.filter(
({ grant_id }) => grant_id !== args.value,
);
if (retained.length === result.grants.length)
return { error: "Grant was not found", grant_id: args.value };
const written = await writeProjectPermissionStore(
result.path,
result.root,
retained,
);
return written.ok
? {
revoked: args.value,
reload: "Send SIGHUP to the REA MCP process",
}
: { error: written.error.message };
}
const capability = capabilitySchema.safeParse(args.value);
if (!capability.success)
return {
error: "A registered capability is required for policy explain",
};
return explain(config.value, capability.data, options);
}),
});
};
const explain = async (
config: AppConfig,
capability: PermissionCapability,
options: {
readonly root?: string | undefined;
readonly executable?: string | undefined;
readonly environmentNames: readonly string[];
readonly network: "none" | "loopback" | "external";
readonly mount: boolean;
readonly write: boolean;
},
) => {
const authority = await loadConfiguredPermissionAuthority(config);
if (!authority.ok) return failure(authority.error);
const evaluated = await authority.value.explain(
{
capability,
roots: options.root === undefined ? [] : [options.root],
executables: options.executable === undefined ? [] : [options.executable],
environment_names: options.environmentNames,
network: options.network,
mount: options.mount,
operation_identity: `policy_explain:${capability}`,
},
options.write ? "write" : "read",
);
return evaluated.ok
? { allowed: true, grant_id: evaluated.value.grant_id }
: evaluated.error instanceof PermissionRequiredError
? { allowed: false, error: projectAnalysisError(evaluated.error) }
: { allowed: false, error: evaluated.error.message };
};
const readProjectGrants = async (config: {
readonly permissionProjectRoot: string | undefined;
readonly permissionProjectStore: string | undefined;
}) => {
if (
config.permissionProjectRoot === undefined ||
config.permissionProjectStore === undefined
)
return {
ok: false as const,
error: { error: "Project policy is not configured" },
};
const store = await readProjectPermissionStore(
config.permissionProjectStore,
config.permissionProjectRoot,
);
return store.ok
? {
ok: true as const,
grants: store.value?.grants ?? [],
path: config.permissionProjectStore,
root: config.permissionProjectRoot,
}
: { ok: false as const, error: { error: store.error.message } };
};
const failure = (error: Parameters<typeof projectAnalysisError>[0]) => ({
error: "Policy command failed",
...projectAnalysisError(error),
});
+107 -22
View File
@@ -6,6 +6,10 @@ import type { LogLevel } from "./logger.js";
import type { ProcessExecutionPolicy } from "./domain/processCapture.js";
import type { EvidenceFilePolicy } from "./domain/evidenceBundle.js";
import type { ReferenceSourcePolicy } from "./domain/referenceSourcePolicy.js";
import type {
PermissionCeiling,
PermissionGrant,
} from "./domain/permissionPolicy.js";
const DEFAULT_HOPPER_LAUNCHER_PATH =
"/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
@@ -22,34 +26,58 @@ export interface AppConfig {
readonly logLevel: LogLevel;
readonly processExecutionPolicy: ProcessExecutionPolicy;
readonly artifactNativeMountEnabled: boolean;
readonly artifactIntegrityContinueEnabled: boolean;
readonly evidenceFilePolicy: EvidenceFilePolicy;
readonly investigationInputRoots: readonly string[];
readonly analysisSnapshotFilePolicy: EvidenceFilePolicy;
readonly referenceSourcePolicy: ReferenceSourcePolicy;
readonly permissionCeilings: readonly PermissionCeiling[];
readonly administratorPermissionGrants: readonly PermissionGrant[];
readonly permissionProjectRoot: string | undefined;
readonly permissionProjectStore: string | undefined;
}
const environmentSchema = z.object({
HOPPER_LAUNCHER_PATH: z.string().min(1).optional(),
HOPPER_TARGET_PATH: z.string().min(1).optional(),
HOPPER_TARGET_KIND: z.enum(["executable", "database"]).default("executable"),
HOPPER_LOADER_ARGS_JSON: z.string().optional(),
REA_LOG_LEVEL: z
.enum(["trace", "debug", "info", "warn", "error", "fatal", "silent"])
.default("info"),
REA_PROCESS_CAPTURE_ENABLED: z.enum(["true", "false"]).default("false"),
REA_ARTIFACT_NATIVE_MOUNT_ENABLED: z.enum(["true", "false"]).default("false"),
REA_PROCESS_ALLOW_EXTERNAL_NETWORK: z
.enum(["true", "false"])
.default("false"),
REA_PROCESS_EXECUTABLE_ROOTS_JSON: z.string().default("[]"),
REA_PROCESS_WORKING_ROOTS_JSON: z.string().default("[]"),
REA_PROCESS_ALLOWED_ENV_JSON: z.string().default("[]"),
REA_EVIDENCE_ROOTS_JSON: z.string().default("[]"),
REA_INVESTIGATION_INPUT_ROOTS_JSON: z.string().default("[]"),
REA_ANALYSIS_SNAPSHOT_ROOTS_JSON: z.string().default("[]"),
REA_REFERENCE_ROOTS_JSON: z.string().default("[]"),
REA_REFERENCE_SECRET_PATTERNS_JSON: z.string().default("[]"),
});
const environmentSchema = z
.object({
HOPPER_LAUNCHER_PATH: z.string().min(1).optional(),
HOPPER_TARGET_PATH: z.string().min(1).optional(),
HOPPER_TARGET_KIND: z
.enum(["executable", "database"])
.default("executable"),
HOPPER_LOADER_ARGS_JSON: z.string().optional(),
REA_LOG_LEVEL: z
.enum(["trace", "debug", "info", "warn", "error", "fatal", "silent"])
.default("info"),
REA_PROCESS_CAPTURE_ENABLED: z.enum(["true", "false"]).default("false"),
REA_ARTIFACT_NATIVE_MOUNT_ENABLED: z
.enum(["true", "false"])
.default("false"),
REA_ARTIFACT_INTEGRITY_CONTINUE_ENABLED: z
.enum(["true", "false"])
.default("false"),
REA_PROCESS_ALLOW_EXTERNAL_NETWORK: z
.enum(["true", "false"])
.default("false"),
REA_PROCESS_EXECUTABLE_ROOTS_JSON: z.string().default("[]"),
REA_PROCESS_WORKING_ROOTS_JSON: z.string().default("[]"),
REA_PROCESS_ALLOWED_ENV_JSON: z.string().default("[]"),
REA_EVIDENCE_ROOTS_JSON: z.string().default("[]"),
REA_INVESTIGATION_INPUT_ROOTS_JSON: z.string().default("[]"),
REA_ANALYSIS_SNAPSHOT_ROOTS_JSON: z.string().default("[]"),
REA_REFERENCE_ROOTS_JSON: z.string().default("[]"),
REA_REFERENCE_SECRET_PATTERNS_JSON: z.string().default("[]"),
REA_PERMISSION_PROJECT_ROOT: z.string().min(1).optional(),
REA_PERMISSION_PROJECT_STORE: z.string().min(1).optional(),
})
.refine(
(value) =>
(value.REA_PERMISSION_PROJECT_ROOT === undefined) ===
(value.REA_PERMISSION_PROJECT_STORE === undefined),
{
message:
"REA_PERMISSION_PROJECT_ROOT and REA_PERMISSION_PROJECT_STORE must be configured together",
},
);
const parseStringArray = (
encoded: string,
@@ -80,6 +108,30 @@ const filePolicy = (roots: readonly string[]): EvidenceFilePolicy => ({
maxNodes: 1_000_000,
});
const permissionScope = (
capability: PermissionCeiling["capability"],
roots: readonly string[],
options: Partial<Omit<PermissionCeiling, "capability" | "roots">> = {},
): PermissionCeiling => ({
capability,
roots,
executables: options.executables ?? [],
environment_names: options.environment_names ?? [],
network: options.network ?? "none",
mount: options.mount ?? false,
});
const administratorGrants = (
ceilings: readonly PermissionCeiling[],
): readonly PermissionGrant[] =>
ceilings.map((ceiling) => ({
...ceiling,
grant_id: `administrator:${ceiling.capability}`,
lifetime: "administrator",
operation_identity: null,
expires_at: null,
}));
const parseLoaderArgs = (
encoded: string | undefined,
): Result<readonly string[], ConfigurationError> => {
@@ -166,6 +218,33 @@ export const parseConfig = (
"REA_REFERENCE_SECRET_PATTERNS_JSON",
);
if (!secretPatterns.ok) return secretPatterns;
const permissionCeilings = [
...(parsedEnvironment.data.REA_PROCESS_CAPTURE_ENABLED === "true"
? [
permissionScope("process_capture", workingRoots.value, {
executables: executableRoots.value,
environment_names: allowedEnvironment.value,
network:
parsedEnvironment.data.REA_PROCESS_ALLOW_EXTERNAL_NETWORK ===
"true"
? "external"
: "none",
}),
]
: []),
permissionScope("evidence_read", evidenceRoots.value),
permissionScope("evidence_write", evidenceRoots.value),
permissionScope("investigation_input", investigationInputRoots.value),
permissionScope("investigation_workspace_read", evidenceRoots.value),
permissionScope("investigation_workspace_write", evidenceRoots.value),
permissionScope("snapshot_read", analysisSnapshotRoots.value),
permissionScope("snapshot_write", analysisSnapshotRoots.value),
permissionScope("artifact_extract", ["/"]),
permissionScope("reference_read", referenceRoots.value),
...(parsedEnvironment.data.REA_ARTIFACT_NATIVE_MOUNT_ENABLED === "true"
? [permissionScope("native_mount", [], { mount: true })]
: []),
] satisfies readonly PermissionCeiling[];
return ok({
hopperLauncherPath:
parsedEnvironment.data.HOPPER_LAUNCHER_PATH ??
@@ -184,6 +263,8 @@ export const parseConfig = (
},
artifactNativeMountEnabled:
parsedEnvironment.data.REA_ARTIFACT_NATIVE_MOUNT_ENABLED === "true",
artifactIntegrityContinueEnabled:
parsedEnvironment.data.REA_ARTIFACT_INTEGRITY_CONTINUE_ENABLED === "true",
evidenceFilePolicy: filePolicy(evidenceRoots.value),
investigationInputRoots: investigationInputRoots.value,
analysisSnapshotFilePolicy: filePolicy(analysisSnapshotRoots.value),
@@ -195,5 +276,9 @@ export const parseConfig = (
maxDepth: 32,
maxPathBytes: 4_096,
},
permissionCeilings,
administratorPermissionGrants: administratorGrants(permissionCeilings),
permissionProjectRoot: parsedEnvironment.data.REA_PERMISSION_PROJECT_ROOT,
permissionProjectStore: parsedEnvironment.data.REA_PERMISSION_PROJECT_STORE,
});
};
+20 -5
View File
@@ -33,11 +33,26 @@ const traversalLimitsInput = {
};
/** Exact caller boundary for deterministic artifact inventory. */
export const artifactInventoryInputSchema = z.object({
native_mount_approved: z.boolean().default(false),
...pageInput,
...traversalLimitsInput,
});
export const artifactInventoryInputSchema = z
.object({
native_mount_approved: z.boolean().default(false),
integrity_policy: z.enum(["fail", "record-and-continue"]).default("fail"),
integrity_continue_approved: z.boolean().default(false),
max_integrity_mismatches: z.number().int().min(1).max(100).default(10),
...pageInput,
...traversalLimitsInput,
})
.superRefine((input, context) => {
if (
input.integrity_policy === "record-and-continue" &&
input.integrity_continue_approved !== true
)
context.addIssue({
code: "custom",
path: ["integrity_continue_approved"],
message: "record-and-continue requires explicit approval",
});
});
/** Exact caller boundary for approved artifact extraction. */
export const artifactExtractionInputSchema = z.object({
+105
View File
@@ -0,0 +1,105 @@
import { z } from "zod";
const categorySchema = z.enum([
"invalid_input",
"permission_required",
"unsupported_provider",
"integrity_mismatch",
"truncated",
"cancelled",
"timeout",
"unavailable",
"execution_failure",
]);
const remediationSchema = z
.object({
action: z.string().min(1),
restart_required: z.boolean(),
elicitation_supported: z.boolean().optional(),
})
.strict();
const common = {
category: categorySchema,
message: z.string().min(1),
retryable: z.boolean(),
remediation: remediationSchema,
};
const genericDetails = z.record(z.string(), z.json()).optional();
const generic = <Code extends string>(code: Code) =>
z
.object({ code: z.literal(code), ...common, details: genericDetails })
.strict();
const scopeSchema = z
.object({
capability: z.string(),
roots: z.array(z.string()),
executables: z.array(z.string()),
environment_names: z.array(z.string()),
network: z.enum(["none", "loopback", "external"]),
mount: z.boolean(),
})
.strict();
const missingScopeSchema = z
.object({
roots: z.array(z.string()).optional(),
executables: z.array(z.string()).optional(),
environment_names: z.array(z.string()).optional(),
network: z.enum(["none", "loopback", "external"]).optional(),
mount: z.literal(true).optional(),
})
.strict();
/** Stable discriminated schema shared by every CLI and MCP error surface. */
export const analysisErrorProjectionSchema = z.discriminatedUnion("code", [
generic("invalid_request"),
generic("unreadable_output"),
generic("capability_unavailable"),
generic("provider_unavailable"),
generic("provider_timeout"),
generic("cancelled"),
z
.object({
code: z.literal("artifact_integrity_mismatch"),
...common,
details: z
.object({
logical_path: z.string(),
declared_sha256: z.string().nullable(),
calculated_sha256: z.string().nullable(),
unpacked: z.boolean(),
})
.strict(),
})
.strict(),
generic("artifact_operation_failed"),
generic("evidence_integrity_mismatch"),
generic("truncated"),
z
.object({
code: z.literal("permission_required"),
...common,
details: z
.object({
capability: z.string(),
requested: scopeSchema,
missing: missingScopeSchema,
ceiling: scopeSchema.nullable(),
})
.strict()
.optional(),
})
.strict(),
generic("process_capture_failed"),
generic("cleanup_incomplete"),
generic("revision_conflict"),
generic("outside_approved_root"),
generic("configuration_invalid"),
generic("target_unavailable"),
generic("execution_failure"),
]);
/** JSON Schema document used by generated API documentation and clients. */
export const analysisErrorJsonSchema = z.toJSONSchema(
analysisErrorProjectionSchema,
);
+11 -1
View File
@@ -389,6 +389,16 @@ export const ENHANCED_TOOL_CONTRACTS = [
),
] as const satisfies readonly ToolContract[];
/** Caller observations used to compare a live server with expected identity. */
export const binarySessionInputSchema = z.object({
expected_package_version: z.string().min(1).optional(),
expected_catalog_digest: z
.string()
.regex(/^[a-f0-9]{64}$/u)
.optional(),
expected_server_path: z.string().min(1).optional(),
});
/** Target lifecycle tools available only on the long-lived MCP adapter. */
export const SESSION_TOOL_CONTRACTS = [
session(
@@ -404,7 +414,7 @@ export const SESSION_TOOL_CONTRACTS = [
session(
"binary_session",
"Report provider identity, deterministic capability descriptors, and whether a target is open; open targets include canonical path, format, and kind. Use availability, effects, limits, and limitations before selecting analysis operations.",
z.object({}),
binarySessionInputSchema,
),
session(
"export_evidence_bundle",
+64 -39
View File
@@ -25,6 +25,7 @@ import { changedBehaviorResultSchema } from "../domain/changedBehavior.js";
import { callPathResultSchema } from "../domain/callPath.js";
import { staticRuntimeCorrelationResultSchema } from "../domain/staticRuntimeCorrelation.js";
import { reconstructionVerificationResultSchema } from "../domain/reconstructionVerification.js";
import { analysisErrorProjectionSchema } from "./errorSchemas.js";
const resultOf = (schema: z.ZodType) =>
evidenceSchema
@@ -96,6 +97,69 @@ const sessionProvider = z.object({
provider: providerIdentity,
providers: z.array(providerIdentity),
capabilities: z.array(providerCapability),
tool_availability: z.array(
z.object({
name: z.string(),
surface: z.string(),
available: z.boolean(),
reason: z.enum([
"available",
"target_required",
"provider_missing",
"provider_unavailable",
"target_unsupported",
"unsupported_host",
"policy_disabled",
]),
remediation: z.string().nullable(),
annotations: z.object({
read_only: z.boolean(),
destructive: z.boolean(),
idempotent: z.boolean(),
open_world: z.boolean(),
}),
}),
),
client_features: z.object({
elicitation_form: z.boolean(),
elicitation_url: z.boolean(),
roots: z.boolean(),
sampling: z.boolean(),
}),
server_identity: z.object({
package: z.object({
name: z.string(),
version: z.string(),
root_path: z.string(),
build_commit: z.string().nullable(),
}),
server: z.object({
name: z.string(),
version: z.string(),
started_at: z.string(),
command_path: z.string(),
}),
sdk: z.object({
server: z.string(),
client_test: z.string(),
core: z.string(),
}),
negotiated_protocol_version: z.string().nullable(),
client: z.object({ name: z.string(), version: z.string() }).nullable(),
skill: z.object({ name: z.string(), expected_version: z.string() }),
catalog: z.record(z.string(), z.json()),
protocol_features: z.object({
progress: z.boolean(),
cancellation: z.boolean(),
evidence_resources: z.boolean(),
elicitation: z.boolean(),
}),
alignment: z.object({
state: z.enum(["aligned", "mcp_server_restart_required", "unknown"]),
reasons: z.array(z.string()),
remediation: z.string().nullable(),
}),
}),
});
const nullableText = z.string().nullable();
const addressList = z.array(z.string());
@@ -177,45 +241,6 @@ const symbolDiscoveryOutput = (property: "classes" | "protocols") =>
[property]: z.array(addressedEntry),
}),
);
const analysisErrorProjectionSchema = z
.object({
category: z.enum([
"invalid_input",
"permission_required",
"unsupported_provider",
"integrity_mismatch",
"truncated",
"cancelled",
"timeout",
"unavailable",
"execution_failure",
]),
message: z.string(),
details: z
.object({
logical_path: z.string(),
declared_sha256: z.string().nullable(),
calculated_sha256: z.string().nullable(),
unpacked: z.boolean(),
})
.strict()
.optional(),
code: z
.enum([
"private_display_unavailable",
"x11_authorization_failed",
"unsupported_hopper_build",
"invalid_launch_command",
"process_ownership_mismatch",
"hopper_exited_during_startup",
"unsupported_demo_dialog",
"unexpected_display_geometry",
"x11_input_failed",
"runtime_dependency_unavailable",
])
.optional(),
})
.strict();
const graphNode = z.discriminatedUnion("status", [
z.object({
address: z.string(),
+48 -11
View File
@@ -20,8 +20,15 @@ const comparisonStatusSchema = z.enum([
"changed",
"truncated",
"unknown",
"contradiction",
]);
const changeKindSchema = z.enum([
"added",
"removed",
"changed",
"unknown",
"contradiction",
]);
const changeKindSchema = z.enum(["added", "removed", "changed", "unknown"]);
const comparisonDimensionSchema = z.enum([
"content",
"kind",
@@ -31,6 +38,7 @@ const comparisonDimensionSchema = z.enum([
"relations",
"metadata",
"availability",
"integrity",
]);
/** Strict Evidence-backed input for deterministic artifact comparison. */
@@ -80,6 +88,7 @@ export const artifactComparisonResultSchema = z.object({
removed: z.number().int().min(0),
changed: z.number().int().min(0),
unknown: z.number().int().min(0),
contradiction: z.number().int().min(0).default(0),
}),
changes: z.object({
items: z.array(artifactChangeSchema).max(500),
@@ -107,9 +116,10 @@ export const compareArtifacts = (
const right = parseArtifactInventoryEvidence(rightEvidence);
const leftComplete = left.inventory.complete;
const rightComplete = right.inventory.complete;
const leftCovered = leftComplete && left.inventory.limitations.length === 0;
const leftCovered =
leftComplete && !hasCoverageLimitation(left.inventory.limitations);
const rightCovered =
rightComplete && right.inventory.limitations.length === 0;
rightComplete && !hasCoverageLimitation(right.inventory.limitations);
const limitations = [
...left.inventory.limitations.map((item) => `Left: ${item}`),
...right.inventory.limitations.map((item) => `Right: ${item}`),
@@ -136,13 +146,17 @@ export const compareArtifacts = (
status:
!leftComplete || !rightComplete
? "truncated"
: !leftCovered || !rightCovered
? "unknown"
: changes.some(({ classification }) => classification === "unknown")
: changes.some(
({ classification }) => classification === "contradiction",
)
? "contradiction"
: !leftCovered || !rightCovered
? "unknown"
: changes.length === 0
? "unchanged"
: "changed",
: changes.some(({ classification }) => classification === "unknown")
? "unknown"
: changes.length === 0
? "unchanged"
: "changed",
left_manifest_id: left.inventory.manifest.manifest_id,
right_manifest_id: right.inventory.manifest.manifest_id,
summary,
@@ -230,6 +244,15 @@ const classifyPath = (input: {
classification: input.complete ? "removed" : "unknown",
dimensions: [input.complete ? "content" : "availability"],
};
if (
input.leftOccurrence.hash_status === "mismatched" ||
input.rightOccurrence.hash_status === "mismatched"
)
return {
...base,
classification: "contradiction",
dimensions: ["integrity"],
};
if (
input.leftOccurrence.hash_status !== "verified" ||
input.rightOccurrence.hash_status !== "verified" ||
@@ -362,7 +385,13 @@ const summarize = (
changes: readonly ArtifactChange[],
covered: boolean,
) => {
const counts = { added: 0, removed: 0, changed: 0, unknown: 0 };
const counts = {
added: 0,
removed: 0,
changed: 0,
unknown: 0,
contradiction: 0,
};
for (const change of changes) counts[change.classification] += 1;
return {
unchanged: covered
@@ -370,6 +399,7 @@ const summarize = (
0,
Math.min(left.occurrences.length, right.occurrences.length) -
counts.changed -
counts.contradiction -
counts.unknown,
)
: 0,
@@ -384,7 +414,14 @@ const summarize = (
) -
counts.added -
counts.removed -
counts.changed,
counts.changed -
counts.contradiction,
),
};
};
const hasCoverageLimitation = (limitations: readonly string[]): boolean =>
limitations.some(
(limitation) =>
!/integrity contradiction\(s\) were recorded/u.test(limitation),
);
+29 -1
View File
@@ -6,6 +6,7 @@ const occurrenceIdSchema = z.string().regex(/^occ_[a-f0-9]{64}$/u);
const edgeIdSchema = z.string().regex(/^edge_[a-f0-9]{64}$/u);
const manifestIdSchema = z.string().regex(/^agm_[a-f0-9]{64}$/u);
const extractionIdSchema = z.string().regex(/^aex_[a-f0-9]{64}$/u);
const contradictionIdSchema = z.string().regex(/^ic_[a-f0-9]{64}$/u);
const boundedRelativePathSchema = z
.string()
.min(1)
@@ -121,11 +122,31 @@ const artifactOccurrenceSchema = z.object({
.nullable(),
executable: z.boolean(),
encrypted: z.boolean(),
hash_status: z.enum(["verified", "not-hashed-limit", "unavailable"]),
hash_status: z.enum([
"verified",
"mismatched",
"not-hashed-limit",
"unavailable",
]),
source_location: artifactByteRangeSchema.nullable(),
limitations: z.array(z.string()),
});
/** Observed bytes that contradict a container's declared integrity identity. */
const integrityContradictionSchema = z.object({
contradiction_id: contradictionIdSchema,
occurrence_id: occurrenceIdSchema,
parent_artifact_id: artifactIdSchema,
logical_path: boundedRelativePathSchema,
declared_sha256: sha256Schema,
observed_sha256: sha256Schema,
entry_kind: z.enum(["file", "slice"]),
unpacked: z.boolean(),
trust: z.literal("observed-untrusted"),
provenance: z.literal("container-integrity-metadata-versus-observed-bytes"),
limitations: z.array(z.string()).min(1),
});
/** Parent-child derivation relation between two content-addressed artifacts. */
const artifactEdgeSchema = z.object({
edge_id: edgeIdSchema,
@@ -177,6 +198,10 @@ export const artifactInventoryResultSchema = z.object({
edges: artifactPageSchema(artifactEdgeSchema),
limits: artifactTraversalLimitsSchema,
provenance: z.array(artifactCommandSchema).max(256),
integrity_contradictions: z
.array(integrityContradictionSchema)
.max(100)
.default([]),
limitations: z.array(z.string()),
});
@@ -224,6 +249,9 @@ export type ArtifactEdge = z.infer<typeof artifactEdgeSchema>;
/** Parsed artifact occurrence. */
export type ArtifactOccurrence = z.infer<typeof artifactOccurrenceSchema>;
export type IntegrityContradiction = z.infer<
typeof integrityContradictionSchema
>;
/** Parsed deterministic artifact graph manifest. */
export type ArtifactGraphManifest = z.infer<typeof artifactGraphManifestSchema>;
+30
View File
@@ -7,6 +7,7 @@ import {
type ArtifactInventoryResult,
type ArtifactNode,
type ArtifactOccurrence,
type IntegrityContradiction,
} from "./artifactGraph.js";
import { parseEvidence, type Evidence } from "./evidence.js";
@@ -16,6 +17,7 @@ export interface InventorySet {
readonly nodes: readonly ArtifactNode[];
readonly occurrences: readonly ArtifactOccurrence[];
readonly edges: readonly ArtifactInventoryResult["edges"]["items"][number][];
readonly integrityContradictions: readonly IntegrityContradiction[];
readonly limitations: readonly string[];
readonly complete: boolean;
}
@@ -99,6 +101,13 @@ const assembleInventorySet = (
for (const page of pages) {
if (canonicalJson(page.inventory.manifest) !== manifestJson)
throw new TypeError("Artifact inventory pages do not share one manifest");
if (
canonicalJson(page.inventory.integrity_contradictions) !==
canonicalJson(first.inventory.integrity_contradictions)
)
throw new TypeError(
"Artifact inventory pages do not share integrity contradictions",
);
for (const node of page.inventory.nodes.items)
mergeExact(nodes, node.artifact_id, node, "node");
for (const occurrence of page.inventory.occurrences.items) {
@@ -148,6 +157,7 @@ const orderedInventory = (
nodes,
occurrences,
edges,
integrityContradictions: first.integrity_contradictions,
limitations: [
...new Set(pages.flatMap(({ inventory }) => inventory.limitations)),
].sort((left, right) => left.localeCompare(right)),
@@ -174,10 +184,30 @@ const validateCompleteInventory = (inventory: InventorySet): void => {
validateOccurrence(occurrence, inventory, nodeIds, occurrenceIds);
for (const edge of inventory.edges)
validateEdge(edge, nodeIds, occurrenceIds);
for (const contradiction of inventory.integrityContradictions) {
if (
!nodeIds.has(contradiction.parent_artifact_id) ||
!occurrenceIds.has(contradiction.occurrence_id)
)
throw new TypeError(
"Integrity contradiction references a missing graph member",
);
const expectedId = `ic_${digestCanonical({
root_artifact_id: inventory.manifest.root_artifact_id,
logical_path: contradiction.logical_path,
declared_sha256: contradiction.declared_sha256,
observed_sha256: contradiction.observed_sha256,
})}`;
if (contradiction.contradiction_id !== expectedId)
throw new TypeError(
"Integrity contradiction ID does not match its identity",
);
}
const graphSha256 = digestCanonical({
nodes: inventory.nodes,
occurrences: inventory.occurrences,
edges: inventory.edges,
integrity_contradictions: inventory.integrityContradictions,
});
if (graphSha256 !== inventory.manifest.graph_sha256)
throw new TypeError("Artifact graph commitment does not match its members");
+5 -3
View File
@@ -331,9 +331,11 @@ const artifactFindings = (evidence: Evidence): Finding[] => {
scope: "static_candidate",
status: change.classification,
classification:
change.classification === "unknown"
? "unresolved_branch"
: "derived_relationship",
change.classification === "contradiction"
? "contradiction"
: change.classification === "unknown"
? "unresolved_branch"
: "derived_relationship",
limitations: result.limitations,
links: change.evidence_links,
}),
+252 -14
View File
@@ -1,4 +1,9 @@
import type { JsonValue } from "./jsonValue.js";
import type {
MissingPermissionScope,
PermissionRequest,
PermissionScope,
} from "./permissionPolicy.js";
import {
hopperStartupFailure,
type HopperStartupFailureCode,
@@ -31,6 +36,7 @@ const ANALYSIS_ERROR_TAGS = [
"ConfigurationError",
"NoBinaryOpenError",
"BinaryTargetError",
"PermissionRequiredError",
] as const;
/** Stable tag for an expected analysis failure. */
@@ -42,6 +48,8 @@ export abstract class AnalysisError extends Error {
readonly userMessage: string | undefined = undefined;
readonly userCategory: "permission_required" | "cancelled" | undefined =
undefined;
readonly cleanupIncomplete: boolean = false;
readonly cleanupResources: readonly string[] = [];
}
/** Base class for failures produced specifically by the Hopper provider. */
@@ -336,6 +344,25 @@ export class BinaryTargetError extends AnalysisError {
export interface AnalysisErrorProjection
extends Readonly<Record<string, JsonValue>> {
readonly code:
| "invalid_request"
| "unreadable_output"
| "capability_unavailable"
| "provider_unavailable"
| "provider_timeout"
| "cancelled"
| "artifact_integrity_mismatch"
| "artifact_operation_failed"
| "evidence_integrity_mismatch"
| "truncated"
| "permission_required"
| "process_capture_failed"
| "cleanup_incomplete"
| "revision_conflict"
| "outside_approved_root"
| "configuration_invalid"
| "target_unavailable"
| "execution_failure";
readonly category:
| "invalid_input"
| "permission_required"
@@ -347,38 +374,246 @@ export interface AnalysisErrorProjection
| "unavailable"
| "execution_failure";
readonly message: string;
readonly code?: HopperStartupFailureCode;
readonly retryable: boolean;
readonly remediation: Readonly<{
action: string;
restart_required: boolean;
elicitation_supported?: boolean;
}>;
readonly details?: Readonly<Record<string, JsonValue>>;
}
/** Exact denied authority used by both CLI and MCP remediation. */
export class PermissionRequiredError extends AnalysisError {
readonly _tag = "PermissionRequiredError" as const;
constructor(
readonly requested: PermissionRequest,
readonly missing: MissingPermissionScope,
readonly ceiling: PermissionScope | null,
readonly elicitationSupported: boolean,
readonly restartRequired: boolean,
) {
super(`Permission required for ${requested.capability}`);
}
}
/** Project expected failures into exhaustive, secret-safe caller fields. */
export const projectAnalysisError = (
error: AnalysisError,
): AnalysisErrorProjection => {
assertKnownTag(error._tag);
const code =
error instanceof HopperProcessError ? error.failureCode : undefined;
const artifact =
error instanceof ArtifactOperationError && error.artifactDetails;
const details = artifact
? {
logical_path: artifact.logicalPath,
declared_sha256: artifact.declaredSha256,
calculated_sha256: artifact.calculatedSha256,
unpacked: artifact.unpacked,
}
: undefined;
const code = errorCode(error);
const details = errorDetails(error);
return {
code,
category: errorCategory(error),
message: userMessage(error),
...(code === undefined ? {} : { code }),
retryable: RETRYABLE_CODES.has(code),
remediation: {
action: remediationAction(error),
restart_required:
error instanceof PermissionRequiredError && error.restartRequired,
...(error instanceof PermissionRequiredError
? { elicitation_supported: error.elicitationSupported }
: {}),
},
...(details === undefined ? {} : { details }),
};
};
const errorCode = (error: AnalysisError): AnalysisErrorProjection["code"] => {
if (error instanceof PermissionRequiredError) return "permission_required";
if (error instanceof ArtifactOperationError)
return error.reason === "integrity" && error.artifactDetails !== undefined
? "artifact_integrity_mismatch"
: error.reason === "limit"
? "truncated"
: error.reason === "cancelled"
? "cancelled"
: "artifact_operation_failed";
if (error instanceof EvidenceFileError)
return error.reason === "outside-root"
? "outside_approved_root"
: error.reason === "too-large"
? "truncated"
: error.reason === "disabled"
? "capability_unavailable"
: "execution_failure";
if (error instanceof InvestigationWorkspaceError) {
if (
error.reason === "revision-conflict" ||
error.reason === "name-conflict"
)
return "revision_conflict";
if (error.reason === "too-large") return "truncated";
if (error.reason === "disabled") return "capability_unavailable";
if (error.reason === "outside-root") return "outside_approved_root";
if (error.reason === "integrity" || error.reason === "invalid-json")
return "evidence_integrity_mismatch";
return "execution_failure";
}
if (error instanceof UnknownRegistryError)
return error.reason === "revision-conflict" ||
error.reason === "already-exists"
? "revision_conflict"
: error.reason === "limit"
? "truncated"
: error.reason === "integrity"
? "evidence_integrity_mismatch"
: "execution_failure";
if (error._tag === "ProcessCaptureError")
return error.cleanupIncomplete
? "cleanup_incomplete"
: error.userCategory === "cancelled"
? "cancelled"
: error.userCategory === "permission_required"
? "permission_required"
: "process_capture_failed";
switch (error._tag) {
case "AnalysisProtocolError":
case "AnalysisOutputError":
case "HopperProtocolError":
return "unreadable_output";
case "AnalysisInputError":
return "invalid_request";
case "AnalysisCapabilityUnavailableError":
case "ProviderSelectionError":
return "capability_unavailable";
case "AnalysisCancelledError":
case "HopperCancelledError":
return "cancelled";
case "AnalysisTimeoutError":
case "HopperTimeoutError":
return "provider_timeout";
case "HopperProcessError":
case "HopperStartError":
return "provider_unavailable";
case "ConfigurationError":
return "configuration_invalid";
case "NoBinaryOpenError":
case "BinaryTargetError":
return "target_unavailable";
case "EvidenceIntegrityError":
return "evidence_integrity_mismatch";
case "EvidenceLimitError":
return "truncated";
case "ProviderAdapterError":
case "HopperRemoteError":
return "execution_failure";
case "ArtifactOperationError":
case "EvidenceFileError":
case "InvestigationWorkspaceError":
case "UnknownRegistryError":
case "PermissionRequiredError":
throw new TypeError("Unhandled specialized analysis error");
}
};
const errorDetails = (
error: AnalysisError,
): Readonly<Record<string, JsonValue>> | undefined => {
if (error instanceof PermissionRequiredError)
return {
capability: error.requested.capability,
requested: scopeDetails(error.requested),
missing: missingScopeDetails(error.missing),
ceiling: error.ceiling === null ? null : scopeDetails(error.ceiling),
};
if (error instanceof ArtifactOperationError && error.artifactDetails)
return {
logical_path: error.artifactDetails.logicalPath,
declared_sha256: error.artifactDetails.declaredSha256,
calculated_sha256: error.artifactDetails.calculatedSha256,
unpacked: error.artifactDetails.unpacked,
};
if (error instanceof ArtifactOperationError)
return {
operation: error.operation,
reason: error.reason,
...(error.reason === "limit" ? { truncated: true } : {}),
};
if (error instanceof AnalysisCancelledError)
return { operation: error.operation, cleanup: "complete" };
if (error instanceof HopperCancelledError)
return { operation: "hopper", cleanup: "complete" };
if (error instanceof AnalysisTimeoutError)
return { operation: error.operation, timeout_ms: error.timeoutMs };
if (error instanceof HopperTimeoutError)
return { operation: "hopper", timeout_ms: error.timeoutMs };
if (error instanceof EvidenceLimitError)
return { limit: error.limit, maximum: error.maximum, truncated: true };
if (error instanceof InvestigationWorkspaceError)
return { operation: error.operation, reason: error.reason };
if (error instanceof UnknownRegistryError) return { reason: error.reason };
if (error instanceof EvidenceFileError)
return { operation: error.operation, reason: error.reason };
if (error instanceof AnalysisCapabilityUnavailableError)
return { provider_id: error.providerId, operation: error.operation };
if (error instanceof ProviderAdapterError)
return { provider_id: error.providerId, operation: error.operation };
if (error instanceof HopperRemoteError)
return { provider_code: error.code, diagnostic_type: error.diagnosticType };
if (error instanceof HopperProcessError && error.failureCode !== undefined)
return { failure_code: error.failureCode, exit_code: error.exitCode };
if (error._tag === "ProcessCaptureError" && error.cleanupIncomplete)
return {
cleanup: "incomplete",
resources: [...error.cleanupResources],
};
if (
error._tag === "ProcessCaptureError" &&
error.userCategory === "cancelled"
)
return { operation: "process_capture", cleanup: "complete" };
if (error instanceof BinaryTargetError) return { path: error.path };
return undefined;
};
const scopeDetails = (
scope: PermissionScope,
): Readonly<Record<string, JsonValue>> => ({
capability: scope.capability,
roots: [...scope.roots],
executables: [...scope.executables],
environment_names: [...scope.environment_names],
network: scope.network,
mount: scope.mount,
});
const missingScopeDetails = (
scope: MissingPermissionScope,
): Readonly<Record<string, JsonValue>> => ({
...(scope.roots === undefined ? {} : { roots: [...scope.roots] }),
...(scope.executables === undefined
? {}
: { executables: [...scope.executables] }),
...(scope.environment_names === undefined
? {}
: { environment_names: [...scope.environment_names] }),
...(scope.network === undefined ? {} : { network: scope.network }),
...(scope.mount === undefined ? {} : { mount: scope.mount }),
});
const RETRYABLE_CODES: ReadonlySet<AnalysisErrorProjection["code"]> = new Set([
"provider_timeout",
"cancelled",
"revision_conflict",
"provider_unavailable",
]);
const remediationAction = (error: AnalysisError): string => {
if (error instanceof PermissionRequiredError)
return error.elicitationSupported
? "Approve the exact missing scope, then retry the operation."
: "Add the exact missing scope beneath the administrator ceiling, then retry.";
return userMessage(error);
};
const errorCategory = (
error: AnalysisError,
): AnalysisErrorProjection["category"] => {
if (error instanceof PermissionRequiredError) return "permission_required";
if (error._tag === "ProcessCaptureError")
return error.userCategory ?? "execution_failure";
if (
@@ -437,6 +672,8 @@ const STATIC_ERROR_CATEGORIES: Readonly<
};
const userMessage = (error: AnalysisError): string => {
if (error instanceof PermissionRequiredError)
return "This operation needs additional local permission. Review the requested scope and remediation.";
if (error instanceof AnalysisInputError)
return "Analysis input is invalid. Check the arguments and try again.";
if (error.userMessage !== undefined) return error.userMessage;
@@ -578,6 +815,7 @@ const KNOWN_ERROR_TAGS = {
ConfigurationError: true,
NoBinaryOpenError: true,
BinaryTargetError: true,
PermissionRequiredError: true,
} as const satisfies Readonly<Record<AnalysisErrorTag, true>>;
const assertKnownTag = (tag: AnalysisErrorTag): void => {
+37 -11
View File
@@ -53,17 +53,32 @@ export type InvestigationRunOptions = z.infer<
>;
/** Explicit write approval and two local versions for an automatic run. */
export const crossVersionInvestigationInputSchema = z.object({
approved: z.literal(true),
workspace_path: z.string().min(1).max(4_096),
workspace_name: z.string().trim().min(1).max(200).default("default"),
expected_workspace_revision: z.number().int().min(1).optional(),
left_path: z.string().min(1).max(4_096),
right_path: z.string().min(1).max(4_096),
options: investigationRunOptionsSchema.default(
DEFAULT_INVESTIGATION_RUN_OPTIONS,
),
});
export const crossVersionInvestigationInputSchema = z
.object({
approved: z.literal(true),
workspace_path: z.string().min(1).max(4_096),
workspace_name: z.string().trim().min(1).max(200).default("default"),
expected_workspace_revision: z.number().int().min(1).optional(),
left_path: z.string().min(1).max(4_096),
right_path: z.string().min(1).max(4_096),
integrity_policy: z.enum(["fail", "record-and-continue"]).default("fail"),
integrity_continue_approved: z.boolean().default(false),
max_integrity_mismatches: z.number().int().min(1).max(100).default(10),
options: investigationRunOptionsSchema.default(
DEFAULT_INVESTIGATION_RUN_OPTIONS,
),
})
.superRefine((input, context) => {
if (
input.integrity_policy === "record-and-continue" &&
input.integrity_continue_approved !== true
)
context.addIssue({
code: "custom",
path: ["integrity_continue_approved"],
message: "record-and-continue requires explicit approval",
});
});
export type CrossVersionInvestigationInput = z.infer<
typeof crossVersionInvestigationInputSchema
@@ -92,6 +107,9 @@ export const investigationRunSchema = z.object({
left: targetSchema,
right: targetSchema,
options: investigationRunOptionsSchema,
integrity_policy: z.enum(["fail", "record-and-continue"]),
integrity_continue_approved: z.boolean(),
max_integrity_mismatches: z.number().int().min(1).max(100),
status: z.enum(["running", "complete"]),
completed_stages: z.array(stageSchema).max(4),
left_inventory_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
@@ -137,12 +155,20 @@ export const createInvestigationRunIdentity = (input: {
readonly left: InvestigationRunTarget;
readonly right: InvestigationRunTarget;
readonly options: InvestigationRunOptions;
readonly integrity_policy: CrossVersionInvestigationInput["integrity_policy"];
readonly integrity_continue_approved: boolean;
readonly max_integrity_mismatches: number;
}): { readonly runId: string; readonly requestSha256: string } => {
const requestSha256 = digestCanonical({
schema: "rea.cross-version-investigation-request/v1",
left: input.left,
right: input.right,
options: input.options,
integrity: {
policy: input.integrity_policy,
approved: input.integrity_continue_approved,
max_mismatches: input.max_integrity_mismatches,
},
});
return { runId: `run_${requestSha256}`, requestSha256 };
};
+322
View File
@@ -0,0 +1,322 @@
import { isAbsolute, relative, resolve, sep } from "node:path";
import { err, ok, type Result } from "./result.js";
/** Local capabilities governed by the shared REA permission policy. */
export type PermissionCapability =
| "process_capture"
| "evidence_read"
| "evidence_write"
| "investigation_input"
| "investigation_workspace_read"
| "investigation_workspace_write"
| "snapshot_read"
| "snapshot_write"
| "artifact_extract"
| "native_mount"
| "reference_read";
/** Ordered network authority; each mode includes the modes before it. */
type PermissionNetwork = "none" | "loopback" | "external";
/** Exact normalized scope requested by one local operation. */
export interface PermissionScope {
readonly capability: PermissionCapability;
readonly roots: readonly string[];
readonly executables: readonly string[];
readonly environment_names: readonly string[];
readonly network: PermissionNetwork;
readonly mount: boolean;
}
/** A request identity associates one-shot grants with exactly one operation. */
export interface PermissionRequest extends PermissionScope {
readonly operation_identity: string;
}
/** Administrator-owned maximum authority for one capability. */
export type PermissionCeiling = PermissionScope;
/** Authority issued beneath the administrator ceiling. */
export interface PermissionGrant extends PermissionScope {
readonly grant_id: string;
readonly lifetime: "once" | "session" | "project" | "administrator";
readonly operation_identity: string | null;
readonly expires_at: string | null;
}
/** Missing requested authority, containing names and paths but never values. */
export interface MissingPermissionScope {
readonly roots?: readonly string[];
readonly executables?: readonly string[];
readonly environment_names?: readonly string[];
readonly network?: PermissionNetwork;
readonly mount?: true;
}
/** Immutable shared policy state. */
export interface PermissionPolicy {
readonly ceilings: readonly PermissionCeiling[];
readonly grants: readonly PermissionGrant[];
readonly revoked_grant_ids: ReadonlySet<string>;
readonly consumed_grant_ids: ReadonlySet<string>;
}
/** A proposed grant exceeds the administrator-owned maximum authority. */
export class PermissionGrantError extends Error {
readonly _tag = "PermissionGrantError" as const;
constructor(
readonly reason: "outside_administrator_ceiling" | "invalid_once_scope",
readonly missing: MissingPermissionScope,
) {
super(`Permission grant rejected: ${reason}`);
}
}
/** Observable decision returned before any governed side effect. */
export type PermissionDecision =
| {
readonly allowed: true;
readonly grant_id: string;
readonly lifetime: PermissionGrant["lifetime"];
}
| {
readonly allowed: false;
readonly reason:
| "outside_administrator_ceiling"
| "grant_required"
| "grant_revoked_or_consumed"
| "grant_expired";
readonly missing: MissingPermissionScope;
};
/** Create a fail-closed policy with no implicit grants. */
export const createPermissionPolicy = (
ceilings: readonly PermissionCeiling[],
grants: readonly PermissionGrant[] = [],
): PermissionPolicy => ({
ceilings: ceilings.map(normalizeScope),
grants: grants.map(normalizeGrant),
revoked_grant_ids: new Set(),
consumed_grant_ids: new Set(),
});
/** Add one grant only when it is a subset of its administrator ceiling. */
export const grantPermission = (
policy: PermissionPolicy,
grant: PermissionGrant,
): Result<PermissionPolicy, PermissionGrantError> => {
const normalized = normalizeGrant(grant);
if (normalized.lifetime === "once" && normalized.operation_identity === null)
return err(new PermissionGrantError("invalid_once_scope", {}));
const missing = missingFromScopes(normalized, policy.ceilings);
if (hasMissing(missing))
return err(
new PermissionGrantError("outside_administrator_ceiling", missing),
);
return ok({ ...policy, grants: [...policy.grants, normalized] });
};
/** Evaluate exact requested authority against the ceiling and active grants. */
export const evaluatePermission = (
policy: PermissionPolicy,
request: PermissionRequest,
now: Date = new Date(),
): PermissionDecision => {
const normalized = normalizeRequest(request);
const outsideCeiling = missingFromScopes(normalized, policy.ceilings);
if (hasMissing(outsideCeiling))
return {
allowed: false,
reason: "outside_administrator_ceiling",
missing: outsideCeiling,
};
const candidates = policy.grants.filter(
(grant) =>
grant.capability === normalized.capability &&
!policy.revoked_grant_ids.has(grant.grant_id) &&
!policy.consumed_grant_ids.has(grant.grant_id) &&
!isExpired(grant, now) &&
(grant.lifetime !== "once" ||
grant.operation_identity === normalized.operation_identity),
);
const selected = candidates.find(
(grant) => !hasMissing(missingFromScopes(normalized, [grant])),
);
if (selected !== undefined)
return {
allowed: true,
grant_id: selected.grant_id,
lifetime: selected.lifetime,
};
const coveringGrant = policy.grants.find(
(grant) =>
grant.capability === normalized.capability &&
(grant.lifetime !== "once" ||
grant.operation_identity === normalized.operation_identity) &&
!hasMissing(missingFromScopes(normalized, [grant])),
);
return {
allowed: false,
reason:
coveringGrant !== undefined && isExpired(coveringGrant, now)
? "grant_expired"
: candidates.length === 0 &&
policy.grants.some(
(grant) => grant.capability === normalized.capability,
)
? "grant_revoked_or_consumed"
: "grant_required",
missing: missingFromScopes(normalized, candidates),
};
};
/** Consume an allowed one-shot decision; longer-lived grants are unchanged. */
export const consumePermission = (
policy: PermissionPolicy,
decision: Extract<PermissionDecision, { readonly allowed: true }>,
): PermissionPolicy =>
decision.lifetime === "once"
? {
...policy,
consumed_grant_ids: new Set([
...policy.consumed_grant_ids,
decision.grant_id,
]),
}
: policy;
/** Revoke one grant for every future evaluation. */
export const revokePermission = (
policy: PermissionPolicy,
grantId: string,
): PermissionPolicy => ({
...policy,
revoked_grant_ids: new Set([...policy.revoked_grant_ids, grantId]),
});
/** Drop connection-bound authority when an MCP or CLI session ends. */
export const clearSessionPermissions = (
policy: PermissionPolicy,
): PermissionPolicy => ({
...policy,
grants: policy.grants.filter(
({ lifetime }) => lifetime !== "once" && lifetime !== "session",
),
});
/** Atomically replace administrator ceilings while retaining auditable grants. */
export const reloadPermissionCeilings = (
policy: PermissionPolicy,
ceilings: readonly PermissionCeiling[],
): PermissionPolicy => ({
...policy,
ceilings: ceilings.map(normalizeScope),
});
const normalizeScope = (scope: PermissionScope): PermissionScope => ({
capability: scope.capability,
roots: uniqueSorted(scope.roots.map((path) => resolve(path))),
executables: uniqueSorted(scope.executables.map((path) => resolve(path))),
environment_names: uniqueSorted(scope.environment_names),
network: scope.network,
mount: scope.mount,
});
const normalizeGrant = (grant: PermissionGrant): PermissionGrant => ({
...normalizeScope(grant),
grant_id: grant.grant_id,
lifetime: grant.lifetime,
operation_identity: grant.operation_identity,
expires_at: grant.expires_at,
});
const normalizeRequest = (request: PermissionRequest): PermissionRequest => ({
...normalizeScope(request),
operation_identity: request.operation_identity,
});
const missingFromScopes = (
request: PermissionScope,
scopes: readonly PermissionScope[],
): MissingPermissionScope => {
const relevant = scopes.filter(
({ capability }) => capability === request.capability,
);
const roots = request.roots.filter(
(path) => !relevant.some((scope) => containsAny(scope.roots, path)),
);
const executables = request.executables.filter(
(path) => !relevant.some((scope) => containsAny(scope.executables, path)),
);
const environmentNames = request.environment_names.filter(
(name) => !relevant.some((scope) => scope.environment_names.includes(name)),
);
const network =
request.network === "none" ||
relevant.some(
(scope) => networkRank(scope.network) >= networkRank(request.network),
)
? undefined
: request.network;
const mount =
!request.mount || relevant.some((scope) => scope.mount)
? undefined
: (true as const);
return {
...(roots.length === 0 ? {} : { roots }),
...(executables.length === 0 ? {} : { executables }),
...(environmentNames.length === 0
? {}
: { environment_names: environmentNames }),
...(network === undefined ? {} : { network }),
...(mount === undefined ? {} : { mount }),
};
};
interface PathOperations {
readonly relative: typeof relative;
readonly isAbsolute: typeof isAbsolute;
readonly sep: string;
}
const HOST_PATH_OPERATIONS: PathOperations = { relative, isAbsolute, sep };
/** Test whether a candidate is inside a root using one platform path flavor. */
export const isPathContained = (
root: string,
candidate: string,
operations: PathOperations = HOST_PATH_OPERATIONS,
): boolean => {
const relation = operations.relative(root, candidate);
return (
relation === "" ||
(relation !== ".." &&
!relation.startsWith(`..${operations.sep}`) &&
!operations.isAbsolute(relation))
);
};
const containsAny = (roots: readonly string[], candidate: string): boolean =>
roots.some((root) => isPathContained(root, candidate));
const networkRank = (network: PermissionNetwork): number => {
switch (network) {
case "none":
return 0;
case "loopback":
return 1;
case "external":
return 2;
}
};
const isExpired = (grant: PermissionGrant, now: Date): boolean =>
grant.expires_at !== null && Date.parse(grant.expires_at) <= now.getTime();
const hasMissing = (missing: MissingPermissionScope): boolean =>
Object.keys(missing).length > 0;
const uniqueSorted = (values: readonly string[]): readonly string[] =>
[...new Set(values)].sort((left, right) => left.localeCompare(right));
+1
View File
@@ -12,6 +12,7 @@ export const comparisonStatusSchema = z.enum([
"changed",
"truncated",
"unknown",
"contradiction",
]);
type ComparisonStatus = z.infer<typeof comparisonStatusSchema>;
+2 -1
View File
@@ -389,7 +389,8 @@ const classify = (
unknowns: readonly ResidualUnknown[],
): ClaimResult["status"] => {
if (limitations.length > 0) return "unknown";
if (["changed", "added", "removed"].includes(observed)) return "fail";
if (["changed", "added", "removed", "contradiction"].includes(observed))
return "fail";
if (observed === "unknown" || observed === "truncated" || unknowns.length > 0)
return "unknown";
return "pass";
@@ -96,6 +96,7 @@ export const reconstructionClaimResultSchema = z.object({
"changed",
"truncated",
"unknown",
"contradiction",
]),
comparison_evidence_id: evidenceIdSchema,
left_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+5 -1
View File
@@ -338,7 +338,11 @@ const selectStatic = (
return {
status,
conclusion_kind:
status === "unknown" ? "unresolved_branch" : "derived_relationship",
status === "contradiction"
? "contradiction"
: status === "unknown"
? "unresolved_branch"
: "derived_relationship",
};
};