rea-agents 4.1.0 → 5.0.0

package/dist/contracts/toolContracts.js

@@ -1,13 +1,16 @@
-import { NATIVE_TOOL_CONTRACTS } from "./nativeToolContracts.js";
+import { NATIVE_TOOL_CONTRACTS } from "./native/nativeToolContracts.js";
 import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";
-import { MANAGED_TOOL_CONTRACTS } from "./managedToolContracts.js";
-import { FIRMWARE_TOOL_CONTRACTS } from "./firmwareToolContracts.js";
-import { ANDROID_TOOL_CONTRACTS } from "./androidToolContracts.js";
-import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "./managedWorkflowToolContracts.js";
+import { MANAGED_TOOL_CONTRACTS } from "./managed/managedToolContracts.js";
+import { FIRMWARE_TOOL_CONTRACTS } from "./firmware/firmwareToolContracts.js";
+import { ANDROID_TOOL_CONTRACTS } from "./android/androidToolContracts.js";
+import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "./managed/managedWorkflowToolContracts.js";
 import { BROWSER_PROVIDER_TOOL_CONTRACTS } from "./browserProviderToolContracts.js";
-import { ELECTRON_TOOL_CONTRACTS } from "./electronToolContracts.js";
-import { JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS } from "./javascriptRuntimeObservationToolContracts.js";
+import { ELECTRON_TOOL_CONTRACTS } from "./javascript/electronToolContracts.js";
+import { JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS } from "./javascript/javascriptRuntimeObservationToolContracts.js";
 import { APPLICATION_TOOL_CONTRACTS } from "./applicationToolContracts.js";
+import { WEB_SCRIPT_TOOL_CONTRACTS } from "./webScriptToolContracts.js";
+import { WEB_RUNTIME_TOOL_CONTRACTS } from "./webRuntimeToolContracts.js";
+import { JAVASCRIPT_RECOVERY_TOOL_CONTRACTS } from "./javascript/javascriptRecoveryToolContracts.js";
 import { OFFICIAL_TOOL_CONTRACTS } from "./officialToolContracts.js";
 import { ENHANCED_TOOL_CONTRACTS } from "./enhancedToolContracts.js";
 import { SESSION_TOOL_CONTRACTS } from "./sessionToolContracts.js";
@@ -25,6 +28,9 @@ export const TOOL_CONTRACTS = [
     ...ELECTRON_TOOL_CONTRACTS,
     ...JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS,
     ...APPLICATION_TOOL_CONTRACTS,
+    ...WEB_SCRIPT_TOOL_CONTRACTS,
+    ...WEB_RUNTIME_TOOL_CONTRACTS,
+    ...JAVASCRIPT_RECOVERY_TOOL_CONTRACTS,
     ...SESSION_TOOL_CONTRACTS,
 ];
 /** Resolve a public contract by name while retaining its exact schema types. */

package/dist/contracts/toolEffects.js

