Files
rea/src/contracts/applicationToolContracts.ts
T
Kaoru0822andClaude Opus 5.5 ade11fa02d feat(apple): inspect dyld shared caches and resolve system paths
macOS 11 and later ship system libraries only inside the dyld shared
cache. trace_dylib_resolution therefore left every /usr/lib and /System
load undetermined, and REA had no way to see what a cache contains.

inspect_dyld_shared_cache (CLI inspect-dyld-shared-cache) reads a cache
file set selected by path, without an open target. Its pure TypeScript
reader parses modern and legacy dyld_cache_header layouts and reports:
- UUID, architecture, platform, OS version, Mac Catalyst alternate,
  cache type, shared region, max slide;
- every VM mapping;
- each subcache by file suffix, checked by UUID. A missing or
  mismatched subcache makes coverage partial;
- the complete image list.
For each requested install path it reads that image's load commands
through the cache mappings with the existing Mach-O reader.

trace_dylib_resolution accepts an optional shared_cache. Absolute
candidates found in a cache that serves the process's CPU family resolve
with the new outcome and status `shared-cache`. That status also takes
precedence over later in-bundle fallbacks such as a back-deployed
libswiftCore. The result names the cache UUID and OS version it used.

verify:dyld-shared-cache checks every image in the host cache (3,649 on
macOS 26.6), with dependencies and their re-export, weak, upward and
delay-init attributes, against `dyld_info -all_dyld_cache
-linked_dylibs`. It also checks CLI/MCP parity, and that each
shared-cache edge in the fixture trace is a library dyld actually loads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 11:43:15 +00:00

364 lines
16 KiB
TypeScript

