mirror of
https://github.com/morluto/rea.git
synced 2026-11-22 06:25:44 +00:00
* feat(snapshots)!: persist the target identity as the snapshot target
The snapshot target is now `{ kind, identity }`, where `identity` is the
FileTargetIdentity that `binaryTargetIdentity` produces and `kind` is the
binary kind query IDs commit to. The per-format target projection and
`snapshotTargetIdentity` are deleted; the schema checks the format's
selection, architecture and kind instead of keeping one union arm per format.
Entry execution subjects use the Evidence subject shape (file or explicit
unknown), so a snapshot entry commits to the same identity, including the
selection, as its Evidence record. Workflow entries take the subject of the
workflow's own Evidence. Replay no longer re-derives the selection from the
open target.
`FileTargetSelection` gains `universal-slice` (`offset`, `size`, and the FAT
`cpu_type`/`cpu_subtype` when target admission supplied the FAT table, else
null). `binaryTargetIdentity` produces it for `mach-o-universal` targets, so
Evidence and snapshots for different slices of one container no longer share
an identity.
Refs #11417
BREAKING CHANGE: analysis snapshot files change shape: `target` is
`{ kind, identity: { kind: "file", sha256, format, architecture, selection } }`
and entry `execution.subject` is the Evidence subject
(`{ identity, name, local_path }`, never null). Snapshot binding mismatch
details report `target.snapshot`/`target.selected` in the same shape. Evidence
IDs of universal Mach-O targets change because their subject identity now
carries the selected slice. Recreate saved snapshots and Evidence bundles of
universal Mach-O targets.
* docs(evidence): name the universal Mach-O slice selection in the subject contract
* fix(snapshots): read the snapshot target identity in the Ghidra verification scripts
The real Ghidra snapshot checks (lifecycle, RISC-V, MIPS, PowerPC) read
snapshot.target.sha256 and .architecture, which moved under
snapshot.target.identity, so they would fail after saving a valid snapshot.
* feat(evidence)!: name live browser page Evidence by its page URL (#11559)
Browser page observations (inspect_web_page, analyze_web_bundle,
observe_web_session, discover_webmcp_tools, capture_web_screenshot,
observe_web_execution, inspect_web_event_listeners) named an unknown
(`not-observed`) subject although the provider reports the page URL.
`TargetIdentity` gains a `url` kind: the reported URL with userinfo removed
and its origin (`null` for an opaque origin). The schema refuses a URL that
carries userinfo or an origin the URL does not have.
`browserUrlTargetIdentity` in the browser URL owner builds it from the
provider's reported URL; a withheld or unparseable URL stays unknown
(`not-observed`). Target lists and comparisons still name no single
document. Analysis views keep their parent's URL subject, as they already
keep a file subject.
BREAKING CHANGE: Evidence IDs of live browser page observations and their
analysis views change, and their subject is
`{ "kind": "url", "url", "origin" }` with `name` and `local_path` null.
Recreate stored Evidence for these tools. This lands inside Evidence format
revision 2 under the release hold (#11417); no `evidence_format` bump.
466 lines
17 KiB
TypeScript
466 lines
17 KiB
TypeScript
import { unknownTarget } from "../../domain/targetIdentity.js";
|
|
import { projectAnalysisErrorWithoutCapturedOutput } from "../../domain/analysisErrorProjection.js";
|
|
import { analysisErrorWithCleanupDependencies } from "../../domain/analysisErrorCleanup.js";
|
|
import { parseAnalysisInput } from "../AnalysisInput.js";
|
|
import { isNativeObservationOperation } from "../../domain/native/nativeObservation.js";
|
|
import { dispatchQueuedInterrupts } from "../../process/queuedInterrupts.js";
|
|
import { readImmutableEvidenceBundle } from "../EvidenceBundleFiles.js";
|
|
import { INSPECT_ANALYSIS_VIEW_OPERATION } from "../../domain/analysisView/analysisViewErrors.js";
|
|
|
|
import { ANALYSIS_VIEW_PROVIDER } from "../../domain/investigationProviders.js";
|
|
import type { EvidenceLookup } from "../EvidenceInputResolver.js";
|
|
import { resolveEvidenceInput } from "../EvidenceInputResolver.js";
|
|
import type { EvidenceWriter } from "../investigation/InvestigationRecordPort.js";
|
|
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
|
|
import {
|
|
AnalysisInputError,
|
|
AnalysisCapabilityUnavailableError,
|
|
cancelledBy,
|
|
} from "../../domain/analysisErrorCore.js";
|
|
import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
|
|
import { validateAnalysisViewSubject } from "../../domain/analysisView/analysisViewParent.js";
|
|
import {
|
|
safeParseEvidence,
|
|
unsupportedEvidenceFormatError,
|
|
} from "../../domain/evidenceValidation.js";
|
|
import { isUnsupportedEvidenceFormat } from "../../domain/evidenceFormat.js";
|
|
import {
|
|
createEvidence,
|
|
evidenceFileTarget,
|
|
evidenceSubjectDisplay,
|
|
evidenceSubjectInput,
|
|
evidenceSubjectTarget,
|
|
rebindEvidenceToTargetPath,
|
|
type Evidence,
|
|
type EvidenceSubjectTarget,
|
|
} from "../../domain/evidence.js";
|
|
import {
|
|
inspectAnalysisViewInputSchema,
|
|
type AnalysisViewRequest,
|
|
type InspectAnalysisViewInput,
|
|
} from "../../domain/analysisView/analysisViewRequest.js";
|
|
import { prepareAnalysisViewProjection } from "../../domain/analysisView/analysisView.js";
|
|
import type { AnalysisViewResult } from "../../domain/analysisView/analysisViewResult.js";
|
|
import {
|
|
immutableJsonSnapshotMember,
|
|
isImmutableJsonSnapshot,
|
|
} from "../../domain/immutableJson.js";
|
|
import { err, ok, type Result } from "../../domain/result.js";
|
|
import {
|
|
readEvidenceFileSource,
|
|
type EvidenceFileReadOptions,
|
|
} from "./evidenceFileSource.js";
|
|
|
|
/** A parsed request whose source can be projected without filesystem access. */
|
|
export interface ReadyAnalysisViewInput {
|
|
readonly source: Exclude<
|
|
InspectAnalysisViewInput["source"],
|
|
{ kind: "evidence-file" }
|
|
>;
|
|
readonly view: AnalysisViewRequest;
|
|
}
|
|
|
|
/** Source acquisition controls shared by CLI and MCP; bundles are selected by the CLI. */
|
|
export interface AnalysisViewReadOptions extends EvidenceFileReadOptions {
|
|
readonly evidenceBundlePath?: string;
|
|
}
|
|
|
|
/** Validate one view request, resolve its selected source, then project completed Evidence. */
|
|
export const inspectAnalysisView = async (
|
|
rawInput: unknown,
|
|
lookup?: EvidenceLookup,
|
|
options: AnalysisViewReadOptions = {},
|
|
): Promise<Result<Evidence, AnalysisError>> => {
|
|
const parsed = parseAnalysisInput(
|
|
INSPECT_ANALYSIS_VIEW_OPERATION,
|
|
rawInput,
|
|
inspectAnalysisViewInputSchema,
|
|
options.signal,
|
|
);
|
|
if (!parsed.ok) return parsed;
|
|
if (options.evidenceBundlePath !== undefined)
|
|
return inspectBundleView(parsed.value, options.evidenceBundlePath, options);
|
|
const source = parsed.value.source;
|
|
if (source.kind === "evidence-file")
|
|
return inspectFileView({ ...parsed.value, source }, lookup, options);
|
|
return inspectAnalysisViewValidated({ ...parsed.value, source }, lookup);
|
|
};
|
|
|
|
/**
|
|
* Read and authenticate an Evidence-file source, then project it as retained
|
|
* Evidence: its strings are bounded by the file reader rather than charged as
|
|
* inline input.
|
|
*/
|
|
const inspectFileView = async (
|
|
input: InspectAnalysisViewInput & {
|
|
readonly source: Extract<
|
|
InspectAnalysisViewInput["source"],
|
|
{ kind: "evidence-file" }
|
|
>;
|
|
},
|
|
lookup?: EvidenceLookup,
|
|
options: EvidenceFileReadOptions = {},
|
|
): Promise<Result<Evidence, AnalysisError>> => {
|
|
const loaded = await readEvidenceFileSource(
|
|
input.source.path,
|
|
options,
|
|
input.source.evidence_id,
|
|
);
|
|
// Authentication and projection are synchronous; dispatch queued callbacks and
|
|
// the signal notifications they enqueue before accepting either result.
|
|
await dispatchQueuedInterrupts();
|
|
// A request cancelled during authentication reports cancellation, even when authentication failed.
|
|
const admitted = cancelledFileViewResult(
|
|
loaded,
|
|
options.signal,
|
|
loaded.ok ? loaded.value : undefined,
|
|
);
|
|
if (!admitted.ok) return admitted;
|
|
const id = admitted.value.evidence_id;
|
|
const projected = inspectAnalysisViewValidated(
|
|
{ ...input, source: { kind: "retained-evidence", evidence_id: id } },
|
|
(evidenceId) => (evidenceId === id ? admitted.value : lookup?.(evidenceId)),
|
|
);
|
|
await dispatchQueuedInterrupts();
|
|
if (!projected.ok) return projected;
|
|
return cancelledFileViewResult(projected, options.signal, projected.value);
|
|
};
|
|
|
|
/** Resolve the caller's exact retained parent from an authenticated portable bundle. */
|
|
const inspectBundleView = async (
|
|
input: InspectAnalysisViewInput,
|
|
bundlePath: string,
|
|
{ resources, signal }: EvidenceFileReadOptions,
|
|
): Promise<Result<Evidence, AnalysisError>> => {
|
|
if (input.source.kind !== "retained-evidence")
|
|
return err(
|
|
new AnalysisInputError("inspect_analysis_view", undefined, [
|
|
{
|
|
path: ["source", "kind"],
|
|
reason: "invalid_value",
|
|
message:
|
|
"An Evidence bundle needs a retained-evidence source with the exact parent evidence_id; inline Evidence already supplies its source",
|
|
},
|
|
]),
|
|
);
|
|
const loaded = await readImmutableEvidenceBundle(
|
|
bundlePath,
|
|
signal,
|
|
resources,
|
|
"inspect_analysis_view",
|
|
);
|
|
// Authentication and projection are synchronous; dispatch queued interrupts before accepting either result.
|
|
await dispatchQueuedInterrupts();
|
|
// Preserve an already-produced bundle failure before considering a later abort.
|
|
if (!loaded.ok) return loaded;
|
|
const parentId = input.source.evidence_id;
|
|
const admitted = cancelledFileViewResult(
|
|
loaded,
|
|
signal,
|
|
signal?.aborted
|
|
? loaded.value.records.find((record) => record.evidence_id === parentId)
|
|
: undefined,
|
|
);
|
|
if (!admitted.ok) return admitted;
|
|
const projected = inspectAnalysisViewValidated(
|
|
{ source: input.source, view: input.view },
|
|
(id) => admitted.value.records.find((record) => record.evidence_id === id),
|
|
);
|
|
await dispatchQueuedInterrupts();
|
|
if (!projected.ok) return projected;
|
|
return cancelledFileViewResult(projected, signal, projected.value);
|
|
};
|
|
|
|
/** Retain completed work and pending cleanup when this stage accepts cancellation.
|
|
* File-source admission explicitly gives queued cancellation precedence over
|
|
* authentication errors; callers preserve other already-produced failures.
|
|
*/
|
|
const cancelledFileViewResult = <T>(
|
|
result: Result<T, AnalysisError>,
|
|
signal?: AbortSignal,
|
|
completedEvidence?: Evidence,
|
|
): Result<T, AnalysisError> => {
|
|
if (!signal?.aborted) return result;
|
|
const cancellation = cancelledBy(
|
|
INSPECT_ANALYSIS_VIEW_OPERATION,
|
|
signal,
|
|
completedEvidence !== undefined
|
|
? { partialObservation: completedEvidence }
|
|
: {},
|
|
);
|
|
if (!result.ok)
|
|
cancellation.retainSecondaryFailure(result.error, {
|
|
source_error: projectAnalysisErrorWithoutCapturedOutput(result.error),
|
|
});
|
|
return err(
|
|
!result.ok && result.error.cleanupIncomplete
|
|
? analysisErrorWithCleanupDependencies(
|
|
cancellation,
|
|
result.error,
|
|
INSPECT_ANALYSIS_VIEW_OPERATION,
|
|
)
|
|
: cancellation,
|
|
);
|
|
};
|
|
|
|
/** Project a parsed request whose selected source is inline or retained. */
|
|
export const inspectAnalysisViewValidated = (
|
|
input: ReadyAnalysisViewInput,
|
|
lookup?: EvidenceLookup,
|
|
): Result<Evidence, AnalysisError> => {
|
|
const projection = prepareAnalysisViewProjection(input.view);
|
|
if (input.source.kind === "inline") {
|
|
const admitted = projection.admitInlineEvidence(input.source.evidence);
|
|
if (!admitted.ok) return admitted;
|
|
}
|
|
const resolved = resolveAnalysisViewSource(input.source, lookup);
|
|
if (!resolved.ok) return resolved;
|
|
return projectResolvedAnalysisView(input, projection, resolved.value);
|
|
};
|
|
|
|
/** Keep payload ownership separate from this delivery's display-only subject. */
|
|
const projectResolvedAnalysisView = (
|
|
input: ReadyAnalysisViewInput,
|
|
projection: ReturnType<typeof prepareAnalysisViewProjection>,
|
|
parent: Evidence,
|
|
selectedTarget?: EvidenceSubjectTarget,
|
|
): Result<Evidence, AnalysisError> => {
|
|
const presentation =
|
|
selectedTarget === undefined
|
|
? parent
|
|
: rebindEvidenceToTargetPath(parent, selectedTarget);
|
|
const projected = projection.project({
|
|
evidenceId: parent.evidence_id,
|
|
operation: parent.operation,
|
|
predicateType: parent.predicate_type,
|
|
provider: parent.provider,
|
|
analysisProfile: parent.analysis_profile,
|
|
authority: parent.authority,
|
|
environment: parent.environment,
|
|
rawResult: parent.raw_result,
|
|
normalizedResult:
|
|
immutableJsonSnapshotMember(parent, "normalized_result") ??
|
|
parent.normalized_result,
|
|
// Sealing an Evidence root deep-freezes it; only the root is registered.
|
|
sealedResult: isImmutableJsonSnapshot(parent),
|
|
subject: presentation.subject,
|
|
limitations: parent.limitations,
|
|
parameters: parent.parameters,
|
|
artifact: viewArtifact(presentation),
|
|
});
|
|
if (!projected.ok) return projected;
|
|
const identity = validateAnalysisViewSubject(
|
|
parent.subject,
|
|
projected.value.artifact?.sha256,
|
|
);
|
|
if (!identity.ok) return identity;
|
|
return ok(createAnalysisViewEvidence(input, presentation, projected.value));
|
|
};
|
|
|
|
/** Session Evidence ownership required to deliver a view instead of a complete record. */
|
|
export interface AnalysisViewRetention {
|
|
readonly evidenceById: EvidenceLookup | undefined;
|
|
readonly recordEvidence: EvidenceWriter["recordEvidence"] | undefined;
|
|
}
|
|
|
|
/** Fail before analysis when selected delivery cannot keep its complete source. */
|
|
export const requireAnalysisViewRetention = (
|
|
operation: string,
|
|
retention: AnalysisViewRetention,
|
|
): Result<
|
|
{
|
|
readonly evidenceById: EvidenceLookup;
|
|
readonly recordEvidence: EvidenceWriter["recordEvidence"];
|
|
},
|
|
AnalysisError
|
|
> => {
|
|
if (
|
|
retention.recordEvidence === undefined ||
|
|
retention.evidenceById === undefined
|
|
)
|
|
return err(
|
|
new AnalysisCapabilityUnavailableError(
|
|
ANALYSIS_VIEW_PROVIDER.id,
|
|
operation,
|
|
"summary detail requires a server session that retains Evidence for later views",
|
|
{
|
|
userMessage:
|
|
"This server does not retain Evidence. Select detail complete to receive the complete analysis inline.",
|
|
},
|
|
),
|
|
);
|
|
return ok({
|
|
evidenceById: retention.evidenceById,
|
|
recordEvidence: retention.recordEvidence,
|
|
});
|
|
};
|
|
|
|
/**
|
|
* Retain complete analysis Evidence in the session, then project its summary
|
|
* with this observation's subject path. Callers page or select the rest through
|
|
* inspect_analysis_view with the view's parent Evidence ID.
|
|
*/
|
|
export const summarizeRetainedAnalysis = (
|
|
evidence: Evidence,
|
|
retention: AnalysisViewRetention,
|
|
): Result<Evidence, AnalysisError> =>
|
|
projectRetainedAnalysis(evidence, retention, { kind: "summary" });
|
|
|
|
/** Retain the complete owner observation and deliver one explicitly selected view. */
|
|
export const projectRetainedAnalysis = (
|
|
evidence: Evidence,
|
|
retention: AnalysisViewRetention,
|
|
view: AnalysisViewRequest,
|
|
): Result<Evidence, AnalysisError> => {
|
|
const ready = requireAnalysisViewRetention(evidence.operation, retention);
|
|
if (!ready.ok) return ready;
|
|
const recorded = ready.value.recordEvidence(evidence);
|
|
if (!recorded.ok) return recorded;
|
|
const source = {
|
|
kind: "retained-evidence" as const,
|
|
evidence_id: evidence.evidence_id,
|
|
};
|
|
const retained = resolveEvidenceInput(source, ready.value.evidenceById);
|
|
if (!retained.ok) return retained;
|
|
// Duplicate semantic records retain their original ledger metadata. Detail
|
|
// selection changes presentation, not the historical lookup or payload owner.
|
|
const projected = projectResolvedAnalysisView(
|
|
{ source, view },
|
|
prepareAnalysisViewProjection(view),
|
|
retained.value,
|
|
evidenceSubjectTarget(evidence.subject),
|
|
);
|
|
if (!projected.ok) projected.error.retainPartialObservation(source);
|
|
return projected;
|
|
};
|
|
|
|
const resolveAnalysisViewSource = (
|
|
source: ReadyAnalysisViewInput["source"],
|
|
lookup: EvidenceLookup | undefined,
|
|
): Result<Evidence, AnalysisError> => {
|
|
if (source.kind === "retained-evidence")
|
|
return resolveEvidenceInput(source, lookup);
|
|
return authenticateEvidence(source.evidence, ["source", "evidence"], {
|
|
source,
|
|
});
|
|
};
|
|
|
|
/** Parse complete Evidence, reporting schema issues under the given request path. */
|
|
const authenticateEvidence = (
|
|
value: unknown,
|
|
path: readonly (string | number)[],
|
|
input: unknown,
|
|
): Result<Evidence, AnalysisError> => {
|
|
const parsed = safeParseEvidence(value);
|
|
if (parsed.ok) return parsed;
|
|
const cause = parsed.error;
|
|
if (isUnsupportedEvidenceFormat(cause))
|
|
return err(unsupportedEvidenceFormatError(cause));
|
|
return err(
|
|
analysisInputErrorFromIssues(
|
|
INSPECT_ANALYSIS_VIEW_OPERATION,
|
|
cause.issues.map((issue) => ({
|
|
...issue,
|
|
path: [...path, ...issue.path],
|
|
})),
|
|
input,
|
|
{ cause },
|
|
),
|
|
);
|
|
};
|
|
|
|
const createAnalysisViewEvidence = (
|
|
input: ReadyAnalysisViewInput,
|
|
parent: Evidence,
|
|
result: AnalysisViewResult,
|
|
): Evidence => {
|
|
// A view names the target its parent observed (a file or a page URL); a
|
|
// parent that names no target is committed through the view's link.
|
|
const subject =
|
|
parent.subject.identity.kind === "unknown"
|
|
? unknownTarget("derived-from-linked-evidence")
|
|
: evidenceSubjectInput(parent.subject);
|
|
const nativeFunctionView =
|
|
result.kind === "native" ||
|
|
(result.kind === "summary" &&
|
|
result.parent_operation === "analyze_function")
|
|
? result
|
|
: undefined;
|
|
const nativeObservationView =
|
|
result.kind === "native-observation" ||
|
|
result.kind === "native-context" ||
|
|
result.kind === "native-instruction-references" ||
|
|
(result.kind === "summary" &&
|
|
isNativeObservationOperation(result.parent_operation));
|
|
return createEvidence(
|
|
subject,
|
|
ANALYSIS_VIEW_PROVIDER,
|
|
{
|
|
predicateType: "rea.analysis-view",
|
|
operation: INSPECT_ANALYSIS_VIEW_OPERATION,
|
|
parameters: {
|
|
parent_evidence_id: parent.evidence_id,
|
|
view: input.view,
|
|
},
|
|
result,
|
|
rawResult: null,
|
|
confidence:
|
|
// A projection never strengthens its parent: inferred facts stay inferred.
|
|
// Grouping is whole-capture, so any templated group or parameter makes the result inferred;
|
|
// entity types and identity in an extracted state, and the coverage summarizing it, always are.
|
|
parent.confidence === "inferred" ||
|
|
result.kind === "environment-state" ||
|
|
result.kind === "environment-coverage" ||
|
|
((result.kind === "api-surface" ||
|
|
result.kind === "environment-manifest") &&
|
|
result.templated_groups > 0)
|
|
? "inferred"
|
|
: "derived",
|
|
authority: parent.authority,
|
|
environment: parent.environment,
|
|
limitations: result.limitations,
|
|
...((nativeFunctionView !== undefined || nativeObservationView) &&
|
|
parent.relationship_coverage !== null
|
|
? { relationshipCoverage: parent.relationship_coverage }
|
|
: {}),
|
|
locations: [
|
|
...(result.artifact != null && result.artifact.path.length > 0
|
|
? [{ kind: "artifact-path" as const, path: result.artifact.path }]
|
|
: []),
|
|
// Scalar text has no structured function entry; retain the producer's
|
|
// authenticated positions without interpreting the caller's selector.
|
|
...(parent.operation === "procedure_pseudo_code"
|
|
? parent.locations.filter(
|
|
(location) =>
|
|
location.kind !== "artifact-path" ||
|
|
location.path !== result.artifact?.path,
|
|
)
|
|
: []),
|
|
...(nativeFunctionView !== undefined &&
|
|
nativeFunctionView.procedure_address !== null &&
|
|
nativeFunctionView.procedure_address.length > 0
|
|
? [
|
|
{
|
|
kind: "address" as const,
|
|
address: nativeFunctionView.procedure_address,
|
|
},
|
|
]
|
|
: []),
|
|
],
|
|
evidenceLinks: [parent.evidence_id],
|
|
},
|
|
{ immutable: true },
|
|
);
|
|
};
|
|
|
|
/** The artifact a view names: the presented file target and its display path. */
|
|
const viewArtifact = (
|
|
evidence: Evidence,
|
|
): { readonly path: string; readonly sha256: string } | null => {
|
|
const target = evidenceFileTarget(evidence);
|
|
const display = evidenceSubjectDisplay(evidence);
|
|
return target === undefined || display === undefined
|
|
? null
|
|
: { path: display.local_path, sha256: target.sha256 };
|
|
};
|