@@ -18,6 +18,25 @@ const browserEvidence = effects({
 const sessionEvidence = effects({ mutatesSession: true });
 /** Explicit effect audit for every public tool. */
 export const TOOL_EFFECTS = {
+    observe_web_execution: effects({
+        mutatesTarget: true,
+        mutatesSession: true,
+        accessesNetwork: true,
+        mayDiscardData: true,
+        idempotent: false,
+    }),
+    inspect_web_event_listeners: browserEvidence,
+    trace_web_source_location: effects({
+        mutatesSession: true,
+        writesFilesystem: true,
+        launchesProcess: true,
+    }),
+    trace_web_module_imports: effects({
+        mutatesSession: true,
+        writesFilesystem: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+    }),
     inspect_firmware_regions: effects({
         mutatesSession: true,
         launchesProcess: true,
@@ -192,7 +211,18 @@ export const TOOL_EFFECTS = {
     list_javascript_runtime_targets: browserEvidence,
     observe_javascript_runtime: browserEvidence,
     analyze_javascript_application: evidence,
+    export_web_scripts: effects({
+        mutatesSession: true,
+        writesFilesystem: true,
+        idempotent: false,
+    }),
     reconcile_javascript_runtime: evidence,
+    recover_javascript_sources: effects({
+        mutatesSession: true,
+        writesFilesystem: true,
+        launchesProcess: true,
+        idempotent: false,
+    }),
     trace_application_feature: evidence,
     trace_javascript_semantics: evidence,
     compare_application_versions: evidence,
@@ -200,6 +230,8 @@ export const TOOL_EFFECTS = {
     compare_javascript_export_shapes: evidence,
     build_reconstruction_obligation_ledger: evidence,
     evaluate_reconstruction_coverage: effects(),
+    project_android_application_graph: evidence,
+    project_apple_application_graph: evidence,
     open_binary: effects({ mutatesSession: true, launchesProcess: true }),
     close_binary: effects({
         mutatesSession: true,

package/dist/contracts/toolOutputSchemaGroups.js

@@ -1,27 +1,27 @@
 import { z } from "zod";
-import { nativeFunctionAnnotationsSchema } from "../domain/nativeFunctionAnnotations.js";
-import { nativeLoadImageSchema } from "../domain/nativeLoadImage.js";
-import { nativeUiResultSchema } from "../domain/nativeUiObservation.js";
-import { nativeValueTraceSchema } from "../domain/nativeValueTrace.js";
-import { nativeDataTypeSchema } from "../domain/nativeDataType.js";
-import { nativeInstructionSchema, nativeCallTargetsSchema, } from "../domain/nativeInstruction.js";
+import { nativeFunctionAnnotationsSchema } from "../domain/native/nativeFunctionAnnotations.js";
+import { nativeLoadImageSchema } from "../domain/native/nativeLoadImage.js";
+import { nativeUiResultSchema } from "../domain/native/nativeUiObservation.js";
+import { nativeValueTraceSchema } from "../domain/native/nativeValueTrace.js";
+import { nativeDataTypeSchema } from "../domain/native/nativeDataType.js";
+import { nativeInstructionSchema, nativeCallTargetsSchema, } from "../domain/native/nativeInstruction.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { residualUnknownSchema } from "../domain/residualUnknown.js";
 import { evidenceBundleSchema } from "../domain/evidenceBundle.js";
 import { processCaptureComparisonSchema, processCaptureSchema, } from "../domain/processCapture.js";
 import { functionInstructionWindowSchema, referenceKindSchema, } from "../domain/hopperValues.js";
-import { nativeApiInspectionResultSchema } from "../domain/nativeApiBoundary.js";
-import { demangleSwiftSchema, inspectMachoSchema, inspectPlistSchema, inspectSignatureSchema, listArchitecturesSchema, } from "../domain/nativeInspection.js";
+import { nativeApiInspectionResultSchema } from "../domain/native/nativeApiBoundary.js";
+import { demangleSwiftSchema, inspectMachoSchema, inspectPlistSchema, inspectSignatureSchema, listArchitecturesSchema, } from "../domain/native/nativeInspection.js";
 import { artifactExtractionResultSchema } from "../domain/artifactGraph.js";
 import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
-import { interfaceBuilderAnalysisSchema } from "../domain/interfaceBuilderGraph.js";
-import { keyedArchiveResultSchema } from "../domain/keyedArchive.js";
-import { appleAssetCatalogResultSchema } from "../domain/appleAssetCatalog.js";
-import { managedArtifactInspectionSchema, managedMemberInspectionSchema, managedNativeBoundaryInspectionSchema, } from "../domain/managedArtifact.js";
-import { managedMemberComparisonResultSchema } from "../domain/managedMemberComparison.js";
-import { managedNativeVerificationResultSchema } from "../domain/managedNativeVerification.js";
-import { managedReconstructionImportResultSchema } from "../domain/managedReconstruction.js";
-import { managedApplicationGraphResultSchema } from "../domain/managedApplicationGraph.js";
+import { interfaceBuilderAnalysisSchema } from "../domain/apple/interfaceBuilderGraph.js";
+import { keyedArchiveResultSchema } from "../domain/apple/keyedArchive.js";
+import { appleAssetCatalogResultSchema } from "../domain/apple/appleAssetCatalog.js";
+import { managedArtifactInspectionSchema, managedMemberInspectionSchema, managedNativeBoundaryInspectionSchema, } from "../domain/managed/managedArtifact.js";
+import { managedMemberComparisonResultSchema } from "../domain/managed/managedMemberComparison.js";
+import { managedNativeVerificationResultSchema } from "../domain/managed/managedNativeVerification.js";
+import { managedReconstructionImportResultSchema } from "../domain/managed/managedReconstruction.js";
+import { managedApplicationGraphResultSchema } from "../domain/managed/managedApplicationGraph.js";
 import { artifactComparisonResultSchema } from "../domain/artifactComparison.js";
 import { functionComparisonResultSchema } from "../domain/functionComparison.js";
 import { bundleComparisonResultSchema } from "../domain/bundleComparison.js";
@@ -30,8 +30,8 @@ import { callPathResultSchema } from "../domain/callPath.js";
 import { staticRuntimeCorrelationResultSchema } from "../domain/staticRuntimeCorrelation.js";
 import { reconstructionVerificationResultSchema } from "../domain/reconstructionVerification.js";
 import { analysisErrorProjectionSchema } from "./errorSchemas.js";
-import { nativeDispatchMetadataResultSchema } from "../domain/objcSwiftMetadata.js";
-import { nativeInvestigationTraceSchema } from "../domain/nativeInvestigationGraph.js";
+import { nativeDispatchMetadataResultSchema } from "../domain/native/objcSwiftMetadata.js";
+import { nativeInvestigationTraceSchema } from "../domain/native/nativeInvestigationGraph.js";
 import { addressList, addressedValue, addressedEntry, containingProcedureResolution, functionDossierOutput, graphNode, lifecycleResultOf, nullableText, procedureIdentity, procedureInfoOutput, evidenceResultOf as resultOf, segmentOutput, sessionProvider, symbolDiscoveryOutput, targetFormatSchema, targetKindSchema, } from "./toolOutputSchemaPrimitives.js";
 const contextFacetSchema = z.discriminatedUnion("state", [
     z.object({ state: z.literal("available"), value: jsonValueSchema }),

package/dist/contracts/webRuntimeToolContracts.js

@@ -0,0 +1,43 @@
+import { toolContractMetadata } from "./toolEffects.js";
+import { evidenceResultOf } from "./toolOutputSchemas.js";
+import { observeWebExecutionInputSchema, webExecutionSchema, } from "../domain/webExecution.js";
+import { inspectWebEventListenersInputSchema, webEventListenersSchema, } from "../domain/webEventListeners.js";
+/** Native website runtime primitives distinguish instrumentation from listener inspection. */
+export const WEB_RUNTIME_TOOL_CONTRACTS = [
+    {
+        name: "observe_web_execution",
+        ...toolContractMetadata("observe_web_execution"),
+        description: "Instrument one selected CDP page for a finite, externally driven precise coverage window. Resets execution counters and prevents optimized execution until stopped. Returns complete nested UTF-16 ranges/counts, independently hashed script text and request initiator associations by session script ID. Does not navigate, click, evaluate selected code or close the externally owned page. Navigation ends document-scoped collection; workers and UI causality remain outside this claim. Emits an actual armed progress notification before external actions.",
+        kind: "browser-provider",
+        inputSchema: observeWebExecutionInputSchema,
+        outputSchema: evidenceResultOf(webExecutionSchema),
+        examples: [
+            {
+                title: "Attribute externally triggered page execution",
+                input: {
+                    cdp_endpoint: "http://127.0.0.1:9222",
+                    target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS",
+                    observation_ms: 10_000,
+                },
+            },
+        ],
+    },
+    {
+        name: "inspect_web_event_listeners",
+        ...toolContractMetadata("inspect_web_event_listeners"),
+        description: "Inspect listeners registered directly on the first main-document CSS match in one selected CDP page. Returns event flags, native callback locations, source ownership and exact script text/digests inline. Does not dispatch events, evaluate JavaScript or invoke handlers. Delegated ancestor/framework listeners and execution history remain unknown. Releases REA's object group and transport, preserving the external page.",
+        kind: "browser-provider",
+        inputSchema: inspectWebEventListenersInputSchema,
+        outputSchema: evidenceResultOf(webEventListenersSchema),
+        examples: [
+            {
+                title: "Find a selected button's callback source",
+                input: {
+                    cdp_endpoint: "http://127.0.0.1:9222",
+                    target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS",
+                    selector: "#submit",
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/webScriptToolContracts.js

@@ -0,0 +1,68 @@
+import { exportWebScriptsInputSchema, webScriptExportResultSchema, } from "../domain/webScriptExport.js";
+import { webModuleTraceInputSchema, webModuleTraceResultSchema, } from "../domain/webModuleTrace.js";
+import { toolContractMetadata } from "./toolEffects.js";
+import { evidenceResultOf } from "./toolOutputSchemas.js";
+import { webSourceLocationInputSchema, webSourceLocationResultSchema, } from "../domain/webSourceLocation.js";
+/** Local captured-script publication contracts shared by CLI and MCP. */
+export const WEB_SCRIPT_TOOL_CONTRACTS = [
+    {
+        name: "trace_web_source_location",
+        ...toolContractMetadata("trace_web_source_location"),
+        description: "Trace one generated position in an exported website script through an explicitly paired local source map. Verifies manifest, selected script and map SHA-256/byte identities; returns every equal-position mapping, reported source/root, resolved source URL, embedded sourcesContent and original position inline. One-based lines and zero-based UTF-16 columns; greatest generated position <= requested across lines. Duplicate sources and generated-only mappings remain distinct. Caller-selected pairing does not establish deployment authenticity or execution. Regular maps and inline indexed sections only; external section URLs are unsupported. No network access or application execution; uses the pinned upstream codec in an owned Node process with private temporary files, independent 192 MiB old-generation heap and 20-second deadline. 4 MiB map, 32 MiB reply; complete evidence or actionable resource failure. Cleanup may extend the deadline.",
+        kind: "application",
+        inputSchema: webSourceLocationInputSchema,
+        outputSchema: evidenceResultOf(webSourceLocationResultSchema),
+        examples: [
+            {
+                title: "Trace a selected captured JavaScript point to embedded original source",
+                input: {
+                    manifest_path: "/analysis/scripts/manifest.json",
+                    script_index: 0,
+                    source_map: {
+                        path: "/analysis/app.js.map",
+                        url: "https://example.test/app.js.map",
+                    },
+                    generated_position: { line: 1, column: 25 },
+                },
+            },
+        ],
+    },
+    {
+        name: "trace_web_module_imports",
+        ...toolContractMetadata("trace_web_module_imports"),
+        description: "Trace one exported website script's outgoing native ES imports/re-exports, using exact URL and optional selected import-map context. Reads a local export_web_scripts manifest and verifies the selected source's SHA-256/size; returns source positions, native resolved URLs or exact errors, every matching captured candidate and explicit unknown execution. Query/fragment identities are preserved. Computed imports and bundler IDs remain unknown. Select importer_url for unknown inline/document-base context. Caller-supplied Chromium executes only a trusted REA resolver stub in an owned context with page requests locally fulfilled/blocked; no captured application execution or asset refetch. Requires absolute REA_BROWSER_EXECUTABLE for literal imports. 32 MiB manifest, 16 MiB source, 4 MiB map and 20-second native deadline; cleanup may extend the deadline.",
+        kind: "application",
+        inputSchema: webModuleTraceInputSchema,
+        outputSchema: evidenceResultOf(webModuleTraceResultSchema),
+        examples: [
+            {
+                title: "Trace an exported module under a selected import map",
+                input: {
+                    manifest_path: "/analysis/exported-scripts/manifest.json",
+                    script_index: 0,
+                    import_map: {
+                        path: "/analysis/import-map.json",
+                        base_url: "https://example.test/app/",
+                    },
+                },
+            },
+        ],
+    },
+    {
+        name: "export_web_scripts",
+        ...toolContractMetadata("export_web_scripts"),
+        description: "Export JavaScript bytes already retained in one local inspect_web_page or capture_browser_scenario JSON capture (normalized result or complete Evidence). Writes scripts and a digest-verified manifest into an absent absolute output_directory. Returns all source URLs, script or transaction/event references, unavailable states, and an analysis_input for analyze_javascript_application when any bytes were exported. Include script sources in inspect_web_page or select capture.network.response_body in scenarios. No refetch or execution. Safe unambiguous URL layouts preserve relative module paths; versions, query variants, inline scripts, and path collisions are isolated with explicit resolution limitations.",
+        kind: "application",
+        inputSchema: exportWebScriptsInputSchema,
+        outputSchema: evidenceResultOf(webScriptExportResultSchema),
+        examples: [
+            {
+                title: "Export a saved website capture for static JavaScript analysis",
+                input: {
+                    capture_path: "/analysis/capture.json",
+                    output_directory: "/analysis/exported-scripts",
+                },
+            },
+        ],
+    },
+];

package/dist/domain/analysisErrorCore.js

@@ -31,11 +31,13 @@ export class AnalysisCapabilityUnavailableError extends AnalysisError {
     operation;
     reason;
     _tag = "AnalysisCapabilityUnavailableError";
-    constructor(providerId, operation, reason) {
-        super(`Provider ${providerId} cannot execute ${operation}: ${reason}`);
+    userMessage;
+    constructor(providerId, operation, reason, options) {
+        super(`Provider ${providerId} cannot execute ${operation}: ${reason}`, options);
         this.providerId = providerId;
         this.operation = operation;
         this.reason = reason;
+        this.userMessage = options?.userMessage;
     }
 }
 /** Caller cancellation won before provider-neutral work completed. */

package/dist/domain/analysisErrorProjection.js

@@ -156,6 +156,7 @@ const artifactStateErrorDetails = (error) => {
             operation: error.operation,
             reason: error.reason,
             ...(error.reason === "limit" ? { truncated: true } : {}),
+            ...(error.detail === undefined ? {} : { detail: error.detail }),
         };
     if (error instanceof UnknownRegistryError)
         return { reason: error.reason };

package/dist/domain/{androidApplication.js → android/androidApplication.js}

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
 import { z } from "zod";
-import { parseArtifactInventoryEvidence } from "./artifactInventoryEvidence.js";
-import { evidenceSchema } from "./evidence.js";
-import { digestSchema } from "./../domain/digests.js";
-import { prefixedDigestSchema } from "./../domain/digests.js";
+import { parseArtifactInventoryEvidence } from "../artifactInventoryEvidence.js";
+import { evidenceSchema } from "../evidence.js";
+import { digestSchema } from "../digests.js";
+import { prefixedDigestSchema } from "../digests.js";
 const evidenceIdSchema = prefixedDigestSchema("ev");
 const pathSchema = z.string().min(1);
 const componentSchema = z.strictObject({
@@ -86,6 +86,7 @@ export const projectAndroidApplication = (input) => {
             ? ["Source inventory pages are incomplete; absence is unknown."]
             : []),
         "Manifest, resource, signing, and bytecode semantics require a dedicated Android provider; this projection reports exact inventory paths and hashes only.",
+        "Runtime families are inferred from inventory formats and paths; filename suffixes do not establish valid DEX or JVM class bytes.",
         "Bridge candidates are path-based hypotheses, not decoded JNI declarations or observed runtime calls.",
     ];
     const withoutId = {
@@ -123,9 +124,9 @@ const classify = (all) => ({
 const runtimeFamilies = (all) => {
     const paths = all.map(({ path }) => path.toLowerCase());
     const families = new Set();
-    if (all.some(({ path, format }) => format === "dex" || path.endsWith(".dex")))
+    if (all.some(({ path, format }) => format === "dex" || path.toLowerCase().endsWith(".dex")))
         families.add("dalvik-art");
-    if (all.some(({ path, format }) => format === "jvm-class" || path.endsWith(".class")))
+    if (all.some(({ path, format }) => format === "jvm-class" || path.toLowerCase().endsWith(".class")))
         families.add("java-kotlin");
     if (all.some(({ format }) => format === "elf"))
         families.add("native");

package/dist/domain/apple/appleApplication.js

@@ -0,0 +1,277 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { appleBundleSchema, appleComponentSchema, applicationRoots, detectBundles, isMachOFormat, isSidecar, isWithin, platformsOf, } from "./appleBundleAnatomy.js";
+import { parseArtifactInventoryEvidence } from "../artifactInventoryEvidence.js";
+import { evidenceSchema } from "../evidence.js";
+import { digestSchema } from "../digests.js";
+import { prefixedDigestSchema } from "../digests.js";
+const evidenceIdSchema = prefixedDigestSchema("ev");
+const pathSchema = z.string().min(1);
+const APPLE_ROOT_FORMATS = ["ipa", "directory", "zip", "dmg"];
+/** Authenticated artifact inventory pages projected as one Apple application. */
+export const appleApplicationProjectionInputSchema = z.strictObject({
+    inventory_evidence: z.array(evidenceSchema).min(1),
+});
+/** Deterministic, execution-free Apple application inventory projection. */
+export const appleApplicationProjectionResultSchema = z.strictObject({
+    projection_id: prefixedDigestSchema("aap"),
+    root_sha256: digestSchema,
+    root_format: z.enum(APPLE_ROOT_FORMATS),
+    platforms: z.array(z.enum(["ios", "macos"])),
+    source_evidence_ids: z.array(evidenceIdSchema).min(1),
+    application_roots: z.array(pathSchema),
+    bundles: z.array(appleBundleSchema),
+    components: z.strictObject({
+        bundle_metadata: z.array(appleComponentSchema),
+        executables: z.array(appleComponentSchema),
+        frameworks: z.array(appleComponentSchema),
+        native_libraries: z.array(appleComponentSchema),
+        javascript: z.array(appleComponentSchema),
+        signing: z.array(appleComponentSchema),
+        privileged_helpers: z.array(appleComponentSchema),
+        launchd_plists: z.array(appleComponentSchema.extend({ domain: z.enum(["agent", "daemon"]) })),
+        helpers: z.array(appleComponentSchema),
+    }),
+    symlinks: z.array(pathSchema),
+    runtime_families: z.array(z.enum([
+        "native",
+        "swift-objective-c",
+        "javascript",
+        "react-native",
+        "flutter",
+        "unity",
+    ])),
+    bridge_candidates: z.array(z.strictObject({
+        source_path: pathSchema,
+        native_path: pathSchema,
+        basis: z.enum([
+            "javascript-and-native-content",
+            "react-native-convention",
+            "flutter-convention",
+            "unity-convention",
+        ]),
+    })),
+    coverage: z.strictObject({
+        status: z.enum(["complete-within-inventory", "partial"]),
+        inventory_complete: z.boolean(),
+    }),
+    limitations: z.array(z.string().min(1)),
+});
+/** Project exact Apple application paths and hashes without parsing or executing target code. */
+export const projectAppleApplication = (input) => {
+    const parsed = appleApplicationProjectionInputSchema.parse(input);
+    const { evidence, inventory } = parseArtifactInventoryEvidence(parsed.inventory_evidence);
+    const rootFormat = appleRootFormat(inventory.manifest.root_format);
+    const nodes = new Map(inventory.nodes.map((node) => [node.artifact_id, node]));
+    const entries = inventory.occurrences
+        .filter(({ logical_path: path }) => path !== ".")
+        .map((occurrence) => {
+        if (occurrence.artifact_id === null)
+            return {
+                path: occurrence.logical_path,
+                kind: occurrence.entry_kind,
+                component: undefined,
+            };
+        const node = nodes.get(occurrence.artifact_id);
+        if (node === undefined)
+            throw new TypeError("Apple application occurrence has no artifact node");
+        return {
+            path: occurrence.logical_path,
+            kind: occurrence.entry_kind,
+            component: {
+                path: occurrence.logical_path,
+                artifact_id: node.artifact_id,
+                sha256: node.sha256,
+                format: node.format,
+            },
+        };
+    });
+    const inventoried = entries.flatMap(({ component }) => component === undefined ? [] : [component]);
+    const roots = applicationRoots(entries, {
+        name: evidence[0]?.subject?.name ?? "",
+        format: rootFormat,
+    });
+    const { all, unattributed } = attributeComponents(inventoried, roots, rootFormat);
+    const bundles = detectBundles(entries, roots);
+    const classified = classifyComponents(entries, all, roots);
+    const runtimeFamilies = identifyRuntimeFamilies(all);
+    const bridgeProjection = identifyBridgeCandidates(classified.javascript, deduplicateComponents([
+        ...classified.executables,
+        ...classified.native_libraries,
+    ]), roots);
+    const uninventoriedImage = rootFormat === "dmg" && inventory.occurrences.length === 1;
+    const complete = inventory.complete && !uninventoriedImage;
+    const limitations = projectionLimitations({
+        complete: inventory.complete,
+        uninventoriedImage,
+        roots,
+        bundles,
+        sidecars: entries.some(({ path }) => isSidecar(path)),
+        symlinks: entries.some(({ kind }) => kind === "symlink"),
+        unattributed,
+    });
+    const withoutId = {
+        root_sha256: inventory.manifest.root_sha256,
+        root_format: rootFormat,
+        platforms: platformsOf(bundles),
+        source_evidence_ids: evidence
+            .map(({ evidence_id: id }) => id)
+            .sort(compare),
+        application_roots: roots,
+        bundles,
+        components: classified,
+        symlinks: entries
+            .filter(({ kind }) => kind === "symlink")
+            .map(({ path }) => path)
+            .sort(compare),
+        runtime_families: runtimeFamilies,
+        bridge_candidates: bridgeProjection.candidates,
+        coverage: {
+            status: complete
+                ? "complete-within-inventory"
+                : "partial",
+            inventory_complete: inventory.complete,
+        },
+        limitations,
+    };
+    return appleApplicationProjectionResultSchema.parse({
+        ...withoutId,
+        projection_id: `aap_${digest(withoutId)}`,
+    });
+};
+/**
+ * IPA projection keeps every archive component, as before. Directory, ZIP,
+ * and DMG inventories can hold installers and other siblings, so only
+ * components inside an application root are attributed to it.
+ */
+const attributeComponents = (inventoried, roots, rootFormat) => {
+    if (rootFormat === "ipa")
+        return { all: [...inventoried], unattributed: 0 };
+    const visible = inventoried.filter(({ path }) => !isSidecar(path));
+    const all = visible.filter(({ path }) => roots.some((root) => isWithin(path, root)));
+    return { all, unattributed: visible.length - all.length };
+};
+const appleRootFormat = (format) => {
+    const root = APPLE_ROOT_FORMATS.find((candidate) => candidate === format);
+    if (root === undefined)
+        throw new TypeError(`Apple application projection requires IPA, directory, ZIP, or DMG inventory Evidence (got ${format})`);
+    return root;
+};
+const classifyComponents = (entries, all, roots) => {
+    const withinApp = (path) => roots.some((root) => isWithin(path, root));
+    const anatomy = (pattern) => entries.flatMap(({ path, kind, component }) => kind === "file" &&
+        component !== undefined &&
+        !isSidecar(path) &&
+        withinApp(path) &&
+        pattern.test(path)
+        ? [component]
+        : []);
+    return {
+        bundle_metadata: all.filter(({ path }) => /(?:^|\/)Info\.plist$/u.test(path)),
+        executables: all.filter(({ path, format }) => withinApp(path) && isMachOFormat(format)),
+        frameworks: all.filter(({ path }) => /\.framework\//u.test(path)),
+        native_libraries: all.filter(({ path }) => /\.(?:dylib|so)$/iu.test(path)),
+        javascript: all.filter(({ format }) => format === "javascript-bundle"),
+        signing: all.filter(({ path }) => /(?:^|\/)(?:embedded\.(?:mobileprovision|provisionprofile)|_CodeSignature\/CodeResources)$/u.test(path)),
+        privileged_helpers: anatomy(/(?:^|\/)Contents\/Library\/LaunchServices\/[^/]+$/u),
+        launchd_plists: anatomy(/(?:^|\/)Contents\/Library\/Launch(?:Agents|Daemons)\/[^/]+\.plist$/u).map((component) => ({
+            ...component,
+            domain: component.path.includes("/LaunchDaemons/")
+                ? "daemon"
+                : "agent",
+        })),
+        helpers: anatomy(/(?:^|\/)Contents\/Helpers\/[^/]+$/u),
+    };
+};
+const deduplicateComponents = (values) => [...new Map(values.map((value) => [value.path, value])).values()].sort((left, right) => compare(left.path, right.path));
+const identifyRuntimeFamilies = (all) => {
+    const paths = all.map(({ path }) => path.toLowerCase());
+    const families = new Set();
+    if (all.some(({ format }) => ["mach-o", "mach-o-universal"].includes(format)))
+        families.add("native");
+    if (paths.some((path) => /\.(?:dylib|framework\/[^/]+)$/u.test(path)))
+        families.add("swift-objective-c");
+    if (all.some(({ format }) => format === "javascript-bundle"))
+        families.add("javascript");
+    if (paths.some((path) => path.includes("reactnative") ||
+        path.includes("react.framework") ||
+        path.includes("hermes")))
+        families.add("react-native");
+    if (paths.some((path) => path.includes("flutter.framework") || path.includes("app.framework")))
+        families.add("flutter");
+    if (paths.some((path) => path.includes("unityframework.framework")))
+        families.add("unity");
+    return [...families].sort(compare);
+};
+/** Pair scripts and native code only within the same application root. */
+const identifyBridgeCandidates = (scripts, native, roots) => {
+    const owner = (path) => roots.find((root) => isWithin(path, root)) ?? null;
+    return {
+        candidates: scripts.flatMap((script) => {
+            const root = owner(script.path);
+            return native
+                .filter(({ path }) => owner(path) === root)
+                .map((item) => ({
+                source_path: script.path,
+                native_path: item.path,
+                basis: bridgeBasis(item.path),
+            }));
+        }),
+    };
+};
+const bridgeBasis = (path) => {
+    const lower = path.toLowerCase();
+    if (lower.includes("react"))
+        return "react-native-convention";
+    if (lower.includes("flutter") || lower.includes("app.framework"))
+        return "flutter-convention";
+    if (lower.includes("unity"))
+        return "unity-convention";
+    return "javascript-and-native-content";
+};
+const projectionLimitations = (facts) => [
+    ...(!facts.complete
+        ? ["Source inventory pages are incomplete; absence is unknown."]
+        : []),
+    ...(facts.uninventoriedImage
+        ? [
+            "The DMG's contents were not inventoried on this host; bundle absence is unknown.",
+        ]
+        : []),
+    ...(facts.roots.length === 0
+        ? [
+            "No application bundle (Payload/*.app or *.app/Contents) was present in the supplied inventory pages.",
+        ]
+        : []),
+    ...(facts.bundles.some(({ layout, info_plist_path: plist }) => layout === "versioned-framework" && plist === null)
+        ? [
+            "A versioned framework has several version directories or no Versions/*/Resources/Info.plist; the Info.plist that Versions/Current selects is unknown because symlink targets are not inventoried.",
+        ]
+        : []),
+    ...(facts.symlinks
+        ? [
+            "Symlinks are reported by path only; their targets are not inventoried, so bundles are reported at their real paths.",
+        ]
+        : []),
+    ...(facts.unattributed > 0
+        ? [
+            `${facts.unattributed} inventoried entries outside every application root are not attributed to the application.`,
+        ]
+        : []),
+    ...(facts.sidecars
+        ? [
+            "AppleDouble sidecar entries (._* files and __MACOSX/) describe neighbouring files and are excluded from bundle roles.",
+        ]
+        : []),
+    "Bundle roles follow path conventions. Read each info_plist_path with inspect_plist for CFBundleExecutable, identifiers, and declared services.",
+    "Bundle identifiers and signing claims require dedicated plist and CMS parsing; this projection reports only exact paths and hashes.",
+    "Bridge candidates are path-based hypotheses, not observed runtime calls.",
+];
+const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const digest = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Apple application projection is not canonical JSON");
+    return createHash("sha256").update(encoded).digest("hex");
+};

package/dist/domain/{appleAssetCatalog.js → apple/appleAssetCatalog.js}

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { jsonValueSchema } from "./jsonValue.js";
-import { AnalysisOutputError } from "./analysisErrorCore.js";
+import { jsonValueSchema } from "../jsonValue.js";
+import { AnalysisOutputError } from "../analysisErrorCore.js";
 /** Caller-controlled page bounds for compiled Apple asset metadata. */
 export const appleAssetCatalogInputSchema = z.strictObject({
     offset: z.number().int().min(0).default(0),