import { applicationVersionComparisonResultSchema } from "../domain/javascript/javascriptApplicationVersionComparisonSchemas.js";
import {
dyldSharedCacheResultSchema,
inspectDyldSharedCacheInputSchema,
} from "../domain/dyldSharedCache.js";
import { applicationFeatureTraceResultSchema } from "../domain/javascript/javascriptFeatureTraceSchemas.js";
import { javaScriptSemanticTraceResultSchema } from "../domain/javascript/javascriptSemanticTraceSchemas.js";
import { javaScriptExportShapeComparisonResultSchema } from "../domain/javascript/javascriptExportShapeComparisonSchemas.js";
import { sourceToBundleComparisonResultSchema } from "../domain/javascript/sourceToBundleComparisonSchemas.js";
import {
compareApplicationVersionsRequestSchema,
compareJavaScriptExportShapesRequestSchema,
compareSourceToBundleRequestSchema,
traceApplicationFeatureRequestSchema,
traceJavaScriptSemanticsRequestSchema,
} from "./javascript/applicationWorkflowInputContracts.js";
import { reconstructionCoverageEvaluationInputSchema } from "../domain/reconstructionCoverageInput.js";
import { reconstructionClosureResultSchema } from "../domain/reconstructionCoverage.js";
import {
reconstructionObligationLedgerInputSchema,
reconstructionObligationLedgerSchema,
} from "../domain/reconstructionObligationLedgerSchemas.js";
import {
androidApplicationProjectionInputSchema,
androidApplicationProjectionResultSchema,
} from "../domain/android/androidApplication.js";
import {
appleApplicationProjectionInputSchema,
appleApplicationProjectionResultSchema,
} from "../domain/appleApplication.js";
import type { ToolContract } from "./toolContracts.js";
import { toolContractMetadata } from "./toolEffects.js";
import { evidenceResultOf } from "./toolOutputSchemas.js";
import {
JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE,
JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE,
} from "./javascript/javascriptApplicationWorkflowExamples.js";
import {
ANDROID_APPLICATION_GRAPH_EXAMPLE,
APPLE_APPLICATION_GRAPH_EXAMPLE,
MACOS_APPLICATION_GRAPH_EXAMPLE,
} from "./mobileApplicationGraphExamples.js";
const traceOutputSchema = evidenceResultOf(applicationFeatureTraceResultSchema);
const semanticTraceOutputSchema = evidenceResultOf(
javaScriptSemanticTraceResultSchema,
);
const comparisonOutputSchema = evidenceResultOf(
applicationVersionComparisonResultSchema,
);
const sourceToBundleOutputSchema = evidenceResultOf(
sourceToBundleComparisonResultSchema,
);
const exportShapeComparisonOutputSchema = evidenceResultOf(
javaScriptExportShapeComparisonResultSchema,
);
const reconstructionObligationLedgerOutputSchema = evidenceResultOf(
reconstructionObligationLedgerSchema,
);
const HASH = "0".repeat(64);
const retained = (evidence_id: string) => ({
kind: "retained-evidence" as const,
evidence_id,
});
/** Provider-neutral graph workflow contracts shared by MCP and CLI adapters. */
export const APPLICATION_TOOL_CONTRACTS = [
{
name: "trace_application_feature",
...toolContractMetadata("trace_application_feature"),
description:
"Trace a typed literal seed through every reachable part of an authenticated JavaScript Application Graph supplied as inline Evidence or exact same-session retained references. Original static, native, passive-runtime, inferred, and unknown authorities remain distinct; native addon handoffs never open a provider or execute the application.",
kind: "application",
inputSchema: traceApplicationFeatureRequestSchema,
outputSchema: traceOutputSchema,
examples: [
{
title: "Trace one module seed through a retained application graph",
input: JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
},
{
title: "Use exact Evidence already retained in this session",
input: {
...JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
application: retained(
JAVASCRIPT_FEATURE_TRACE_EXAMPLE.application.evidence_id,
),
},
},
],
},
{
name: "trace_javascript_semantics",
...toolContractMetadata("trace_javascript_semantics"),
description:
"Trace static JavaScript data-flow, direct call/return, and closure relations from inline application Evidence or an exact same-session retained reference. Dynamic or unsupported semantics remain explicit unknowns; static reachability never claims runtime execution.",
kind: "application",
inputSchema: traceJavaScriptSemanticsRequestSchema,
outputSchema: semanticTraceOutputSchema,
examples: [
{
title: "Trace backward provenance from one semantic node",
input: {
application: JAVASCRIPT_FEATURE_TRACE_EXAMPLE.application,
query: {
seed: { kind: "semantic-node", node_id: `jsrg_node_${HASH}` },
direction: "backward-provenance",
},
},
},
],
},
{
name: "compare_application_versions",
...toolContractMetadata("compare_application_versions"),
description:
"Compare two authenticated JavaScript Application Graph versions supplied as inline Evidence or exact same-session retained references. Uses unique-only exact digest, module source digest, source-map identity, structural fingerprint, and non-module semantic-key tiers. Reports added, removed, changed, ambiguous, and unknown entities plus the complete matching changed_from graph without fuzzy or module-ordinal pairing.",
kind: "application",
inputSchema: compareApplicationVersionsRequestSchema,
outputSchema: comparisonOutputSchema,
examples: [
{
title: "Compare authenticated static and reconciled application graphs",
input: JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
},
{
title: "Use exact Evidence already retained in this session",
input: {
...JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
left: retained(
JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE.left.evidence_id,
),
right: retained(
JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE.right.evidence_id,
),
},
},
],
},
{
name: "compare_source_to_bundle",
...toolContractMetadata("compare_source_to_bundle"),
description:
"Compare a cryptographically committed HistoricalSourceGraph with authenticated JavaScript Application Graph Evidence supplied inline or by exact same-session retained reference. Uses explicit exact-digest, source-map path, current-path, suffix, and basename signals with stable weights. Classifies unchanged, modified, removed, split, merged, duplicated, and unknown; incomplete coverage and ambiguous weak signals never become absence or forced matches.",
kind: "application",
inputSchema: compareSourceToBundleRequestSchema,
outputSchema: sourceToBundleOutputSchema,
examples: [
{
title:
"Compare committed historical source with a shipped bundle graph",
input: SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE,
},
],
},
{
name: "compare_javascript_export_shapes",
...toolContractMetadata("compare_javascript_export_shapes"),
description:
"Compare static return shapes for one exact module/export selector on each authenticated JavaScript Application Graph supplied as inline Evidence or exact same-session retained references. Variants pair only by reciprocal unique literal discriminants; dynamic values, incomplete properties, and ambiguous variants remain unknown. Reports JSON Pointer changes without executing JavaScript; runtime behavior requires a separate agent-run probe.",
kind: "application",
inputSchema: compareJavaScriptExportShapesRequestSchema,
outputSchema: exportShapeComparisonOutputSchema,
examples: [
{
title: "Compare one exact parser export without execution",
input: JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE,
},
{
title: "Use exact Evidence already retained in this session",
input: {
...JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE,
left: retained(
JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE.left.evidence_id,
),
right: retained(
JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE.right.evidence_id,
),
},
},
],
},
{
name: "build_reconstruction_obligation_ledger",
...toolContractMetadata("build_reconstruction_obligation_ledger"),
description:
"Generate the complete deterministic ReconstructionObligationLedger from an authenticated Evidence bundle, reviewed obligations, and an explicit reconstruction manifest. Static candidates remain candidates; duplicate ownership, missing original or reconstruction cases, missing parser/type, weak verifier authority, unenumerated claims, contradictions, dependencies, and residual unknowns fail closed. The inline result carries the full-ledger closure digest and typed per-obligation diagnostics.",
kind: "application",
inputSchema: reconstructionObligationLedgerInputSchema,
outputSchema: reconstructionObligationLedgerOutputSchema,
examples: [
{
title: "Generate the complete obligation ledger",
input: {
evidence_bundle: {
artifacts: [],
providers: [],
environments: [],
scenarios: [],
captures: [],
unknowns: [],
records: [],
},
reviewed_obligations: [],
manifest: {
bindings: [],
contradictions: [],
},
},
},
],
},
{
name: "evaluate_reconstruction_coverage",
...toolContractMetadata("evaluate_reconstruction_coverage"),
description:
"Evaluate inline evidence-backed reconstruction coverage against one named boundary. Missing ownership or inventory is partial; stale, weak, truncated, skipped, or unresolved proof is unknown; contradictions, failed proof, missing owners, and authority routing fail closed.",
kind: "application",
inputSchema: reconstructionCoverageEvaluationInputSchema,
outputSchema: reconstructionClosureResultSchema,
examples: [
{
title: "Evaluate one replacement boundary",
input: {
coverage: {
evidence_bundle: {
artifacts: [],
providers: [],
environments: [],
scenarios: [],
captures: [],
unknowns: [],
records: [],
},
artifacts: [],
surfaces: [],
owners: [],
claims: [],
verifier_contracts: [],
verifier_results: [],
residual_unknown_ids: [],
contradictions: [],
package_proofs: [],
boundaries: [
{
boundary_id: "replacement.cli",
title: "CLI replacement",
required_surface_ids: ["cli.help"],
required_claim_ids: ["claim.cli.help"],
required_package_proof_kinds: [
"clean-install",
"authority-independence",
],
allowed_dispositions: [],
allowed_unknown_ids: [],
},
],
},
boundary_id: "replacement.cli",
},
},
],
},
{
name: "project_android_application_graph",
...toolContractMetadata("project_android_application_graph"),
description:
"Project authenticated APK inventory_artifact Evidence into an execution-free Android application inventory. Reports exact component paths and hashes, runtime-family hints, and path-based bridge hypotheses without decoding DEX, executing the APK, or claiming observed runtime calls.",
kind: "application",
inputSchema: androidApplicationProjectionInputSchema,
outputSchema: evidenceResultOf(androidApplicationProjectionResultSchema),
examples: [
{
title:
"Project APK inventory Evidence into an Android application graph",
input: ANDROID_APPLICATION_GRAPH_EXAMPLE,
},
],
},
{
name: "project_apple_application_graph",
...toolContractMetadata("project_apple_application_graph"),
description:
"Project authenticated IPA, macOS .app directory, ZIP, or DMG inventory Evidence into an execution-free Apple application inventory. Reports application roots, nested bundles with path-convention roles (app extensions, XPC services, login items, privileged helpers, system extensions, frameworks), launchd plists, exact component paths and hashes, runtime-family hints, and path-based bridge hypotheses without parsing plist/CMS semantics or claiming observed runtime calls.",
kind: "application",
inputSchema: appleApplicationProjectionInputSchema,
outputSchema: evidenceResultOf(appleApplicationProjectionResultSchema),
examples: [
{
title: "Project IPA inventory Evidence into an Apple application graph",
input: APPLE_APPLICATION_GRAPH_EXAMPLE,
},
{
title:
"Project a macOS .app directory inventory into its bundle anatomy",
input: MACOS_APPLICATION_GRAPH_EXAMPLE,
},
],
},
{
name: "inspect_dyld_shared_cache",
...toolContractMetadata("inspect_dyld_shared_cache"),
description:
"Inspect an Apple dyld shared cache file set selected by path, such as /System/Volumes/Preboot/Cryptexes/OS/System/Library/dyld/dyld_shared_cache_arm64e or one extracted from an IPSW. Reports the cache UUID, architecture, platform and OS version, VM mappings, every subcache with UUID verification, and the complete image list. For each requested install path, it reads that image's load commands (install name, dependencies, rpaths) through the cache mappings. Pure file parsing: nothing is executed, slid, or extracted.",
kind: "application",
inputSchema: inspectDyldSharedCacheInputSchema,
outputSchema: evidenceResultOf(dyldSharedCacheResultSchema),
examples: [
{
title: "Inspect the host's arm64e shared cache and libSystem",
input: {
cache_path:
"/System/Volumes/Preboot/Cryptexes/OS/System/Library/dyld/dyld_shared_cache_arm64e",
images: ["/usr/lib/libSystem.B.dylib"],
},
},
],
},
] as const satisfies readonly ToolContract[];
/** Resolve one named application contract without relying on array position. */
export function applicationToolContract(
name: "trace_application_feature",
): (typeof APPLICATION_TOOL_CONTRACTS)[0];
export function applicationToolContract(
name: "trace_javascript_semantics",
): (typeof APPLICATION_TOOL_CONTRACTS)[1];
export function applicationToolContract(
name: "compare_application_versions",
): (typeof APPLICATION_TOOL_CONTRACTS)[2];
export function applicationToolContract(
name: "compare_source_to_bundle",
): (typeof APPLICATION_TOOL_CONTRACTS)[3];
export function applicationToolContract(
name: "compare_javascript_export_shapes",
): (typeof APPLICATION_TOOL_CONTRACTS)[4];
export function applicationToolContract(
name: "build_reconstruction_obligation_ledger",
): (typeof APPLICATION_TOOL_CONTRACTS)[5];
export function applicationToolContract(
name: "evaluate_reconstruction_coverage",
): (typeof APPLICATION_TOOL_CONTRACTS)[6];
export function applicationToolContract(
name: "project_android_application_graph",
): (typeof APPLICATION_TOOL_CONTRACTS)[7];
export function applicationToolContract(
name: "project_apple_application_graph",
): (typeof APPLICATION_TOOL_CONTRACTS)[8];
export function applicationToolContract(
name: "inspect_dyld_shared_cache",
): (typeof APPLICATION_TOOL_CONTRACTS)[9];
export function applicationToolContract(
name: (typeof APPLICATION_TOOL_CONTRACTS)[number]["name"],
): (typeof APPLICATION_TOOL_CONTRACTS)[number] {
const contract = APPLICATION_TOOL_CONTRACTS.find(
({ name: candidate }) => candidate === name,
);
if (contract === undefined)
throw new Error(`Missing application tool contract: ${name}`);
return contract;
}