rea-agents 5.0.0 → 6.0.0

package/dist/domain/analysisErrorProjection.js

@@ -1,5 +1,6 @@
+import { jsonValueSchema } from "./jsonValue.js";
 import { analysisErrorCategory, analysisErrorRemediationAction, analysisErrorUserMessage, assertKnownAnalysisErrorTag, } from "./analysisErrorPresentation.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, } from "./analysisErrorCore.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisUnsupportedTargetError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, AnalysisResourceConstraintError, } from "./analysisErrorCore.js";
 import { ArtifactOperationError } from "./artifactOperationError.js";
 import { BinaryTargetError } from "./configurationErrors.js";
 import { BrowserObservationError } from "./browserObservationError.js";
@@ -13,7 +14,10 @@ import {} from "./analysisErrorBase.js";
 export const projectAnalysisError = (error) => {
     assertKnownAnalysisErrorTag(error._tag);
     const code = errorCode(error);
-    const details = errorDetails(error);
+    const primaryDetails = errorDetails(error);
+    const details = error.capturedOutput === undefined
+        ? primaryDetails
+        : { ...primaryDetails, captured_output: { ...error.capturedOutput } };
     return {
         code,
         category: analysisErrorCategory(error),
@@ -88,10 +92,14 @@ const STATIC_ERROR_CODES = {
     AnalysisOutputError: "unreadable_output",
     HopperProtocolError: "unreadable_output",
     AnalysisInputError: "invalid_request",
+    AnalysisAccessDeniedError: "access_denied",
+    AnalysisArtifactChangedError: "artifact_changed",
     AnalysisCapabilityUnavailableError: "capability_unavailable",
+    AnalysisUnsupportedTargetError: "unsupported_target",
     AnalysisCancelledError: "cancelled",
     HopperCancelledError: "cancelled",
     AnalysisTimeoutError: "provider_timeout",
+    AnalysisResourceConstraintError: "resource_constraint",
     HopperTimeoutError: "provider_timeout",
     HopperProcessError: "provider_unavailable",
     HopperStartError: "provider_unavailable",
@@ -120,6 +128,33 @@ const errorDetails = (error) => requestErrorDetails(error) ??
     providerErrorDetails(error) ??
     lifecycleErrorDetails(error);
 const requestErrorDetails = (error) => {
+    if (error instanceof AnalysisUnsupportedTargetError)
+        return {
+            operation: error.operation,
+            path: error.path,
+            reason: error.reason,
+        };
+    if (error instanceof AnalysisResourceConstraintError)
+        return {
+            operation: error.operation,
+            resource: error.resource,
+            reason: error.reason,
+            reported_limits: error.reportedLimits,
+        };
+    if (error instanceof AnalysisArtifactChangedError)
+        return {
+            operation: error.operation,
+            path: error.path,
+            reason: error.reason,
+            boundary: "stable-artifact-read",
+        };
+    if (error instanceof AnalysisAccessDeniedError)
+        return {
+            operation: error.operation,
+            path: error.path,
+            system_code: error.systemCode,
+            boundary: "filesystem-read",
+        };
     if (error instanceof AnalysisOutputError)
         return { operation: error.operation, reason: error.reason };
     if (error instanceof AnalysisInputError && error.issues.length > 0)
@@ -272,10 +307,24 @@ const lifecycleErrorDetails = (error) => {
         return {
             cleanup: "incomplete",
             resources: [...error.cleanupResources],
+            ...(error.cleanupReport === undefined
+                ? {}
+                : { cleanup_report: jsonValueSchema.parse(error.cleanupReport) }),
+            ...(error.executionFailure === undefined
+                ? {}
+                : { execution_failure: error.executionFailure }),
+            ...(error.partialObservation === undefined
+                ? {}
+                : {
+                    partial_observation: jsonValueSchema.parse(error.partialObservation),
+                }),
         };
     if (error._tag === "ProcessCaptureError" &&
         error.userCategory === "cancelled")
         return { operation: "process_capture", cleanup: "complete" };
+    if (error._tag === "ProcessCaptureError" &&
+        error.executionFailure !== undefined)
+        return { execution_failure: error.executionFailure };
     if (error instanceof BinaryTargetError)
         return {
             path: error.path,
@@ -287,6 +336,7 @@ const lifecycleErrorDetails = (error) => {
     return undefined;
 };
 const RETRYABLE_CODES = new Set([
+    "artifact_changed",
     "invalid_request",
     "provider_timeout",
     "cancelled",

package/dist/domain/analysisSnapshot.js

@@ -77,11 +77,26 @@ const entrySchema = z.object({
         subject: subjectSchema.nullable(),
     }),
 });
+const workflowEntrySchema = z.object({
+    query_id: prefixedDigestSchema("query"),
+    operation: z.string().min(1),
+    parameters: jsonObjectSchema,
+    execution: z.object({
+        result: jsonValueSchema,
+        raw_result: jsonValueSchema.nullable(),
+        provider: committedProviderSchema,
+        analysis_profile: analysisProfileSchema,
+        limitations: z.array(z.string()),
+        locations: z.array(evidenceLocationSchema),
+        subject: subjectSchema.nullable(),
+    }),
+});
 /** Provider- and profile-exact cache of successful immutable analysis calls. */
 export const analysisSnapshotSchema = z.object({
     target: targetSchema,
     binding: bindingSchema,
     entries: z.array(entrySchema),
+    workflow_entries: z.array(workflowEntrySchema).optional(),
     evidence_bundle: evidenceBundleSchema,
 });
 const canonicalJson = (value) => {
@@ -122,6 +137,11 @@ export const snapshotEvidenceForQuery = (snapshot, query) => {
     if (!snapshotMatchesBinding(snapshot, target, bindingProfile))
         return undefined;
     const encodedParameters = canonicalJson(parameters);
+    const queryId = analysisQueryId(snapshot.target, snapshot.binding, operation, parameters);
+    const entry = snapshot.entries.find((candidate) => candidate.query_id === queryId);
+    const workflowEntry = snapshot.workflow_entries?.find((candidate) => candidate.query_id === queryId);
+    if (entry === undefined && workflowEntry === undefined)
+        return undefined;
     return snapshot.evidence_bundle.records.find((record) => record.subject?.digest.sha256 === target.sha256 &&
         record.operation === operation &&
         record.provider.id === provider.id &&
@@ -129,8 +149,54 @@ export const snapshotEvidenceForQuery = (snapshot, query) => {
         record.provider.version === provider.version &&
         "analysis_profile" in record &&
         analysisProfilesEqual(record.analysis_profile, evidenceProfile) &&
-        canonicalJson(record.parameters) === encodedParameters);
+        canonicalJson(record.parameters) === encodedParameters &&
+        ((entry !== undefined && evidenceMatchesEntry(record, entry, snapshot)) ||
+            (workflowEntry !== undefined &&
+                evidenceMatchesWorkflowEntry(record, workflowEntry, snapshot))));
+};
+/** Create one exact replay record for a derived application workflow result. */
+export const createAnalysisSnapshotWorkflowEntry = (input) => {
+    const { target, binding, operation, parameters, execution } = input;
+    if (execution.provider.id !== execution.analysisProfile.provider.id ||
+        execution.provider.name !== execution.analysisProfile.provider.name ||
+        execution.provider.version !== execution.analysisProfile.provider.version)
+        throw new TypeError("Workflow snapshot execution provider does not match its profile");
+    return {
+        query_id: analysisQueryId(target, binding, operation, parameters),
+        operation,
+        parameters: jsonObjectSchema.parse(parameters),
+        execution: {
+            result: execution.result,
+            raw_result: execution.rawResult,
+            provider: execution.analysisProfile.provider,
+            analysis_profile: execution.analysisProfile,
+            limitations: [...execution.limitations],
+            locations: [...execution.locations],
+            subject: execution.subject === null
+                ? null
+                : {
+                    ...execution.subject,
+                    architecture: execution.subject.architecture ?? null,
+                },
+        },
+    };
 };
+const evidenceMatchesEntry = (evidence, entry, snapshot) => isCorrespondingEvidence(evidence, snapshot) &&
+    canonicalJson({
+        query: evidenceQueryKey(evidence),
+        normalized_result: evidence.normalized_result,
+        raw_result: evidence.raw_result,
+        limitations: evidence.limitations,
+        locations: evidence.locations,
+        subject: evidence.subject === null
+            ? null
+            : {
+                local_path: evidence.subject.local_path,
+                sha256: evidence.subject.digest.sha256,
+                format: evidence.subject.format,
+                architecture: evidence.subject.architecture,
+            },
+    }) === entryEvidenceKey(entry, snapshot.binding);
 /** Compute the stable lookup key for one provider/profile-specific query. */
 export const analysisQueryId = (target, binding, operation, parameters) => `query_${createHash("sha256")
     .update(canonicalJson({ target, binding, operation, parameters }))
@@ -171,7 +237,9 @@ export const parseAnalysisSnapshot = (input) => {
         throw new TypeError("Analysis snapshot evidence contains records for another target");
     const ids = new Set();
     const boundEntries = [];
+    const boundWorkflowEntries = [];
     const index = createEvidenceIndex(parsed);
+    const workflowIndex = createWorkflowEvidenceIndex(parsed);
     for (const entry of parsed.entries) {
         if (entry.execution.provider.id !== parsed.binding.provider.id ||
             entry.execution.provider.name !== parsed.binding.provider.name ||
@@ -192,10 +260,41 @@ export const parseAnalysisSnapshot = (input) => {
         }
         boundEntries.push(entry);
     }
+    for (const entry of parsed.workflow_entries ?? []) {
+        if (entry.execution.provider.id !==
+            entry.execution.analysis_profile.provider.id ||
+            entry.execution.provider.name !==
+                entry.execution.analysis_profile.provider.name ||
+            entry.execution.provider.version !==
+                entry.execution.analysis_profile.provider.version)
+            throw new TypeError("Analysis snapshot workflow entry provider does not match its profile");
+        const expected = analysisQueryId(parsed.target, parsed.binding, entry.operation, entry.parameters);
+        if (entry.query_id !== expected)
+            throw new TypeError("Analysis snapshot workflow query identifier does not match");
+        if (ids.has(entry.query_id))
+            throw new TypeError("Analysis snapshot contains duplicate queries");
+        ids.add(entry.query_id);
+        if (!workflowEntryHasMatchingEvidence(entry, workflowIndex)) {
+            if (workflowEntryHasCorrespondingEvidence(entry, workflowIndex))
+                throw new TypeError(`Analysis snapshot workflow entry ${entry.operation} differs from its Evidence record`);
+            continue;
+        }
+        boundWorkflowEntries.push(entry);
+    }
     const sorted = [...parsed.entries].sort((left, right) => left.query_id.localeCompare(right.query_id));
     if (JSON.stringify(parsed.entries) !== JSON.stringify(sorted))
         throw new TypeError("Analysis snapshot entries are not canonical");
-    return { ...parsed, entries: boundEntries };
+    const sortedWorkflows = [...(parsed.workflow_entries ?? [])].sort((left, right) => left.query_id.localeCompare(right.query_id));
+    if (parsed.workflow_entries !== undefined &&
+        JSON.stringify(parsed.workflow_entries) !== JSON.stringify(sortedWorkflows))
+        throw new TypeError("Analysis snapshot workflow entries are not canonical");
+    return {
+        ...parsed,
+        entries: boundEntries,
+        ...(parsed.workflow_entries === undefined
+            ? {}
+            : { workflow_entries: boundWorkflowEntries }),
+    };
 };
 const createEvidenceIndex = (snapshot) => {
     const matching = new Set();
@@ -259,5 +358,70 @@ const entryEvidenceKey = (entry, binding) => canonicalJson({
             architecture: entry.execution.subject.architecture,
         },
 });
+const workflowEntryQueryKey = (entry) => canonicalJson({
+    operation: entry.operation,
+    parameters: entry.parameters,
+    provider: entry.execution.provider,
+    analysis_profile: entry.execution.analysis_profile,
+});
+const workflowEntryEvidenceKey = (entry) => canonicalJson({
+    query: workflowEntryQueryKey(entry),
+    normalized_result: entry.execution.result,
+    raw_result: entry.execution.raw_result,
+    limitations: entry.execution.limitations,
+    locations: entry.execution.locations,
+    subject: entry.execution.subject === null
+        ? null
+        : {
+            local_path: entry.execution.subject.path,
+            sha256: entry.execution.subject.sha256,
+            format: entry.execution.subject.format,
+            architecture: entry.execution.subject.architecture,
+        },
+});
+const isWorkflowEvidence = (evidence, snapshot, entry) => evidence.predicate_type === "rea.analysis" &&
+    evidence.confidence === "derived" &&
+    evidence.authority === "shipped-artifact" &&
+    evidence.subject?.digest.sha256 === snapshot.target.sha256 &&
+    "analysis_profile" in evidence &&
+    analysisProfilesEqual(evidence.analysis_profile, entry.execution.analysis_profile) &&
+    evidence.provider.id === entry.execution.provider.id &&
+    evidence.provider.name === entry.execution.provider.name &&
+    evidence.provider.version === entry.execution.provider.version;
+const createWorkflowEvidenceIndex = (snapshot) => {
+    const matching = new Set();
+    const corresponding = new Set();
+    for (const evidence of snapshot.evidence_bundle.records) {
+        if (evidence.predicate_type !== "rea.analysis" ||
+            evidence.confidence !== "derived" ||
+            evidence.authority !== "shipped-artifact" ||
+            evidence.subject?.digest.sha256 !== snapshot.target.sha256 ||
+            !("analysis_profile" in evidence))
+            continue;
+        corresponding.add(evidenceQueryKey(evidence));
+        matching.add(canonicalJson(evidenceContentProjection(evidence)));
+    }
+    return { matching, corresponding };
+};
+const workflowEntryHasMatchingEvidence = (entry, index) => index.matching.has(workflowEntryEvidenceKey(entry));
+const workflowEntryHasCorrespondingEvidence = (entry, index) => index.corresponding.has(workflowEntryQueryKey(entry));
+const evidenceMatchesWorkflowEntry = (evidence, entry, snapshot) => isWorkflowEvidence(evidence, snapshot, entry) &&
+    canonicalJson(evidenceContentProjection(evidence)) ===
+        workflowEntryEvidenceKey(entry);
+const evidenceContentProjection = (evidence) => ({
+    query: evidenceQueryKey(evidence),
+    normalized_result: evidence.normalized_result,
+    raw_result: evidence.raw_result,
+    limitations: evidence.limitations,
+    locations: evidence.locations,
+    subject: evidence.subject === null
+        ? null
+        : {
+            local_path: evidence.subject.local_path,
+            sha256: evidence.subject.digest.sha256,
+            format: evidence.subject.format,
+            architecture: evidence.subject.architecture,
+        },
+});
 /** Serialize a validated snapshot with byte-stable canonical entry ordering. */
 export const serializeAnalysisSnapshot = (snapshot) => `${canonicalJson(parseAnalysisSnapshot(snapshot))}\n`;

package/dist/domain/apple/dyldPaths.js

@@ -0,0 +1,81 @@
+const MAX_SYMLINK_HOPS = 32;
+/**
+ * Resolve a root-relative path one segment at a time, as `open` would:
+ * symlinks are followed inside the root, `..` applies to the real parent,
+ * and any escape above the root or through an absolute link stops.
+ */
+export const resolveTreePath = async (view, input) => {
+    const pending = segmentsOf(input);
+    const resolved = [];
+    let last;
+    let hops = 0;
+    while (pending.length > 0) {
+        const segment = pending.shift() ?? "";
+        if (segment === "..") {
+            if (resolved.length === 0)
+                return { kind: "escapes" };
+            resolved.pop();
+            last = { kind: "directory" };
+            continue;
+        }
+        const path = [...resolved, segment].join("/");
+        const entry = await view.entry(path);
+        if (entry === undefined)
+            return { kind: "absent" };
+        if (entry.kind === "symlink") {
+            hops += 1;
+            if (hops > MAX_SYMLINK_HOPS)
+                return { kind: "absent" };
+            if (entry.target.startsWith("/"))
+                return { kind: "escapes" };
+            pending.unshift(...segmentsOf(entry.target));
+            continue;
+        }
+        if (entry.kind === "file" && pending.length > 0)
+            return { kind: "absent" };
+        resolved.push(segment);
+        last = entry;
+    }
+    return last?.kind === "file"
+        ? { kind: "file", path: resolved.join("/") }
+        : { kind: "not-file" };
+};
+const segmentsOf = (path) => path.split("/").filter((segment) => segment !== "" && segment !== ".");
+export const directoryOf = (path) => {
+    const index = path.lastIndexOf("/");
+    return index < 0 ? "" : path.slice(0, index);
+};
+export const joinPath = (directory, rest) => directory === "" ? rest : rest === "" ? directory : `${directory}/${rest}`;
+/** Expand one dyld path prefix relative to its owning image. */
+export const expandPrefix = (raw, context) => {
+    const variable = /^@(executable_path|loader_path)(?:\/(.*))?$/u.exec(raw);
+    if (variable !== null) {
+        const rest = variable[2] ?? "";
+        if (variable[1] === "loader_path")
+            return { scope: "target", path: joinPath(context.ownerDirectory, rest) };
+        return context.executable === null
+            ? { scope: "undetermined", path: raw }
+            : {
+                scope: "target",
+                path: joinPath(directoryOf(context.executable), rest),
+            };
+    }
+    if (raw.startsWith("/"))
+        return { scope: "outside", path: raw };
+    return { scope: "undetermined", path: raw };
+};
+/**
+ * Slices a process may load, best first, following dyld's graded
+ * architectures: an x86_64h process also accepts generic x86_64.
+ */
+const COMPATIBLE_ARCHITECTURES = {
+    x86_64h: ["x86_64h", "x86_64"],
+};
+export const compatibleSlice = (slices, process) => {
+    for (const architecture of COMPATIBLE_ARCHITECTURES[process] ?? [process]) {
+        const slice = slices.find((item) => item.architecture === architecture);
+        if (slice !== undefined)
+            return slice;
+    }
+    return undefined;
+};