mirror of
https://github.com/morluto/rea.git
synced 2026-11-19 13:12:26 +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.
176 lines
6.1 KiB
TypeScript
176 lines
6.1 KiB
TypeScript
import { browserUrlTargetIdentity } from "../domain/browserObservation.js";
|
|
import { z } from "zod";
|
|
import type { ExecutionOptions } from "../ports/AnalysisProvider.js";
|
|
import type { WebRuntimePort } from "../ports/WebRuntimePort.js";
|
|
import type { AnalysisError } from "../domain/analysisErrorBase.js";
|
|
import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
|
|
import { createEvidence, type Evidence } from "../domain/evidence.js";
|
|
import { err, type Result } from "../domain/result.js";
|
|
import {
|
|
observeWebExecutionInputSchema,
|
|
webExecutionSchema,
|
|
webExecutionObservationSchema,
|
|
} from "../domain/webExecution.js";
|
|
import {
|
|
inspectWebEventListenersInputSchema,
|
|
webEventListenersSchema,
|
|
webEventListenersObservationSchema,
|
|
} from "../domain/webEventListeners.js";
|
|
import {
|
|
completeProviderEvidence,
|
|
keepIncompleteObservation,
|
|
} from "./ProviderOperationExecution.js";
|
|
import { parseAnalysisInput } from "./AnalysisInput.js";
|
|
|
|
/** Shared public workflows keep instrumentation and listener inspection independently selectable. */
|
|
export class WebRuntimeService {
|
|
constructor(readonly provider: WebRuntimePort) {}
|
|
|
|
/** Observe externally triggered execution; selection authorizes the declared instrumentation. */
|
|
async observe(
|
|
rawInput: unknown,
|
|
options?: ExecutionOptions,
|
|
): Promise<Result<Evidence, AnalysisError>> {
|
|
const operation = "observe_web_execution";
|
|
const parsed = parseAnalysisInput(
|
|
operation,
|
|
rawInput,
|
|
observeWebExecutionInputSchema,
|
|
options?.signal,
|
|
);
|
|
if (!parsed.ok) return parsed;
|
|
const result = await this.provider.observeExecution(parsed.value, options);
|
|
if (!result.ok)
|
|
return this.retainRuntimePartial(
|
|
result.error,
|
|
operation,
|
|
"Provider retained a non-JSON incomplete execution observation.",
|
|
(partial) => {
|
|
if (!("instrumentation" in partial) || !("window" in partial))
|
|
return undefined;
|
|
const verified = webExecutionObservationSchema.safeParse(partial);
|
|
if (!verified.success) return undefined;
|
|
return this.evidence(operation, parsed.value, verified.data);
|
|
},
|
|
);
|
|
const verified = webExecutionSchema.safeParse(result.value);
|
|
if (!verified.success)
|
|
return err(new AnalysisOutputError(operation, verified.error.message));
|
|
return this.evidence(operation, parsed.value, verified.data, options);
|
|
}
|
|
|
|
/** Inspect one selected node's listener declarations without dispatching an event. */
|
|
async inspect(
|
|
rawInput: unknown,
|
|
options?: ExecutionOptions,
|
|
): Promise<Result<Evidence, AnalysisError>> {
|
|
const operation = "inspect_web_event_listeners";
|
|
const parsed = parseAnalysisInput(
|
|
operation,
|
|
rawInput,
|
|
inspectWebEventListenersInputSchema,
|
|
options?.signal,
|
|
);
|
|
if (!parsed.ok) return parsed;
|
|
const result = await this.provider.inspectEventListeners(
|
|
parsed.value,
|
|
options,
|
|
);
|
|
if (!result.ok)
|
|
return this.retainRuntimePartial(
|
|
result.error,
|
|
operation,
|
|
"Provider retained a non-JSON incomplete event-listener observation.",
|
|
(partial) => {
|
|
if (!("selected_node" in partial) || !("listeners" in partial))
|
|
return undefined;
|
|
const verified =
|
|
webEventListenersObservationSchema.safeParse(partial);
|
|
if (!verified.success) return undefined;
|
|
return this.evidence(operation, parsed.value, verified.data);
|
|
},
|
|
);
|
|
const verified = webEventListenersSchema.safeParse(result.value);
|
|
if (!verified.success)
|
|
return err(new AnalysisOutputError(operation, verified.error.message));
|
|
return this.evidence(operation, parsed.value, verified.data, options);
|
|
}
|
|
|
|
/** Promote a schema-valid partial, or keep a JSON snapshot of an incomplete one. */
|
|
private retainRuntimePartial(
|
|
error: AnalysisError,
|
|
operation: string,
|
|
nonJsonReason: string,
|
|
promote: (
|
|
partial: NonNullable<AnalysisError["partialObservation"]>,
|
|
) => Result<Evidence, AnalysisError> | undefined,
|
|
): Result<Evidence, AnalysisError> {
|
|
const partial = error.partialObservation;
|
|
if (partial !== undefined && !("evidence_id" in partial)) {
|
|
const evidence = promote(partial);
|
|
if (evidence !== undefined) {
|
|
if (evidence.ok) {
|
|
error.partialObservation = evidence.value;
|
|
return err(error);
|
|
}
|
|
}
|
|
}
|
|
return err(keepIncompleteObservation(error, operation, nonJsonReason));
|
|
}
|
|
|
|
private evidence(
|
|
operation: string,
|
|
input:
|
|
| z.infer<typeof observeWebExecutionInputSchema>
|
|
| z.infer<typeof inspectWebEventListenersInputSchema>,
|
|
result:
|
|
| z.infer<typeof webExecutionObservationSchema>
|
|
| z.infer<typeof webEventListenersObservationSchema>,
|
|
options?: ExecutionOptions,
|
|
): Result<Evidence, AnalysisError> {
|
|
if (
|
|
result.target.target_id !== input.target_id ||
|
|
("observation_ms" in input &&
|
|
(!("window" in result) ||
|
|
result.window.requested_ms !== input.observation_ms)) ||
|
|
("selector" in input &&
|
|
(!("selected_node" in result) ||
|
|
result.selected_node.selector !== input.selector))
|
|
)
|
|
return err(
|
|
new AnalysisOutputError(
|
|
operation,
|
|
"observation_ms" in input
|
|
? "Provider changed the selected target or requested window."
|
|
: "Provider changed the selected target or node selector.",
|
|
),
|
|
);
|
|
if (
|
|
input.allowed_origins.length > 0 &&
|
|
!input.allowed_origins.includes(result.target.origin)
|
|
)
|
|
return err(
|
|
new AnalysisOutputError(
|
|
operation,
|
|
"Provider returned a document outside the selected origin scope.",
|
|
),
|
|
);
|
|
return completeProviderEvidence(
|
|
createEvidence(
|
|
browserUrlTargetIdentity(result.target.initial_url),
|
|
this.provider.identity(),
|
|
{
|
|
predicateType: `rea.${operation.replaceAll("_", "-")}`,
|
|
operation,
|
|
parameters: input,
|
|
result,
|
|
confidence: "observed",
|
|
authority: "external-service",
|
|
limitations: result.limitations,
|
|
},
|
|
),
|
|
options?.signal,
|
|
);
|
|
}
|
|
}
|